个人开发接口文档

Appearance

通知公告 ​

概述 ​

通知公告模块是系统中用于发布和管理各类重要信息的核心模块。通过该模块，管理员可以发布公告、通知或重要事项，并且可以配置通知的受众范围和状态。通知公告模块确保了信息的及时传递和有效传达，使得不同角色的用户可以根据其权限访问相应的通知内容，从而提高信息透明度和沟通效率。

主要功能 ​

  1. 通知列表展示

    • 功能描述：以表格形式展示所有通知公告的详细信息，包括标题、发布人、发布时间、最后更新时间、状态（已发布/草稿）等。
    • 操作按钮：
      • 搜索：支持按标题、发布人等关键字进行模糊查询。
      • 批量操作：支持批量发布、删除通知。
      • 导出：将当前页面或全部通知数据导出为 Excel 文件。

  2. 添加通知

    • 功能描述：提供表单用于创建新通知，管理员可以填写字典项的详细信息并设置初始状态。
    • 字段说明：
      • 标题：必填，通知的标题。
      • 内容：必填，通知的具体内容。
      • 发布人：默认为当前登录用户。
      • 状态：默认草稿，可以选择是否立即发布。
      • 受众范围：可选，选择通知的受众范围（如全体用户、特定部门等）。

  3. 编辑通知

    • 功能描述：管理员可以编辑现有通知的详细信息，包括修改标题、内容、状态和受众范围。
    • 字段说明：
      • 标题：可修改，确保唯一性。
      • 内容：可修改，更新通知的具体内容。
      • 状态：可修改，发布或撤回通知。
      • 受众范围：可修改，调整通知的受众范围。

  4. 删除通知

    • 功能描述：管理员可以删除不再需要的通知。为了防止误操作，删除操作会弹出确认框提示。
    • 注意事项：
      • 删除后无法恢复，请谨慎操作。
      • 如果通知有未完成的任务或关联的数据，建议先处理这些数据再删除通知。

  5. 通知日志审计

    • 功能描述：记录通知的操作日志，便于管理员审查通知的变更情况，确保系统的安全性和合规性。
    • 日志内容：
      • 操作时间：记录每次操作的具体时间。
      • 操作用户：记录执行操作的用户名。
      • 操作类型：记录具体操作（如添加通知、编辑通知、删除通知等）。
      • 操作结果：记录操作是否成功及其相关信息。

技术实现 ​

数据库设计 ​

  • 通知表 (notices)：

    • id：主键，自增。
    • title：通知标题。
    • content：通知内容。
    • publisher_id：外键，关联用户表。
    • status：通知状态（0: 草稿, 1: 已发布）。
    • audience：受众范围（如全体用户、特定部门等）。
    • created_at：创建时间。
    • updated_at：更新时间。

  • 用户表 (users)：

    • id：主键，自增。
    • username：用户名。
    • role：用户角色（如管理员、普通用户等）。
    • created_at：创建时间。
    • updated_at：更新时间。

前端实现 ​

技术栈 ​

  • 框架：Vue.js 3.x
  • UI库：Naive UI
  • 状态管理：Pinia
  • 路由管理：Vue Router
  • API请求：Axios

页面结构 ​

  1. 通知列表页

    • 组件：NoticeList.vue
    • 功能：
      • 使用 Naive UI 的 n-data-table 组件展示通知列表。
      • 支持分页、排序和筛选功能。
      • 提供搜索栏，使用 n-input 和 n-button 组件实现模糊查询。
      • 提供批量操作按钮，使用 n-popconfirm 组件实现批量发布、删除通知的确认框。
      • 提供导出按钮，调用后端 API 导出通知数据为 Excel 文件。

  2. 通知详情页

    • 组件：NoticeDetail.vue
    • 功能：
      • 使用 Naive UI 的 n-form 和 n-form-item 组件构建通知信息表单。
      • 表单字段包括标题、内容、状态、受众范围。
      • 使用 n-switch 组件切换通知状态（草稿/已发布）。
      • 提交表单时，调用后端 API 进行通知信息的添加或编辑操作。

接口列表 ​

1. 获取通知列表 ​

  • URL：/api/notices
  • 方法：GET

请求参数 ​

参数名类型是否必填默认值描述
pageint否1当前页码
pageSizeint否10每页显示条数
searchstring否搜索关键字（标题、发布人等）

成功响应 ​

json
{
  "total": 100,
  "data": [
    {
      "id": 1,
      "title": "重要通知",
      "content": "这是一条重要通知的内容。",
      "publisherId": 1,
      "status": 1,
      "audience": "全体用户",
      "createdAt": "2023-09-01T08:00:00Z",
      "updatedAt": "2023-09-01T08:00:00Z"
    },
    ...
  ]
}

2. 添加通知 ​

  • URL：/api/notices
  • 方法：POST
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "title": "新通知",
  "content": "这是新通知的内容。",
  "status": 0,
  "audience": "全体用户"
}

成功响应 ​

json
{
  "id": 101,
  "title": "新通知",
  "content": "这是新通知的内容。",
  "publisherId": 1,
  "status": 0,
  "audience": "全体用户",
  "createdAt": "2023-09-01T08:00:00Z",
  "updatedAt": "2023-09-01T08:00:00Z"
}

3. 编辑通知 ​

  • URL：/api/notices/{id}
  • 方法：PUT
  • 路径参数：
    • id：通知ID
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "title": "更新后的通知",
  "content": "这是更新后通知的内容。",
  "status": 1,
  "audience": "特定部门"
}

成功响应 ​

json
{
  "id": 101,
  "title": "更新后的通知",
  "content": "这是更新后通知的内容。",
  "publisherId": 1,
  "status": 1,
  "audience": "特定部门",
  "updatedAt": "2023-09-01T08:00:00Z"
}

4. 删除通知 ​

  • URL：/api/notices/{id}
  • 方法：DELETE
  • 路径参数：
    • id：通知ID

成功响应 ​

json
{
  "message": "删除成功"
}

5. 批量操作通知 ​

  • URL：/api/notices/batch
  • 方法：POST
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "ids": [1, 2, 3],
  "action": "publish" // 可选值：publish, delete
}

成功响应 ​

json
{
  "message": "批量操作成功"
}

6. 导出通知数据 ​

  • URL：/api/notices/export
  • 方法：GET
  • 请求参数：
    • status：通知状态（可选）
    • audience：受众范围（可选）

成功响应 ​

  • 返回一个 Excel 文件流，文件名为 notice_export.xlsx

附录 ​

接口规范 ​

  • HTTP状态码：

    • 200 OK：请求成功。
    • 201 Created：资源创建成功。
    • 204 No Content：请求成功但无返回内容。
    • 400 Bad Request：客户端请求有误。
    • 404 Not Found：请求的资源不存在。
    • 409 Conflict：请求冲突，例如资源已存在。

  • 错误响应格式：

    json
    {
  "error": "Error message",
  "details": ["Detail 1", "Detail 2"]
}

  • 时间格式：

    • 使用 ISO 8601 标准格式，例如 2023-01-01T00:00:00Z。

总结 ​

通知公告模块是系统中不可或缺的一部分，它不仅提供了对通知数据的全面管理，还确保了信息的及时传递和有效传达。通过合理的通知配置和日志审计，管理员可以有效地管理和调整通知结构，保障系统的稳定运行和用户体验。如果有其他问题或需要进一步的帮助，请随时联系技术支持团队。

滇ICP备2024047254号-1
滇公网安备53011102001490