operations_project/apps/accounts/README_ACCOUNTS.md

账户管理模块API文档

简介

账户管理模块提供用户注册、登录、信息管理等功能，是系统的基础模块。本文档详细说明了各接口的使用方法、参数要求、注意事项以及可优化的地方。

基础URL

所有API都以/api/accounts/为前缀。

认证方式

除了登录和注册接口外，所有请求都需要在请求头中添加令牌认证信息：

Authorization: Token 您的认证令牌

接口列表

1. 用户注册

URL: /api/accounts/register/
方法: POST
权限: 无需认证

请求参数:

{
  "username": "testuser",
  "password": "password123",
  "email": "test@example.com",
  "role": "member",
  "name": "测试用户",
  "department": "技术部",
  "group": "开发组"
}

必填字段: username, password, email, role, name
可选字段: department, group

响应结果:

{
  "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
权限: 无需认证

请求参数:

{
  "username": "testuser",
  "password": "password123"
}

响应结果:

{
  "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
权限: 需要认证

请求参数: 无

响应结果:

{
  "code": 200,
  "message": "登出成功",
  "data": null
}

注意事项:

• 登出后，原令牌将失效，需要重新登录获取新令牌

4. 获取当前用户信息

URL: /api/accounts/profile/
方法: GET
权限: 需要认证

请求参数: 无

响应结果:

{
  "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
权限: 需要认证

请求参数:

{
  "name": "新名称",
  "email": "newemail@example.com",
  "department": "新部门",
  "group": "新小组"
}

响应结果:

{
  "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
权限: 需要认证

请求参数:

{
  "old_password": "password123",
  "new_password": "newpassword123"
}

响应结果:

{
  "code": 200,
  "message": "密码修改成功",
  "data": {
    "token": "新的认证令牌"
  }
}

注意事项:

• 修改密码成功后，原令牌将失效，响应中会返回新令牌
• 新密码长度必须大于等于8位

7. 验证令牌有效性

URL: /api/accounts/verify-token/
方法: POST
权限: 需要认证

请求参数: 无

响应结果:

{
  "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: 搜索关键词，可搜索用户名、邮箱、姓名或部门

响应结果:

{
  "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
权限: 需要认证

请求参数: 无

响应结果:

{
  "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
权限: 需要认证（管理员可更新任何用户，普通用户只能更新自己）

请求参数 (管理员):

{
  "email": "new@example.com",
  "name": "新名称",
  "role": "leader",
  "department": "新部门",
  "group": "新小组",
  "is_active": true
}

请求参数 (普通用户，仅当更新自己时):

{
  "email": "new@example.com",
  "name": "新名称"
}

响应结果:

{
  "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
权限: 需要管理员权限

请求参数: 无

响应结果:

{
  "code": 200,
  "message": "用户 user1 删除成功",
  "data": null
}

注意事项:

• 只有管理员可以删除用户
• 不允许删除管理员账户

错误响应

所有接口在发生错误时都会返回包含错误代码和错误信息的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. 进行性能测试，确保接口在高负载下仍能正常工作