th-hotel-simple/docs/project/requirements/M012-processing-run-lifecycle-log-v1.md

M012 Processing Run 全生命周期日志 V1（现行输出已升级 V2）

项	内容
状态	lifecycle V2 与完整公开返回 journal 已实现并完成定向验收；新邮件真实记录待下一次回放产生
确认日期	2026-08-17
适用页面	开发测试 AgentBus EML 全流程回放页
数据根	一次 replay 对应的 Processing Run

1. 背景

全链路测试人员需要把一封邮件从接入、材料处理、事实解析、上下文组装、Booking Business Agent、确定性校验到人工确认边界的过程完整取出，用于复盘某一次处理为什么失败。当前页面可以逐阶段查看，但缺少一份可一次复制或导出的统一数据；SuperAgent 已返回的公开运行轨迹也未在两类 Agent 主链中完整保留。

2. 目标

• 以 Processing Run 为主线，输出一份按阶段和时间排序的全生命周期日志。
• 每个阶段记录时间、状态、耗时、输入、输出、问题、证据、Agent 公开轨迹及安全错误信息。
• Parsing Agent 和 Booking Business Agent 调用 SuperAgent 时携带 include_trace=true，按实际接收顺序、原内容保存 平台返回的每一条公开事件和客户端交给业务解析器的完整最终答案。
• 回放页对同一份日志数据提供“复制完整日志”和“导出完整日志”两个操作。
• 日志按需生成和读取，不建设独立日志平台、不生成诊断包、不复制第二套业务事实。

3. 非目标

• 不记录或推导 SuperAgent 没有返回的隐藏思考；平台确实返回的公开事件（包括公开推理内容）按原内容记录。
• 不保存 API Key、Cookie、数据库密码、完整工具原始入参或其它 Secret。
• 不复制出站请求正文、请求头或调用凭据；完整返回 journal 只记录 Provider 实际返回内容。
• 不修改 Parser、Layer 5 业务判断、Layer 6 校验、人工确认语义或 PMS/Opera 边界。
• 不把严格回放中预留的 Layer 7 伪装为已经执行。
• 不启用生产 PostgreSQL、Agent provider、worker 或其它生产开关。

4. 用户与场景

• 全链路测试人员：在某次 EML 回放页复制或下载完整 JSON，交给协作人员定位故障阶段。
• 开发排查人员：通过统一的 replay、processing run、provider run 和阶段时间信息，还原一次处理。
• 普通酒店员工：本需求不改变正式业务工作台，也不向普通员工页面增加技术日志。

5. 核心概念守门

• Processing Run 是一次邮件处理生命周期的主线；replay 只是开发测试入口。
• Layer 5 生成的业务目标仍由现有 Booking Agent 输出和校验结果表达，日志不成为新的业务权威来源。
• SourceMessage、Order、Order Task 和 Task Card 的既有含义不变。
• SuperAgent 公开轨迹是运行证据，不是业务事实，也不替代 Layer 6 校验。

6. 后端契约

• 新增只读调试接口：GET /api/system/debug/agentbus-eml-replays/{replayId}/lifecycle-log。
• 沿用 SYSTEM_DEBUG_EML_RUN 权限、酒店隔离、replay 归属和保留期校验。
• 返回一个版本化 JSON 对象，包含 replay/run 标识、起止时间、总耗时和按阶段排序的 entries。
• 每个 entry 复用现有 trace stage 快照及 Booking PostgreSQL 只读审计数据；不新增“全生命周期事实表”，但由 PostgreSQL V13 新增共用追加式 Provider response journal，作为 Parsing/Booking 的通信运行证据。
• 返回契约为 agentbus-processing-lifecycle-log-v2。Parsing/Booking 相关 entry 的 provider_exchange 给出 journal contract/version/count，provider_response_journal[] 按 attempt、delivery_sequence 返回；每条包含记录类型、Provider 事件编号/ 时间、系统接收时间、session、run、execution、invocation、attempt、原始内容及其 hash。
• Parsing Agent 与 Booking Business Agent 的 Open API 配置必须为 include_trace=true；显式关闭时启动/配置校验 fail closed。共享 transport 仍为旧 Field Recovery 保留 no-Trace 兼容，不能借此绕过两条主线门禁。
• Trace 模式只有收到公开 run.completed(status=success) 与顶层 end 才可成功；message.final 只提供本次 最终回答，不能替代完成证据。Provider 返回内容不做摘要、截断、脱敏或去重；重连造成的重复投递也按实际接收 顺序保留。出站 API Key、Authorization、Cookie、CSRF、数据库密码和请求头不进入 journal。
• session response、公开 SSE event、恢复 run snapshot、HTTP 错误正文及最终答案都使用同一追加式记录；timeout、 断流和本地校验失败时保留已收到部分。journal 写入失败则 Agent attempt fail closed。
• lifecycle 查询无法读取 journal 时返回 503 / SUPERAGENT_RESPONSE_JOURNAL_UNAVAILABLE，不能返回看似完整的 残缺日志。
• 读取一次完整日志只记一条安全审计，不因聚合多个阶段重复产生十五条审计。

7. 前端契约

• 在开发回放页的全链路轨迹区域增加“复制完整日志”和“导出完整日志”。
• 两个操作必须调用并使用同一接口、同一对象和同一 JSON 序列化结果；导出只是把该字符串保存为 .json。
• 日志按用户点击时获取，避免页面轮询反复下载完整阶段数据。
• 复制/导出成功或失败需给出简短反馈；不新增导出包、压缩包或第二种报告格式。

8. 测试与 smoke

• 后端覆盖权限/酒店隔离、阶段顺序、时间字段、阶段详情合并、原内容/原顺序、重复投递、部分失败记录和 journal 不可用时 fail closed。
• SuperAgent 两类专用客户端覆盖 include_trace=true；两条 Agent 主线覆盖 run/execution/invocation/attempt 和 final answer 关联。
• 前端覆盖两按钮复用同一日志数据、复制内容和下载内容一致。
• 使用合成或已脱敏 fixture；不得把真实邮件、凭据或旅客信息写入仓库。
• 只做与本变更直接相关的定向测试，不宣称本地合成测试等于真实完整链路通过。

9. 需求追踪表

需求项	后端状态	前端状态	测试状态	文档位置	当前状态
SuperAgent 完整公开返回记录	Completed	N/A	Covered（后端合并聚焦 65 项）	本文第 6 节、独立 CR、ADR-017	Complete
统一生命周期日志接口	Completed	Completed	Covered（后端聚焦测试＋本机接口 smoke）	本文第 6–7 节	Complete
同数据复制与导出	N/A	Completed	Covered（前端全量 45 files / 348 tests＋typecheck）	本文第 7 节	Complete
权限与凭据边界同步	Completed	N/A	Covered（配置门禁、关联校验、凭据排除）	本文第 3、6 节	Complete

10. 未确认问题

无。本版范围已由产品确认；若后续要求把该能力开放到正式员工工作台、扩大保留期或记录出站请求内容，必须另行 确认权限与数据范围。

实现说明：Parsing 与 Booking 当前都由 V13 journal 保存逐 attempt 的原始返回记录，原有 execution/invocation 聚合审计继续保留兼容但不再是完整返回的权威来源。旧 replay 不会被反向补写；只有本实现启用后真正发出的 Agent 调用才会产生 journal。获准测试 PostgreSQL 已迁移到 V13，本地 8082 已就绪；尚未由本次实现主动触发新 EML，不能把 合成测试或旧 replay 的 0 条记录误报为真实完整链路通过。