# 用户管理接口说明

## 概述

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

## 接口列表

### 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. **缓存建议**: 组织架构数据变化不频繁，建议前端适当缓存