hertz_django/docs/API接口文档/认证模块接口文档.md

Hertz Studio Django 认证模块接口文档

• 基础路径: /api/
• 统一响应: 使用 HertzResponse，结构如下（参考 hertz_studio_django_utils/responses/HertzResponse.py）

  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {}
  }
  

• 路由挂载: 项目主路由中已通过 path('api/', include('hertz_studio_django_auth.urls')) 挂载（hertz_server_django/urls.py:31）。
• 认证说明:
  • 登录、注册、发送邮箱验证码、重置密码：不需要登录
  • 其他接口需要在请求头携带 Authorization: Bearer <access_token>（hertz_studio_django_auth/utils/decorators/auth_decorators.py:24）。
• 路由前缀说明:
  • 认证相关接口前缀为 /api/auth/
  • 管理接口（用户/角色/菜单/部门）前缀为 /api/

一、用户认证

（1）用户登录

• 方法: POST
• 路径: /api/auth/login/
• 认证: 不需要登录
• 请求体: application/json
• 字段: username, password, captcha_code, captcha_key
• 实现: user_login（hertz_studio_django_auth/views/auth_views.py:132）
• 请求示例:

  POST /api/auth/login/
  Content-Type: application/json
  
  {
    "username": "admin",
    "password": "Passw0rd!",
    "captcha_code": "A1B2",
    "captcha_key": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
  }
  

• 返回示例:

  {
    "success": true,
    "code": 200,
    "message": "登录成功",
    "data": {
      "access_token": "eyJhbGci...",
      "refresh_token": "eyJhbGci...",
      "user_info": {
        "user_id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "phone": "13800000000",
        "real_name": "管理员",
        "avatar": null,
        "roles": [{"role_id": 1, "role_name": "管理员", "role_code": "admin"}],
        "permissions": ["system:user:list", "system:role:list"]
      }
    }
  }
  

（2）用户注册

• 方法: POST
• 路径: /api/auth/register/
• 认证: 不需要登录
• 请求体: application/json
• 字段: username, password, confirm_password, email, phone, real_name, email_code?
• 实现: user_register（hertz_studio_django_auth/views/auth_views.py:131）
• 请求示例:

  POST /api/auth/register/
  Content-Type: application/json
  
  {
    "username": "newuser",
    "password": "Passw0rd!",
    "confirm_password": "Passw0rd!",
    "email": "new@example.com",
    "phone": "13800000001",
    "real_name": "新用户",
    "email_code": "123456"
  }
  

• 返回示例:

  {"success": true, "code": 200, "message": "注册成功", "data": {"user_id": 12, "username": "newuser"}}
  

（3）用户登出

• 方法: POST
• 路径: /api/auth/logout/
• 认证: 需要登录
• 实现: user_logout（hertz_studio_django_auth/views/auth_views.py:184）
• 请求示例:

  curl -X POST "http://localhost:8000/api/auth/logout/" -H "Authorization: Bearer <access_token>"
  

• 返回示例:

  {"success": true, "code": 200, "message": "登出成功"}
  

（4）修改密码

• 方法: POST
• 路径: /api/auth/password/change/
• 认证: 需要登录
• 请求体: application/json
• 字段: old_password, new_password, confirm_password
• 实现: change_password（hertz_studio_django_auth/views/auth_views.py:214）
• 请求示例:

  POST /api/auth/password/change/
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {"old_password": "Passw0rd!", "new_password": "N3wPass!", "confirm_password": "N3wPass!"}
  

• 返回示例:

  {"success": true, "code": 200, "message": "密码修改成功"}
  

（5）重置密码

• 方法: POST
• 路径: /api/auth/password/reset/
• 认证: 不需要登录
• 请求体: application/json
• 字段: email, email_code, new_password, confirm_password
• 实现: reset_password（hertz_studio_django_auth/views/auth_views.py:259）
• 请求示例:

  POST /api/auth/password/reset/
  Content-Type: application/json
  
  {"email": "user@example.com", "email_code": "654321", "new_password": "N3wPass!", "confirm_password": "N3wPass!"}
  

• 返回示例:

  {"success": true, "code": 200, "message": "密码重置成功"}
  

（6）获取当前用户信息

• 方法: GET
• 路径: /api/auth/user/info/
• 认证: 需要登录
• 实现: get_user_info（hertz_studio_django_auth/views/auth_views.py:310）
• 请求示例:

  curl "http://localhost:8000/api/auth/user/info/" -H "Authorization: Bearer <access_token>"
  

• 返回示例（节选）:

  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "user_id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "phone": "13800000000",
      "real_name": "管理员",
      "department_id": 2,
      "department_name": "技术部",
      "roles": [{"role_id": 1, "role_name": "管理员", "role_code": "admin"}],
      "last_login_time": "2025-11-17T09:00:00Z"
    }
  }
  

（7）更新当前用户信息

• 方法: PUT
• 路径: /api/auth/user/info/update/
• 认证: 需要登录
• 请求体: application/json
• 字段: email, phone, real_name, avatar, gender, birthday
• 实现: update_user_info（hertz_studio_django_auth/views/auth_views.py:339）
• 请求示例:

  PUT /api/auth/user/info/update/
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {"real_name": "张三", "phone": "13800000002"}
  

• 返回示例:

  {"success": true, "code": 200, "message": "用户信息更新成功", "data": {"real_name": "张三", "phone": "13800000002"}}
  

（8）获取用户菜单

• 方法: GET
• 路径: /api/auth/user/menus/
• 认证: 需要登录
• 实现: get_user_menus（hertz_studio_django_auth/views/auth_views.py:368）
• 请求示例:

  curl "http://localhost:8000/api/auth/user/menus/" -H "Authorization: Bearer <access_token>"
  

• 返回示例（树形结构）:

  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": [
      {"menu_id": 1, "menu_name": "系统管理", "menu_code": "system", "menu_type": 1, "path": "/system", "children": [
        {"menu_id": 2, "menu_name": "用户管理", "menu_code": "system:user", "menu_type": 2, "path": "/system/users", "children": []}
      ]}
    ]
  }
  

（9）发送邮箱验证码

• 方法: POST
• 路径: /api/auth/email/code/
• 认证: 不需要登录
• 请求体: application/json
• 字段: email, code_type（如 register|reset_password）
• 实现: send_email_code（hertz_studio_django_auth/views/auth_views.py:441）
• 请求示例:

  POST /api/auth/email/code/
  Content-Type: application/json
  
  {"email": "user@example.com", "code_type": "register"}
  

• 返回示例:

  {"success": true, "code": 200, "message": "验证码发送成功，请查收邮件", "data": {"email": "user@example.com", "code_type": "register", "expires_in": 300}}
  

（10）刷新访问令牌

• 方法: POST
• 路径: /api/auth/token/refresh/
• 认证: 需要登录
• 请求体: application/json
• 字段: refresh_token
• 实现: refresh_token（hertz_studio_django_auth/views/auth_views.py:544）
• 请求示例:

  POST /api/auth/token/refresh/
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {"refresh_token": "eyJhbGci..."}
  

• 返回示例:

  {"success": true, "code": 200, "message": "token刷新成功", "data": {"access_token": "eyJhbGci..."}}
  

二、用户管理

• 前缀: /api/

（1）获取用户列表

• 方法: GET
• 路径: /api/users/
• 权限: system:user:list
• 查询参数: page, page_size, username, email, real_name, department_id, status
• 实现: user_list（hertz_studio_django_auth/views/management_views.py:38）

（2）创建用户

• 方法: POST
• 路径: /api/users/create/
• 权限: system:user:add
• 请求体: UserManagementSerializer 字段
• 实现: user_create（hertz_studio_django_auth/views/management_views.py:106）

（3）获取用户详情

• 方法: GET
• 路径: /api/users/{user_id}/
• 权限: system:user:query
• 实现: user_detail（hertz_studio_django_auth/views/management_views.py:149）

（4）更新用户

• 方法: PUT
• 路径: /api/users/{user_id}/update/
• 权限: system:user:edit
• 请求体: UserManagementSerializer
• 实现: user_update（hertz_studio_django_auth/views/management_views.py:190）

（5）删除用户

• 方法: DELETE
• 路径: /api/users/{user_id}/delete/
• 权限: system:user:remove
• 实现: user_delete（hertz_studio_django_auth/views/management_views.py:236）

（6）分配用户角色

• 方法: POST
• 路径: /api/users/assign-roles/
• 权限: system:user:role
• 请求体: user_id, role_ids: number[]
• 实现: user_assign_roles（hertz_studio_django_auth/views/management_views.py:279）

三、角色管理

• 前缀: /api/

（1）获取角色列表

• 方法: GET
• 路径: /api/roles/
• 权限: system:role:list
• 查询参数: page, page_size, role_name, role_code, status
• 实现: role_list（hertz_studio_django_auth/views/management_views.py:328）

（2）创建角色

• 方法: POST
• 路径: /api/roles/create/
• 权限: system:role:add
• 请求体: RoleManagementSerializer
• 实现: role_create（hertz_studio_django_auth/views/management_views.py:393）

（3）获取角色详情

• 方法: GET
• 路径: /api/roles/{role_id}/
• 权限: system:role:query
• 实现: role_detail（hertz_studio_django_auth/views/management_views.py:437）

（4）更新角色

• 方法: PUT
• 路径: /api/roles/{role_id}/update/
• 权限: system:role:edit
• 请求体: RoleManagementSerializer
• 实现: role_update（hertz_studio_django_auth/views/management_views.py:477）

（5）删除角色

• 方法: DELETE
• 路径: /api/roles/{role_id}/delete/
• 权限: system:role:remove
• 实现: role_delete（hertz_studio_django_auth/views/management_views.py:527）

（6）分配角色菜单

• 方法: POST
• 路径: /api/roles/assign-menus/
• 权限: system:role:menu
• 请求体: role_id, menu_ids: number[]
• 实现: role_assign_menus（hertz_studio_django_auth/views/management_views.py:579）

（7）获取角色菜单

• 方法: GET
• 路径: /api/roles/{role_id}/menus/
• 权限: system:role:menu
• 实现: role_menus（hertz_studio_django_auth/views/management_views.py:631）

四、菜单管理

• 前缀: /api/

（1）获取菜单列表

• 方法: GET
• 路径: /api/menus/
• 权限: system:menu:list
• 实现: menu_list（hertz_studio_django_auth/views/management_views.py:665）

（2）获取菜单树

• 方法: GET
• 路径: /api/menus/tree/
• 权限: system:menu:list
• 实现: menu_tree（hertz_studio_django_auth/views/management_views.py:710）

（3）创建菜单

• 方法: POST
• 路径: /api/menus/create/
• 权限: system:menu:add
• 请求体: MenuManagementSerializer
• 实现: menu_create（hertz_studio_django_auth/views/management_views.py:744）

（4）获取菜单详情

• 方法: GET
• 路径: /api/menus/{menu_id}/
• 权限: system:menu:query
• 实现: menu_detail（hertz_studio_django_auth/views/management_views.py:787）

（5）更新菜单

• 方法: PUT
• 路径: /api/menus/{menu_id}/update/
• 权限: system:menu:edit
• 请求体: MenuManagementSerializer
• 实现: menu_update（hertz_studio_django_auth/views/management_views.py:828）

（6）删除菜单

• 方法: DELETE
• 路径: /api/menus/{menu_id}/delete/
• 权限: system:menu:remove
• 实现: menu_delete（hertz_studio_django_auth/views/management_views.py:878）

五、部门管理

• 前缀: /api/

（1）获取部门列表

• 方法: GET
• 路径: /api/departments/
• 权限: system:dept:list
• 实现: department_list（hertz_studio_django_auth/views/management_views.py:921）

（2）获取部门树

• 方法: GET
• 路径: /api/departments/tree/
• 权限: system:dept:list
• 实现: department_tree（hertz_studio_django_auth/views/management_views.py:963）

（3）创建部门

• 方法: POST
• 路径: /api/departments/create/
• 权限: system:dept:add
• 请求体: DepartmentManagementSerializer
• 实现: department_create（hertz_studio_django_auth/views/management_views.py:997）

（4）获取部门详情

• 方法: GET
• 路径: /api/departments/{dept_id}/
• 权限: system:dept:query
• 实现: department_detail（hertz_studio_django_auth/views/management_views.py:1040）

（5）更新部门

• 方法: PUT
• 路径: /api/departments/{dept_id}/update/
• 权限: system:dept:edit
• 请求体: DepartmentManagementSerializer
• 实现: department_update（hertz_studio_django_auth/views/management_views.py:1081）

（6）删除部门

• 方法: DELETE
• 路径: /api/departments/{dept_id}/delete/
• 权限: system:dept:remove
• 实现: department_delete（hertz_studio_django_auth/views/management_views.py:1131）

六、错误响应示例

• 未授权访问:

  {"success": false, "code": 401, "message": "未提供认证令牌"}
  

• 权限不足:

  {"success": false, "code": 403, "message": "缺少权限：system:user:list"}
  

• 参数验证失败:

  {"success": false, "code": 422, "message": "参数验证失败", "errors": {"email": ["邮箱格式不正确"]}}