Wyndham-RSVN-0918/docs/project/frontend-backend/agentbus-eml-records-integration-guide.md

AgentBus EML 处理记录与详情对接

本文件说明 2026-09-08 已批准的统一处理记录改造的页面与接口契约。它承接 ADR-032通知专用规则和 ADR-034的 FRESH 回放投影边界。代码实现、实际运行环境加载和最终验收是不同事项；本文不证明环境已经切换或真实邮件已完成验收。

2026-09-10修订：历史、分页与永久保留CR增加近三个月、全部历史、分页及成功/失败/处理中结果列，并取消日志期限。本文描述目标实现，统一加载状态见当前工作记录。

页面行为

/agentbus/eml-replay 顶部保留“处理记录”和“手动上传测试”两个页签，默认进入处理记录。列表为系统接收时间、来源、发件人、耗时、处理结果、查看详情六列；来源显示“AgentBus真实邮件”或“手动上传”。处理结果为成功、失败或处理中，正常人工业务结果属于成功。不展示主题、阶段、来源/状态筛选、统计卡片或人员跟进信息。

• 默认日期是酒店时区的今天，可选今天、近7天、近三个月、全部历史，按系统接收时间倒序。每页30条，显示当前页和上一页/下一页，返回详情前的筛选与页码保存在URL。
• 仅提供发件人搜索、“只看异常”快捷开关和刷新。正常进入人工业务处理不是系统异常。
• 点击详情仍留在当前模块，复用 AgentBusReplayTraceWorkspace 的阶段、输入输出、错误、日志与复制导出；不新增顶部摘要，不跳转待处理任务或预订记录。
• 新详情通过 record_id 保存身份；date_range、sender、only_abnormal 和分页条件保存在 URL，返回时保持条件并刷新。历史 replay_id 仍可恢复，已执行运行转入对应 record_id=replay-{id}；未执行的预览继续打开上传预览。
• 手动上传复用选择、预览、二次确认和执行。预览不进入处理记录；执行提交后直接打开本次详情，列表在下次读取时显示该上传记录。

统一只读列表

GET /api/system/debug/agentbus-eml-records

查询参数	含义与约束
hotel_id	可选；使用认证用户有权访问的酒店，未传时按现有酒店上下文解析。
date_range	TODAY（默认）、LAST_7_DAYS、LAST_3_MONTHS、ALL；近7天包含今天及之前6个酒店本地日；近三个月从当地日期向前3个自然月同日零点开始；全部历史无下界。
sender	可选，去首尾空白后按发件人不区分大小写包含搜索，最长320字符。
only_abnormal	布尔值，默认 false；只过滤系统失败、超时或无法正常完成的记录。
page	从1开始，默认1。
page_size	默认30，范围1–100；当前页面提交30。

响应为 {items, total, has_next, page, page_size, read_at}。筛选后扫描到下一页首条即停止；有下一页时total=null，无下一页时返回已知准确总数。翻页使用has_next，不强制计算全部历史总页数。read_at 是本次读取的统一截止点。所有时间点均为带 Z 的 ISO 8601 UTC，页面按酒店时区格式化。

行字段	类型	含义
record_id	string	source-{SourceMessage ID} 或 replay-{Replay ID}，浏览器不得把长整数转成 JavaScript number。
source_kind	AGENTBUS / MANUAL_UPLOAD	自动收件或手动上传执行。
replay_id	string / null	仅手动上传存在。真实收件不新建持久化 Replay。
source_message_id	string / null	已落 Inbox 的来源消息身份；早期上传失败可以为空。
processing_run_id	string / null	已验证酒店及来源关联的系统处理运行。
received_at	UTC时间	自动收件取 Inbox 系统创建时间；上传取 EML 进入系统的创建时间。均不使用邮件发送日期或邮件头接收时间。
started_at / completed_at	UTC时间 / null	系统开始及结束时间。处理中 completed_at=null。
duration_ms	number	已结束为开始至结束；处理中为开始至 read_at。页面直接展示本次读取值，不为列表另设计时器。
terminal	boolean	系统处理已经结束；不等待员工确认任务或已知悉通知。
abnormal	boolean	最终系统异常。正常人工业务处理不属于异常；最终系统失败被业务复核接住时仍保留真实失败证据。尚可恢复的处理中记录不计最终异常。
status / result_disposition	string / null	供详情使用；列表以terminal=false显示处理中，终态按abnormal区分失败/成功，不按人工业务处置码染红。
sender	string / null	来源的发件人展示值；缺失如实显示。

列表聚合已有 Replay 和 SourceMessage/Processing Run，只读且不推进处理状态。仅预览被排除，上传关联的 SourceMessage 不重复显示成真实邮件；列表不返回主题、正文、附件地址或 Agent 输入输出。记录及关联日志永久保留，酒店时区缺失或无效时明确报错，不能按服务器时区猜测“今天”。

统一详情与日志

接口	返回与用途
GET /api/system/debug/agentbus-eml-records/{recordId}	{record, replay}；真实邮件 replay=null，手动上传 replay 为既有 Replay 详情格式。只读取，不触发旧 Replay 状态写回补偿。
GET /api/system/debug/agentbus-eml-records/{recordId}/trace	沿用现有 Trace 索引，包括 stages[]、起止时间、耗时、terminal 与 refresh_after_ms。
GET /api/system/debug/agentbus-eml-records/{recordId}/trace/stages/{stageKey}	沿用单阶段详情、输入输出、错误、证据、Agent decision 和 provider exchange。
GET /api/system/debug/agentbus-eml-records/{recordId}/lifecycle-log	沿用 agentbus-processing-lifecycle-log-v2，按需读取完整生命周期及公开返回 journal。

手动上传通过已有 Replay 关系读取；自动邮件通过 SourceMessage 及其当前关联 Processing Run 读取同一套证据与聚合器，Trace/单阶段/lifecycle 响应中的 replay_id 为 null。原 /api/system/debug/agentbus-eml-replays/{replayId} 及其详情、日志路径保留历史读取能力。

真实收件没有保存的 EML 解析或材料预处理快照保持 UNAVAILABLE，并给出 SOURCE_INGEST_TRACE_NOT_CAPTURED，不能凭处理终态补造成功。已有完整来源 frame、Layer1–6、阶段错误与公开返回仍按实际保存情况读取。

阶段与生命周期读取遵守权限、酒店、SourceMessage、Processing Run 关联校验；无权、关联失效、查询失败均明确返回错误，不再按旧期限拒读。完整 journal 无法读取时仍返回 503 / SUPERAGENT_RESPONSE_JOURNAL_UNAVAILABLE，不生成看似完整的残缺日志。两个日志按钮使用同一 JSON 字符串；运行更新、切换或离开详情后不复用陈旧日志内容。

这里是 SYSTEM_DEBUG_EML_RUN 受控开发排障模块。普通员工页面的最小正式 Trace 仍使用 /api/reservation/booking-processing-runs/v2/{runId}/trace 和 RESERVATION_TASK_READ，两类读取边界不能混用。

通知专用邮箱的完整测试

opfit.liantaitravel@gmail.com 的准确规范化识别由后端现有通知规则负责。普通 GENERAL_NOTIFICATION 结果并不证明命中专用邮箱；前端使用后端 notification_only_sender、阶段 NOTIFICATION_ONLY_SENDER 或同名兼容模式/公开 provider exchange 标记，禁止另建邮箱白名单。

新上传仍提交 FRESH_DELIVERY + REQUIRE_REAL_L3_L5。该规则内明确豁免通知不适用的 Parser/Agent 阶段，其他固定渠道仍遵守真实双 Agent 门槛，不启用历史兼容执行。

现有步骤	通知专用分支
邮件接收、Layer1、Layer2	保存邮件和附件关联，完成来源与材料准备；不读取预订表格内容。
Layer3 Deterministic Parser / Parsing Agent	SKIPPED，灰色“已跳过”，解释通知专用规则。
Layer4 Context / Rate-Room	SKIPPED，不补造预订上下文或价格处理。
Layer5 Booking判断与结果组装	整体有真实结果；其中 Booking Agent 显示已跳过，通知结果生成显示完成并生成1条其他通知。
Layer6 Validation	校验现有通知结果，不要求预订姓名、团号或房型字段。

Layer5 以 execution_kind=DETERMINISTIC、compatibility_mode=NOTIFICATION_ONLY_SENDER 描述真实执行，provider_exchange 给出 notification_only_sender=true、booking_agent_executed=false、provider_status=SKIPPED、system_acceptance_status=SUCCEEDED、notification_count=1，不伪造 Provider 调用成功。

系统成功保存并完成员工“其他通知”投影后才进入处理完成；投影仍在等待时详情继续更新，投影失败进入系统异常。员工是否点击已知悉不影响系统终态。成功后默认展示 Layer5；用户已手动选择其他阶段时不强行切回。通知不建立预订订单、任务卡、人工处理项或预订记录。

原 capabilities 新增两个只读布尔字段：

• preview_ready：预览所需功能开关与对象存储已就绪，不依赖双 Agent。
• notification_execution_ready：通知所需真实入站、对象存储、Booking PostgreSQL 与 V2 authority 已就绪，不依赖 Parsing/Booking Agent 配置。

原预览/运行详情新增 notification_only_sender。执行按钮仅在该字段为 true 时采用 notification_execution_ready，其他来源继续采用 strict_execution_ready；后端执行时再次校验已保存 frame 与业务适用性，前端布尔值不构成放行依据。不能为通过测试修改 Agent、Profile、版本绑定或 Secret。

刷新与取消

2026-09-09按日志准确性CR纠正：中途Parsing等步骤失败、后续Booking仍执行时，记录可以abnormal=true，但terminal=false、completed_at=null，继续原10秒详情刷新。全部自动步骤结束后，列表、Trace和生命周期日志使用实际自动结束时间；员工稍后确认、查看详情或其他updated_at变化不能延长自动处理耗时。通知专用来源仍以通知投影的实际完成为准。

阶段provider_exchange的raw_answer_persisted按同阶段、调用、attempt及平台session/run的已保存最终回答核实；旧快照不能借用另一调用的用量或保存状态。tokens各项允许null，表示未取得；真实0保留。阶段轮询只读取保存记录的身份元信息，完整正文仍仅在主动读取完整日志时获取，不新增轮询内容或页面状态标签。

列表不定时轮询，仅首次进入、上传页签切回、浏览器重新获得焦点/恢复可见、刷新按钮、详情返回或查询条件变化时读取。相邻 focus/visibility 事件在已有读取进行中时合并，不重复派请求。

只有当前打开且未结束的详情每10秒更新。每次 Trace 的 terminal 是详情停止依据，不能让初次读取的旧 Replay PROCESSING 或 asynchronous 标记覆盖新终态；完成、失败、离开、组件卸载或酒店/记录切换后停止定时器并取消/忽略晚响应。同一详情只保留一个轮询入口，不在页面外层再轮询 Replay，不轮询完整生命周期大对象。