247 lines
6.6 KiB
Markdown
247 lines
6.6 KiB
Markdown
# 用户管理接口说明
|
|
|
|
## 概述
|
|
|
|
为支持交叉评查系统中创建评查任务时的用户选择功能，新增了用户管理相关接口。这些接口提供了获取用户列表、组织架构等功能，支持无限层级选择。
|
|
|
|
## 接口列表
|
|
|
|
### 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. **缓存建议**: 组织架构数据变化不频繁，建议前端适当缓存 |