接入用户管理口

2025-07-20 21:31:04 +08:00
parent 4d5ec6cdb7
commit 2d7ed51e97
4 changed files with 1097 additions and 0 deletions
@@ -0,0 +1,247 @@
+# 用户管理接口说明
+
+## 概述
+
+为支持交叉评查系统中创建评查任务时的用户选择功能，新增了用户管理相关接口。这些接口提供了获取用户列表、组织架构等功能，支持无限层级选择。
+
+## 接口列表
+
+### 1. 获取用户列表
+
+**接口地址**: `GET /admin/v2/users/users`
+
+**功能描述**: 获取用户列表，支持分页、过滤和搜索
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| page | integer | 否 | 1 | 页码，从1开始 |
+| page_size | integer | 否 | 20 | 每页数量，最大100 |
+| ou_id | string | 否 | - | 组织单位ID过滤 |
+| is_leader | boolean | 否 | - | 是否为领导过滤 |
+| status | integer | 否 | 0 | 用户状态过滤（0:正常） |
+| search | string | 否 | - | 搜索关键词（用户名或昵称） |
+
+**响应示例**:
+```json
+{
+    "users": [
+        {
+            "id": 1,
+            "username": "zhang_san",
+            "nick_name": "张三",
+            "ou_id": "001",
+            "ou_name": "梅州市烟草局",
+            "is_leader": true,
+            "status": 0
+        }
+    ],
+    "total": 150
+}
+```
+
+### 2. 获取组织架构
+
+**接口地址**: `GET /admin/v2/users/organizations`
+
+**功能描述**: 获取组织架构树，支持无限层级
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| include_users | boolean | 否 | true | 是否包含用户信息 |
+
+**响应示例**:
+```json
+{
+    "organizations": [
+        {
+            "ou_id": "001",
+            "ou_name": "梅州市",
+            "parent_ou_id": null,
+            "level": 0,
+            "children": [
+                {
+                    "ou_id": "001001",
+                    "ou_name": "梅州市烟草局",
+                    "parent_ou_id": "001",
+                    "level": 1,
+                    "children": [],
+                    "users": [
+                        {
+                            "id": 1,
+                            "username": "zhang_san",
+                            "nick_name": "张三",
+                            "ou_id": "001001",
+                            "ou_name": "梅州市烟草局",
+                            "is_leader": true,
+                            "status": 0
+                        }
+                    ]
+                }
+            ],
+            "users": []
+        }
+    ],
+    "total_organizations": 10,
+    "total_users": 150
+}
+```
+
+### 3. 获取扁平化组织列表
+
+**接口地址**: `GET /admin/v2/users/organizations/flat`
+
+**功能描述**: 获取扁平化的组织列表，便于前端处理
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| include_users | boolean | 否 | true | 是否包含用户信息 |
+
+**响应示例**:
+```json
+{
+    "organizations": [
+        {
+            "ou_id": "001",
+            "ou_name": "梅州市",
+            "parent_ou_id": null,
+            "level": 0,
+            "children": [],
+            "users": [
+                {
+                    "id": 1,
+                    "username": "zhang_san",
+                    "nick_name": "张三",
+                    "ou_id": "001",
+                    "ou_name": "梅州市",
+                    "is_leader": true,
+                    "status": 0
+                }
+            ]
+        }
+    ],
+    "total_organizations": 10,
+    "total_users": 150
+}
+```
+
+## 数据模型
+
+### UserInfo 用户信息模型
+```python
+class UserInfo(BaseModel):
+    id: int                    # 用户ID
+    username: str              # 用户名
+    nick_name: str             # 昵称
+    ou_id: str                 # 组织单位ID
+    ou_name: str               # 组织单位名称
+    is_leader: bool            # 是否为领导
+    status: int                # 用户状态
+```
+
+### OrganizationNode 组织节点模型
+```python
+class OrganizationNode(BaseModel):
+    ou_id: str                 # 组织单位ID
+    ou_name: str               # 组织单位名称
+    parent_ou_id: Optional[str] # 父组织单位ID
+    level: int                 # 组织层级
+    children: List[OrganizationNode] # 子组织
+    users: List[UserInfo]      # 该组织下的用户
+```
+
+## 前端使用建议
+
+### 1. 无限层级选择组件
+
+前端可以使用这些接口实现类似图片中的无限层级选择组件：
+
+```javascript
+// 示例：获取组织架构并构建树形选择器
+async function loadOrganizationTree() {
+    const response = await fetch('/admin/v2/users/organizations?include_users=true');
+    const data = await response.json();
+    
+    // 构建树形结构
+    const treeData = data.organizations.map(org => ({
+        key: org.ou_id,
+        title: org.ou_name,
+        children: org.children.map(child => ({
+            key: child.ou_id,
+            title: child.ou_name,
+            children: child.users.map(user => ({
+                key: `user_${user.id}`,
+                title: user.nick_name,
+                isLeaf: true,
+                user: user
+            }))
+        }))
+    }));
+    
+    return treeData;
+}
+```
+
+### 2. 搜索功能
+
+```javascript
+// 示例：用户搜索
+async function searchUsers(keyword) {
+    const response = await fetch(`/admin/v2/users/users?search=${encodeURIComponent(keyword)}`);
+    const data = await response.json();
+    return data.users;
+}
+```
+
+### 3. 分页加载
+
+```javascript
+// 示例：分页加载用户列表
+async function loadUsers(page = 1, pageSize = 20) {
+    const response = await fetch(`/admin/v2/users/users?page=${page}&page_size=${pageSize}`);
+    const data = await response.json();
+    return {
+        users: data.users,
+        total: data.total,
+        hasMore: page * pageSize < data.total
+    };
+}
+```
+
+## 权限控制
+
+所有接口都需要有效的JWT令牌，通过 `verify_token` 依赖进行验证。用户只能访问自己权限范围内的数据。
+
+## 错误处理
+
+接口会返回标准的HTTP状态码：
+
+- `200`: 请求成功
+- `400`: 请求参数错误
+- `401`: 未授权（需要登录）
+- `500`: 服务器内部错误
+
+错误响应格式：
+```json
+{
+    "detail": "错误描述信息"
+}
+```
+
+## 测试
+
+可以使用提供的测试脚本 `test_user_apis.py` 来验证接口功能：
+
+```bash
+python test_user_apis.py
+```
+
+## 注意事项
+
+1. **数据源**: 所有用户数据来自 `sso_users` 表
+2. **状态过滤**: 默认只返回状态为0（正常）的用户
+3. **组织层级**: 基于 `ou_id` 的命名规则自动分析层级关系
+4. **性能考虑**: 大量数据时建议使用分页和搜索功能
+5. **缓存建议**: 组织架构数据变化不频繁，建议前端适当缓存