# Apifox 指南｜通知公告模块（MVP，已拆分）

> 提示：本指南为合并版，现已拆分为：
> - 门户端：docs/apifox/通知公告-门户.md
> - 管理端：docs/apifox/通知公告-管理.md

- baseURL: `http://localhost:8080`
- 认证：`Authorization: Bearer <token>`（通过登录接口获取）
- 账号建议：准备三类账号用于验证可见范围与权限
  - `staff`（学生工作者，具备发布权限）
  - `user`（普通用户，仅只读）
  - `admin`（管理员，全部权限）

## 步骤 0：获取 Token（公共）
- 接口：POST `/login`
- Body: `{ "username": "admin", "password": "admin123" }`
- 断言：`code==200` 且 响应 `token` 存在
- 设置环境变量：`token = 响应.token`

## 步骤 1：staff 新增公告（草稿）
- 接口：POST `/manage/notice`
- Headers：`Authorization: Bearer {{token}}`
- Body：
```json
{
  "title": "期中考试安排",
  "contentHtml": "<p>本周五发布正式安排</p>",
  "type": 2,
  "visibleAll": 0,
  "expireTime": "2025-10-31 23:59:59",
  "attachments": [
    { "fileName": "安排.pdf", "fileUrl": "https://oss/bucket/arrange.pdf", "fileType": "pdf", "fileSize": 102400, "sort": 1 }
  ],
  "scopes": [
    { "scopeType": 0, "refId": 2 },   
    { "scopeType": 1, "refId": 10 },  
    { "scopeType": 2, "refId": 5 }
  ]
}
```
- 断言：`code==200`，保存 `noticeId = data.id`

## 步骤 2：发布公告
- 接口：PUT `/manage/notice/{{noticeId}}/publish`
- 断言：`code==200`

## 步骤 3：置顶公告
- 接口：PUT `/manage/notice/{{noticeId}}/pin`
- Body: `{ "pinned": true }`
- 断言：`code==200`

## 步骤 4：user 登录查看列表与详情（验证“或逻辑”可见范围与已读标识）
- 获取 user Token → 设置 `Authorization`
- 列表（默认“全部”、不含过期）：GET `/manage/notice/list?pageNum=1&pageSize=10&status=-1`
  - 断言：`code==200`；列表包含 `noticeId`；该条记录字段 `pinned==1`
- 详情：GET `/manage/notice/{{noticeId}}`
  - 断言：`code==200`；返回 `data.notice.id==noticeId`
  - 再次请求详情或列表，断言列表中该条 `read==true`，且详情 `data.notice.readCount` 增加

## 补充：已读/未读筛选与排序
- 仅查看已读：GET `/manage/notice/list?pageNum=1&pageSize=10&status=-1&read=true`
  - 断言：返回记录的 `read` 全部为 `true`
- 仅查看未读：GET `/manage/notice/list?pageNum=1&pageSize=10&status=-1&read=false`
  - 断言：返回记录的 `read` 全部为 `false`
- 按发布时间升序：GET `/manage/notice/list?pageNum=1&pageSize=10&orderBy=publishTime&orderDir=asc`
  - 断言：`rows[0].publishTime <= rows[1].publishTime`（注意置顶仍优先）
- 按过期时间降序：GET `/manage/notice/list?pageNum=1&pageSize=10&includeExpired=true&orderBy=expireTime&orderDir=desc`
  - 断言：出现 `expired==true` 的记录，`rows` 按 `expireTime` 降序（置顶除外）

## 步骤 5：编辑公告（验证 publishTime 不变、editCount+1）
- staff 登录
- 接口：PUT `/manage/notice`
- Body：在步骤1的基础上附加 `id: {{noticeId}}`，并修改 `title`（或 `contentHtml`）
- 断言：`code==200`
- 再次获取详情：GET `/manage/notice/{{noticeId}}`
  - 断言：`publishTime` 与发布前一致；`editCount` 较之前 +1；`updateTime` 更新

## 步骤 6：过期策略（验证 includeExpired）
- 使用 admin 账号，将公告 `expireTime` 改为过去时间（PUT `/manage/notice`）
- 列表（默认）：GET `/manage/notice/list?pageNum=1&pageSize=10`
  - 断言：该公告不在列表
- 列表（含过期）：GET `/manage/notice/list?pageNum=1&pageSize=10&includeExpired=true`
  - 断言：该公告出现在列表；记录字段 `expired==true`
- 详情：GET `/manage/notice/{{noticeId}}`
  - 断言：可访问，且需在页面显著标注“已过期”

## 步骤 7：撤回与删除
- 撤回：PUT `/manage/notice/{{noticeId}}/retract` → 断言 `code==200`
  - 断言：详情再查 `pinned==0`（撤回自动取消置顶）
- 删除：DELETE `/manage/notice/{{noticeId}}` → 断言 `code==200`

## 常见失败点与解决办法
- 403 无权限：检查按钮权限是否分配到角色；重新登录生效
- 404 详情不可见：当前用户不在可见范围且非管理员
- 409 状态冲突：未发布公告置顶、已撤回公告再次撤回等
- 422 文件限制：附件不在白名单或超过 20MB；或 scopes 重复（命中唯一约束）

## 断言建议
- 列表响应：`code==200`、`rows` 为数组、`total` 为数字
- 详情响应：`code==200`、`data.notice.id==noticeId`
- 阅读计数：详情前后仅首次递增（或 ≥ 初始值+1）
- 编辑计数：`editCount` 递增；`publishTime` 不变