上传规范文档

2025-11-17 16:39:30 +08:00
parent 545335b666
commit 638e152cff
11 changed files with 2757 additions and 0 deletions
--- a/docs/API接口文档/认证模块接口文档.md
+++ b/docs/API接口文档/认证模块接口文档.md
@@ -0,0 +1,452 @@
+# 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": ["邮箱格式不正确"]}}
+  ```