会话管理员
发布状态
网关、控制台及 0049_conversation_supervision.sql 迁移已于 2026 年 9 月 11 日 （UTC+8）部署至生产环境。本次是功能发布，不代表真实 Provider、SLA、支付、DPA 及价格等商业验收全部完成。
入口与权限
在对应环境控制台打开 Conversation Hub，路径为 /dashboard/conversations。 生产目标域名为 https://console.open4x.com，测试目标为 https://staging-console.open4x.com；目标地址不代表可用性承诺。
租户所有者可管理自己的会话。团队所有者可以在 Roles 中创建包含 conversation:supervise 的角色，再分配给授权管理员。此权限允许查看租户全部 会话和内部备注，不能授予作者或普通客户。不同租户仍然隔离。
浏览器访问租户级会话中心需要监管权限。普通客服和作者应使用参与者隔离的 Widget 或客户自己的授权后台；本次未提供“仅查看分配给自己的会话”的控制台。 现有服务端 Bridge Key 继续使用原有读写 Scope；监管接口额外要求 conversation:supervise。API Key 不得放入浏览器。
操作流程
| 操作 | 作用 |
|---|---|
| Observe／旁观 | 查看会话，不占用控制权 |
| Join／加入 | 记录加入操作，可参与回复，不独占 |
| Take over／接管 | 独占客服回复，暂停 AI 和其他客服竞争回复 |
| Transfer／转交 | 将控制权交给同团队有效管理员或租户所有者 |
| Release／释放 | 退出接管，保留并恢复原有分配流程 |
消息约每 3 秒通过增量 HTTP 查询同步，详情每 30 秒刷新，会话列表每 15 秒刷新。 这不是新增 WebSocket 协议，也不是实时送达 SLA。连接异常会显示提示；同步不会 清空草稿与收件人。可按会话 ID 或业务对象 ID 搜索并分页。列表按活动排序， 翻页过程中有新消息时可能发生位置变化，不能作为稳定导出快照。
公开回复默认选择具体参与者；内部备注保持内部可见。消息仍经过既有服务端 收件人校验与渠道投递规则。
接口与 SDK
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /v1/conversations/inbox?q=order-id&offset=0&limit=50 | 搜索、分页查询 |
| GET | /v1/conversations/{id}/supervision | 查询控制者、当前操作者及版本 |
| POST | /v1/conversations/{id}/supervision | 旁观、加入、接管、转交、释放 |
| GET | /v1/conversations/{id}/audit?offset=0&limit=50 | 查询监管审计 |
先查询状态，再提交，例如 { "action": "takeover", "revision": 0 }。 释放也需要最新 revision；转交额外传 target_user_id，它是 Open4X 用户 ID， 不是客户业务参与者 ID。版本过期或其他管理员已接管时返回 409，应刷新并由 操作者确认，不应盲目重试。参数错误返回 400，权限不足返回 403，会话不存在 或不属于当前租户返回 404。认证、限流沿用网关策略，轮询没有额外免限流待遇。
服务端 SDK 增加 getSupervision、supervise、listSupervisionAudit 及分页 listInbox。完整界面使用托管控制台；本次没有新增可嵌入浏览器的管理员组件。
保证与边界
- 控制权变更和审计原子写入；回复操作者由服务端产生，不能通过自定义 metadata 冒充。
- 控制台 JWT 只能以客服或内部备注身份发送；可信 Bridge 仍负责验证客户、作者身份。
- 接管期间，新 AI 或其他客服公开回复被拒绝；尚未领取的待投递消息暂停且不消耗重试 次数，释放后恢复。释放前应检查是否有已经过时的待发回复。
- Telegram 客服回复被拒绝时会生成
message.failed事件，包含code: conversation_taken_over、Provider 消息 ID 和retryable: false； 这类被拒绝的新回复不会在释放后自动重发。 - 已在途的 Provider 请求无法撤回。接管范围是 Conversation Hub，不包括独立 AI 任务 或其他旧版 Bot 接口。
- 用户、作者的消息与内部备注不因接管而暂停。
- 关闭浏览器不会自动释放；当前只有控制者可释放或转交。在删除其账号、撤销 Key 或移除角色前应先释放。失联控制权需运维审计恢复，本次未提供自助强制释放。
- 审计涵盖详情查看、旁观、加入、接管、转交、释放以及 API 回复和备注；它是业务数据库 日志，不是不可篡改的法律存证。单独读取每页消息不会另记一条查看日志。
- 租户账号清理会删除监管状态和审计。本次没有新增定时保留策略，合同保留周期仍需约定。
验收
检查跨租户隔离、团队角色、并发接管、旧版本冲突、备注隔离、同一消息 ID 重试、 待发 AI 消息暂停与恢复、草稿保留及手机布局。之后在 staging 验证真实 Widget／Telegram 双向链路，通过后再启用生产。