通用约定
Product HTTP 的地址、JSON、标识、游标和重试规则。
以下规则适用于当前公开的 Product HTTP 接口。
地址与格式
| 约定 | 行为 |
|---|---|
| Base URL | 本地示例为 http://127.0.0.1:5001；所有路径从 / 开始 |
| 请求 | POST 使用 UTF-8 JSON；/route 使用 GET 查询参数 |
| 响应 | JSON；不同端点没有统一响应信封 |
| UID / Channel ID | 由业务系统维护的字符串 |
| Channel | 由 channel_id 与 channel_type 共同标识 |
| Message sequence | 仅在单个 Channel 内有序 |
调用方应先检查 HTTP 状态，再按端点 Schema 解析响应。不要强行套用统一的 {data,error} 类型。
标识与游标
uid是业务身份，不是昵称、连接 ID 或设备 ID。- 个人 Channel 的客户端视图使用对端 UID。
message_seq是 Channel 内游标；JavaScript 应优先保留message_idstr，避免大整数精度损失。next_cursor是不透明值，必须原样回传，直到done=true。
重试
| 操作 | 规则 |
|---|---|
/route | 网络失败或临时 5xx 可退避重试 |
/user/token | 只重试同一身份意图，不要循环生成新 Token |
/channel/messagesync | 使用同一游标重试，并容忍与实时投递重复 |
| Channel 变更 | 仅在业务意图仍有效时重试；谨慎使用 reset 和 remove-all |
/conversation/list | 原样传递 next_cursor，只以 done=true 结束 |
/conversation/retry | 只重试返回的有界 unresolved 键 |