th-hotel-simple/docs/project/requirements/M012-superagent-complete-public-response-journal-change-request-v1.md

M012 SuperAgent 完整公开返回记录 Change Request V1

项	内容
状态	已实现并完成聚焦验收；等待下一封新 EML 产生真实记录
日期	2026-08-17
批准来源	产品明确要求测试与生产均“SuperAgent 返回什么，信息系统就记录什么”
适用主线	Fixed-channel Parsing Agent、Booking Business Agent V2

1. 背景

现有 Processing Run 生命周期日志只保存经过脱敏、限长的公开 Trace 摘要，并明确丢弃 message.delta、 message.final 和 Booking V2 最终回答。真实 QBD 回放在 Parsing Agent 等待约四分钟后失败；SuperAgent run 后来完成，但信息系统没有保留逐事件原文、逐次尝试和最终答案，因此无法判断耗时发生在哪个公开步骤，也无法从 现有日志还原 Provider 实际返回。

2. 目标

• Parsing Agent 与 Booking Business Agent 的每次 Provider 尝试，按实际接收顺序保存所有公开 SSE 事件。
• 保存客户端实际交给本地 decoder 的完整最终答案。
• 每条记录包含本地顺序号、Provider event id、外层/内层事件类型、Provider 原始时间、系统接收时间、session、 run、Agent 阶段、execution、invocation 和 attempt。
• 事件内容与最终答案按 SuperAgent 返回原文保存，不摘要、不截断、不脱敏、不省略。
• timeout、断流、重连、Provider 失败和本地校验失败时，保留此前已经收到的部分记录。
• 生命周期 JSON、页面复制和导出读取同一份完整持久记录。
• 该记录能力在测试与生产使用同一代码和数据库结构，不依赖 Debug-only 写入开关。

3. 非目标

• 不推导或伪造 SuperAgent 没有返回的隐藏思考。
• 不保存出站 API Key、Authorization、Cookie、CSRF、数据库密码或请求头；这些不是 Provider 返回内容。
• 不保存 SuperAgent 请求正文的第二份副本。
• 不改变 Parser、Layer 4、Layer 5、Layer 6、人工确认、Prompt/Skill、Agent Profile 或业务开关。
• 不调用 PMS/Opera，不接入 LIANTAI_FIT。
• 不建设独立日志平台、诊断包、搜索集群或第二种导出格式。

4. 数据与顺序契约

新增 Booking PostgreSQL 追加式 journal。每一行只表示一次实际收到的 Provider 返回记录：

• SESSION_RESPONSE：创建 session 的原始响应。
• PUBLIC_EVENT：公开 SSE event 的原始 data 内容；重连重复投递也照实记录。
• RUN_SNAPSHOT：断流恢复期间读取到的 run 原始响应。
• HTTP_ERROR_RESPONSE：Provider 非 2xx 响应正文。
• FINAL_ANSWER：共享 transport 最终选定并交给业务 decoder 的完整答案。

本地 delivery_sequence 是同一 Agent execution/attempt 内的接收顺序。Provider event id 只作为原始标识，不能 替代本地顺序，也不能用于删除重连时的实际重复投递。原文以 TEXT 保存，JSONB 不能作为唯一原文载体。

5. 失败与一致性

• journal 采用小批量短事务追加；正常完成、timeout、断流和异常退出 Provider 调用时必须刷新尾部记录。
• journal 无法写入时，本次 Agent attempt 必须 fail closed，不能产生“业务成功但完整运行证据丢失”的结果。
• 历史运行不反向补写、不猜测；只有本变更启用后的真实调用才有完整 journal。
• journal 是运行证据，不是业务事实，不参与 Candidate、任务类型、Layer 6 校验或正式任务卡生成。

6. 读取与权限

• 现有 Debug AgentBus EML replay 生命周期接口升级为 V2，在 Parsing Agent 与 Booking Agent 阶段返回完整 provider_response_journal[]。
• 仍沿用 replay、酒店、SourceMessage、Processing Run、SYSTEM_DEBUG_EML_RUN 和保留期校验。
• 复制与导出继续复用同一接口对象和同一 JSON 字符串。
• 生产环境持续写 journal；本 CR 不把 Debug replay 页面开放给生产普通员工，也不扩大正式业务接口权限。

7. 验收

• SSE parser 测试证明所有外层事件按接收顺序回调，原始多行 data 不被 trim/改写，重连重复投递仍进入 journal。
• Parsing 与 Booking 主线测试证明 execution、invocation、attempt、session、run 和 final answer 正确关联。
• Repository 测试证明批量追加、顺序读取、原文 hash 与 Processing Run/酒店/SourceMessage 关联正确。
• 生命周期接口测试证明 Parsing/Booking 两阶段读取同一 journal，复制和导出无需新格式。
• 定向测试不得调用真实 SuperAgent、上传真实 EML 或调用 PMS/Opera；真实回放另行由测试人员触发。

8. 需求追踪

项目	后端	前端	测试	状态
追加式 Provider journal	已完成（PostgreSQL V13）	N/A	已覆盖	Complete
Parsing/Booking 逐 attempt 接入	已完成	N/A	已覆盖	Complete
生命周期 V2 完整读取	已完成	复用现有操作	已覆盖	Complete
文档与安全边界修订	已完成	N/A	N/A	Complete

实施验收：后端相关 65 项聚焦测试全部通过；前端 45 个测试文件、348 项测试与 typecheck 通过。获准测试 PostgreSQL 已迁移到 V13，当前本地 8082 进程已校验该版本并显示严格执行能力就绪。本次没有主动上传或重跑 真实 EML；历史运行不回填 journal，需由下一封新 EML 验证真实 Provider 返回。