上传规范文档

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,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` 状态记录。