448 lines
9.4 KiB
Markdown
448 lines
9.4 KiB
Markdown
# 账户管理模块API文档
|
||
|
||
## 简介
|
||
|
||
账户管理模块提供用户注册、登录、信息管理等功能，是系统的基础模块。本文档详细说明了各接口的使用方法、参数要求、注意事项以及可优化的地方。
|
||
|
||
## 基础URL
|
||
|
||
所有API都以`/api/accounts/`为前缀。
|
||
|
||
## 认证方式
|
||
|
||
除了登录和注册接口外，所有请求都需要在请求头中添加令牌认证信息：
|
||
|
||
```
|
||
Authorization: Token 您的认证令牌
|
||
```
|
||
|
||
## 接口列表
|
||
|
||
### 1. 用户注册
|
||
|
||
**URL**: `/api/accounts/register/`
|
||
**方法**: POST
|
||
**权限**: 无需认证
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "password123",
|
||
"email": "test@example.com",
|
||
"role": "member",
|
||
"name": "测试用户",
|
||
"department": "技术部",
|
||
"group": "开发组"
|
||
}
|
||
```
|
||
|
||
**必填字段**: username, password, email, role, name
|
||
**可选字段**: department, group
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "注册成功",
|
||
"data": {
|
||
"id": "uuid字符串",
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"role": "member",
|
||
"department": "技术部",
|
||
"name": "测试用户",
|
||
"group": "开发组",
|
||
"token": "认证令牌",
|
||
"created_at": "2023-05-10 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- `username`必须是唯一的
|
||
- `password`长度必须大于等于8位
|
||
- `role`必须是以下值之一: admin(管理员), leader(组长), member(组员)
|
||
- `email`必须是有效的邮箱格式
|
||
|
||
### 2. 用户登录
|
||
|
||
**URL**: `/api/accounts/login/`
|
||
**方法**: POST
|
||
**权限**: 无需认证
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "password123"
|
||
}
|
||
```
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"id": "uuid字符串",
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"name": "测试用户",
|
||
"role": "member",
|
||
"department": "技术部",
|
||
"group": "开发组",
|
||
"token": "认证令牌"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 登录成功后，应保存返回的token用于后续请求的认证
|
||
|
||
### 3. 用户登出
|
||
|
||
**URL**: `/api/accounts/logout/`
|
||
**方法**: POST
|
||
**权限**: 需要认证
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登出成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 登出后，原令牌将失效，需要重新登录获取新令牌
|
||
|
||
### 4. 获取当前用户信息
|
||
|
||
**URL**: `/api/accounts/profile/`
|
||
**方法**: GET
|
||
**权限**: 需要认证
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取用户信息成功",
|
||
"data": {
|
||
"id": "uuid字符串",
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"name": "测试用户",
|
||
"role": "member",
|
||
"department": "技术部",
|
||
"group": "开发组",
|
||
"date_joined": "2023-05-10 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 更新当前用户信息
|
||
|
||
**URL**: `/api/accounts/profile/`
|
||
**方法**: PUT
|
||
**权限**: 需要认证
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"name": "新名称",
|
||
"email": "newemail@example.com",
|
||
"department": "新部门",
|
||
"group": "新小组"
|
||
}
|
||
```
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "用户信息更新成功，已更新字段: name, email, department, group",
|
||
"data": {
|
||
"id": "uuid字符串",
|
||
"username": "testuser",
|
||
"email": "newemail@example.com",
|
||
"name": "新名称",
|
||
"role": "member",
|
||
"department": "新部门",
|
||
"group": "新小组"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 普通用户只能更新自己的信息，且字段有限
|
||
- 请确保email格式正确
|
||
|
||
### 6. 修改密码
|
||
|
||
**URL**: `/api/accounts/change-password/`
|
||
**方法**: POST
|
||
**权限**: 需要认证
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"old_password": "password123",
|
||
"new_password": "newpassword123"
|
||
}
|
||
```
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "密码修改成功",
|
||
"data": {
|
||
"token": "新的认证令牌"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 修改密码成功后，原令牌将失效，响应中会返回新令牌
|
||
- 新密码长度必须大于等于8位
|
||
|
||
### 7. 验证令牌有效性
|
||
|
||
**URL**: `/api/accounts/verify-token/`
|
||
**方法**: POST
|
||
**权限**: 需要认证
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "令牌有效",
|
||
"data": {
|
||
"is_valid": true,
|
||
"user": {
|
||
"id": "uuid字符串",
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"name": "测试用户",
|
||
"role": "member",
|
||
"department": "技术部",
|
||
"group": "开发组"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**用途**:
|
||
- 在前端启动时验证当前存储的令牌是否有效
|
||
- 获取当前用户的基本信息
|
||
|
||
### 8. 获取用户列表
|
||
|
||
**URL**: `/api/accounts/users/`
|
||
**方法**: GET
|
||
**权限**: 需要认证（不同角色看到不同范围的用户）
|
||
|
||
**请求参数**:
|
||
- `page`: 页码，默认1
|
||
- `page_size`: 每页条数，默认20
|
||
- `keyword`: 搜索关键词，可搜索用户名、邮箱、姓名或部门
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取用户列表成功",
|
||
"data": {
|
||
"total": 50,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"users": [
|
||
{
|
||
"id": "uuid字符串",
|
||
"username": "user1",
|
||
"email": "user1@example.com",
|
||
"name": "用户1",
|
||
"role": "member",
|
||
"department": "技术部",
|
||
"group": "开发组",
|
||
"is_active": true,
|
||
"date_joined": "2023-05-01 10:00:00"
|
||
},
|
||
// ...更多用户
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 管理员可以看到所有用户
|
||
- 部门领导只能看到本部门用户
|
||
- 普通成员只能看到自己
|
||
|
||
### 9. 获取用户详情
|
||
|
||
**URL**: `/api/accounts/users/{用户ID}/`
|
||
**方法**: GET
|
||
**权限**: 需要认证
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取用户信息成功",
|
||
"data": {
|
||
"id": "uuid字符串",
|
||
"username": "user1",
|
||
"email": "user1@example.com",
|
||
"name": "用户1",
|
||
"role": "member",
|
||
"department": "技术部",
|
||
"group": "开发组"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 用户ID必须是有效的UUID格式
|
||
|
||
### 10. 更新用户信息
|
||
|
||
**URL**: `/api/accounts/users/{用户ID}/update/`
|
||
**方法**: PUT
|
||
**权限**: 需要认证（管理员可更新任何用户，普通用户只能更新自己）
|
||
|
||
**请求参数** (管理员):
|
||
```json
|
||
{
|
||
"email": "new@example.com",
|
||
"name": "新名称",
|
||
"role": "leader",
|
||
"department": "新部门",
|
||
"group": "新小组",
|
||
"is_active": true
|
||
}
|
||
```
|
||
|
||
**请求参数** (普通用户，仅当更新自己时):
|
||
```json
|
||
{
|
||
"email": "new@example.com",
|
||
"name": "新名称"
|
||
}
|
||
```
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "用户信息更新成功",
|
||
"data": {
|
||
"id": "uuid字符串",
|
||
"username": "user1",
|
||
"email": "new@example.com",
|
||
"name": "新名称",
|
||
"role": "leader",
|
||
"department": "新部门",
|
||
"group": "新小组",
|
||
"is_active": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 普通用户只能更新自己的信息，且可更新的字段有限
|
||
- 管理员可以更新任何用户的所有信息，包括角色和状态
|
||
|
||
### 11. 删除用户
|
||
|
||
**URL**: `/api/accounts/users/{用户ID}/delete/`
|
||
**方法**: DELETE
|
||
**权限**: 需要管理员权限
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应结果**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "用户 user1 删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**注意事项**:
|
||
- 只有管理员可以删除用户
|
||
- 不允许删除管理员账户
|
||
|
||
## 错误响应
|
||
|
||
所有接口在发生错误时都会返回包含错误代码和错误信息的JSON响应：
|
||
|
||
```json
|
||
{
|
||
"code": 错误代码,
|
||
"message": "错误信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
常见错误代码：
|
||
- 400: 请求参数错误
|
||
- 401: 认证失败
|
||
- 403: 权限不足
|
||
- 404: 资源不存在
|
||
- 500: 服务器内部错误
|
||
|
||
## 安全建议
|
||
|
||
1. 使用HTTPS传输所有数据
|
||
2. 前端在发送请求前应该对用户输入进行验证
|
||
3. 敏感操作应要求用户重新验证身份
|
||
4. 定期更换密码和令牌
|
||
|
||
## 性能优化建议
|
||
|
||
1. 使用缓存减少数据库查询，特别是对频繁访问的用户信息
|
||
2. 对用户列表接口实施合理的分页策略
|
||
3. 考虑使用异步任务处理耗时操作，如批量用户导入
|
||
|
||
## 需要优化的地方
|
||
|
||
### 功能优化
|
||
|
||
1. **令牌过期机制**：当前令牌没有过期时间，建议实现令牌自动过期机制，增强安全性
|
||
2. **多设备登录支持**：支持一个账号在多设备上同时登录，或提供登录设备管理功能
|
||
3. **密码策略增强**：增加密码复杂度要求，如必须包含大小写字母、数字和特殊字符等
|
||
4. **第三方登录支持**：添加微信、钉钉等第三方登录支持
|
||
5. **两步验证**：添加双因素认证，提高账号安全性
|
||
|
||
### 代码优化
|
||
|
||
1. **移除代码冗余**：一些视图函数中有重复的逻辑，应提取为通用函数
|
||
2. **统一响应格式**：确保所有接口返回一致的响应格式
|
||
3. **完善错误处理**：使用更具体的异常类型，而不是通用Exception
|
||
4. **加强参数验证**：使用序列化器进行更严格的参数验证
|
||
5. **模型优化**：理清User和UserProfile模型的关系，避免数据冗余
|
||
|
||
### 文档优化
|
||
|
||
1. **添加接口版本控制**：为API添加版本号，便于后续升级和维护
|
||
2. **完善API文档**：使用Swagger或ReDoc等工具生成更完善的API文档
|
||
3. **添加接口示例代码**：为每个接口提供不同语言的调用示例代码
|
||
|
||
## 测试建议
|
||
|
||
1. 使用Apifox或Postman创建完整的测试用例集
|
||
2. 测试不同角色用户的权限边界
|
||
3. 测试异常情况下的错误处理
|
||
4. 进行性能测试，确保接口在高负载下仍能正常工作 |