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

# Hertz Studio Django 认证模块接口文档

- 基础路径: `/api/`
- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
  ```json
  {
    "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`）
- 请求示例:
  ```http
  POST /api/auth/login/
  Content-Type: application/json
  
  {
    "username": "admin",
    "password": "Passw0rd!",
    "captcha_code": "A1B2",
    "captcha_key": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
  }
  ```
- 返回示例:
  ```json
  {
    "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`）
- 请求示例:
  ```http
  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"
  }
  ```
- 返回示例:
  ```json
  {"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`）
- 请求示例:
  ```bash
  curl -X POST "http://localhost:8000/api/auth/logout/" -H "Authorization: Bearer <access_token>"
  ```
- 返回示例:
  ```json
  {"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`）
- 请求示例:
  ```http
  POST /api/auth/password/change/
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {"old_password": "Passw0rd!", "new_password": "N3wPass!", "confirm_password": "N3wPass!"}
  ```
- 返回示例:
  ```json
  {"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`）
- 请求示例:
  ```http
  POST /api/auth/password/reset/
  Content-Type: application/json
  
  {"email": "user@example.com", "email_code": "654321", "new_password": "N3wPass!", "confirm_password": "N3wPass!"}
  ```
- 返回示例:
  ```json
  {"success": true, "code": 200, "message": "密码重置成功"}
  ```

### （6）获取当前用户信息
- 方法: `GET`
- 路径: `/api/auth/user/info/`
- 认证: 需要登录
- 实现: `get_user_info`（`hertz_studio_django_auth/views/auth_views.py:310`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/auth/user/info/" -H "Authorization: Bearer <access_token>"
  ```
- 返回示例（节选）:
  ```json
  {
    "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`）
- 请求示例:
  ```http
  PUT /api/auth/user/info/update/
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {"real_name": "张三", "phone": "13800000002"}
  ```
- 返回示例:
  ```json
  {"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`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/auth/user/menus/" -H "Authorization: Bearer <access_token>"
  ```
- 返回示例（树形结构）:
  ```json
  {
    "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`）
- 请求示例:
  ```http
  POST /api/auth/email/code/
  Content-Type: application/json
  
  {"email": "user@example.com", "code_type": "register"}
  ```
- 返回示例:
  ```json
  {"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`）
- 请求示例:
  ```http
  POST /api/auth/token/refresh/
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {"refresh_token": "eyJhbGci..."}
  ```
- 返回示例:
  ```json
  {"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`）


## 六、错误响应示例
- 未授权访问:
  ```json
  {"success": false, "code": 401, "message": "未提供认证令牌"}
  ```
- 权限不足:
  ```json
  {"success": false, "code": 403, "message": "缺少权限：system:user:list"}
  ```
- 参数验证失败:
  ```json
  {"success": false, "code": 422, "message": "参数验证失败", "errors": {"email": ["邮箱格式不正确"]}}
  ```