上传规范文档

docs/API接口文档/AI聊天模块接口文档.md

@@ -0,0 +1,246 @@
+# Hertz Studio Django AI聊天模块接口文档
+
+- 基础路径: `/api/ai/`
+- 统一响应: 使用 `HertzResponse`，结构如下
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由通过 `path('api/ai/', include('hertz_studio_django_ai.urls'))` 挂载（`hertz_server_django/urls.py:23`）。
+- 认证说明: 所有接口需在请求头携带 `Authorization: Bearer <access_token>`（`hertz_studio_django_ai/views.py:34` 使用 `login_required`）。
+
+## 接口列表
+
+### 获取聊天列表
+- 方法: `GET`
+- 路径: `/api/ai/chats/`
+- 查询参数:
+  - `query` 可选，按标题模糊搜索
+  - `page` 可选，默认 `1`
+  - `page_size` 可选，默认 `10`
+- 实现: `AIChatListView.get`（`hertz_studio_django_ai/views.py:36`）
+- 请求示例:
+  ```http
+  GET /api/ai/chats/?query=Python&page=1&page_size=10
+  Authorization: Bearer <access_token>
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "total": 25,
+      "page": 1,
+      "page_size": 10,
+      "chats": [
+        {
+          "id": 1,
+          "title": "Python编程问题",
+          "created_at": "2024-01-15 10:30:00",
+          "updated_at": "2024-01-15 10:35:00",
+          "latest_message": "如何使用Django创建API接口？..."
+        }
+      ]
+    }
+  }
+  ```
+
+### 创建聊天
+- 方法: `POST`
+- 路径: `/api/ai/chats/create/`
+- 请求体: `application/json`
+- 字段: `title` 可选，默认 `"新对话"`
+- 实现: `AIChatCreateView.post`（`hertz_studio_django_ai/views.py:100`）
+- 请求示例:
+  ```http
+  POST /api/ai/chats/create/
+  Authorization: Bearer <access_token>
+  Content-Type: application/json
+
+  {
+    "title": "AI编程助手"
+  }
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "创建成功",
+    "data": {
+      "chat_id": 3,
+      "title": "AI编程助手"
+    }
+  }
+  ```
+
+### 聊天详情
+- 方法: `GET`
+- 路径: `/api/ai/chats/{chat_id}/`
+- 路径参数: `chat_id` 聊天ID（整数）
+- 实现: `AIChatDetailView.get`（`hertz_studio_django_ai/views.py:137`）
+- 请求示例:
+  ```http
+  GET /api/ai/chats/1/
+  Authorization: Bearer <access_token>
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "id": 1,
+      "title": "Python编程问题",
+      "created_at": "2024-01-15 10:30:00",
+      "updated_at": "2024-01-15 10:35:00",
+      "messages": [
+        {
+          "id": 1,
+          "role": "user",
+          "content": "如何使用Django创建API接口？",
+          "created_at": "2024-01-15 10:30:00"
+        },
+        {
+          "id": 2,
+          "role": "assistant",
+          "content": "使用Django REST Framework可以快速构建API...",
+          "created_at": "2024-01-15 10:30:30"
+        }
+      ]
+    }
+  }
+  ```
+
+### 更新聊天
+- 方法: `PUT`
+- 路径: `/api/ai/chats/{chat_id}/update/`
+- 路径参数: `chat_id` 聊天ID（整数）
+- 请求体: `application/json`
+- 字段: `title` 新标题
+- 实现: `AIChatUpdateView.put`（`hertz_studio_django_ai/views.py:192`）
+- 请求示例:
+  ```http
+  PUT /api/ai/chats/1/update/
+  Authorization: Bearer <access_token>
+  Content-Type: application/json
+
+  {
+    "title": "更新后的标题"
+  }
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "更新成功",
+    "data": null
+  }
+  ```
+
+### 删除聊天（批量）
+- 方法: `POST`
+- 路径: `/api/ai/chats/delete/`
+- 请求体: `application/json`
+- 字段: `chat_ids` 要删除的聊天ID数组（整数）
+- 实现: `AIChatDeleteView.post`（`hertz_studio_django_ai/views.py:231`）
+- 请求示例:
+  ```http
+  POST /api/ai/chats/delete/
+  Authorization: Bearer <access_token>
+  Content-Type: application/json
+
+  {
+    "chat_ids": [1, 2, 3]
+  }
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "成功删除3个聊天",
+    "data": null
+  }
+  ```
+
+### 发送消息
+- 方法: `POST`
+- 路径: `/api/ai/chats/{chat_id}/send/`
+- 路径参数: `chat_id` 聊天ID（整数）
+- 请求体: `application/json`
+- 字段: `content` 必填，消息内容，不能为空
+- 实现: `AIChatSendMessageView.post`（`hertz_studio_django_ai/views.py:280`）
+- 请求示例:
+  ```http
+  POST /api/ai/chats/1/send/
+  Authorization: Bearer <access_token>
+  Content-Type: application/json
+
+  {
+    "content": "你好，请介绍一下Python的特点"
+  }
+  ```
+- 成功返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "user_message": {
+        "id": 5,
+        "role": "user",
+        "content": "你好，请介绍一下Python的特点",
+        "created_at": "2024-01-15 11:30:00"
+      },
+      "ai_message": {
+        "id": 6,
+        "role": "assistant",
+        "content": "Python是一种高级编程语言，语法简洁，生态丰富...",
+        "created_at": "2024-01-15 11:30:05"
+      }
+    }
+  }
+  ```
+- 失败返回示例（参数验证失败）:
+  ```json
+  {
+    "success": false,
+    "code": 422,
+    "message": "参数验证失败",
+    "data": {
+      "content": ["消息内容不能为空"]
+    }
+  }
+  ```
+- 失败返回示例（聊天不存在）:
+  ```json
+  {
+    "success": false,
+    "code": 404,
+    "message": "聊天不存在或无权访问",
+    "data": null
+  }
+  ```
+- 失败返回示例（AI生成失败）:
+  ```json
+  {
+    "success": false,
+    "code": 500,
+    "message": "AI回复生成失败：服务不可用",
+    "data": null
+  }
+  ```
+
+## 附注
+- 列表与详情时间字段为字符串格式 `YYYY-MM-DD HH:mm:ss`（`hertz_studio_django_ai/views.py:65`、`hertz_studio_django_ai/views.py:151`）。
+- AI模型名称由配置项 `settings.AI_MODEL_NAME` 控制，默认 `deepseek-r1:1.5b`（`hertz_studio_django_ai/views.py:263`）。

docs/API接口文档/Wiki模块接口文档.md

@@ -0,0 +1,367 @@
+# Hertz Studio Django Wiki 接口文档
+
+- 基础路径: `/api/wiki/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/wiki/', include('hertz_studio_django_wiki.urls'))` 挂载（`hertz_server_django/urls.py:29`）。
+- 认证说明: 标注“需要登录”的接口需在请求头携带 `Authorization: Bearer <token>`（`hertz_studio_django_auth/utils/decorators/auth_decorators.py:1`）。
+
+
+## 一、知识分类管理
+
+### （1）获取分类列表
+- 方法: `GET`
+- 路径: `/api/wiki/categories/`
+- 认证: 不需要
+- 查询参数:
+  - `page`: 页码，默认 `1`
+  - `page_size`: 每页数量，默认 `10`
+  - `name`: 分类名称关键字
+  - `parent_id`: 父分类ID（`0` 表示顶级）
+  - `is_active`: `true/false`
+- 实现: `wiki_category_list`（`hertz_studio_django_wiki/views.py:41`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/wiki/categories/?page=1&page_size=10&name=技术"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "list": [
+        {
+          "id": 1,
+          "name": "技术文档",
+          "description": "技术相关文档",
+          "parent": null,
+          "parent_name": null,
+          "sort_order": 1,
+          "is_active": true,
+          "created_at": "2024-01-01T10:00:00Z",
+          "updated_at": "2024-01-01T10:00:00Z",
+          "children_count": 3,
+          "articles_count": 15,
+          "full_path": "技术文档"
+        }
+      ],
+      "total": 1,
+      "page": 1,
+      "page_size": 10
+    }
+  }
+  ```
+
+### （2）获取树形分类
+- 方法: `GET`
+- 路径: `/api/wiki/categories/tree/`
+- 认证: 不需要
+- 实现: `wiki_category_tree`（`hertz_studio_django_wiki/views.py:101`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/wiki/categories/tree/"
+  ```
+- 返回示例:
+  ```json
+  [
+    {
+      "id": 1,
+      "name": "技术文档",
+      "description": "技术相关文档",
+      "sort_order": 1,
+      "is_active": true,
+      "articles_count": 15,
+      "children": [
+        {"id": 2, "name": "后端", "children": []}
+      ]
+    }
+  ]
+  ```
+
+### （3）创建分类
+- 方法: `POST`
+- 路径: `/api/wiki/categories/create/`
+- 认证: 不需要
+- 请求体: `application/json`
+- 字段: `name`, `description`, `parent`, `sort_order`, `is_active`
+- 实现: `wiki_category_create`（`hertz_studio_django_wiki/views.py:136`）
+- 请求示例:
+  ```http
+  POST /api/wiki/categories/create/
+  Content-Type: application/json
+  
+  {
+    "name": "新分类",
+    "description": "分类描述",
+    "parent": null,
+    "sort_order": 10,
+    "is_active": true
+  }
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "知识分类创建成功",
+    "data": {
+      "id": 5,
+      "name": "新分类",
+      "description": "分类描述",
+      "parent": null,
+      "parent_name": null,
+      "sort_order": 10,
+      "is_active": true,
+      "created_at": "2025-11-17T10:00:00Z",
+      "updated_at": "2025-11-17T10:00:00Z",
+      "children_count": 0,
+      "articles_count": 0,
+      "full_path": "新分类"
+    }
+  }
+  ```
+
+### （4）分类详情
+- 方法: `GET`
+- 路径: `/api/wiki/categories/{category_id}/`
+- 认证: 不需要
+- 实现: `wiki_category_detail`（`hertz_studio_django_wiki/views.py:178`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/wiki/categories/1/"
+  ```
+- 返回示例: 同“获取分类列表”中的单项结构。
+
+### （5）更新分类
+- 方法: `PUT`（支持部分更新）
+- 路径: `/api/wiki/categories/{category_id}/update/`
+- 认证: 不需要
+- 请求体: `application/json`
+- 可更新字段: `name`, `description`, `parent`, `sort_order`, `is_active`
+- 实现: `wiki_category_update`（`hertz_studio_django_wiki/views.py:220`）
+- 请求示例:
+  ```http
+  PUT /api/wiki/categories/1/update/
+  Content-Type: application/json
+  
+  {
+    "name": "更新后的分类名",
+    "description": "更新后的描述",
+    "sort_order": 20
+  }
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "知识分类更新成功", "data": {"id": 1, "name": "更新后的分类名"}}
+  ```
+
+### （6）删除分类
+- 方法: `DELETE`
+- 路径: `/api/wiki/categories/{category_id}/delete/`
+- 认证: 不需要
+- 行为: 软删除（将 `is_active=false`）；若存在子分类或文章将返回错误
+- 实现: `wiki_category_delete`（`hertz_studio_django_wiki/views.py:270`）
+- 请求示例:
+  ```bash
+  curl -X DELETE "http://localhost:8000/api/wiki/categories/1/delete/"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "知识分类删除成功"}
+  ```
+
+
+## 二、知识文章管理
+
+### （1）获取文章列表
+- 方法: `GET`
+- 路径: `/api/wiki/articles/`
+- 认证: 不需要
+- 查询参数:
+  - `page`, `page_size`
+  - `title`: 标题关键字
+  - `category_id`: 分类ID
+  - `author_id`: 作者ID
+  - `status`: `draft|published|archived`
+- 实现: `wiki_article_list`（`hertz_studio_django_wiki/views.py:318`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/wiki/articles/?page=1&page_size=10&category_id=1&status=published"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "list": [
+        {
+          "id": 101,
+          "title": "如何部署Django",
+          "summary": "部署流程概览",
+          "image": null,
+          "category_name": "技术文档",
+          "author_name": "alice",
+          "status": "published",
+          "status_display": "已发布",
+          "view_count": 42,
+          "created_at": "2025-11-01T09:00:00Z",
+          "updated_at": "2025-11-10T09:00:00Z",
+          "published_at": "2025-11-10T09:00:00Z"
+        }
+      ],
+      "total": 1,
+      "page": 1,
+      "page_size": 10
+    }
+  }
+  ```
+
+### （2）创建文章（需要登录）
+- 方法: `POST`
+- 路径: `/api/wiki/articles/create/`
+- 认证: 需要登录（`Authorization: Bearer <token>`）
+- 请求体: `application/json`
+- 字段: `title`, `content`, `summary`, `image`, `category`, `status`, `tags`, `sort_order`
+- 实现: `wiki_article_create`（`hertz_studio_django_wiki/views.py:384`）
+- 请求示例:
+  ```http
+  POST /api/wiki/articles/create/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {
+    "title": "新文章",
+    "content": "文章内容...",
+    "summary": "文章摘要...",
+    "image": null,
+    "category": 1,
+    "status": "draft",
+    "tags": "django,部署",
+    "sort_order": 10
+  }
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "知识文章创建成功",
+    "data": {
+      "id": 102,
+      "title": "新文章",
+      "content": "文章内容...",
+      "summary": "文章摘要...",
+      "image": null,
+      "category": 1,
+      "category_name": "技术文档",
+      "author": 2,
+      "author_name": "alice",
+      "status": "draft",
+      "status_display": "草稿",
+      "tags": "django,部署",
+      "tags_list": ["django", "部署"],
+      "view_count": 0,
+      "sort_order": 10,
+      "created_at": "2025-11-17T11:00:00Z",
+      "updated_at": "2025-11-17T11:00:00Z",
+      "published_at": null
+    }
+  }
+  ```
+
+### （3）文章详情
+- 方法: `GET`
+- 路径: `/api/wiki/articles/{article_id}/`
+- 认证: 不需要
+- 行为: 获取详情并增加浏览量
+- 实现: `wiki_article_detail`（`hertz_studio_django_wiki/views.py:426`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/wiki/articles/102/"
+  ```
+- 返回示例: 同“创建文章”中的完整字段结构，`view_count` 将递增。
+
+### （4）更新文章
+- 方法: `PUT`（支持部分更新）
+- 路径: `/api/wiki/articles/{article_id}/update/`
+- 认证: 不需要
+- 请求体: `application/json`
+- 可更新字段: `title`, `content`, `summary`, `image`, `category`, `status`, `tags`, `sort_order`
+- 实现: `wiki_article_update`（`hertz_studio_django_wiki/views.py:472`）
+- 请求示例:
+  ```http
+  PUT /api/wiki/articles/102/update/
+  Content-Type: application/json
+  
+  {
+    "status": "published",
+    "summary": "更新后的摘要"
+  }
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "知识文章更新成功", "data": {"id": 102, "status": "published"}}
+  ```
+
+### （5）删除文章
+- 方法: `DELETE`
+- 路径: `/api/wiki/articles/{article_id}/delete/`
+- 认证: 不需要
+- 实现: `wiki_article_delete`（`hertz_studio_django_wiki/views.py:518`）
+- 请求示例:
+  ```bash
+  curl -X DELETE "http://localhost:8000/api/wiki/articles/102/delete/"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "知识文章删除成功"}
+  ```
+
+### （6）发布文章
+- 方法: `POST`
+- 路径: `/api/wiki/articles/{article_id}/publish/`
+- 认证: 不需要
+- 实现: `wiki_article_publish`（`hertz_studio_django_wiki/views.py:561`）
+- 请求示例:
+  ```bash
+  curl -X POST "http://localhost:8000/api/wiki/articles/102/publish/"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "知识文章发布成功"}
+  ```
+- 失败示例（已发布再次发布）:
+  ```json
+  {"success": false, "code": 500, "message": "系统错误", "error": "文章已经是发布状态"}
+  ```
+
+### （7）归档文章
+- 方法: `POST`
+- 路径: `/api/wiki/articles/{article_id}/archive/`
+- 认证: 不需要
+- 实现: `wiki_article_archive`（`hertz_studio_django_wiki/views.py:609`）
+- 请求示例:
+  ```bash
+  curl -X POST "http://localhost:8000/api/wiki/articles/102/archive/"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "知识文章归档成功"}
+  ```
+
+
+## 三、备注
+- 文章状态枚举: `draft|published|archived`（`hertz_studio_django_wiki/models.py:35`）。
+- 分类软删除通过 `is_active=false` 实现；删除校验会阻止删除存在子分类或文章的分类（`views.py:270`）。
+- 文章详情接口会递增 `view_count`（`hertz_studio_django_wiki/models.py:70` 和 `views.py:431`）。

docs/API接口文档/YOLO模块接口文档.md

@@ -0,0 +1,461 @@
+# Hertz Studio Django YOLO 接口文档
+
+- 基础路径: `/api/yolo/`
+- 统一响应: 使用 `HertzResponse` 封装，结构为：
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+  参考 `hertz_studio_django_utils/responses/HertzResponse.py`
+- 认证说明: 标注“需要登录”的接口需在请求头携带 `Authorization: Bearer <token>`，验证逻辑参考 `hertz_studio_django_auth/utils/decorators/auth_decorators.py`。
+
+
+## 一、模型上传与转换
+
+### （1）上传模型（压缩包或文件夹）
+- 方法: `POST`
+- 路径: `/api/yolo/upload/`
+- 认证: 不需要
+- 请求类型: `multipart/form-data`
+- 参数:
+  - `zip_file`: ZIP 压缩包文件，与 `folder_files` 互斥
+  - `folder_files[...]`: 文件夹内的多个文件（键名形如 `folder_files[path/to/file]`），与 `zip_file` 互斥
+  - `name`: 模型名称（必填）
+  - `version`: 模型版本（默认 `1.0`）
+  - `description`: 模型描述（可选）
+- 参考实现: `views.py` 中 `model_upload`，`_handle_zip_upload`，`_handle_folder_upload`，`_validate_and_create_model`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1018,1058,1129,1182）
+- 示例请求（ZIP 上传）:
+  ```bash
+  curl -X POST "http://localhost:8000/api/yolo/upload/" \
+    -F "zip_file=@/path/to/yolo_model.zip" \
+    -F "name=MyYolo" \
+    -F "version=1.0" \
+    -F "description=Demo model"
+  ```
+- 示例响应:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "模型上传成功",
+    "data": {
+      "id": 12,
+      "name": "MyYolo",
+      "version": "1.0",
+      "folder_path": "/absolute/path/to/media/models/MyYolo_xxxxxxxx",
+      "weights_path": "/absolute/path/to/media/models/MyYolo_xxxxxxxx/weights",
+      "model_path": "/absolute/path/to/media/models/MyYolo_xxxxxxxx/weights/best.pt",
+      "best_model_path": "/absolute/path/to/media/models/.../weights/best.pt",
+      "last_model_path": "/absolute/path/to/media/models/.../weights/last.pt",
+      "categories": {"0":"person","1":"bicycle"},
+      "created_at": "2025-10-22T03:20:00Z"
+    }
+  }
+  ```
+
+### （2）上传 .pt 并转换为 ONNX
+- 方法: `POST`
+- 路径: `/api/yolo/onnx/upload/`
+- 认证: 不需要
+- 请求类型: `multipart/form-data`
+- 参数:
+  - `file`: `.pt` 模型文件（必填）
+  - `imgsz`: 导出图像尺寸（如 `640` 或 `640,640`，默认 `640`）
+  - `opset`: ONNX opset 版本（默认 `12`）
+  - `simplify`: 是否简化 ONNX（`true/false`，默认 `false`）
+- 参考实现: `views.py` 中 `upload_pt_convert_onnx`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:877）
+- 示例请求:
+  ```bash
+  curl -X POST "http://localhost:8000/api/yolo/onnx/upload/" \
+    -F "file=@/path/to/best.pt" \
+    -F "imgsz=640" \
+    -F "opset=12" \
+    -F "simplify=true"
+  ```
+- 示例响应:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "ONNX 导出成功",
+    "data": {
+      "onnx_relative_path": "yolo/ONNX/best_xxxxxxxx.onnx",
+      "download_url": "http://localhost:8000/media/yolo/ONNX/best_xxxxxxxx.onnx",
+      "labels_relative_path": "yolo/ONNX/best_xxxxxxxx.labels.json",
+      "labels_download_url": "http://localhost:8000/media/yolo/ONNX/best_xxxxxxxx.labels.json"
+    }
+  }
+  ```
+
+
+## 二、模型管理
+
+### （1）获取模型列表
+- 方法: `GET`
+- 路径: `/api/yolo/models/`
+- 认证: 不需要
+- 参考实现: `model_list`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:101）
+- 示例响应:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取模型列表成功",
+    "data": [
+      {"id": 1, "name": "ModelA", "version": "1.0", "is_enabled": true, "created_at": "2025-10-22T03:20:00Z"}
+    ]
+  }
+  ```
+
+### （2）获取模型详情
+- 方法: `GET`
+- 路径: `/api/yolo/models/{pk}/`
+- 认证: 不需要
+- 参考实现: `model_detail`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:121）
+- 示例响应（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取模型详情成功",
+    "data": {
+      "id": 1,
+      "name": "ModelA",
+      "version": "1.0",
+      "model_file": "/media/yolo/models/modela.pt",
+      "model_folder_path": "/abs/path/models/modela_...",
+      "model_path": "/abs/path/models/modela_/weights/best.pt",
+      "weights_folder_path": "/abs/path/models/modela_/weights",
+      "categories": {"0": "person"},
+      "is_enabled": true,
+      "description": "...",
+      "created_at": "...",
+      "updated_at": "..."
+    }
+  }
+  ```
+
+### （2）更新模型
+- 方法: `PUT` 或 `PATCH`
+- 路径: `/api/yolo/models/{pk}/update/`
+- 认证: 不需要
+- 请求类型: `application/json` 或 `multipart/form-data`
+- 可更新字段: `description`, `is_enabled`,（如上传 `model_file` 必须为 `.pt`）
+- 参考实现: `model_update`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:134）
+- 示例请求（PATCH）:
+  ```http
+  PATCH /api/yolo/models/1/update/
+  Content-Type: application/json
+  
+  {
+    "description": "更新描述",
+    "is_enabled": true
+  }
+  ```
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "模型更新成功", "data": {"id": 1, "name": "ModelA", "is_enabled": true}}
+  ```
+
+### （3）删除模型
+- 方法: `DELETE`
+- 路径: `/api/yolo/models/{pk}/delete/`
+- 认证: 不需要
+- 参考实现: `model_delete`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:152）
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "模型删除成功"}
+  ```
+
+### （4）启用指定模型
+- 方法: `POST`
+- 路径: `/api/yolo/models/{pk}/enable/`
+- 认证: 不需要
+- 行为: 先禁用其他模型，再启用当前模型
+- 参考实现: `model_enable`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:165）
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "模型 ModelA 已启用", "data": {"id": 1, "is_enabled": true}}
+  ```
+
+### （5）获取当前启用的模型
+- 方法: `GET`
+- 路径: `/api/yolo/models/enabled/`
+- 认证: 不需要
+- 参考实现: `model_enabled`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:186）
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "获取启用模型成功", "data": {"id": 1, "name": "ModelA"}}
+  ```
+
+### （6）创建模型（占位）
+- 方法: `POST`
+- 路径: `/api/yolo/models/create/`
+- 说明: 返回 405，提示使用 `/api/yolo/upload/`
+- 参考实现: `model_create`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:114）
+
+
+## 三、模型类别管理
+
+> 提示：类别通常随模型上传自动导入。手动创建/删除不推荐，仅保留接口。
+
+### （1）获取类别列表
+- 方法: `GET`
+- 路径: `/api/yolo/categories/`
+- 认证: 不需要
+- 参考实现: `category_list`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1301）
+
+### （2）获取类别详情
+- 方法: `GET`
+- 路径: `/api/yolo/categories/{pk}/`
+- 认证: 不需要
+- 参考实现: `category_detail`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1329）
+
+### （3）更新类别
+- 方法: `PUT` 或 `PATCH`
+- 路径: `/api/yolo/categories/{pk}/update/`
+- 认证: 不需要
+- 请求类型: `application/json`
+- 可更新字段: `alias`, `alert_level`（`high|medium|low|none`）, `is_active`
+- 参考实现: `category_update`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1342）
+- 示例请求（PATCH）:
+  ```http
+  PATCH /api/yolo/categories/10/update/
+  Content-Type: application/json
+  
+  {"alias": "行人", "alert_level": "high", "is_active": true}
+  ```
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "更新类别成功", "data": {"id": 10, "alias": "行人", "alert_level": "high"}}
+  ```
+
+### （4）切换类别启用状态
+- 方法: `POST`
+- 路径: `/api/yolo/categories/{pk}/toggle-status/`
+- 认证: 不需要
+- 参考实现: `category_toggle_status`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1385）
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "类别 'person' 启用成功", "data": {"is_active": true}}
+  ```
+
+### （5）获取启用的类别列表
+- 方法: `GET`
+- 路径: `/api/yolo/categories/active/`
+- 认证: 不需要
+- 参考实现: `category_active_list`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1405）
+
+### （6）创建类别（不推荐）
+- 方法: `POST`
+- 路径: `/api/yolo/categories/create/`
+- 认证: 不需要
+- 请求类型: `application/json`
+- 参考实现: `category_create`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1312）
+
+### （7）删除类别（不推荐）
+- 方法: `DELETE`
+- 路径: `/api/yolo/categories/{pk}/delete/`
+- 认证: 不需要
+- 参考实现: `category_delete`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:1362）
+
+
+## 四、目标检测
+
+### 执行检测
+- 方法: `POST`
+- 路径: `/api/yolo/detect/`
+- 认证: 需要登录（`Authorization: Bearer <token>`）
+- 请求类型: `multipart/form-data`
+- 参数:
+  - `file`: 要检测的图片或视频文件（支持图片：`.jpg,.jpeg,.png,.bmp,.tiff,.webp`；视频：`.mp4,.avi,.mov,.mkv,.wmv,.flv`）
+  - `model_id`: 指定模型ID（可选，未提供则使用当前启用模型）
+  - `confidence_threshold`: 置信度阈值（默认 `0.5`，范围 `0.1-1.0`）
+- 参考实现: `yolo_detection`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:446）
+- 示例请求:
+  ```bash
+  curl -X POST "http://localhost:8000/api/yolo/detect/" \
+    -H "Authorization: Bearer <token>" \
+    -F "file=@/path/to/image.jpg" \
+    -F "model_id=1" \
+    -F "confidence_threshold=0.5"
+  ```
+- 示例响应:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "检测完成",
+    "data": {
+      "detection_id": 1001,
+      "result_file_url": "/media/detection/result/result_xxx.jpg",
+      "original_file_url": "/media/detection/original/uuid_image.jpg",
+      "object_count": 3,
+      "detected_categories": ["person"],
+      "confidence_scores": [0.91, 0.87, 0.79],
+      "avg_confidence": 0.8567,
+      "processing_time": 0.43,
+      "model_used": "ModelA 1.0",
+      "confidence_threshold": 0.5,
+      "user_id": 2,
+      "user_name": "alice",
+      "alert_level": "medium"
+    }
+  }
+  ```
+
+
+## 五、检测记录
+
+### （1）获取检测记录列表
+- 方法: `GET`
+- 路径: `/api/yolo/detections/`
+- 认证: 不需要
+- 查询参数:
+  - `type`: `image` 或 `video`
+  - `model_id`: 模型ID
+  - `user_id`: 用户ID
+- 参考实现: `detection_list`（d:\All_template\yolo\hertz_studio_django_yolo\views.py:204）
+- 示例响应（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取检测记录列表成功",
+    "data": [
+      {
+        "id": 1001,
+        "original_file": "/media/detection/original/uuid_image.jpg",
+        "result_file": "/media/detection/result/result_xxx.jpg",
+        "original_filename": "uuid_image.jpg",
+        "result_filename": "result_xxx.jpg",
+        "detection_type": "image",
+        "model_name": "ModelA 1.0",
+        "model_info": {"id":1, "name":"ModelA", "version":"1.0"},
+        "object_count": 3,
+        "detected_categories": ["person"],
+        "confidence_threshold": 0.5,
+        "confidence_scores": [0.91, 0.87, 0.79],
+        "avg_confidence": 0.8567,
+        "processing_time": 0.43,
+        "created_at": "..."
+      }
+    ]
+  }
+  ```
+
+### （2）获取指定用户的检测记录
+- 方法: `GET`
+- 路径: `/api/yolo/detections/{user_id}/user/`
+- 认证: 不需要
+- 查询参数同上
+- 参考实现: `user_detection_records`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:231）
+
+### （3）获取检测记录详情
+- 方法: `GET`
+- 路径: `/api/yolo/detections/{pk}/`
+- 认证: 不需要
+- 参考实现: `detection_detail`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:253）
+
+### （4）删除检测记录
+- 方法: `DELETE`
+- 路径: `/api/yolo/detections/{pk}/delete/`
+- 认证: 不需要
+- 行为: 同时删除其关联的原始文件、结果文件及关联的告警
+- 参考实现: `detection_delete`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:265）
+- 示例响应:
+  ```json
+  {"success": true, "code": 200, "message": "检测记录删除成功"}
+  ```
+
+### （5）批量删除检测记录
+- 方法: `POST`
+- 路径: `/api/yolo/detections/batch-delete/`
+- 认证: 不需要
+- 请求类型: `application/json`
+- 请求体:
+  ```json
+  {"ids": [1001, 1002, 1003]}
+  ```
+- 参考实现: `detection_batch_delete`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:299）
+- 示例响应:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "成功删除 3 条检测记录",
+    "data": {
+      "deleted_count": 3,
+      "found_ids": ["1001","1002","1003"],
+      "not_found_ids": []
+    }
+  }
+  ```
+
+### （6）检测统计
+- 方法: `GET`
+- 路径: `/api/yolo/stats/`
+- 认证: 不需要
+- 参考实现: `detection_stats`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:840）
+
+
+## 六、告警记录
+
+### （1）获取告警记录列表（管理员）
+- 方法: `GET`
+- 路径: `/api/yolo/alerts/`
+- 认证: 不需要
+- 查询参数:
+  - `status`: 默认 `pending`；传 `all` 表示不过滤
+  - `level`: 告警等级（`high|medium|low|none`）
+  - `user_id`: 用户ID
+  - `alter_category`: 告警类别关键字（注意字段名为 `alter_category`）
+- 参考实现: `alert_list`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:358）
+
+### （2）获取用户的告警记录
+- 方法: `GET`
+- 路径: `/api/yolo/users/{user_id}/alerts/`
+- 认证: 需要登录（仅本人或管理员可查）
+- 查询参数:
+  - `status`: `pending|is_confirm|false_positive|all`
+  - `level`: `high|medium|low|none`
+  - `category`: 类别关键字
+- 参考实现: `user_alert_records`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:391）
+
+### （3）更新告警状态
+- 方法: `PUT` 或 `PATCH`
+- 路径: `/api/yolo/alerts/{pk}/update-status/`
+- 认证: 不需要
+- 请求类型: `application/json`
+- 请求体:
+  ```json
+  {"status": "is_confirm"}
+  ```
+- 可选值: `pending`, `is_confirm`, `false_positive`
+- 参考实现: `alert_update_status`（d:\AllTemplate\yolo\hertz_studio_django_yolo\views.py:426）
+- 示例响应:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "更新告警状态成功",
+    "data": {
+      "id": 555,
+      "status": "is_confirm",
+      "alert_level": "medium",
+      "alert_category": "person",
+      "alert_level_display": "中"
+    }
+  }
+  ```
+
+
+## 七、备注
+- 所有文件型字段响应通常包含可直接访问的媒体 URL，媒体服务由 `MEDIA_URL=/media/` 提供。
+- 分类的告警等级枚举参考 `ModelCategory.ALERT_LEVELS` 与 `Alert.ALERT_LEVELS`（d:\AllTemplate\yolo\hertz_studio_django_yolo\models.py:118,153）。
+- 检测请求的文件大小限制：图片 ≤ 50MB，视频 ≤ 500MB（d:\AllTemplate\yolo\hertz_studio_django_yolo\serializers.py:99）。
+

docs/API接口文档/代码生成模块接口文档.md

@@ -0,0 +1,123 @@
+# Hertz Studio Django 代码生成模块接口文档
+
+- 基础路径: `/api/codegen/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/codegen/', include(('hertz_studio_django_codegen.urls', 'hertz_studio_django_codegen'), namespace='codegen'))` 挂载（`hertz_server_django/urls.py:51`）。
+- 认证说明: 接口需要登录，需在请求头携带 `Authorization: Bearer <token>`（`hertz_studio_django_codegen/views/simple_generator_views.py:136`）。
+
+
+## 一、简化代码生成
+
+### 生成应用代码与菜单配置
+- 方法: `POST`
+- 路径: `/api/codegen/simple/generate/`
+- 认证: 需要登录
+- 实现: `simple_code_generate`（`hertz_studio_django_codegen/views/simple_generator_views.py:136`）
+- 请求体: `application/json`
+- 字段:
+  - `module_name` 字符串，模块中文名，例如 `产品管理`
+  - `model_name` 字符串，模型英文名，例如 `Product`
+  - `app_name` 字符串，Django 应用名称，例如 `hertz_studio_django_product`
+  - `fields` 数组，字段定义列表，每项包含：`name`、`type`、`verbose_name`、`help_text`、`required`、`max_length`、`choices`
+  - `operations` 数组，支持的操作，默认 `['list','create','update','delete']`
+  - `menu_config` 对象，菜单配置：`enabled`、`parent_code`、`prefix`、`sort_order`、`icon`
+  - `generate_app` 布尔，是否生成应用代码，默认 `true`
+  - `generate_menu` 布尔，是否生成菜单配置，默认 `true`
+- 请求示例（同时生成应用与菜单）:
+  ```http
+  POST /api/codegen/simple/generate/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {
+    "module_name": "产品管理",
+    "model_name": "Product",
+    "app_name": "hertz_studio_django_product",
+    "fields": [
+      {"name": "name", "type": "CharField", "verbose_name": "产品名称", "required": true, "max_length": 100},
+      {"name": "price", "type": "FloatField", "verbose_name": "价格", "required": true},
+      {"name": "status", "type": "IntegerField", "verbose_name": "状态", "choices": [[0,"下线"],[1,"上线"]]}
+    ],
+    "operations": ["list","create","update","delete"],
+    "menu_config": {"enabled": true, "parent_code": "system", "prefix": "product", "sort_order": 10, "icon": "box"},
+    "generate_app": true,
+    "generate_menu": true
+  }
+  ```
+- 返回示例（成功）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "成功生成产品管理模块代码和菜单配置",
+    "data": {
+      "generated_files": {
+        "hertz_studio_django_product/models.py": "...",
+        "hertz_studio_django_product/serializers.py": "...",
+        "hertz_studio_django_product/views.py": "...",
+        "hertz_studio_django_product/urls.py": "...",
+        "hertz_studio_django_product/apps.py": "..."
+      },
+      "menu_configs": [
+        {"code": "product", "name": "产品管理", "type": "menu", "sort_order": 10},
+        {"code": "product:list", "name": "产品列表", "type": "permission", "sort_order": 11}
+      ],
+      "app_path": "hertz_studio_django_product",
+      "menu_file": "d:/All_template/yolo/pending_menus_product.py"
+    }
+  }
+  ```
+- 请求示例（仅生成菜单配置）:
+  ```http
+  POST /api/codegen/simple/generate/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {
+    "module_name": "库存管理",
+    "model_name": "Inventory",
+    "app_name": "hertz_studio_django_inventory",
+    "fields": [],
+    "operations": ["list"],
+    "menu_config": {"enabled": true, "parent_code": "system", "prefix": "inventory"},
+    "generate_app": false,
+    "generate_menu": true
+  }
+  ```
+- 返回示例（仅菜单）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "成功生成库存管理模块代码和菜单配置",
+    "data": {
+      "generated_files": {},
+      "menu_configs": [{"code": "inventory", "name": "库存管理", "type": "menu"}],
+      "app_path": "",
+      "menu_file": "d:/All_template/yolo/pending_menus_inventory.py"
+    }
+  }
+  ```
+
+
+## 二、错误响应示例
+- 缺少必填参数:
+  ```json
+  {"success": false, "code": 422, "message": "缺少必填参数: fields"}
+  ```
+- 请求体格式错误（非JSON）:
+  ```json
+  {"success": false, "code": 422, "message": "请求参数格式错误，请使用JSON格式"}
+  ```
+- 生成失败（异常信息）：
+  ```json
+  {"success": false, "code": 500, "message": "代码生成失败: <错误信息>"}
+  ```

docs/API接口文档/日志模块接口文档.md

@@ -0,0 +1,121 @@
+# Hertz Studio Django 日志模块接口文档
+
+- 基础路径: `/api/log/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/log/', include('hertz_studio_django_log.urls'))` 挂载（`hertz_server_django/urls.py:46`）。
+- 认证与权限: 接口需要登录并具备相应权限，其中列表接口需 `system:log:list`，详情接口需 `system:log:query`（`hertz_studio_django_log/views/log_views.py:18`, `225`）。
+
+
+## 一、操作日志列表
+
+### 获取操作日志列表
+- 方法: `GET`
+- 路径: `/api/log/list/`
+- 权限: 仅管理员（`system:log:list`）
+- 查询参数:
+  - `user_id`: 用户ID
+  - `username`: 用户名（模糊匹配）
+  - `action_type`: 操作类型（`create|update|delete|view|list|login|logout|export|import|other`）
+  - `module`: 操作模块（模糊匹配）
+  - `status`: 操作状态（`0|1`）
+  - `ip_address`: IP地址
+  - `start_date`: 开始时间（ISO日期时间）
+  - `end_date`: 结束时间（ISO日期时间）
+  - `page`: 页码，默认 `1`
+  - `page_size`: 每页数量，默认 `20`
+- 实现: `operation_log_list`（`hertz_studio_django_log/views/log_views.py:117`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/log/list/?username=admin&action_type=login&page=1&page_size=10" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取操作日志列表成功",
+    "data": {
+      "logs": [
+        {
+          "log_id": 1001,
+          "username": "admin",
+          "action_type": "login",
+          "action_type_display": "登录",
+          "module": "认证",
+          "description": "用户登录",
+          "ip_address": "127.0.0.1",
+          "response_status": 200,
+          "status": 1,
+          "status_display": "成功",
+          "is_success": true,
+          "created_at": "2025-11-17T08:30:00Z"
+        }
+      ],
+      "pagination": {
+        "page": 1,
+        "page_size": 10,
+        "total_count": 1,
+        "total_pages": 1,
+        "has_next": false,
+        "has_previous": false
+      }
+    }
+  }
+  ```
+
+
+## 二、操作日志详情
+
+### 获取操作日志详情
+- 方法: `GET`
+- 路径: `/api/log/detail/{log_id}/`
+- 权限: 仅管理员（`system:log:query`）
+- 路径参数: `log_id` 日志ID
+- 实现: `operation_log_detail`（`hertz_studio_django_log/views/log_views.py:259`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/log/detail/1001/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取操作日志详情成功",
+    "data": {
+      "log_id": 1001,
+      "user": 1,
+      "username": "admin",
+      "action_type": "login",
+      "action_type_display": "登录",
+      "module": "认证",
+      "description": "用户登录",
+      "target_model": null,
+      "target_id": null,
+      "ip_address": "127.0.0.1",
+      "user_agent": "Mozilla/5.0",
+      "request_data": {"username": "admin"},
+      "formatted_request_data": "{\n  \"username\": \"admin\"\n}",
+      "response_status": 200,
+      "status": 1,
+      "status_display": "成功",
+      "is_success": true,
+      "created_at": "2025-11-17T08:30:00Z"
+    }
+  }
+  ```
+
+
+## 三、备注
+- 列表返回采用 `OperationLogListSerializer` 字段子集以简化展示。
+- 详情返回使用 `OperationLogSerializer`，包含格式化的请求数据与成功判断等辅助字段。

docs/API接口文档/系统监控模块接口文档.md

@@ -0,0 +1,302 @@
+# Hertz Studio Django 系统监控模块接口文档
+
+- 基础路径: `/api/system/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/system/', include('hertz_studio_django_system_monitor.urls'))` 挂载（`hertz_server_django/urls.py:23`）。
+- 认证说明: 所有接口均需要登录，需在请求头携带 `Authorization: Bearer <token>`（`hertz_studio_django_auth/utils/decorators/auth_decorators.py:1`）。
+
+
+## 一、系统信息
+
+### 获取系统信息
+- 方法: `GET`
+- 路径: `/api/system/system/`
+- 认证: 需要登录
+- 实现: `SystemInfoView.get`（`hertz_studio_django_system_monitor/views.py:63`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/system/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "hostname": "DESKTOP-ABC123",
+      "platform": "Windows-10-10.0.19041-SP0",
+      "architecture": "AMD64",
+      "boot_time": "2025-11-16T08:30:00Z",
+      "uptime": "2 days, 14:30:00"
+    }
+  }
+  ```
+
+
+## 二、CPU 信息
+
+### 获取CPU信息
+- 方法: `GET`
+- 路径: `/api/system/cpu/`
+- 认证: 需要登录
+- 实现: `CPUInfoView.get`（`hertz_studio_django_system_monitor/views.py:63`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/cpu/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "cpu_count": 8,
+      "cpu_percent": 25.6,
+      "cpu_freq": {"current": 2400.0, "min": 800.0, "max": 3600.0},
+      "load_avg": [1.2, 1.5, 1.8]
+    }
+  }
+  ```
+
+
+## 三、内存信息
+
+### 获取内存信息
+- 方法: `GET`
+- 路径: `/api/system/memory/`
+- 认证: 需要登录
+- 实现: `MemoryInfoView.get`（`hertz_studio_django_system_monitor/views.py:94`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/memory/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "total": 17179869184,
+      "available": 8589934592,
+      "used": 8589934592,
+      "percent": 50.0,
+      "free": 8589934592
+    }
+  }
+  ```
+
+
+## 四、磁盘信息
+
+### 获取磁盘信息
+- 方法: `GET`
+- 路径: `/api/system/disks/`
+- 认证: 需要登录
+- 实现: `DiskInfoView.get`（`hertz_studio_django_system_monitor/views.py:127`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/disks/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": [
+      {
+        "device": "C:\\",
+        "mountpoint": "C:\\",
+        "fstype": "NTFS",
+        "total": 1073741824000,
+        "used": 536870912000,
+        "free": 536870912000,
+        "percent": 50.0
+      }
+    ]
+  }
+  ```
+
+
+## 五、网络信息
+
+### 获取网络信息
+- 方法: `GET`
+- 路径: `/api/system/network/`
+- 认证: 需要登录
+- 实现: `NetworkInfoView.get`（`hertz_studio_django_system_monitor/views.py:170`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/network/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": [
+      {
+        "interface": "以太网",
+        "bytes_sent": 1048576000,
+        "bytes_recv": 2097152000,
+        "packets_sent": 1000000,
+        "packets_recv": 1500000
+      }
+    ]
+  }
+  ```
+
+
+## 六、进程信息
+
+### 获取进程信息
+- 方法: `GET`
+- 路径: `/api/system/processes/`
+- 认证: 需要登录
+- 查询参数:
+  - `limit`: 返回条数，默认 `20`
+  - `sort_by`: 排序字段，默认 `cpu_percent`（可选 `cpu_percent|memory_percent|create_time`）
+- 实现: `ProcessInfoView.get`（`hertz_studio_django_system_monitor/views.py:204`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/processes/?limit=10&sort_by=cpu_percent" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": [
+      {
+        "pid": 1234,
+        "name": "python.exe",
+        "status": "running",
+        "cpu_percent": 15.6,
+        "memory_percent": 8.2,
+        "memory_info": {"rss": 134217728, "vms": 268435456},
+        "create_time": "2025-11-16T10:30:00Z",
+        "cmdline": ["python", "manage.py", "runserver"]
+      }
+    ]
+  }
+  ```
+
+
+## 七、GPU 信息
+
+### 获取GPU信息
+- 方法: `GET`
+- 路径: `/api/system/gpu/`
+- 认证: 需要登录
+- 实现: `GPUInfoView.get`（`hertz_studio_django_system_monitor/views.py:259`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/gpu/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（有GPU设备）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "gpu_available": true,
+      "gpu_info": [
+        {
+          "id": 0,
+          "name": "NVIDIA GeForce RTX 3080",
+          "load": 45.6,
+          "memory_total": 10240,
+          "memory_used": 4096,
+          "memory_util": 40.0,
+          "temperature": 65
+        }
+      ],
+      "timestamp": "2025-11-16 18:30:00"
+    }
+  }
+  ```
+- 返回示例（无GPU设备）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "gpu_available": false,
+      "message": "未检测到GPU设备",
+      "timestamp": "2025-11-16 18:30:00"
+    }
+  }
+  ```
+- 返回示例（GPU库不可用）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "gpu_available": false,
+      "message": "GPU监控不可用，请安装GPUtil库",
+      "timestamp": "2025-11-16 18:30:00"
+    }
+  }
+  ```
+
+
+## 八、综合监控
+
+### 获取系统监测综合信息
+- 方法: `GET`
+- 路径: `/api/system/monitor/`
+- 认证: 需要登录
+- 实现: `SystemMonitorView.get`（`hertz_studio_django_system_monitor/views.py:325`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/system/monitor/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {
+      "system": {"hostname": "DESKTOP-ABC123", "platform": "Windows-10-10.0.19041-SP0", "architecture": "AMD64", "boot_time": "2025-11-16T08:30:00Z", "uptime": "2 days, 14:30:00"},
+      "cpu": {"cpu_count": 8, "cpu_percent": 25.6, "cpu_freq": {"current": 2400.0, "min": 800.0, "max": 3600.0}, "load_avg": [1.2, 1.5, 1.8]},
+      "memory": {"total": 17179869184, "available": 8589934592, "used": 8589934592, "percent": 50.0, "free": 8589934592},
+      "disks": [{"device": "C:\\", "mountpoint": "C:\\", "fstype": "NTFS", "total": 1073741824000, "used": 536870912000, "free": 536870912000, "percent": 50.0}],
+      "network": [{"interface": "以太网", "bytes_sent": 1048576000, "bytes_recv": 2097152000, "packets_sent": 1000000, "packets_recv": 1500000}],
+      "processes": [{"pid": 1234, "name": "python.exe", "status": "running", "cpu_percent": 15.6, "memory_percent": 8.2, "memory_info": {"rss": 134217728, "vms": 268435456}, "create_time": "2025-11-16T10:30:00Z", "cmdline": ["python", "manage.py", "runserver"]}],
+      "gpus": [{"id": 0, "name": "NVIDIA GeForce RTX 3080", "load": 45.6, "memory_total": 10240, "memory_used": 4096, "memory_util": 40.0, "temperature": 65}]
+    }
+  }
+  ```
+
+
+## 九、错误响应示例
+- 通用错误格式:
+  ```json
+  {"success": false, "code": 401, "message": "未授权访问"}
+  ```

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": ["邮箱格式不正确"]}}
+  ```

docs/API接口文档/通知模块接口文档.md

@@ -0,0 +1,391 @@
+# Hertz Studio Django 通知模块接口文档
+
+- 基础路径: `/api/notice/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/notice/', include('hertz_studio_django_notice.urls'))` 挂载（`hertz_server_django/urls.py:19`）。
+- 认证说明: 所有接口均需要登录，需在请求头携带 `Authorization: Bearer <token>`（`hertz_studio_django_auth/utils/decorators/auth_decorators.py:1`）。
+
+
+## 一、管理员通知接口
+
+### （1）创建通知
+- 方法: `POST`
+- 路径: `/api/notice/admin/create/`
+- 认证: 需要登录
+- 请求体: `application/json`
+- 字段: `title`, `content`, `notice_type`, `priority`, `is_top`, `publish_time`, `expire_time`, `attachment_url`
+- 实现: `admin_create_notice`（`hertz_studio_django_notice/views/admin_views.py:39`）
+- 请求示例:
+  ```http
+  POST /api/notice/admin/create/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {
+    "title": "系统维护通知",
+    "content": "将于周六晚间进行系统维护。",
+    "notice_type": 1,
+    "priority": 3,
+    "is_top": true,
+    "publish_time": "2025-11-18 09:00:00",
+    "expire_time": "2025-11-20 23:59:59",
+    "attachment_url": null
+  }
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "通知创建成功", "data": {"notice_id": 101}}
+  ```
+
+### （2）更新通知
+- 方法: `PUT`
+- 路径: `/api/notice/admin/update/{notice_id}/`
+- 认证: 需要登录
+- 请求体: `application/json`
+- 字段: `title`, `content`, `notice_type`, `priority`, `is_top`, `publish_time`, `expire_time`, `attachment_url`, `status`
+- 实现: `admin_update_notice`（`hertz_studio_django_notice/views/admin_views.py:94`）
+- 请求示例:
+  ```http
+  PUT /api/notice/admin/update/101/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {"priority": 4, "is_top": false}
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "通知更新成功"}
+  ```
+
+### （3）删除通知
+- 方法: `DELETE`
+- 路径: `/api/notice/admin/delete/{notice_id}/`
+- 认证: 需要登录
+- 实现: `admin_delete_notice`（`hertz_studio_django_notice/views/admin_views.py:146`）
+- 请求示例:
+  ```bash
+  curl -X DELETE "http://localhost:8000/api/notice/admin/delete/101/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "通知删除成功"}
+  ```
+
+### （4）获取通知列表
+- 方法: `GET`
+- 路径: `/api/notice/admin/list/`
+- 认证: 需要登录
+- 查询参数:
+  - `page`, `page_size`
+  - `notice_type`, `status`, `priority`, `is_top`, `keyword`
+  - `start_date`, `end_date`（按发布时间范围筛选）
+- 实现: `admin_get_notice_list`（`hertz_studio_django_notice/views/admin_views.py:184`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/notice/admin/list/?page=1&page_size=10&status=1&is_top=true" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取通知列表成功",
+    "data": {
+      "notices": [
+        {
+          "notice_id": 101,
+          "title": "系统维护通知",
+          "notice_type": 1,
+          "notice_type_display": "系统通知",
+          "priority": 3,
+          "priority_display": "高",
+          "status": 1,
+          "status_display": "已发布",
+          "is_top": true,
+          "publish_time": "2025-11-18T09:00:00Z",
+          "expire_time": "2025-11-20T23:59:59Z",
+          "publisher_name": "管理员",
+          "view_count": 12,
+          "is_expired": false,
+          "read_count": 30,
+          "unread_count": 5,
+          "created_at": "2025-11-17T10:00:00Z",
+          "updated_at": "2025-11-17T10:00:00Z"
+        }
+      ],
+      "pagination": {"current_page": 1, "page_size": 10, "total_pages": 1, "total_count": 1, "has_next": false, "has_previous": false}
+    }
+  }
+  ```
+
+### （5）获取通知详情
+- 方法: `GET`
+- 路径: `/api/notice/admin/detail/{notice_id}/`
+- 认证: 需要登录
+- 实现: `admin_get_notice_detail`（`hertz_studio_django_notice/views/admin_views.py:273`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/notice/admin/detail/101/" -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取通知详情成功",
+    "data": {
+      "notice_id": 101,
+      "title": "系统维护通知",
+      "content": "将于周六晚间进行系统维护。",
+      "notice_type": 1,
+      "notice_type_display": "系统通知",
+      "priority": 3,
+      "priority_display": "高",
+      "status": 1,
+      "status_display": "已发布",
+      "is_top": true,
+      "publish_time": "2025-11-18T09:00:00Z",
+      "expire_time": "2025-11-20T23:59:59Z",
+      "attachment_url": null,
+      "publisher_name": "管理员",
+      "publisher_username": "admin",
+      "view_count": 12,
+      "is_expired": false,
+      "read_count": 30,
+      "unread_count": 5,
+      "created_at": "2025-11-17T10:00:00Z",
+      "updated_at": "2025-11-17T10:00:00Z"
+    }
+  }
+  ```
+
+### （6）发布通知
+- 方法: `POST`
+- 路径: `/api/notice/admin/publish/{notice_id}/`
+- 认证: 需要登录
+- 实现: `admin_publish_notice`（`hertz_studio_django_notice/views/admin_views.py:317`）
+- 请求示例:
+  ```bash
+  curl -X POST "http://localhost:8000/api/notice/admin/publish/101/" -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "通知发布成功"}
+  ```
+
+### （7）撤回通知
+- 方法: `POST`
+- 路径: `/api/notice/admin/withdraw/{notice_id}/`
+- 认证: 需要登录
+- 实现: `admin_withdraw_notice`（`hertz_studio_django_notice/views/admin_views.py:374`）
+- 请求示例:
+  ```bash
+  curl -X POST "http://localhost:8000/api/notice/admin/withdraw/101/" -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "通知撤回成功"}
+  ```
+
+
+## 二、用户通知接口
+
+### （1）获取通知列表
+- 方法: `GET`
+- 路径: `/api/notice/user/list/`
+- 认证: 需要登录
+- 查询参数:
+  - `page`, `page_size`
+  - `notice_type`, `is_read`, `is_starred`, `priority`, `keyword`
+  - `show_expired`: `true/false`，默认不显示过期通知
+- 实现: `user_get_notice_list`（`hertz_studio_django_notice/views/user_views.py:28`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/notice/user/list/?page=1&page_size=10&is_read=false&is_starred=true" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取通知列表成功",
+    "data": {
+      "notices": [
+        {
+          "title": "系统维护通知",
+          "notice_type_display": "系统通知",
+          "priority_display": "高",
+          "is_top": true,
+          "publish_time": "2025-11-18T09:00:00Z",
+          "is_read": false,
+          "read_time": null,
+          "is_starred": true,
+          "starred_time": "2025-11-17T12:00:00Z",
+          "is_expired": false,
+          "created_at": "2025-11-17T10:00:00Z"
+        }
+      ],
+      "pagination": {
+        "current_page": 1,
+        "page_size": 10,
+        "total_pages": 1,
+        "total_count": 1,
+        "has_next": false,
+        "has_previous": false
+      },
+      "statistics": {"total_count": 10, "unread_count": 2, "starred_count": 3}
+    }
+  }
+  ```
+
+### （2）获取通知详情
+- 方法: `GET`
+- 路径: `/api/notice/user/detail/{notice_id}/`
+- 认证: 需要登录
+- 行为: 自动标记为已读并增加查看次数
+- 实现: `user_get_notice_detail`（`hertz_studio_django_notice/views/user_views.py:147`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/notice/user/detail/101/" -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取通知详情成功",
+    "data": {
+      "title": "系统维护通知",
+      "content": "将于周六晚间进行系统维护。",
+      "notice_type_display": "系统通知",
+      "priority_display": "高",
+      "attachment_url": null,
+      "publish_time": "2025-11-18T09:00:00Z",
+      "expire_time": "2025-11-20T23:59:59Z",
+      "is_top": true,
+      "is_expired": false,
+      "publisher_name": "管理员",
+      "is_read": true,
+      "read_time": "2025-11-17T12:05:00Z",
+      "is_starred": true,
+      "starred_time": "2025-11-17T12:00:00Z"
+    }
+  }
+  ```
+
+### （3）标记通知已读
+- 方法: `POST`
+- 路径: `/api/notice/user/mark-read/`
+- 认证: 需要登录
+- 请求体: `application/json`
+- 字段: `notice_id`
+- 实现: `user_mark_notice_read`（`hertz_studio_django_notice/views/user_views.py:214`）
+- 请求示例:
+  ```http
+  POST /api/notice/user/mark-read/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {"notice_id": 101}
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "标记已读成功"}
+  ```
+
+### （4）批量标记已读
+- 方法: `POST`
+- 路径: `/api/notice/user/batch-mark-read/`
+- 认证: 需要登录
+- 请求体: `application/json`
+- 字段: `notice_ids: number[]`
+- 实现: `user_batch_mark_read`（`hertz_studio_django_notice/views/user_views.py:260`）
+- 请求示例:
+  ```http
+  POST /api/notice/user/batch-mark-read/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {"notice_ids": [101, 102, 103]}
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "批量标记已读成功"}
+  ```
+
+### （5）标记全部已读
+- 方法: `POST`
+- 路径: `/api/notice/user/mark-all-read/`
+- 认证: 需要登录
+- 实现: `user_mark_all_read`（`hertz_studio_django_notice/views/user_views.py:317`）
+- 请求示例:
+  ```bash
+  curl -X POST "http://localhost:8000/api/notice/user/mark-all-read/" -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "标记全部已读成功，共标记3条通知", "data": {"updated_count": 3}}
+  ```
+
+### （6）切换收藏状态
+- 方法: `POST`
+- 路径: `/api/notice/user/toggle-star/`
+- 认证: 需要登录
+- 请求体: `application/json`
+- 字段: `notice_id`, `is_starred`
+- 实现: `user_toggle_notice_star`（`hertz_studio_django_notice/views/user_views.py:401`）
+- 请求示例:
+  ```http
+  POST /api/notice/user/toggle-star/
+  Authorization: Bearer <token>
+  Content-Type: application/json
+  
+  {"notice_id": 101, "is_starred": true}
+  ```
+- 返回示例:
+  ```json
+  {"success": true, "code": 200, "message": "收藏成功"}
+  ```
+
+### （7）获取通知统计信息
+- 方法: `GET`
+- 路径: `/api/notice/user/statistics/`
+- 认证: 需要登录
+- 实现: `user_get_notice_statistics`（`hertz_studio_django_notice/views/user_views.py:417`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/notice/user/statistics/" -H "Authorization: Bearer <token>"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取统计信息成功",
+    "data": {
+      "total_count": 10,
+      "unread_count": 2,
+      "read_count": 8,
+      "starred_count": 3,
+      "type_statistics": {"系统通知": 6, "公告通知": 3, "活动通知": 1, "维护通知": 0},
+      "priority_statistics": {"低": 2, "中": 4, "高": 3, "紧急": 1}
+    }
+  }
+  ```
+
+
+## 三、备注
+- 列表与详情序列包含显示用枚举字段（如 `notice_type_display`, `priority_display`, `status_display`）。
+- 用户视图中 `user_get_notice_detail` 会自动将未读标记为已读并累加 `view_count`。
+- 管理员发布接口会为所有启用用户创建 `HertzUserNotice` 状态记录。

docs/API接口文档/验证码模块接口文档.md

@@ -0,0 +1,83 @@
+# Hertz Studio Django 验证码模块接口文档
+
+- 基础路径: `/api/captcha/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/captcha/', include('hertz_studio_django_captcha.urls'))` 挂载（`hertz_server_django/urls.py:28`）。
+- 认证说明: 接口允许匿名访问（`AllowAny`），不需要登录（`hertz_studio_django_captcha/api_views.py:18`, `hertz_studio_django_captcha/api_views.py:60`）。
+- 验证接口说明: 独立的验证码验证接口已删除，验证逻辑集成到具体业务接口（`hertz_studio_django_captcha/api_views.py:54`）。
+
+
+## 一、生成验证码
+
+### 生成新的验证码
+- 方法: `POST`
+- 路径: `/api/captcha/generate/`
+- 认证: 不需要登录
+- 实现: `CaptchaGenerateAPIView.post`（`hertz_studio_django_captcha/api_views.py:38`）
+- 请求示例:
+  ```bash
+  curl -X POST "http://localhost:8000/api/captcha/generate/"
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "验证码生成成功",
+    "data": {
+      "captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
+      "image_data": "data:image/png;base64,iVBORw0KGgo...",
+      "expires_in": 300
+    }
+  }
+  ```
+
+
+## 二、刷新验证码
+
+### 刷新已有验证码，生成新图像
+- 方法: `POST`
+- 路径: `/api/captcha/refresh/`
+- 认证: 不需要登录
+- 请求体: `application/json`
+- 字段: `captcha_id` 旧验证码ID
+- 实现: `CaptchaRefreshAPIView.post`（`hertz_studio_django_captcha/api_views.py:84`）
+- 请求示例:
+  ```http
+  POST /api/captcha/refresh/
+  Content-Type: application/json
+  
+  {"captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"}
+  ```
+- 返回示例:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "验证码刷新成功",
+    "data": {
+      "captcha_id": "f2b3c4d5-e6f7-8901-bcde-0123456789ab",
+      "image_data": "data:image/png;base64,iVBORw0KGgo...",
+      "expires_in": 300
+    }
+  }
+  ```
+
+
+## 三、错误响应示例
+- 参数不完整（刷新接口）:
+  ```json
+  {"success": false, "code": 400, "message": "参数不完整"}
+  ```
+- 生成/刷新失败（异常信息）：
+  ```json
+  {"success": false, "code": 500, "message": "验证码生成失败", "error": "<错误信息>"}
+  ```