## 消息 (`messages`)

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

鉴权: 用户 · 文档: https://www-demo.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 |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |
| `type` | string |  | 消息类型,如 announcement、cert-expire。 |
| `site_id` | integer |  | 网站 ID |

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

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

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

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content` | string |  | 消息正文。 |
| `is_bold` | boolean |  | 标题是否加粗。 |
| `is_external` | boolean |  | 为真时点击跳 url,url 必填;否则 content 必填。 |
| `is_popup` | boolean |  | 是否弹窗显示。 |
| `is_red` | boolean |  | 标题是否标红。 |
| `is_show` | boolean |  | 是否显示。 |
| `sort` | integer |  | 排序值(小的在前)。 |
| `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":"维护通知"}'
```

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

标记已读 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | integer[] |  | 为空表示发给自己的全部已读。 |

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

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

近期未读消息 · 鉴权: 用户

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `days` | integer |  | 只取最近这么多天的消息。 默认: 30 |
| `limit` | integer |  | 最多返回的条数。 默认: 8 |

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

### GET `/api/v2/messages/unread-count`

未读消息数 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/messages/unread-count" \
  -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 |  | 消息正文。 |
| `is_bold` | boolean |  | 标题是否加粗。 |
| `is_external` | boolean |  | 为真时点击跳 url,url 必填;否则 content 必填。 |
| `is_popup` | boolean |  | 是否弹窗显示。 |
| `is_red` | boolean |  | 标题是否标红。 |
| `is_show` | boolean |  | 是否显示。 |
| `sort` | integer |  | 排序值(小的在前)。 |
| `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 |  | 消息正文。 |
| `count` | integer |  | 未读消息数。 |
| `created_at` | string |  | 创建时间 (只读) |
| `id` | integer |  | 记录 ID (只读) |
| `ids` | integer[] |  | 为空表示发给自己的全部已读。 |
| `is_bold` | boolean |  | 标题是否加粗。 |
| `is_external` | boolean |  | 为真时点击跳 url,url 必填;否则 content 必填。 |
| `is_popup` | boolean |  | 是否弹窗显示。 |
| `is_red` | boolean |  | 标题是否标红。 |
| `is_show` | boolean |  | 是否显示。 |
| `items` | Message[] |  | 本页条目 |
| `read` | boolean |  | 是否已读。 (只读) |
| `site_id` | integer |  | 网站 ID (只读) |
| `sort` | integer |  | 排序值(小的在前)。 |
| `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 为真时点击跳转的链接。 |