# 通用约定

# 通用约定

## 标识符与时间

资源 ID 是带类型前缀的不可变字符串，例如 `project_…`、`session_…` 和 `work_…`。时间使用 ISO 8601 字符串。客户端应把 ID 当作不透明值，不要依赖长度或自行解析业务含义。

## 幂等请求

创建项目、创建会话和重建 WorkSet 等可能重试的写操作需要 `Idempotency-Key`。同一个业务动作重试时复用原值，不同动作必须使用新值。

```http
Idempotency-Key: 018f6d7e-0dd1-7b67-9f65-2ec3fd436ef0
```

上传音频分块还必须提供 `X-CapWorks-Chunk-ID`。服务端会在响应中标明该分块是否为重复提交。

## 错误响应

业务 API 使用稳定的错误结构：

```json
{
  "error": {
    "code": "project_not_found",
    "message": "Project not found.",
    "retryable": false,
    "requestId": "request_..."
  }
}
```

自动重试前必须同时检查 HTTP 状态和 `retryable`。验证错误、权限错误和幂等键冲突不应盲目重试。

## 实时连接

WebSocket 连接使用现有登录会话。会话和成果协作通道支持 `resume` 消息，客户端应保存最后收到的 sequence，并在断线重连时请求补发。实时草稿更新携带客户端生成的 `updateId`，用于重复提交去重。完整消息联合类型见[实时 API](/api/realtime)。