# 工单进度

v1 支持只读组织工单进度，使用 `tickets:read`。只处理通过组织一次性邀请创建的工单，不开放个人工单或工作人员全局队列。

## 已加入工单列表

```http
GET /v1/partners/{partner_id}/tickets?page=1
```

每页 20 条，按邀请创建时间倒序。返回 `data.items` 中的邀请元数据，且仅包含 `state=joined` 的邀请。每项的 `id` 为邀请 ID，`ticket_id` 为正式工单 ID；详情状态需要单独查询。

列表不是所有历史类型工单的全站目录，也不提供消息正文。组织网页中归档的已加入邀请仍可以出现在历史列表中，`archived_at` 会标记整理时间。

## 工单详情

```http
GET /v1/partners/{partner_id}/tickets/{invitation_id}
```

**路径末段使用邀请 ID，不是正式工单 ID。** 邀请 ID 是组织隔离和持久工单定位所使用的公开标识。

```json
{
  "ok":true,
  "data":{
    "id":"FORMAL_TICKET_ID",
    "invitation_id":"8f86690d-76d7-4e87-84d2-27b5fc8b6d41",
    "partner_id":"ORGANIZATION_ID",
    "game":"minecraft",
    "status":"open",
    "created_at":"2026-09-25T03:00:00.000Z",
    "updated_at":"2026-09-25T03:10:00.000Z",
    "message_count":3
  },
  "request_id":"req_EXAMPLE"
}
```

| status | 含义 |
| --- | --- |
| `open` | 等待工作人员处理或回复 |
| `waiting_user` | 等待用户或发起方回应 |
| `resolved` | 工单已解决 |

尚未加入时返回 `409 PLAYER_NOT_JOINED`。邀请不存在、属于其他组织或工单关联校验失败时，不会返回会话内容。

## 工单关闭不等于查端通过

`resolved` 只描述会话状态。它不能推导出 `clean`、`warning` 或 `cheating`。查端结果以 [记录接口](/records/) 返回的正式记录为准。

v1 事件中的工单 ID 与记录 ID 是不同命名空间。当前没有可供第三方依赖的一对一自动关联字段；不要通过相似名字或时间擅自认定某条记录属于某个工单。应用需要明确关联时，应在自己的业务流程中由授权人员确认记录 UUID。

## 同步建议

优先接收 `invitation.joined`、`ticket.message.created`、`ticket.status.updated`。收到事件后重新读取进度，以最新状态为准。通知可能重复或乱序；`message_count` 是当前可见的非系统消息数量，不应被当作严格单调递增的业务流水号。

没有 Webhook 时，可每 30–60 秒查询正在处理的工单，给请求加入随机偏移，并遵守所有密钥合计限额。已解决工单降低轮询频率。API 不提供会话回复、关闭、重开、附件或远程信息操作。