th-hotel-simple/docs/project/requirements/booking-email-architecture-v0.4.md

Booking 邮件处理架构 v0.4

迁移状态（2026-08-13）：本版本仅用于旧 V4 读取和迁移回归。它曾配套的 CandidateDecision v1 正式契约 从未上线且已删除。新运行只以 v0.5、 contracts-v2 和 ADR-012 为准；不得依据本文件产生新业务结果。

项目	内容
文档状态	历史读取兼容；新写入已由 v0.5 取代
架构版本	booking-architecture-v0.4
契约版本	booking-contracts-v1
业务基线	BR00-BASELINE-1
范围终点	用户确认；不调用 PMS、Opera、付款或部门流转

1. 目的与替代关系

本架构把邮件获取、附件识别、固定渠道确定性解析、历史上下文、Booking Agent、校验和人工确认收敛为一条可追溯主线。它替代以附件 Parser 或旧 V4 入站模型为中心的实施方式。

早期 architecture-v0.3、M002 叙述和 M012 V0.1 实现记录只可用于迁移和回归，不能作为新功能实施依据。 新增实现必须使用 v0.5 与 contracts-v2；本文件不再指向或定义旧 CandidateDecision 契约。

2. 七层职责与边界

层	负责什么	输入	输出	不负责什么
1. 信息系统接入与编排	接收 AgentBus 邮件或手工 EML，建立幂等、处理批次与状态查询	AgentBus payload / .eml	SourceMessageEnvelope	不理解业务、不直接建最终任务
2. 材料预处理	分离 current/quoted history，列举附件、图片、工作簿结构和候选材料，保留证据引用	SourceMessageEnvelope	MaterialPackage	不把历史内容重复当作本次动作
3. 确定性 Parser + 字段恢复与本地组装	对适用固定渠道生成不可变来源观察与 AFTER/CURRENT facts；只将 UNRESOLVED+RECOVERABLE 字段送字段解析兜底 Agent，再由本地校验、依赖重算与投影形成统一有效事实视图	MaterialPackage	ParsedFactSet（含 ParserObservationSet）+ EffectiveFactView	不做 Rate/Room 目录映射，不让 Agent 重写整行，不做最终业务决定
4. Context Assembler + RateRoomResolver	按 Group Code、订单线索或会话定向读取当前态；并将 Layer 3 source_room_type/source_price 与版本化 Rate/Room 目录确定性解析	EffectiveFactView + 来源/历史线索 + Rate/Room 目录	ContextPackage（含 rate_room_resolutions）	不扫描全库、不让历史邮件重新触发动作、不回写 Layer 3 来源事实
5. 业务识别 / Booking Agent	合并 Layer 3 有效事实和 Context，形成候选业务决定；Parser 失败/不适用/歧义时使用受控最小 ParsedFactSet 分支	固定渠道：EffectiveFactView + ContextPackage；其他分支：最小 ParsedFactSet + ContextPackage	CandidateDecision	不下载附件、不直接读写数据库、不建最终任务、不调用 PMS
6. Validator 与人工确认准备	校验 schema、Catalog、证据、目标、生命周期、前置关系和确认必填项	CandidateDecision	ValidationResult、ConfirmationProjection	不绕过校验建卡、不执行外部业务动作
7. 用户确认	展示安全的关键参数、证据、阻断、可编辑字段和链接动作；冻结已确认参数与审计	ConfirmationProjection	CONFIRMED 记录	不调用 PMS/Opera，不改变付款或部门状态

2.1 信息系统与 Agent 的职责分界

• 信息系统拥有 SourceMessage、幂等、附件/证据存储、确定性 Parser、本地 Recovery 校验/组装、RateRoomResolver、Context 查询、Validator、数据库事务、确认 API 和审计。
• AgentBus既是邮件消息入口适配器，也是 Booking Agent 的承载平台；它不成为业务事实源。
• Booking Agent对固定渠道只消费最小化的 EffectiveFactView + ContextPackage；Parser 不适用等分支可消费最小 ParsedFactSet + ContextPackage，其中唯一的正文材料是 policy 脱敏、限长的 agent_input_material current excerpt。它不能自行扩大材料范围、下载附件、调用 PMS 或写任务表。
• Rate/Room 目录从 Layer 4 开始使用独立 catalog_version；Layer 3 只记录 Parser normalization catalog/version，不消费 207 行目录，也不生成 canonical Room Type 或最终 Rate Code。Booking Agent 只消费 Layer 4 的受控解析结果，不能自行重做目录映射。
• Name of Group、Group Name、Tour Code、Group Code 是固定渠道对同一团号的不同列名；第 3 层统一写入 group_code，第 4 层也只以该统一值定向查询，不能把列名差异制造成多目标。

2.2 Layer 3 固定渠道内部链路

Layer 3 固定为：Deterministic Parser → ParserObservationSet + AFTER/CURRENT facts → RecoveryRequestBuilder → 字段解析兜底 Agent → RecoveryPatchSet → 本地 RecoveryPatchValidator / dependency resolver / projector → EffectiveFactView。详细字段身份、状态、patch 校验和 overlay 规则只在唯一共用协调契约 ../../../../.planning/booking_completion_roadmap/fixed_channel_parser_recovery_contract_v2_discussion_draft.md 维护；本文只冻结层间边界，不复制第二套格式。

• parser_observations 是不可变来源观察，保存 BEFORE/AFTER/CURRENT、raw/normalized value、稳定 row/segment/room/field/evidence 身份及未解决原因；原 Parser facts 不被 Agent 改写。
• facts[] 只承载 Parser 首次确定的 AFTER/CURRENT 当前事实；BEFORE 只用于展示和审计。
• Recovery 只允许处理持久 UNRESOLVED+RECOVERABLE 的稳定 field_id，Agent 只能返回候选 PatchSet；冲突、结构问题、业务合并和校验失败保持人工复核。
• accepted patch 先经过本地校验和同版依赖重算，再使用与 Parser 相同的 current-fact projector 形成 EffectiveFactView；没有恢复任务时也建立同格式 baseline view。
• Layer 3 房型名固定为 source_room_type。room_type_code 和最终 Rate Code 只属于 Layer 4 RateRoomResolver；QBD F 列完全忽略，且 source_rate_code=NOT_APPLICABLE。

3. 统一状态机

处理运行（processing run）使用以下状态；状态是运行主线，不等同于单张业务卡的用户可见状态：

RECEIVED
  → MATERIAL_READY
  → PARSER_COMPLETE | PARSER_NOT_APPLICABLE | PARSER_FAILED
  → CONTEXT_READY
  → AGENT_COMPLETE（仅在需要 Agent 时）
  → VALIDATED
  → AWAITING_CONFIRMATION
  → CONFIRMED

• PARSER_FAILED、PARSER_NOT_APPLICABLE 不代表整封邮件失败；它们是允许进入 Context 和按需 Agent 的受控分支。
• 对适用固定渠道，PARSER_COMPLETE 的 Layer 3 artifact 必须进一步形成 baseline 或 recovery-applied EffectiveFactView 后才能进入 Layer 4；字段恢复子步骤不新增一套跨层事实格式。
• Validator 可以把受影响目标隔离为 Risk，但同封其他清晰目标继续到确认准备。
• 任何阶段发生可重试技术错误时记录 run attempt、错误代码和安全摘要，不伪造业务完成。
• CONFIRMED 是本期终点。PMS/Opera 适配器必须是后续独立状态机，不得从本状态机隐式触发。

4. 处理结果与隔离规则

每封邮件及每个候选目标都使用以下稳定结果类型：

结果	适用条件	后续行为
IN_SCOPE_TASKS	当前邮件存在可识别的 Booking 业务目标	形成候选卡，经过 Validator 后进入确认
GENERAL_NOTIFICATION	整封 current 邮件确定没有任何支持的业务任务	最多一条 General 通知
RISK_NOTIFICATION	业务类型、目标、材料或 Parser 结果存在无法安全消解的歧义	每封最多一张 Risk；隔离不明确部分
IGNORED_DIRECTION	确定为酒店外发、内部邮件或不属于本系统处理范围	不创建待办任务，保留安全处理记录

补充规则：

• 已知业务类型但字段缺失，保留原业务类型并标记 REVIEW_REQUIRED，不能降格成 General 或 Risk。
• 同封邮件存在清晰任务和不清晰片段时，清晰任务继续，Risk 只承载不清晰片段。
• 重复投递、真实新邮件、revision、历史底色遗留和业务内容相同是不同判断维度；由 Validator 结合证据、消息幂等键和生命周期处理。

5. 固定渠道材料与 Parser 边界

5.1 预处理为何独立

Excel、图片和正文的原始材料体积大、结构多变且含历史内容。预处理把“能安全给 Parser/Agent 的本次材料”缩小为可定位、可审计的引用集合，因此 Agent 不必读取整张工作簿或整段会话。

• current body 和 quoted history 必须分开；quoted history 只能辅助理解、继承身份或提示重复，不可再次触发动作。
• Excel 附件保留工作簿/Sheet/行/列/底色/哈希等证据；普通任务 API 不返回整行原文。
• 图片作为 IMAGE 材料进入预处理。它可辅助判断 Trace、Payment/Voucher 或不在范围，但不因“有图片”自动创建业务卡。
• 无附件邮件仍经过第 1 层接入和第 4 层 Context；仅跳过 Excel 专用预处理与 Parser。
• 对 Parser fallback，信息系统可从 current subject/body 生成受控 Agent excerpt，并提取唯一明确的 Group Code 或 old→new relation 供 Context 定向查询；这不是把全文、quoted history 或附件重新交给 Agent。
• 字段解析兜底 Agent 与 Layer 5 Booking Agent 是两个不同职责：前者只收到稳定 field_id 及同 row/segment/room item 的最小只读上下文，不能读取或重写整份附件；后者只在 Layer 4 之后形成业务候选决定。

5.2 严格底色与 Profile

• 固定渠道 Profile 必须同时满足文件信号、明确业务 Sheet 规则和表头签名；平分、未知或非法 Sheet 均停止确定性解析，进入 Risk/fallback。
• STRICT_CURRENT_CANDIDATE 必须在 Catalog 定义的业务范围内整行非白底。字体颜色、批注、条件格式推测和白底不计入。
• anchor 行提供身份/明细列；合法 continuation 行仅补动作/状态列。任意多行互补都不能升级为确定事实。
• 未知房量保持 booking_type=null/UNRESOLVED，不能按 0 推断 FIT；Trace 部门只有邮件证据唯一明确时预填，否则由用户选择 FO、HSK 或二者。

5.3 改团号与 Trace 生命周期

• old→new 团号只在 current body 明确标注后进入 GROUP_CODE_REPLACEMENT；Context 只读 old/new 两个 Group Code，old 有效且 new 不存在才允许 Update 继续。两个普通团号、历史引用或多条矛盾关系均进入复核。
• 同团同封的 standalone Trace 在信息系统内合并为一张候选卡，保留每条服务项和证据；跨封 Trace 绝不并入旧卡，Context 只以无自由文本的时间序摘要提供历史顺序。
• Trace 的最终确认至少选择 FO 或 HSK，可同时选择二者；本期确认不触发部门流转。

5.4 运行重试与可观测性

• FAILED run 只能从已保存的 PARSED_FACT_SET、CONTEXT_PACKAGE、MATERIAL_PACKAGE 重放；不会重新拉取邮件、附件或历史，也不会创建新的 source revision。重试在 worker 中继续，processing attempt 与 retry_count 形成可审计的尝试链。
• FAILED 之外的状态拒绝重试；旧的确认投影在重试期间不返回，避免用户确认过期候选。
• 管理员只读指标固定统计最近 24 小时：失败率、Agent fallback 比率、Risk 比率、活跃积压、已重试 run 与 retry attempt。指标只来自 th_hotel_booking 聚合，不含个人数据、邮件内容、附件、团号或跨库查询。
• 任何监控、重试或 retention 任务都以用户确认前为终点，不能触发 PMS/Opera、付款、库存扣减或部门流转。

6. 数据与事实源

• 新 Booking 主线的事实源是 PostgreSQL schema th_hotel_booking。处理运行、版本化契约、证据引用、候选、校验和确认投影均落入该 schema。
• 旧 MySQL V4 数据仅作历史兼容读取；禁止未定义双写、跨库事务或把 MySQL 记录当作新主线事实源。
• 每次读取 Context 必须按 Group Code、订单线索或已知 SourceMessage 定向查询；无目标线索时不能扫描全库找“最像”的订单。
• 主数据（渠道白名单、sender → Account/Market/Source、Rate/Room 目录映射）也是版本化事实。目录映射由 Layer 4 RateRoomResolver 执行；零候选、多候选和未配置均保留待用户补充，不能让 Parser 或 Recovery Agent 猜测。

7. 接口与并行工作边界

后续实现可以并行，但只能依赖 contracts-v1：

• Track A：BookingMessageOrchestrator 和入口适配器。
• Track B：Booking Agent profile、prompt、skill/reference 与离线 contract tests。
• Track C：Context/lifecycle assembler。
• Track D：PostgreSQL repository、Flyway、主数据与 processing run。

四条线不能直接依赖对方内部 Entity、Parser 私有 record 或 AgentBus payload。共享只通过 contracts-v1 的版本化数据结构、错误码和 evidence reference。

8. 实施前置与验收

G1 通过条件：信息系统、Agent、Context、数据库、Validator、前端和 QA 能在不引用旧 architecture-v0.3 的前提下，只基于 contracts-v1 明确输入、输出、版本字段、状态机、结果类型和失败边界后开始实现。

与现有 V0.1 的关系：V0.1 保留为受控纵向切片和回归基线；在 contracts-v1 适配完成前，不以其旧 V4 内部结构作为新模块之间的接口。