# 通知公告（管理）API 文档（高质量版）

更新时间：2025-11-07

## 概览
- 能力：新建/编辑（含范围与附件）、发布/撤回、置顶、删除；门户/管理详情均会记录阅读回执（幂等）。
- 权限：按钮级 `manage:notice:*`；发布与撤回共用 `manage:notice:publish`。
- 环境：baseURL `http://localhost:8080`；依赖表：`tb_notice`、`tb_notice_attachment`、`tb_notice_scope`、`tb_notice_read`

## 模型与状态
- Notice 可写字段：
  - 基础：`title`（必填≤128）、`contentHtml`（富文本）、`type`（1通知/2公告）
  - 范围：`visibleAll`（1全员 0自定义）、`scopes[]`（自定义时必填）
    - `scopeType`：0角色/1部门/2岗位；`refId`：对应系统实体ID（来源：sys_user_role/sys_user.dept_id/sys_user_post）
  - 发布/过期：`publishTime`（系统维护）、`expireTime`（可选）
  - 置顶：`pinned/pinnedTime`（置顶接口维护）
  - 统计：`readCount/attachmentCount`（系统维护）
- NoticeAttachment：`fileName/fileUrl/fileType/fileSize/sort`
- 状态：0草稿 1已发布 2撤回；过期为计算字段 `expired`（不持久化，受 `expireTime` 影响）。

## 查询/分页/排序
- 列表：GET `/manage/notice/list` | 权限：`manage:notice:list`
- 参数（query，可选）：
  - `pageNum/pageSize`
  - `keyword`(string) 标题关键字
  - `status`(int) 若为空默认仅返回已发布；传 `-1` 表示“全部”（见下）
  - `pinned`(int) 0/1 过滤置顶
  - `includeExpired`(bool) 是否包含过期
  - `read`(bool) 基于回执的已读/未读筛选
  - `orderBy/orderDir` 同门户
- 可见性与“全部”规则（与 SQL 一致）：
  - 非管理员：当 `status` 为空 → 仅返回已发布；当 `status=-1` → 仅返回“已发布”或“本人发布”的记录；当 `status!=1` → 仅限本人发布。
  - 管理员：不受范围与本人限制。
- 默认排序：`pinned desc, pinned_time desc, publish_time desc`。

## 详情
- GET `/manage/notice/{id}` | 权限：`manage:notice:get`
- 返回：`{ notice, attachments[], scopes[] }`；读取回执幂等记录并可能自增 `readCount`。

## 新增/编辑/删除
- POST `/manage/notice` | 权限：`manage:notice:add`
- PUT  `/manage/notice` | 权限：`manage:notice:edit`
- DELETE `/manage/notice/{ids}` | 权限：`manage:notice:remove`
- 请求体示例：
```json
{
  "title": "期末考试安排",
  "contentHtml": "<p>请同学们按时参加考试</p>",
  "type": 2,
  "visibleAll": 0,
  "scopes": [ { "scopeType": 0, "refId": 3 }, { "scopeType": 1, "refId": 201 } ],
  "attachments": [
    { "fileName": "安排表.pdf", "fileUrl": "https://oss/.../a.pdf", "fileType": "pdf", "fileSize": 102400, "sort": 1 }
  ],
  "expireTime": "2025-12-31 23:59:59"
}
```
- 约束：当 `visibleAll=0` 时 `scopes` 至少一项；(scopeType, refId) 去重；新增时系统补齐 `publisherId/createBy/...`。

## 发布/撤回/置顶
- 发布：PUT `/manage/notice/{id}/publish` | 权限：`manage:notice:publish`
  - 结果语义：`>0` 成功；`-404` 不存在；`-409` 状态冲突（仅草稿/撤回可发布；已发布幂等成功）
- 撤回：PUT `/manage/notice/{id}/retract` | 权限：`manage:notice:publish`
  - 结果语义：`>0` 成功；`-404` 不存在；`-409` 状态冲突（仅已发布可撤回）
- 置顶：PUT `/manage/notice/{id}/pin` | 权限：`manage:notice:pin` | Body：`{ "pinned": true|false }`
  - 结果语义：`>0` 成功；`-404` 不存在；`-409` 置顶仅允许“已发布”

## 上传附件
- 管理端上传网关：`POST /manage/upload/oss`（`manage:upload:oss`）
  - 表单：`file`；可选 `dir/publicUrl`
  - 返回：`data.url` → `attachments[].fileUrl`
- 门户上传网关（备用）：`POST /portal/upload/oss`，`scene=notice.attachment`（pdf/doc/docx/xls/xlsx/png/jpg/jpeg/zip，≤20MB）

## 错误码与语义
- 401 未授权；403 权限不足
- 404 不存在或已删除
- 409 状态冲突：发布/撤回/置顶不满足前置条件
- 500 业务失败：参数/范围/附件校验失败，返回明确 `msg`