# 通知公告 API 文档（MVP，已拆分）

> 重要说明：本文为早期管理端总览，门户与管理已分册：
> - 门户端：docs/api/通知公告-门户.md
> - 管理端：docs/api/通知公告-管理.md


更新时间：2025-10-19

## 概览
- 业务：公告发布与阅读，支持富文本、附件、置顶、有效期、阅读回执。
- 可见范围：全员 或 自定义（角色/部门/岗位，任一匹配即可见，采用“或”逻辑）。
- 与 RuoYi 结合：权限标识对齐；分页参数使用 `pageNum/pageSize`；列表返回 `rows/total`。

依赖表：`tb_notice`、`tb_notice_scope`、`tb_notice_attachment`、`tb_notice_read`。

权限矩阵（按钮级）：
- `manage:notice:list` `manage:notice:get`
- `manage:notice:add` `manage:notice:edit` `manage:notice:remove`
- `manage:notice:publish` `manage:notice:pin`

## 路由清单
- GET `/manage/notice/list`（分页列表） 权限：`manage:notice:list`
- GET `/manage/notice/{id}`（详情并记录阅读回执） 权限：`manage:notice:get`
- POST `/manage/notice`（新增） 权限：`manage:notice:add`
- PUT `/manage/notice`（编辑） 权限：`manage:notice:edit`
- DELETE `/manage/notice/{ids}`（删除，支持逗号分隔） 权限：`manage:notice:remove`
- PUT `/manage/notice/{id}/publish`（发布/重复发布幂等） 权限：`manage:notice:publish`
- PUT `/manage/notice/{id}/retract`（撤回） 权限：`manage:notice:publish`
- PUT `/manage/notice/{id}/pin`（置顶/取消置顶） 权限：`manage:notice:pin`

## 公共数据结构
- NoticeVO（列表项）
  - `id, title, type, status, visibleAll, publishTime, expireTime, pinned, pinnedTime, editCount, readCount, attachmentCount, read(是否已读), expired(是否过期)`
- NoticeDetailVO（详情）
  - `notice`（同上）
  - `attachments: [{ id, fileName, fileUrl, fileType, fileSize, sort }]`
  - `scopes: [{ scopeType(0角色/1部门/2岗位), refId }]`（仅发布者/管理员可见，普通读者无须返回）

## 接口：列表
- 方法：GET
- 路径：/manage/notice/list
- 权限：manage:notice:list
- 请求参数（query）：
  - `pageNum` int 必需，页号，从1开始
  - `pageSize` int 必需，单页条数，建议≤50
  - `keyword` string 可选，按标题模糊
  - `status` int 可选（0草稿/1已发布/2撤回/3已过期；-1=全部，非管理员仅返回“本人草稿/撤回 + 所有已发布”）
  - `pinned` int 可选（0/1）
  - `includeExpired` boolean 可选，默认 false；true 时可见范围内的过期公告也返回
- `read` boolean 可选（true=仅已读；false=仅未读）
- `orderBy` string 可选：publishTime|updateTime|expireTime（默认 publishTime）
- `orderDir` string 可选：asc|desc（默认 desc）
- 排序：置顶优先；其余字段由 `orderBy/orderDir` 控制，默认 `pinned DESC, pinnedTime DESC, publishTime DESC`
- 过滤：非全员时基于“或逻辑”匹配角色/部门/岗位任一命中可见
- 返回示例：
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 101,
      "title": "期中考试安排",
      "type": 2,
      "status": 1,
      "visibleAll": 0,
      "publishTime": "2025-10-19 09:00:00",
      "expireTime": "2025-10-31 23:59:59",
      "pinned": 1,
      "pinnedTime": "2025-10-19 09:00:00",
      "editCount": 2,
      "readCount": 56,
      "attachmentCount": 1,
      "read": true,
      "expired": false
    }
  ],
  "total": 123
}
```

## 接口：详情
- 方法：GET
- 路径：/manage/notice/{id}
- 权限：manage:notice:get
- 行为：进入详情即根据当前用户自动记录阅读回执（若无则插入）
- 返回示例：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "notice": {
      "id": 101,
      "title": "期中考试安排",
      "contentHtml": "<p>...</p>",
      "type": 2,
      "status": 1,
      "visibleAll": 0,
      "publishTime": "2025-10-19 09:00:00",
      "expireTime": "2025-10-31 23:59:59",
      "pinned": 1,
      "pinnedTime": "2025-10-19 09:00:00",
      "editCount": 2,
      "readCount": 57,
      "attachmentCount": 1,
      "expired": false
    },
    "attachments": [
      { "id": 1, "fileName": "安排.pdf", "fileUrl": "https://oss/...pdf", "fileType": "pdf", "fileSize": 102400, "sort": 1 }
    ],
    "scopes": [
      { "scopeType": 0, "refId": 2 },
      { "scopeType": 1, "refId": 10 },
      { "scopeType": 2, "refId": 5 }
    ]
  }
}
```

## 接口：新增公告
- 方法：POST
- 路径：/manage/notice
- 权限：manage:notice:add
- 请求体（application/json）：
```json
{
  "title": "期中考试安排",
  "contentHtml": "<p>...</p>",
  "type": 2,
  "visibleAll": 0,
  "expireTime": "2025-10-31 23:59:59",
  "attachments": [
    { "fileName": "安排.pdf", "fileUrl": "https://oss/...pdf", "fileType": "pdf", "fileSize": 102400, "sort": 1 }
  ],
  "scopes": [
    { "scopeType": 0, "refId": 2 },
    { "scopeType": 1, "refId": 10 },
    { "scopeType": 2, "refId": 5 }
  ]
}
```
- 返回示例：
```json
{ "code": 200, "msg": "操作成功", "data": { "id": 101 } }
```
- 备注：新增仅保存草稿（status=0）；发布请调用发布接口。

## 接口：编辑公告
- 方法：PUT
- 路径：/manage/notice
- 权限：manage:notice:edit
- 请求体：与新增相同，需包含 `id`
- 行为：允许编辑已发布公告；`editCount+1`，更新 `updateTime`；不改变 `publishTime`（已确认规则）。
- 返回示例：
```json
{ "code": 200, "msg": "操作成功" }
```

## 接口：删除公告
- 方法：DELETE
- 路径：/manage/notice/{ids}
- 权限：manage:notice:remove
- 行为：软删除（`del_flag=2`），附件与回执保留
- 返回示例：
```json
{ "code": 200, "msg": "操作成功" }
```

## 接口：发布公告
- 方法：PUT
- 路径：/manage/notice/{id}/publish
- 权限：manage:notice:publish
- 行为：设置 `status=1`、`publishTime=当前时间`；重复调用幂等
- 返回示例：
```json
{ "code": 200, "msg": "操作成功" }
```

## 接口：撤回公告
- 方法：PUT
- 路径：/manage/notice/{id}/retract
- 权限：manage:notice:publish
- 行为：设置 `status=2` 并自动取消置顶（`pinned=0, pinnedTime=null`）；可再次编辑后重新发布
- 返回示例：
```json
{ "code": 200, "msg": "操作成功" }
```

## 接口：置顶/取消置顶
- 方法：PUT
- 路径：/manage/notice/{id}/pin
- 权限：manage:notice:pin
- 请求体：
```json
{ "pinned": true }
```
- 行为：仅对“已发布”有效；置顶设置 `pinned=1, pinnedTime=当前时间`；取消置顶 `pinned=0`
- 返回示例：
```json
{ "code": 200, "msg": "操作成功" }
```

## 错误码
- 400 参数错误：标题必填≤200、内容必填、`expireTime > publishTime`（若已发布且设置了过期）
- 401 未授权：未登录或 Token 失效
- 403 无权限：无对应按钮权限或不可见范围访问详情
- 404 不存在：公告已删除或不可见
- 409 冲突：状态不允许操作（如未发布却置顶）
- 422 约束：可见范围重复、附件超白名单或大小限制

## 备注
- 可见范围采用“或逻辑”：角色/部门/岗位任一满足即可见。
- 修改可见范围不会改变 `publishTime`，仅更新 `updateTime` 与 `editCount`。
- 过期策略：过期公告默认不在列表返回；`includeExpired=true` 可显式查询；详情仍可访问并返回 `expired=true`。
- 附件：白名单 pdf/docx/xlsx/png/jpg/zip；单文件≤20MB。