## 消息 (`messages`)

站内信与公告;管理员发布公告,租户查看、标记已读。

鉴权: 仅管理员 · 文档: https://www-sa2.kuxitong.com/zh/docs/api/messages

### GET `/api/v2/messages`

列出消息 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
| `tenant_ids` | string |  | 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。 |
| `type` | string |  | 消息类型,如 announcement、cert-expire。 |
| `site_id` | integer |  | 网站 ID |
| `site_ids` | string |  | 按网站(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
| `read` | boolean |  | 已读筛选。false 只要未读(与顶栏铃铛未读数同口径,恒相等,不含公告),true 只要已读(同一范围内);不传不筛。管理员看到的已读状态是管理员自己的。 |

```sh
curl "https://panel.example.com/api/v2/messages" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/messages`

发布公告 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content` | string |  | 消息正文。公告按白名单净化后保存(段落、标题、加粗、斜体、列表、引用、http(s) 链接),脚本、事件属性、图片、表格被去掉。 |
| `is_external` | boolean |  | 为真时点击跳 url,url 必填;否则 content 必填。 |
| `is_important` | boolean |  | 是否标为重要(标题前带「重要」标签)。 |
| `is_pinned` | boolean |  | 是否置顶。新置顶的排在置顶组最前,组内顺序用 PUT /messages/pin-order 调整。 |
| `is_popup` | boolean |  | 是否弹窗显示。 |
| `is_show` | boolean |  | 是否显示。 |
| `sort` | integer |  | 置顶组内的排序值(小的在前),只对置顶的公告有意义;置顶时服务端放到组最前,调整顺序用 PUT /messages/pin-order。 |
| `title` | string | 有 | 消息标题。 |
| `url` | string |  | is_external 为真时点击跳转的链接。 |

```sh
curl -X POST "https://panel.example.com/api/v2/messages" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"今晚 23 点维护。","title":"维护通知"}'
```

### PUT `/api/v2/messages/pin-order`

置顶公告重排 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | integer[] | 有 | 置顶公告 id,按希望的顺序(前面的排在前)。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/messages/pin-order" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/messages/read`

标记已读 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | integer[] |  | 置顶公告 id,按希望的顺序(前面的排在前)。 |

```sh
curl -X POST "https://panel.example.com/api/v2/messages/read" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/messages/{id}`

获取消息 · 鉴权: 用户（部分参数仅管理员）

```sh
curl "https://panel.example.com/api/v2/messages/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/messages/{id}`

修改消息 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content` | string |  | 消息正文。公告按白名单净化后保存(段落、标题、加粗、斜体、列表、引用、http(s) 链接),脚本、事件属性、图片、表格被去掉。 |
| `is_external` | boolean |  | 为真时点击跳 url,url 必填;否则 content 必填。 |
| `is_important` | boolean |  | 是否标为重要(标题前带「重要」标签)。 |
| `is_pinned` | boolean |  | 是否置顶。新置顶的排在置顶组最前,组内顺序用 PUT /messages/pin-order 调整。 |
| `is_popup` | boolean |  | 是否弹窗显示。 |
| `is_show` | boolean |  | 是否显示。 |
| `sort` | integer |  | 置顶组内的排序值(小的在前),只对置顶的公告有意义;置顶时服务端放到组最前,调整顺序用 PUT /messages/pin-order。 |
| `title` | string |  | 消息标题。 |
| `url` | string |  | is_external 为真时点击跳转的链接。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/messages/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### DELETE `/api/v2/messages/{id}`

删除消息 · 鉴权: 仅管理员

```sh
curl -X DELETE "https://panel.example.com/api/v2/messages/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

消息对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content` | string |  | 消息正文。公告按白名单净化后保存(段落、标题、加粗、斜体、列表、引用、http(s) 链接),脚本、事件属性、图片、表格被去掉。 |
| `count` | integer |  | 未读消息数。 |
| `created_at` | string |  | 创建时间 (只读) |
| `id` | integer |  | 记录 ID (只读) |
| `ids` | integer[] | 有 | 置顶公告 id,按希望的顺序(前面的排在前)。 |
| `is_external` | boolean |  | 为真时点击跳 url,url 必填;否则 content 必填。 |
| `is_important` | boolean |  | 是否标为重要(标题前带「重要」标签)。 |
| `is_pinned` | boolean |  | 是否置顶。新置顶的排在置顶组最前,组内顺序用 PUT /messages/pin-order 调整。 |
| `is_popup` | boolean |  | 是否弹窗显示。 |
| `is_show` | boolean |  | 是否显示。 |
| `read` | boolean |  | 是否已读。 (只读) |
| `read_count` | integer |  | 已读的租户数(只数租户,不算管理员自己;管理员接口才带,租户看不到)。 (只读) |
| `site_id` | integer |  | 网站 ID (只读) |
| `sort` | integer |  | 置顶组内的排序值(小的在前),只对置顶的公告有意义;置顶时服务端放到组最前,调整顺序用 PUT /messages/pin-order。 |
| `tenant_id` | integer |  | 收件租户;公告为空。 (只读) |
| `title` | string |  | 消息标题。 |
| `title_args` | object |  | 标题键的参数:名字 → 字符串、数字,或子句 {key, args}(子句同样先查词典再填占位,可嵌套)。 (只读) |
| `title_key` | string |  | 标题键(中文原句,{名字} 占位)。有值时面板拿它查界面语言的词典、用 title_args 填占位来显示标题;为空(旧消息、公告、标题被改过)显示 title 原文。 (只读) |
| `type` | string |  | announcement = 公告;其余为通知类型(如 cert-expire、package-expire)。 (只读) |
| `updated_at` | string |  | 更新时间 (只读) |
| `url` | string |  | is_external 为真时点击跳转的链接。 |
