## 工单 (`tickets`)

管理端处理用户工单:列表、详情、回复、内部备注、关闭与重开。

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

### GET `/api/v2/tickets`

列出工单 · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `status` | string |  | 标签页:open 待处理(用户端为处理中)、replied 待用户确认(用户端为待您确认)、closed 已关闭;不传 = 全部。 可选值: ["open","replied","closed"] |
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
| `q` | string |  | 搜索:纯数字按编号精确,否则按标题子串。 |
| `urgent` | boolean |  | 只看紧急(true)或只看一般(false)。 |
| `category` | string |  | 按分类过滤:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他;逗号分隔可多选。 |
| `site_id` | integer |  | 按关联网站或转发规则的 id 过滤。 |
| `created_from` | string |  | 提交时间起(含)。 |
| `created_to` | string |  | 提交时间止(不含)。 |

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

### POST `/api/v2/tickets`

代用户提交工单 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `body` | string | 有 | 正文,最长 2000 字符。 |
| `category` | string | 有 | 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。 可选值: ["site","cert","security","l4","billing","other"] |
| `image_ids` | integer[] |  | 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。 |
| `notify` | boolean |  | 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。 |
| `rel_id` | integer |  | 关联对象 id,0 = 无。 |
| `tenant_id` | integer | 有 | 提交用户(租户)id。 |
| `title` | string | 有 | 标题,最长 60 字符。 |
| `urgent` | boolean |  | 是否紧急。 |

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

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

工单详情 · 鉴权: 仅管理员

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

### PATCH `/api/v2/tickets/{id}`

改工单紧急程度或分类 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `category` | string |  | 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。 可选值: ["site","cert","security","l4","billing","other"] |
| `urgent` | boolean |  | 是否紧急。 |

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

### POST `/api/v2/tickets/{id}/close`

关闭工单 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `note` | string |  | 选填:作为最后一条客服回复,最长 2000 字符。 |
| `notify` | boolean |  | 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。 |

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

### POST `/api/v2/tickets/{id}/notes`

加内部备注 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `body` | string | 有 | 正文,最长 2000 字符。 |

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

### POST `/api/v2/tickets/{id}/reopen`

重开工单 · 鉴权: 仅管理员

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

### POST `/api/v2/tickets/{id}/replies`

客服回复 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | string |  | wait_user 回复并置等待用户确认、close 回复并关闭、none 只回复;缺省 wait_user。 可选值: ["wait_user","close","none"] |
| `body` | string |  | 正文,最长 2000 字符。 |
| `image_ids` | integer[] |  | 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。 |

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

工单对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | string |  | wait_user 回复并置等待用户确认、close 回复并关闭、none 只回复;缺省 wait_user。 可选值: ["wait_user","close","none"] |
| `author_avatar_ver` | integer |  | 作者头像版本,每次上传变大;没有头像或不给 author_id 时缺省。 |
| `author_id` | integer |  | 作者的用户 id,供取头像用。管理端的 user / staff / note 消息都有;用户端只在用户自己的消息上带(客服与系统记录不给,不暴露管理员信息)。 |
| `author_name` | string |  | 作者名。管理端:用户名或管理员名;用户端:客服与系统记录一律「客服」。 |
| `auto_close_at` | string |  | 自动关闭的到期时间:仅「待用户确认」且开了自动关闭时有值(答复时间 + 设置天数,改设置后按新值);否则为空。列表药丸「N 天后自动关闭」据此算。 |
| `body` | string | 有 | 正文,最长 2000 字符。 |
| `can_rate` | boolean |  | 仅用户端:已关闭或待确认、没评价过且评价开关开着(待确认单据此决定「已解决」弹框出不出评价区)。 |
| `can_reopen` | boolean |  | 仅用户端:已关闭且还在重开期限内。 |
| `category` | string |  | 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。 可选值: ["site","cert","security","l4","billing","other"] |
| `close_reason` | string |  | 关闭原因:user 用户、staff 客服、timeout 超时自动关闭;未关闭为空。 可选值: ["","user","staff","timeout"] |
| `closed_at` | string |  | 关闭时间;未关闭为空。 |
| `created_at` | string |  | 创建时间 |
| `created_by_admin` | boolean |  | 是否管理员代用户提交;仅管理端有值。 |
| `event` | string |  | 系统记录的事件:urgent 改紧急、category 改分类、closed 关闭、reopened 重开、timeout 超时关闭、reply 回复引起状态变化(from/to 为旧/新状态)、submitted 用户提交、submitted_for 管理员代用户提交(to 为用户名);其他消息为空。 可选值: ["","urgent","category","closed","reopened","timeout","reply","submitted","submitted_for"] |
| `from` | string |  | 系统记录的原值。 |
| `id` | integer |  | 工单编号。 |
| `image_ids` | integer[] |  | 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。 |
| `images` | TicketImage[] |  | 附图。 |
| `kind` | string |  | user 用户、staff 客服、note 内部备注(只管理端)、system 系统记录。 可选值: ["user","staff","note","system"] |
| `last_at` | string |  | 最后一次有消息或状态变化的时间。 |
| `last_kind` | string |  | 最后一条消息的发送方:user 用户、staff 客服,空 = 没有消息。用户端列表据此给客服消息加「客服:」前缀。 可选值: ["","user","staff"] |
| `last_snippet` | string |  | 最后一条客服/用户消息的摘要(去换行折空白,最长 80 字符,超出以省略号结尾);内部备注与系统行不算;没有消息为空。 |
| `messages` | TicketMessage[] |  | 消息串,按 id 升序;用户端没有 note。 |
| `msg_count` | integer |  | 客服/用户消息条数(含提交时的首条描述,不含内部备注与系统行)。 |
| `new_count` | integer |  | read_pos 之后对方新发的条数。 |
| `note` | string |  | 选填:作为最后一条客服回复,最长 2000 字符。 |
| `notify` | boolean |  | 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。 |
| `rating` | string |  | 评价:good 满意、normal 一般、bad 不满意,空 = 未评。 可选值: ["","good","normal","bad"] |
| `rating_enabled` | boolean |  | 仅用户端:工单设置里的评价开关(关着时已解决弹框不显示评价区)。 |
| `rating_note` | string |  | 评价附言。 |
| `read_pos` | integer |  | 本端打开前的已读位置(消息 id);新消息分隔线画在它之后。 |
| `rel_id` | integer |  | 关联对象 id,0 = 无。 |
| `rel_name` | string |  | 关联对象名称(提交时的快照)。 |
| `rel_type` | string |  | 关联对象类型:site 网站、stream 转发规则,空 = 无。 可选值: ["","site","stream"] |
| `reopen_until` | string |  | 仅用户端:已关闭时,可重开的截止时间。 |
| `status` | string |  | open 待客服处理、replied 等用户确认、closed 已关闭。 可选值: ["open","replied","closed"] |
| `tenant_id` | integer |  | 提交用户(租户)id。 |
| `title` | string |  | 标题,最长 60 字符。 |
| `to` | string |  | 系统记录的新值。 |
| `unread` | integer |  | 对方新发、本端还没读的消息条数。 |
| `urgent` | boolean |  | 是否紧急。 |
| `user` | object |  | 提交用户信息;仅管理端有。 |
| `user_name` | string |  | 提交用户名;只管理端有值。 |
