leaudit-platform-frontend/docs/用户管理接口说明.md

用户管理接口说明

概述

为支持交叉评查系统中创建评查任务时的用户选择功能，新增了用户管理相关接口。这些接口提供了获取用户列表、组织架构等功能，支持无限层级选择。

接口列表

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	否	-	搜索关键词（用户名或昵称）

响应示例:

{
    "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	是否包含用户信息

响应示例:

{
    "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	是否包含用户信息

响应示例:

{
    "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 用户信息模型

class UserInfo(BaseModel):
    id: int                    # 用户ID
    username: str              # 用户名
    nick_name: str             # 昵称
    ou_id: str                 # 组织单位ID
    ou_name: str               # 组织单位名称
    is_leader: bool            # 是否为领导
    status: int                # 用户状态

OrganizationNode 组织节点模型

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. 无限层级选择组件

前端可以使用这些接口实现类似图片中的无限层级选择组件：

// 示例：获取组织架构并构建树形选择器
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. 搜索功能

// 示例：用户搜索
async function searchUsers(keyword) {
    const response = await fetch(`/admin/v2/users/users?search=${encodeURIComponent(keyword)}`);
    const data = await response.json();
    return data.users;
}

3. 分页加载

// 示例：分页加载用户列表
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: 服务器内部错误

错误响应格式：

{
    "detail": "错误描述信息"
}

测试

可以使用提供的测试脚本 test_user_apis.py 来验证接口功能：

python test_user_apis.py

注意事项

1. 数据源: 所有用户数据来自 sso_users 表
2. 状态过滤: 默认只返回状态为0（正常）的用户
3. 组织层级: 基于 ou_id 的命名规则自动分析层级关系
4. 性能考虑: 大量数据时建议使用分页和搜索功能
5. 缓存建议: 组织架构数据变化不频繁，建议前端适当缓存