trade-message-center/docs/onetalk-summary-internal-api.md

OneTalk 内部纪要读取接口

本文交付给 trade-mind 所有者。它描述 Center 已发布的内部 Docker listener；Mind 代码和部署改动不在本仓库。

前提与安全边界

Center 与 Mind 容器必须运行在同一 Docker daemon，并共同加入名为 trade-message-center-summary 的 Docker internal 网络。该网络的成员资格是唯一访问控制：加入网络的任意容器可读取任意已知 channelAccountId + conversationId 的摘要历史；它不提供 workspace、用户、账号或会话级授权，也不防护 Docker socket 持有者或宿主机 root。

Center 运行在仅供其公网发布与 egress 的 trade-message-center-public bridge 网络，并额外挂载 summary internal 网络；其它业务容器不得加入前者来访问 Center。Center 仍通过宿主机发布 public 7878；内部 7777 绝不配置 Docker --publish 或 Compose ports。EXPOSE 7777 只是镜像元数据，不会对外发布端口。

Mind 请求

GET http://trade-message-center:7777/api/bright/onetalk/accounts/:channelAccountId/conversations/:conversationId/messages?fromSentAtMs=:inclusiveEpochMs&toSentAtMs=:exclusiveEpochMs&cursor=:opaqueCursor&limit=:1to100

• fromSentAtMs 与 toSentAtMs 必填，均为 safe integer，窗口为 [fromSentAtMs,toSentAtMs)，且前者必须小于后者。
• cursor 仅可原样回传上一页 nextCursor；limit 默认为 50，范围 1..100。
• 不发送 Cookie、Authorization、X-Mind-Purpose 或 X-Mind-Workspace-Id。Center 不读取这些头，也不会回调 Mind 的授权接口。
• 成功响应只含 conversationId、语义化 messages 与 page；没有 scope、workspaceId、mindUserId、binding 或授权版本。Mind 以自己的调用上下文关联 workspace。
• historyComplete=false 时返回 503 { error: { code: "history_incomplete" } } 和 Retry-After: 30。其它分页、内容投影和错误码与 Bright OneTalk 会话读取 API 的消息读取契约一致。

部署与验收

Center 的 release workflow 会创建或验证该网络为 internal，并在启动后将容器 trade-message-center 接入其中。Mind 部署所有者需要在同一 Docker daemon 执行等价操作：

docker network connect trade-message-center-summary <mind-container-name>

发布后至少验证：

docker network inspect trade-message-center-summary
docker network inspect trade-message-center-public
docker port trade-message-center
docker exec <mind-container-name> \
  curl -fsS 'http://trade-message-center:7777/api/bright/onetalk/accounts/<account>/conversations/<conversation>/messages?fromSentAtMs=<from>&toSentAtMs=<to>&limit=1'

docker port trade-message-center 不得出现 7777。若 Center 回滚到不含内部 listener 的旧镜像，Mind 必须同时回滚其 base URL/请求头；共享网络不应在回滚时删除。