同步V4与M011文档状态

docs/project/integrations/superagent-api-contract.md

@@ -4,9 +4,9 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.9 |
-| 日期 | 2026-07-18 |
-| 状态 | 当前代码契约已支持 V4 入站解析基线、V2 `ai_task_results[]` 兼容、结构化 S10/S99、V3 业务根基础解析、旧 S000/S999 兼容和单酒店 hotel_id 后端解析 |
+| 文档版本 | 0.10 |
+| 日期 | 2026-07-20 |
+| 状态 | 当前代码契约已支持 V4 订单任务 + 多卡入站、V4 S10/S99 来源通知、V2 `ai_task_results[]` 兼容、V3 业务根兼容、旧 S000/S999 兼容、M011 Booking Excel 调 SuperAgent 前预处理增强和单酒店 hotel_id 后端解析 |
 | 适用范围 | SuperAgent 调用本系统查询上下文、查询邮件会话、提交 AI 任务结果 |
 | 主要读者 | SuperAgent 对接方、后端、测试、运维 |
 
@@ -105,7 +105,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID，也不需要为
 
 查询接口 3、4 面向已经入库的邮件会话：缺省酒店由后端解析，`external_conversation_id` 最终仍按 `hotel_id + source_provider + source_channel + external_conversation_id` 查询；`source_message_id` 表示外部来源消息 ID，可作为锚点反查该邮件所属会话。
 
-## 3.1 M002 V3 迁移提醒
+## 3.1 M002 V3 / V4 迁移提醒
 
 2026-07-11 起，项目需求基线已确认采用 `docs/project/requirements/M002-order-task-workflow-v3.md`；2026-07-12 起，Parent Group / Allotment 路由采用 `docs/project/requirements/M002-v3-p0.1-parent-group-routing-update.md`：
 
@@ -116,16 +116,39 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID，也不需要为
 - 完整 Parent split 的父事件必须使用 `Cancel Allotment + cancel_allotment_control_block`；`relationship_type=linked_parent_release_after_child_split` 只用于关联和 Preflight，不再作为独立任务 subtype。
 - 当前新入站不接受 `Cancel Booking + linked_parent_release_after_child_split` 作为合法业务任务；该组合仅允许历史数据只读兼容。
 
-当前后端已完成 M002 V3 CP1-CP6：
+2026-07-18 起，M002 V4 以 `docs/project/requirements/M002-v4-agent-callback-field-contract.md` 和 `docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md` 为当前有效业务入站契约：
+
+- V4 普通业务包使用 `route_code=null`、`source_message`、`order_contexts[]` 和 `message_events[]`。
+- `source_message.source_message_id` 是外部来源消息 ID，对应 SourceMessage Inbox 的 `external_message_id`，不是本系统内部数据库 ID。
+- 普通业务按 `source_message + order_ref` 创建 V4 订单任务，并在订单任务下创建来源消息只读卡、Basic Information 卡和业务事件卡。
+- Basic Information 必须先确认；业务卡逐卡确认或复核解阻，确认后永久锁定；V4 第一版不提供前端草稿。
+- `route_code=S10/S99` 使用 V4 来源通知模型，不创建隐藏技术订单，不进入订单详情时间线，不阻塞普通订单；前端只展示和 ack。
+- Account / Market / Source、Room Type、Rate Code 以本系统数据库目录稳定代码为准；SuperAgent 不应输出显示文案作为业务判断依据。
+
+当前后端仍兼容 M002 V3 CP1-CP6：
 
 - 已建立 40 条 P0.1 路由枚举 / 稳定配置；`route_code` 保持历史稳定，不按总数连续重编号，`R41/R42` 仍可能出现在响应和历史 transition 中。
-- 已支持结构化 `S10/S99` 入站，创建只读 `SOURCE_MESSAGE_ONLY` 任务。
+- 已支持结构化 `S10/S99` 历史入站兼容；当前 V4 新入站使用来源通知模型。
 - 已支持 V3 业务根 `source_message + message_events[]` 的基础解析；可派生到现有任务模型的 event 会创建业务任务，无法派生、显式契约错误或基础 manual_review / parent split 结构不完整的 event 只落 `adapter_contract_error` transition，不创建业务任务。
 - 已支持 `unhandled_current_intents[]` 最小落库：只写 `UNHANDLED_CURRENT_INTENT` transition，不创建业务任务，也不按 adapter 契约错误返回。
 - 已在 `workflow_reservation_ai_transition` 保存 `route_code`、`system_process_category`、`adapter_error_code` 和 `adapter_error_message`。
 - 已支持 type-known manual review 同卡解阻、当前订单归属确认、P0 fixtures 回归测试和 V3 typed `infrastructure_input_error` 响应。
 
-尚未完成：真实 OPERA / OHIP、普通任务切换订单、字段矩阵从当前扁平结构整体迁移到 0711 P0 新结构、历史旧 Parent Cancel Booking payload 批量迁移。
+尚未完成：真实 OPERA / OHIP、普通任务切换订单、历史旧 Parent Cancel Booking payload 批量迁移、真实 PMS / OPERA / OHIP 目录同步和 SuperAgent 目录机器接口。
+
+## 3.2 M011 Booking Excel 预处理输入增强
+
+M011 已在 Debug EML 和 AgentBus 自动分发链路中接入 Booking Excel 附件预处理。该能力发生在 TH Hotel 后端调用 SuperAgent Open API 前，不属于 SuperAgent 调本系统的 `task-results` 请求体字段，但会影响 SuperAgent 实际看到的邮件 payload。
+
+处理边界：
+
+- 后端只处理邮件附件中的 `.xls` / `.xlsx`，识别并排除 `PASSENGER_ROSTER` 人员名单类 Excel。
+- 对 `BOOKING_UPDATE` 和 `BOOKING_SURCHARGE` 类 Excel，按最近 6 个月候选窗口选择文件内实际存在的最新 3 个业务月，并抽取有背景色标记的业务行。
+- 非空结果追加到 AgentBus Outlook-like payload 的 `attachment_extractions[]` 字段，供 SuperAgent 作为证据输入。
+- `attachment_extractions[]` 只增强 SuperAgent 判断上下文，不直接创建订单、订单任务、任务卡、客户回复或 OPERA / OHIP 操作。
+- 测试机 AgentBus 增强已开启；生产 AgentBus 增强默认关闭。只有 `reservation.booking-excel-extraction.enabled` 和 AgentBus dispatch include 开关同时开启时才会追加该字段。
+
+字段契约、抽取规则和安全边界以 `docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` 为准。SuperAgent 生成最终 V4 结果时，仍必须按本文第 8 节的 `source_message + order_contexts[] + message_events[]` 契约回调本系统。
 
 ## 4. 接口 1：查询订单上下文
 
@@ -564,14 +587,15 @@ V4 字段说明：
 
 当前已支持的 V4 行为：
 
-- 命中 SourceMessage 后保存 AI batch / transition，并按 `message_events[]` 顺序处理。
-- 可映射 event 先复用现有订单 / 任务 / 任务卡链路，`ai_payload_json` 会保留 `v4_source_message`、`v4_order_context`、`v4_message_event`。
-- `route_code=S10/S99` 创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见。
-- V4 包级结构错误如果仍能通过 `source_message.source_message_id` 定位 SourceMessage，会返回成功接收并写入 `adapter_contract_error` transition；不创建订单、任务或用户可处理卡。`source_message_id` 缺失或找不到 SourceMessage 时仍返回明确错误。
-- `PAYMENT.attachment_ids[]` 引用不存在的附件、`UPDATE_BOOKING` 携带 `rate_code`、以及其他 V4 event 契约错误，只写 `adapter_contract_error` transition，不创建用户可处理业务任务。
+- 命中 SourceMessage 后保存 AI batch / transition，并按 `source_message + order_contexts[] + message_events[]` 处理。
+- 普通业务包按 `source_message + order_ref` 创建 V4 订单任务，并创建 `SOURCE_MESSAGE_DISPLAY`、`BASIC_INFORMATION` 和业务事件卡。
+- Basic Information 必须先确认；业务卡逐卡确认或复核解阻，确认后永久锁定；V4 第一版不提供前端草稿。
+- `route_code=S10/S99` 创建 V4 来源通知，工作台可见，订单列表和订单详情不可见；来源通知只能 ack，不创建订单、不阻塞订单。
+- V4 包级结构错误如果仍能通过 `source_message.source_message_id` 定位 SourceMessage，会返回成功接收并写入 `adapter_contract_error` transition；不创建订单任务、任务卡或来源通知。`source_message_id` 缺失或找不到 SourceMessage 时仍返回明确错误。
+- `PAYMENT.attachment_ids[]` 引用不存在的附件、`UPDATE_BOOKING` 携带不允许字段、目录代码无法匹配当前酒店数据库目录，以及其他 V4 event 契约错误，只写 `adapter_contract_error` transition，不创建用户可处理业务任务。
 - 技术契约错误不会自动转为 S10/S99，也不会创建前端可处理业务任务。
 
-当前 V4 入站仍未完成完整多卡模型：Basic Information 独立卡、V4 页面模型、真实 OPERA / OHIP、普通任务切换订单均后置。
+当前仍未完成：真实 OPERA / OHIP、真实 PMS / OPERA / OHIP 目录同步、普通任务切换订单、SuperAgent 目录机器接口和前端订单详情 V4 化。
 
 ### 8.3 V3 S10/S99 结构化请求体
 
@@ -682,7 +706,7 @@ V3 字段说明：
 - MCP 路径缺失 `source_message.source_message_id` 或整个 `source_message` 时，保留业务入站层 `MISSING_SOURCE_MESSAGE_ID` 错误语义。
 - 40 条 P0.1 路由进入后端枚举 / 稳定配置。
 - `route_code` 是稳定代码，不因路由总数从 42 调整为 40 而重编号；联调方不要按数字连续性判断合法性。
-- 结构化 `S10/S99` 创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见。
+- V3 结构化 `S10/S99` 兼容路径创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见；V4 新入站不走该模型，改用来源通知。
 - 业务 event 能派生到稳定路由时，复用现有订单 / 任务 / 任务卡创建链路。
 - 完整 Parent split 父事件必须提交为 `event_type=Cancel Allotment`、`extracted_fields.cancel_scope=entire_allotment_control_block`、`task_subtype=cancel_allotment_control_block`，并保留 `relationship_type=linked_parent_release_after_child_split` 作为关系字段。
 - 当前新入站若提交 `event_type=Cancel Booking` 且 `relationship_type=linked_parent_release_after_child_split`，写入 `adapter_contract_error` transition，不创建业务任务；旧 V2 兼容 `ai_task_results[]` 中的同等三元组按请求级 `ADAPTER_CONTRACT_ERROR` 拒绝。
@@ -759,7 +783,7 @@ V3 字段说明：
 
 正式联调时，SuperAgent 不需要传 `hotel_id`。后端通过系统酒店和外部 `source_message_id` 查找唯一 `platform_source_message_inbox.external_message_id`，真实 provider/channel 以 Inbox 入库值为准。如果没有找到，返回 `SOURCE_MESSAGE_NOT_FOUND`；如果同一系统酒店下匹配到多条，返回 `SOURCE_MESSAGE_AMBIGUOUS`。本地旧夹具允许在缺少 `hotel_id` 时使用内部数字 SourceMessage ID，但该兼容路径不作为 SuperAgent 正式契约。
 
-`informational_message` 结构化任务仅用于历史兼容。新数据如果是纯信息类邮件或无法形成业务素材包，应优先使用 V3 结构化 `S10/S99`；旧联调或兼容场景仍可使用下面的 `S000/S999` 文本请求体。
+`informational_message` 结构化任务仅用于历史兼容。新数据如果是纯信息类邮件或无法形成业务素材包，应优先使用 V4 `S10/S99` 来源通知；V3 结构化 `S10/S99` 和下面的 `S000/S999` 文本请求体仅作为旧联调或兼容路径。
 
 ### 8.6 S000/S999 文本请求体
 
@@ -783,7 +807,7 @@ S999,mail-20260708-0001
 | `S999` | 入口阶段无法形成业务素材包，不需要进入业务执行。 |
 | `mail-20260708-0001` | 外部来源消息 ID，对应 SourceMessage Inbox 的 `external_message_id`。 |
 
-S000/S999 不在 body 里传 `hotel_id`，后端使用平台酒店表唯一 `ACTIVE` 酒店和外部消息 ID 查询 SourceMessage Inbox。命中后创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务：任务列表可见，订单列表不可见，不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA，也不参与同订单任务执行顺序阻塞。该文本格式仅为兼容路径，新数据优先使用结构化 `S10/S99`。
+S000/S999 不在 body 里传 `hotel_id`，后端使用平台酒店表唯一 `ACTIVE` 酒店和外部消息 ID 查询 SourceMessage Inbox。命中后创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务：任务列表可见，订单列表不可见，不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA，也不参与同订单任务执行顺序阻塞。该文本格式仅为兼容路径；新数据优先使用 V4 `S10/S99` 来源通知。
 
 ### 8.7 成功响应