AgentBus EML 处理记录与详情对接

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

页面行为

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

默认日期是酒店时区的今天，只可选今天或近7天，按系统接收时间倒序。
仅提供发件人搜索、“只看异常”快捷开关和刷新。正常进入人工业务处理不是系统异常。
点击详情仍留在当前模块，复用 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`；近7天包含今天及之前6个酒店本地日。
`sender`	可选，去首尾空白后按发件人不区分大小写包含搜索，最长320字符。
`only_abnormal`	布尔值，默认 `false`；只过滤系统失败、超时或无法正常完成的记录。
`page`	从1开始，默认1。
`page_size`	默认20，范围1–100；当前页面提交30。

响应为 {items, total, page, page_size, read_at}。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	供详情与稳定业务判断使用，列表不增加状态列。
`sender`	string / null	来源的发件人展示值；缺失如实显示。

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

统一详情与日志

接口	返回与用途
`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，不轮询完整生命周期大对象。

11 KiB Raw Blame History