hertz_django_studio/hertz_django

Fork 0

Files

pony 638e152cff 上传规范文档

2025-11-17 16:39:30 +08:00

12 KiB

Raw Blame History

Hertz Studio Django 通知模块接口文档

基础路径: /api/notice/
统一响应: 使用 HertzResponse，结构如下（参考 hertz_studio_django_utils/responses/HertzResponse.py）
```
{
  "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）

请求示例:

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
}

返回示例:

{"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）

请求示例:

PUT /api/notice/admin/update/101/
Authorization: Bearer <token>
Content-Type: application/json

{"priority": 4, "is_top": false}

返回示例:

{"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）

请求示例:

curl -X DELETE "http://localhost:8000/api/notice/admin/delete/101/" \
  -H "Authorization: Bearer <token>"

返回示例:

{"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）

请求示例:

curl "http://localhost:8000/api/notice/admin/list/?page=1&page_size=10&status=1&is_top=true" \
  -H "Authorization: Bearer <token>"

返回示例（节选）:

{
  "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）

请求示例:

curl "http://localhost:8000/api/notice/admin/detail/101/" -H "Authorization: Bearer <token>"

返回示例（节选）:

{
  "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）

请求示例:

curl -X POST "http://localhost:8000/api/notice/admin/publish/101/" -H "Authorization: Bearer <token>"

返回示例:

{"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）

请求示例:

curl -X POST "http://localhost:8000/api/notice/admin/withdraw/101/" -H "Authorization: Bearer <token>"

返回示例:

{"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）

请求示例:

curl "http://localhost:8000/api/notice/user/list/?page=1&page_size=10&is_read=false&is_starred=true" \
  -H "Authorization: Bearer <token>"

返回示例（节选）:

{
  "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）

请求示例:

curl "http://localhost:8000/api/notice/user/detail/101/" -H "Authorization: Bearer <token>"

返回示例（节选）:

{
  "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）

请求示例:

POST /api/notice/user/mark-read/
Authorization: Bearer <token>
Content-Type: application/json

{"notice_id": 101}

返回示例:

{"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）

请求示例:

POST /api/notice/user/batch-mark-read/
Authorization: Bearer <token>
Content-Type: application/json

{"notice_ids": [101, 102, 103]}

返回示例:

{"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）

请求示例:

curl -X POST "http://localhost:8000/api/notice/user/mark-all-read/" -H "Authorization: Bearer <token>"

返回示例:

{"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）

请求示例:

POST /api/notice/user/toggle-star/
Authorization: Bearer <token>
Content-Type: application/json

{"notice_id": 101, "is_starred": true}

返回示例:

{"success": true, "code": 200, "message": "收藏成功"}

（7）获取通知统计信息

方法: GET
路径: /api/notice/user/statistics/
认证: 需要登录
实现: user_get_notice_statistics（hertz_studio_django_notice/views/user_views.py:417）

请求示例:

curl "http://localhost:8000/api/notice/user/statistics/" -H "Authorization: Bearer <token>"

返回示例:

{
  "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 状态记录。

12 KiB Raw Blame History Unescape Escape

Hertz Studio Django 通知模块接口文档

一、管理员通知接口

（1）创建通知

（2）更新通知

（3）删除通知

（4）获取通知列表

（5）获取通知详情

（6）发布通知

（7）撤回通知

二、用户通知接口

（1）获取通知列表

（2）获取通知详情

（3）标记通知已读

（4）批量标记已读

（5）标记全部已读

（6）切换收藏状态

（7）获取通知统计信息

三、备注

12 KiB

Raw Blame History