# 通知公告（门户）API 文档（高质量版）

更新时间：2025-11-07

## 概览
- 业务说明：登录用户在门户端浏览公告；服务层按照“可见范围”自动过滤，详情接口会幂等记录阅读回执（不重复计数）。
- 权限模型：登录（`isAuthenticated()`）；可见范围由管理端配置（全员/自定义角色/部门/岗位）。
- 依赖表：`tb_notice`、`tb_notice_attachment`、`tb_notice_scope`、`tb_notice_read`
- 环境：baseURL `http://localhost:8080`；认证头 `Authorization: Bearer <token>`

## 领域模型（只读）
- Notice
  - 基础：`id`、`title`、`contentHtml`、`type(1通知/2公告)`
  - 状态：`status` 0草稿 1已发布 2撤回；过期为计算字段 `expired`（非持久化）
  - 范围：`visibleAll` 1全员 0自定义；`publisherId`；`publishTime`；`expireTime`
  - 展示：`pinned`/`pinnedTime`
  - 统计：`editCount/readCount/attachmentCount`
  - 查询辅助：`keyword`、`includeExpired`、`read`(true/false)、`orderBy`(publishTime/updateTime/expireTime)、`orderDir`(asc/desc)
- NoticeAttachment：`id/fileName/fileUrl/fileType/fileSize/sort`
- NoticeScope：`scopeType` 0角色 1部门 2岗位；`refId` 对应系统实体ID

## 列表
- 方法：GET
- 路径：`/portal/notice/list`
- 权限：登录
- 请求参数（query，可选）：
  - `pageNum`(int)/`pageSize`(int) 默认 1/10
  - `keyword`(string) 标题关键字
  - `pinned`(int) 0/1 过滤置顶
  - `includeExpired`(bool) 是否包含过期，默认 false（过期判断基于 `expireTime`）
  - `read`(bool) 已读/未读筛选（基于 `tb_notice_read`）
  - `orderBy`(string) publishTime/updateTime/expireTime；`orderDir`(string) asc/desc
- 默认仅返回“已发布(1)”；非管理员无法看到他人草稿/撤回。
- 返回：`{ code:200, rows:[Notice], total:n }`

## 详情（记录阅读回执）
- 方法：GET
- 路径：`/portal/notice/{id}`
- 权限：登录
- 行为：返回 `{ notice, attachments[], scopes[] }`，并幂等插入 `tb_notice_read`；首次阅读会自增 `readCount`。
- 可见性：非“已发布(1)”仅发布者或管理员可看；越权返回 `{ code:500, msg: '无权查看该公告' }`。
- 返回示例：
```json
{
  "code": 200,
  "data": {
    "notice": {
      "id": 1001,
      "title": "期末考试安排",
      "type": 2,
      "status": 1,
      "publishTime": "2025-10-20 10:00:00",
      "expireTime": "2025-12-31 23:59:59",
      "pinned": 1,
      "readCount": 120
    },
    "attachments": [
      { "id": 11, "fileName": "安排表.pdf", "fileUrl": "https://.../a.pdf", "fileSize": 102400 }
    ],
    "scopes": [ { "scopeType": 0, "refId": 3 } ]
  }
}
```

## 错误码与语义
- 401 未授权：未登录或 token 过期
- 403 无权查看：非发布者/非管理员访问“非已发布”公告（服务端抛业务异常）
- 404 不存在：公告已删除或不可见
- 500 业务失败：服务异常（返回明确 `msg`）

## 排序与置顶
- 默认排序：置顶优先（`pinned desc, pinned_time desc`），再按 `publish_time desc`。
- 可通过 `orderBy/orderDir` 调整排序字段与方向。

## 上传附件（门户可选）
- 上传网关：`POST /portal/upload/oss`
  - 场景：`notice.attachment`（pdf/doc/docx/xls/xlsx/png/jpg/jpeg/zip，≤20MB）
  - 表单：`file`；可选 `dir/publicUrl`
  - 返回：`data.url` 可直用于附件 `fileUrl`

## 备注
- 若需“游客可浏览”，可在后端为列表/详情加 `@Anonymous` 并仅返回“已发布”记录；当前实现为“登录可见”。