落定M002 V4 Agent回调字段契约

docs/import/20260718/0718-M002-V4-Agent回调草案审查与最新答复.md

@@ -0,0 +1,541 @@
+# 0718 M002 V4 Agent 回调草案审查与最新答复
+
+日期：2026-07-18
+
+审查对象：`M002-v4-agent-callback-field-contract-draft.md` 0.1
+
+适用范围：0718 业务基线下，Agent → Adapter / MCP → 信息系统的业务回调字段
+
+## 1. 最重要的修正：Basic Information 是订单级数据
+
+最新确认如下：
+
+- 一笔订单只有一份 Basic Information。
+- Basic Information 跟随订单，不跟随具体 Event。
+- Basic Information 不是 `event_type`，但它是订单任务中的一张独立可确认、独立锁定任务卡。
+- 同一订单下即使同时有 Update、Trace、Rooming List、Payment，也只显示一张 Basic Information 卡。
+- 一封邮件可能包含多笔订单，因此 Basic Information 也不能放成整个结果包唯一的一份。
+
+### 与此前结构是否吻合
+
+分两层看：
+
+- 页面和业务结果吻合：此前信息系统会按 `order_ref` 聚合，同一订单最终只显示一张 Basic Information。
+- Agent 回调字段归属不完全吻合：此前要求每个 Event 重复输出 `account_code`，再由系统校验同单一致。这能得到一张卡，但数据本身仍跟着 Event 重复，不能准确表达“Basic Information 属于订单”。
+
+因此，最新规则正式改为：
+
+- `account_code` 不再放在每个 Event 上。
+- 每个 `order_ref` 只提供一份订单级 Basic Information 数据。
+- Event 通过 `order_ref` 关联该订单，不复制 Account。
+- Market、Source 仍由信息系统目录派生，不由 Agent 输出。
+
+## 2. 推荐的 V4 结果包骨架
+
+以下是当前最容易表达业务语义、同时保留 `source_message + message_events[]` 的推荐结构：
+
+```json
+{
+  "route_code": null,
+  "source_message": {
+    "source_message_id": "AAMkAG...",
+    "conversation_id": "thread-001",
+    "subject": "Booking update",
+    "sender": "op@example.com",
+    "sent_at": "2026-07-18T02:10:00Z",
+    "body": "original current email body",
+    "attachments": []
+  },
+  "order_contexts": [
+    {
+      "order_ref": "order-1",
+      "basic_information": {
+        "account_code": "ACCOUNT_CODE",
+        "manual_review": null
+      }
+    }
+  ],
+  "message_events": [
+    {
+      "order_ref": "order-1",
+      "event_type": "UPDATE_BOOKING",
+      "target_order": {
+        "booking_type": "GROUP",
+        "locator_type": "GROUP_CODE",
+        "locator_value": "LLTQ260510QVIPA"
+      },
+      "after": {
+        "arrival_date": "2026-07-27",
+        "departure_date": "2026-07-30"
+      },
+      "manual_review": null
+    },
+    {
+      "order_ref": "order-1",
+      "event_type": "PAYMENT",
+      "target_order": {
+        "booking_type": "GROUP",
+        "locator_type": "GROUP_CODE",
+        "locator_value": "LLTQ260510QVIPA"
+      },
+      "attachment_ids": ["att-1"],
+      "manual_review": null
+    }
+  ]
+}
+```
+
+说明：
+
+- `order_contexts` 是本答复采用的推荐工作字段名；它表达“一封邮件结果包内的订单级数据集合”。最终技术命名可由 SuperAgent、Adapter、MCP Schema 和信息系统统一，但不能改变订单级归属。
+- 每个非 S10 订单至少有一个非空 `order_ref`，并且在 `order_contexts[]` 中只能出现一次。
+- 每个具体 Event 必须引用一个已存在的 `order_ref`。
+- 同一订单的多个 Event 使用同一个 `order_ref`；不同订单使用不同值。
+- `order_ref` 只在当前结果包内有效，不是 PMS 订单键、系统订单 ID、任务 ID或幂等键。
+- 当前继续保留 Event 自己的 `target_order`，由信息系统按它查单；相同 `order_ref` 下的非空 `target_order` 必须一致。
+
+## 3. Basic Information 的最终字段责任
+
+订单级结构：
+
+```json
+{
+  "order_ref": "order-1",
+  "basic_information": {
+    "account_code": "ACCOUNT_CODE | null",
+    "manual_review": null
+  }
+}
+```
+
+规则：
+
+- `account_code` 是信息系统 Account 目录中的稳定 code，不是自由文本或显示名称。
+- Agent 可依据发件人和历史业务信息判断 Account，但不重复输出 sender。
+- Agent 无法可靠确定 Account 时，输出 `account_code=null`，并在同一个 `basic_information` 对象中输出 `manual_review=true`。
+- Basic Information 的人工复核只作用于 Basic Information 卡，不要求同订单所有 Event 都变成 `manual_review=true`。
+- 信息系统根据 Account 目录带出 Market 和 Source。
+- 用户只能从信息系统已有 Account、Market、Source 中受控改选；不存在 Manual 或自由输入。
+- Agent 给出非空 code、但信息系统运行时目录不存在该值时，属于系统目录 / 契约校验问题：Basic Information 卡阻止确认并显示字段错误，但不得反向篡改 Agent 原始 `manual_review`。
+- 同一封邮件的不同 `order_ref` 可以对应不同 Account。
+
+删除旧规则：
+
+- 不再要求每个 Event 都携带 `account_code`。
+- 不再要求信息系统比较同一 `order_ref` 下多个 Event 的 Account 是否冲突。
+- 不因 Event 数量创建多份 Basic Information。
+
+## 4. source_message 最终业务内容
+
+当前邮件在包级只出现一次，业务最小字段为：
+
+```json
+{
+  "source_message_id": "string",
+  "conversation_id": "string | null",
+  "subject": "string | null",
+  "sender": "string | null",
+  "sent_at": "ISO-8601 string | null",
+  "body": "string | null",
+  "attachments": []
+}
+```
+
+草案需要修正：
+
+- 不拆 `sender.display / sender.address`；`sender` 直接使用邮件监听提供的单一值。
+- 不同时输出 `text_body` 和 `html_body`；只保留监听到的当前邮件单一原文 `body`。
+- Agent 不摘要、清洗、翻译或改写 `body`。
+- `received_at` 不是当前页面和业务处理必需字段；若基础设施需要，可作为内部技术元数据，不进入业务必传。
+- 完整历史邮件线程不嵌入当前结果包；信息系统通过 `conversation_id` 查询。
+- 标题、发件人、时间、正文、附件字段始终保留；极端不可得时字段值为 null，不删除字段或猜值。
+
+## 5. 附件结构
+
+当前附件 item 维持：
+
+```json
+{
+  "id": "att-1",
+  "name": "payment-slip.jpg",
+  "content_type": "image/jpeg",
+  "url": "https://upstream-storage/...",
+  "size": 251524
+}
+```
+
+- `id / name / content_type / url` 必填。
+- `size` 可选。
+- URL 由上游邮件监听或文件存储层提供；Agent 只原样转发，不生成、拼接、刷新或签发。
+- Payment 只按 ID 引用附件，不在 Event 内复制文件名、类型、URL 或完整对象。
+
+## 6. Event 公共结构
+
+每个具体业务 Event 的公共字段为：
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "...",
+  "target_order": {
+    "booking_type": "GROUP | FIT | null",
+    "locator_type": "GROUP_CODE | BOOKING_CODE | CONFIRMATION_NUMBER | null",
+    "locator_value": "string | null"
+  },
+  "manual_review": null
+}
+```
+
+不再属于 Event 公共字段：
+
+- `account_code`：改为订单级 Basic Information。
+- `payload`：当前目标契约直接使用各 Event 的专属业务字段，不再增加一层无业务含义的通用 payload。
+- `evidence`：不是信息系统页面业务必传；如 Agent 内部需要，可留在内部诊断，不驱动页面业务。
+- `event_index`：数组顺序不承载业务顺序，页面顺序由信息系统按固定卡片规则决定。
+- `event_id`：不是业务字段；只有真实 transport / 幂等机制需要时才由技术契约另行增加，不能代替 `order_ref`。
+
+## 7. event_type 最终枚举
+
+只保留：
+
+```text
+NEW_BOOKING
+UPDATE_BOOKING
+CANCEL_BOOKING
+TRACE_RESERVATION_NOTES
+ROOMING_LIST
+PAYMENT
+```
+
+- Basic Information 不是 Event。
+- 邮件展示卡不是 Event，由 `source_message` 固定生成。
+- S10 是包级纯通知路由，不属于上述业务枚举。
+- S99、Fallback、`Need Manual Review`、独立 Voucher、Payment Evidence、Voucher Received 均不再作为新 Agent 输出。
+
+## 8. target_order 最终规则
+
+| 场景 | `booking_type` | `locator_type` | `locator_value` |
+|---|---|---|---|
+| Group 的所有业务 | `GROUP` | `GROUP_CODE` | Group Code，即 Block Name |
+| Fit New，以及与该 New 同包同目标的 Trace | `FIT` | `BOOKING_CODE` | Booking Code |
+| 当前无 PMS API、尚无真实 Confirmation Number 的 Fit 后续业务 | `FIT` | `BOOKING_CODE` | 查询信息系统本地订单投影 |
+| 已取得真实 Confirmation Number 的 Fit 后续业务 | `FIT` | `CONFIRMATION_NUMBER` | PMS Confirmation Number |
+
+规则：
+
+- 当前包内同订单归组使用 `order_ref`，不是使用相同 `target_order` 或相同 null。
+- `target_order` 用于信息系统查单和绑定订单。
+- 定位值未解决时保留原 Event，未知字段为 null，Event 的 `manual_review=true`。
+- Agent 能判断多个 Event 属于同单但定位未解决时，仍使用相同 `order_ref`。
+- Agent 连是否同单都无法判断时，使用不同 `order_ref`，不能把相同 null 合并。
+- 不输出 `case_keys`、定位候选数组、原因码或 `missing_fields[]`。
+- AMEND GROUP CODE 统一走 S10，不形成 Update Event。
+
+## 9. 各 Event 最新字段
+
+### 9.1 NEW_BOOKING
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "NEW_BOOKING",
+  "target_order": {},
+  "arrival_date": "YYYY-MM-DD | null",
+  "departure_date": "YYYY-MM-DD | null",
+  "rate_code": "RATE_CODE | null",
+  "room_items": [
+    {
+      "room_type_code": "ROOM_TYPE_CODE | null",
+      "room_count": 1
+    }
+  ],
+  "manual_review": null
+}
+```
+
+Group 条件字段：
+
+```json
+{
+  "booking_scenario": "STANDARD | PROPOSAL"
+}
+```
+
+Fit 条件字段：
+
+```json
+{
+  "guest_name": "REAL GUEST NAME | null"
+}
+```
+
+修正草案：
+
+- 删除 `booking_name`；Group Code 已在 `target_order.locator_value`，同时作为 Block Name。
+- 删除独立 `booking_code`；Fit Booking Code 也在 `target_order.locator_value`。
+- `proposal` 改为 Group 专用受控 `booking_scenario=STANDARD | PROPOSAL`。
+- `room_type` 使用受控 `room_type_code`。
+- `room_quantity` 使用 `room_count`。
+- 删除 `adult_per_room`；Adult 由信息系统按 RoomType 映射派生。
+- Agent 不输出 Nights、Breakfast、Group Booking Status、Block ID 或 Confirmation Number。
+- `room_items=[]` 只能用于表示已识别 New 但完整房型清单未解决，并必须 `manual_review=true`；最终 validator 需按这一规则固定。
+
+### 9.2 UPDATE_BOOKING
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "UPDATE_BOOKING",
+  "target_order": {},
+  "after": {
+    "guest_name": "NEW NAME | null",
+    "arrival_date": "YYYY-MM-DD | null",
+    "departure_date": "YYYY-MM-DD | null",
+    "room_items": [
+      {
+        "room_type_code": "ROOM_TYPE_CODE | null",
+        "room_count": 1
+      }
+    ]
+  },
+  "manual_review": null
+}
+```
+
+规则：
+
+- `after` 是稀疏对象；字段缺省表示本次不修改。
+- 字段存在但为 null，表示已识别要改该字段、但目标值未解决，同时 `manual_review=true`；null 不表示清空。
+- `guest_name` 只用于 Fit Name 更新，不使用 `booking_name`。
+- 只要修改涉及房型或房量，`after.room_items[]` 必须是修改后的完整房型清单，不是变化行。
+- 如果只能识别局部房型变化、无法形成完整目标清单，建议固定为 `after.room_items=null + manual_review=true`，禁止确认直到人工补全。
+- Rate Code 不允许出现在 Update。若 Agent 仍输出，按业务契约错误处理，不能静默忽略后继续执行。
+- Before、原订单和完整最新订单由信息系统查单后生成，不由 Agent 输出。
+
+### 9.3 CANCEL_BOOKING
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "CANCEL_BOOKING",
+  "target_order": {},
+  "manual_review": null
+}
+```
+
+- `CANCEL_BOOKING` 本身已经表示整单取消。
+- 删除 `cancel_scope`、`cancel_reason`、`after` 和当前订单快照。
+- 减少房量、删除房型、修改日期或修改 Fit Name 属于 Update，不是 Cancel。
+
+### 9.4 TRACE_RESERVATION_NOTES
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "TRACE_RESERVATION_NOTES",
+  "target_order": {},
+  "trace_items": [
+    {
+      "item_type": "GENERAL",
+      "text": "HONEYMOON SETUP",
+      "department_code": "FO"
+    },
+    {
+      "item_type": "EXTRA_BED",
+      "target_room_type_code": "TWN",
+      "extra_bed_room_count": 1,
+      "department_code": "FO+HSK"
+    }
+  ],
+  "manual_review": null
+}
+```
+
+修正草案：
+
+- 使用 `item_type=GENERAL | EXTRA_BED`，不使用 `trace_type=NORMAL`。
+- GENERAL 输出 `text + department_code`。
+- EXTRA_BED 不输出自由 `content`；信息系统固定显示 `SET EXTRA BED`。
+- EXTRA_BED 不输出 `adult_after_extra_bed`；信息系统按当前 / 基础 Adult +1 计算，页面确认前允许用户纠正。
+- Department code 由 Agent 必传，值来自信息系统维护的受控部门目录或组合目录。
+- 加床目标房型不在当前订单时，Trace 卡不能确认，并提示用户核对目标房型和订单关联；只有订单定位本身不可信时，才触发共享查单门槛阻断整个订单上下文。
+
+### 9.5 ROOMING_LIST
+
+当前最小 Event：
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "ROOMING_LIST",
+  "target_order": {
+    "booking_type": "GROUP",
+    "locator_type": "GROUP_CODE",
+    "locator_value": "GROUP-CODE"
+  },
+  "manual_review": null
+}
+```
+
+- 只适用于 Group。
+- 当前 Agent 只需识别这是 Rooming List 任务。
+- 不输出 `rows[]`、逐人名单、同住分组、18 列、Excel 或 PMS 导入参数。
+- 当前也不要求 Rooming List Event 单独输出 `attachment_ids[]`；原附件已经在包级 `source_message.attachments[]`，只在邮件展示卡查看。
+- 页面固定展示 12 个必填字段表头的标准表格示意，当前内容不代表附件已经真实转换。
+- 未来取得 PMS API 后，按真实接口重新冻结住客与执行参数，不直接恢复草案中的 rows。
+
+### 9.6 PAYMENT
+
+```json
+{
+  "order_ref": "order-1",
+  "event_type": "PAYMENT",
+  "target_order": {},
+  "attachment_ids": ["att-1", "att-2"],
+  "manual_review": null
+}
+```
+
+- `account_code` 已移至订单级 Basic Information，不在 Payment 重复。
+- 一笔订单多份凭证放在同一个 Payment Event。
+- `attachment_ids[]` 没有业务顺序，每个 ID 必须引用同包附件。
+- 不输出金额、日期、付款人、交易号、银行账号、付款状态、Department 或完整附件对象。
+- 推荐把“正常 Payment 的 `attachment_ids[]` 至少一项”设为 validator 规则。
+- 如果 Agent 输出 PAYMENT 但没有任何附件 ID，而来源附件实际存在，属于 Agent 契约错误，不能创建一张正常空 Payment 卡。
+- 如果来源本身没有可用于当前图片卡的付款凭证，无法形成 Payment 任务，则按 S10 展示原邮件。
+- 如果附件 metadata 存在但 URL 读取失败，属于附件 / 存储技术异常，不应伪装成人工复核字段。
+
+## 10. manual_review 最终规则
+
+唯一合法值：
+
+```json
+null
+```
+
+或：
+
+```json
+true
+```
+
+规则：
+
+- 正常数据为 null，不使用 false。
+- Event 的人工复核只属于该 Event 对应任务卡。
+- Basic Information 的人工复核放在订单级 `basic_information.manual_review`，只属于 Basic Information 卡。
+- 未解决值放在原业务字段位置，例如 `rate_code=null`、`room_type_code=null` 或 `account_code=null`。
+- `manual_review=true` 必须至少能由当前对象中的一个 null、空清单或其他 Schema 可识别未解决值解释。
+- 所有字段完整合法却只给 true，属于 Agent 契约异常。
+- 不输出 `manual_review_info`、`reason_code`、`visible_message`、`missing_fields[]`、JSON Pointer、候选或建议动作。
+- 信息系统依据条件必填、Account / RoomType / Rate Code 目录、日期 / 数量规则和查单结果生成字段级错误路径、错误码与页面提示。
+- 信息系统查单 0 / 多笔或目录运行时校验失败，不反向修改 Agent 原始 `manual_review`。
+
+因此，草案第 16 节的扩展 `manual_review_info` 整节应删除。
+
+## 11. S10 纯通知
+
+业务语义已经冻结：
+
+```json
+{
+  "route_code": "S10",
+  "source_message": {},
+  "order_contexts": [],
+  "message_events": []
+}
+```
+
+- 只显示邮件展示卡。
+- 不显示 Basic Information、房间信息或其他业务卡。
+- 不需要 `order_ref`、`target_order`、Account 或业务字段。
+- 用户点击“确认”后任务完成。
+- 不提供人工终止。
+- 不调用 PMS，不修改订单。
+- 不输出 S99、Fallback、原因码、通知说明或 `Need Manual Review`。
+
+`route_code` 是当前推荐工作字段名；最终 discriminator 的技术命名仍需 Adapter / MCP Schema 统一，但 S10 的业务语义不再有歧义。
+
+## 12. 技术异常
+
+下列情况不生成酒店用户可见任务，也不转换成 S10 或人工复核：
+
+- 非法 JSON；
+- 输出不符合 Schema；
+- Event 引用了不存在的 `order_ref`；
+- 同一 `order_ref` 下出现冲突的非空 `target_order`；
+- Rate Code 出现在 Update；
+- `manual_review=true` 但没有任何可识别的未解决字段；
+- Adapter 转换失败；
+- MCP 提交失败；
+- Agent / Skill 执行异常；
+- 附件 metadata 存在但存储 URL 无法读取。
+
+后台 debug、告警和技术重试接口属于技术运维需求，不进入本次业务回调，也不在酒店用户任务卡上增加“重试”。
+
+## 13. 对草案第 20 节 18 个问题的逐项答复
+
+| # | 草案问题 | 最新答案 |
+|---:|---|---|
+| 1 | `message_events` 字段名是否冻结 | 业务上继续使用事件数组；`message_events` 可作为 V4 工作字段名。新增订单级 `order_contexts[]` 表达每笔订单的 Basic Information。最终 transport key 需四方 Schema 一致 |
+| 2 | `route_code=S10` 与 S99 | S10 是唯一纯通知；S99 完全删除。`route_code` 可作为当前工作 key，最终 discriminator 只需技术对齐 |
+| 3 | `source_message_id` 是否对应 `external_message_id` | 业务要求是当前邮件稳定 ID；是否映射 AgentBus `external_message_id` 属于 Adapter 技术映射，必须以真实上游契约核对 |
+| 4 | source_message 字段 | 固定业务内容为邮件 ID、会话 ID、subject、单值 sender、sent_at、单一 body、attachments；不拆 text / HTML，received_at 非业务必传 |
+| 5 | event_type 完整枚举 | 已冻结为 New、Update、Cancel、Trace、Rooming List、Payment 六种 |
+| 6 | account_code 包级还是 Event 级 | 两者都不是；它是订单级 Basic Information 字段，每个 `order_ref` 只出现一次 |
+| 7 | 同订单多个 Event 的 Account 冲突 | 新结构不再重复，所以正常情况下不存在；旧输入冲突由 Adapter 拒绝 / 迁移，不让信息系统或用户任选 |
+| 8 | 是否扩展 manual_review | 不扩展，只允许 null / true；字段级问题由系统按 Schema 和目录生成 |
+| 9 | locator_value=null 如何归组 | 使用非空包内 `order_ref`；同单同值，不同订单不同值，不按相同 null 合并 |
+| 10 | 无 API Fit 后续只有 Booking Code | 允许临时查询本地订单投影；取得真实 Confirmation Number 后切换正式定位，不生成假编号 |
+| 11 | New Booking 字段 | 使用 dates、订单级 rate_code、完整 room_items、Group booking_scenario、Fit guest_name；删除 booking_name、独立 booking_code 和 Adult |
+| 12 | Update 是否给完整 After | `after` 整体是稀疏对象；但只要涉及房型 / 房量，`after.room_items` 必须是修改后的完整清单 |
+| 13 | Update 出现 Rate Code | 业务契约错误，不静默忽略，不允许正常执行 |
+| 14 | Cancel 是否需要 cancel_scope | 不需要；`CANCEL_BOOKING` 已表示整单取消，也不输出 cancel_reason |
+| 15 | Trace 字段与 Department 来源 | 使用 GENERAL / EXTRA_BED item；Department 是 Agent 必传的系统受控 code；固定加床文案和 Adult 由系统派生 |
+| 16 | Rooming List 是否允许不输出 rows | 不只是允许，而是当前明确不要求 rows；只输出最小 Group Rooming List Event，页面显示表头示意 |
+| 17 | Payment attachment_ids 为空 | 推荐正常 Payment 必须非空；空引用属于无法形成正常图片卡。按来源情况进入契约错误、S10 或附件技术异常，不使用复杂人工复核对象 |
+| 18 | 技术异常是否需要后台重试 | 不属于本轮业务契约；可另做开发 / 运维需求，但不得生成用户业务任务或卡片重试按钮 |
+
+## 14. 草案各章节的处理结论
+
+| 草案章节 | 处理 |
+|---|---|
+| 第 3 节总体结论 | 将“相同 target_order 聚合”改为“按 source_message_id + order_ref 聚合，再按 target_order 查单”；增加订单级 Basic Information 集合 |
+| 第 4 节包级结构 | 改成单值 sender、单一 body；删除业务必传 text_body、html_body、received_at |
+| 第 5 节附件 | 基本正确，保留 |
+| 第 6 节 Event 通用结构 | 删除 Event account_code、通用 payload、业务 evidence、event_index；event_id 仅可作为待证实 transport 字段 |
+| 第 7 节 target_order | 增加 order_ref 归组和无 API Fit Booking Code 临时定位；AMEND GROUP CODE 冻结为 S10 |
+| 第 8 节枚举 | 六种枚举正式冻结 |
+| 第 9 节 Basic Information | 改为每个 order_ref 一份订单级对象，不再 Event 级重复 |
+| 第 10 节 New | 按第 9.1 节整体替换 |
+| 第 11 节 Update | 按第 9.2 节整体替换 |
+| 第 12 节 Cancel | 删除整个 cancel payload，保留最小 Event |
+| 第 13 节 Trace | 按第 9.4 节整体替换，删除 Agent Adult 与固定加床文案 |
+| 第 14 节 Rooming List | 删除 rows 和 Event attachment_ids，改为当前最小 Event |
+| 第 15 节 Payment | 删除 Event account_code，保留非空附件 ID 集合 |
+| 第 16 节 manual_review | 删除 manual_review_info、reason_code、visible_message 和 missing_fields |
+| 第 17 节 S10 | 业务处理正确，补充无订单级数据 |
+| 第 18 节技术异常 | 基本正确；后台重试另立技术需求 |
+| 第 19 节后端建模 | 不再按 target_order 直接分组；先按 order_ref 形成订单任务，再按 target_order 查单；每个订单只补一张 Basic Information |
+
+## 15. 目前仍需技术团队最终对齐的内容
+
+业务规则已经足够让开发进行领域建模。以下剩余项是技术接口命名或运行机制，不应再次让业务方决定页面含义：
+
+1. `order_contexts`、`message_events` 和 S10 discriminator 的最终 JSON key。
+2. `source_message_id` 到 AgentBus / SourceMessage Inbox 字段的真实映射。
+3. `conversation_id`、`sent_at` 等 key 与时间格式的最终机器 Schema。
+4. Payment 附件引用 key 是否最终命名为 `attachment_ids`。
+5. 无附件、监听失败、附件 metadata 存在但 URL 读取失败的 transport 错误码。
+6. `event_id` / 幂等键是否为运行时必需；如需增加，它只属于 transport，不是页面业务字段。
+7. Department、Account、RoomType、Rate Code 等受控目录的真实 code 集合和版本管理。
+8. Adapter、MCP Schema、信息系统 DTO 与 validator 的版本切换方式。
+9. 技术失败后台、告警和开发重试入口是否建设。
+
+这些技术项不会改变以下业务事实：一封邮件一个结果包、一个 `order_ref` 一笔订单、一笔订单一张 Basic Information、每个 Event 一张对应业务任务卡、每张卡独立确认并永久锁定。
+
+## 16. 最终结论
+
+开发草案已经覆盖了大部分讨论主题，但不能直接冻结为 V4 Schema。主要原因不是缺少问题，而是其中多项“当前建议”已经被最新业务共识明确否决或替代。
+
+开发可按本文继续推进业务模型和页面数据模型；正式实现 Agent 回调前，还需要由 SuperAgent、Adapter、MCP Schema 和信息系统共同完成第 15 节的技术 key 与运行契约对齐。

docs/import/20260718/0718-V4剩余10项确认回复.md

@@ -0,0 +1,210 @@
+# 0718 V4 剩余 10 项确认回复
+
+日期：2026-07-18
+
+适用范围：Agent → Adapter / MCP → 信息系统的 V4 回调技术契约
+
+说明：以下内容不改变已经确认的页面业务规则，主要用于冻结字段名、校验规则，以及明确需要 SuperAgent、Adapter 和信息系统共同对齐的技术边界。
+
+## 1. Key 是否正式冻结
+
+建议 V4 正式采用并冻结以下 key：
+
+- `route_code`
+- `source_message`
+- `order_contexts`
+- `message_events`
+- `order_ref`
+- `target_order`
+- `attachment_ids`
+
+具体语义：
+
+- `route_code`：普通业务为 `null`，纯通知为 `S10`。
+- `source_message`：当前触发邮件的包级来源事实，只出现一次。
+- `order_contexts[]`：每个 `order_ref` 一项，承载订单级 Basic Information。
+- `message_events[]`：承载 New、Update、Cancel、Trace、Rooming List、Payment 六类业务 Event。
+- `order_ref`：只用于当前结果包内聚合同一订单，不用于 PMS 查单。
+- `target_order`：用于信息系统查询和绑定真实订单。
+- `attachment_ids[]`：仅用于 Payment 关联包级附件。
+
+SuperAgent、Adapter、MCP Schema 和信息系统最终必须使用完全相同的字段名与嵌套位置。
+
+## 2. source_message_id 与 external_message_id
+
+业务要求是：`source_message_id` 必须代表本次触发邮件的稳定唯一 ID。
+
+建议 Adapter 将 AgentBus / SourceMessage Inbox 的 `external_message_id` 映射为：
+
+```text
+source_message.source_message_id
+```
+
+是否能直接一对一使用同一个值，需要根据真实 AgentBus / SourceMessage Inbox 契约确认。这是技术映射，不是新的业务问题。
+
+## 3. 时间格式
+
+同意统一为 UTC ISO-8601，例如：
+
+```text
+2026-07-18T02:10:00Z
+```
+
+如果系统需要保留来源邮件原时区，可以作为内部技术元数据保存；Agent 对信息系统的标准时间统一使用 UTC。
+
+## 4. body 的内容格式
+
+已经确认的业务规则是：
+
+- 只保留一个 `body`；
+- 邮件监听层取得什么原文，Agent 就原样转发什么；
+- Agent 不清洗、摘要、翻译、重排或改写；
+- 不恢复 `text_body + html_body` 双正文。
+
+为了让信息系统选择正确的安全渲染策略，建议增加一个技术字段：
+
+```text
+body_content_type = text/plain | text/html
+```
+
+信息系统根据该字段进行纯文本转义展示或 HTML 安全渲染。无论使用哪种渲染方式，都不能改写保存的原始 `body`。
+
+如果邮件监听层能够保证所有正文永远只有一种固定格式，也可以由 Adapter 固定该类型，不要求 Agent 重新判断。
+
+## 5. 受控 code 目录
+
+Account、RoomType、RateCode、Department 的目录由信息系统或其主数据服务统一维护，并作为唯一事实源。
+
+规则如下：
+
+- SuperAgent 只能输出目录中已有的稳定 code；
+- 不允许输出自由文本或自行创造 code；
+- Agent 无法可靠匹配时，按对应业务字段的未解决规则处理；
+- Agent 输出非空 code、但信息系统目录不存在该值时，属于目录校验或契约问题；
+- 目录如何同步或提供给 SuperAgent，由双方技术方案决定，可以使用版本化目录快照或查询能力。
+
+Market 和 Source 仍由信息系统根据订单级 `account_code` 派生，不由 Agent 输出。
+
+## 6. 技术异常通知链路
+
+同意需要独立的技术运行链路，但技术失败不属于酒店用户任务。
+
+建议至少具备：
+
+- `dispatch_run_id` 或同类技术运行 ID；
+- `PENDING / RUNNING / SUCCEEDED / FAILED / TIMED_OUT` 等运行状态；
+- Agent 未回调的超时检测；
+- Agent、Skill、Adapter、MCP 和附件读取错误记录；
+- 面向开发或运维的告警、日志或错误查询入口。
+
+技术失败不得创建 S10、人工复核卡或其他酒店用户业务任务。
+
+`dispatch_run_id` 如何产生、请求与回调如何关联、错误通过回调还是独立 channel 返回，需要由 AgentBus、SuperAgent 和信息系统共同设计。
+
+## 7. PAYMENT 的 attachment_ids
+
+同意正常 Payment 冻结为：
+
+```text
+attachment_ids.length > 0
+```
+
+同时建议校验：
+
+- `attachment_ids[]` 至少一项；
+- ID 不重复；
+- 每个 ID 都必须存在于同包 `source_message.attachments[]`；
+- 每个 ID 必须属于当前订单的付款凭证；
+- 正常 Payment 至少关联一份可用付款凭证。
+
+没有任何凭证附件时，不能创建正常的空 Payment 卡：
+
+- 来源附件存在，但 Agent 没有关联任何 ID：Agent / Adapter 契约错误；
+- 来源本身没有可用于 Payment 卡的付款凭证：不形成正常 Payment，按 S10 展示原邮件；
+- 附件 metadata 存在但 URL 无法读取：附件或存储技术异常。
+
+以上情况都不使用复杂 `manual_review` 对象。
+
+## 8. manual_review=true 的 validator
+
+同意冻结，但必须按当前对象的具体 Schema 判断，不能把任意空值都视为合法。
+
+规则如下：
+
+- `manual_review` 只允许 `null | true`；
+- 正常对象为 `null`，不使用 `false`；
+- `manual_review=true` 时，当前 Basic Information 或 Event 中必须存在至少一个由该 Schema 允许的未解决标记；
+- 未解决标记可以是特定可空字段、被允许的空清单或不完整 item；
+- 来源冲突时，把无法可靠决定的原业务字段置为 `null`；
+- 不能笼统认为任何空数组都能解释 `manual_review=true`；
+- 所有字段完整、合法且通过目录校验，却仍输出 `manual_review=true`，属于 Agent / Adapter 契约异常。
+
+不增加以下字段：
+
+- `manual_review_info`
+- `missing_fields[]`
+- `reason_code`
+- 字段路径
+- 候选值
+- 复核说明对象
+
+具体字段错误路径、错误码和页面提示由信息系统根据 Schema、目录和业务规则生成。
+
+## 9. Update 的 after.room_items=null
+
+同意冻结为三态语义：
+
+| 结构 | 语义 |
+|---|---|
+| `after` 中不存在 `room_items` | 本次邮件没有要求修改房型或房量 |
+| `after.room_items=null` | 已识别本次涉及房型或房量修改，但无法形成修改后的完整房型清单；必须同时 `manual_review=true` |
+| `after.room_items=[...]` | 修改后的完整房型清单，不是只输出变化行 |
+
+不要使用空数组表达“无法形成完整房型清单”。
+
+如果修改后整笔订单不再保留任何房间，应按整单 `CANCEL_BOOKING` 处理，而不是提交空的 Update 房型清单。
+
+## 10. 无 Confirmation Number 阶段的 Fit 后续定位
+
+确认接受既有规则。
+
+当前无 PMS API，且该 Fit 尚未取得真实 Confirmation Number 时：
+
+- Agent 可以输出 `booking_type=FIT`；
+- `locator_type=BOOKING_CODE`；
+- `locator_value=Booking Code`；
+- 信息系统使用 Booking Code 查询本地订单投影。
+
+取得真实 Confirmation Number 后：
+
+- 后续业务切换为 `locator_type=CONFIRMATION_NUMBER`；
+- 不生成假的 Confirmation Number；
+- Booking Code 不成为未来 PMS 场景的永久关联键；
+- 信息系统不使用当前 Name 查询已有 Fit。
+
+## 11. 确认状态汇总
+
+| 项目 | 当前处理 |
+|---|---|
+| 1. V4 key | 建议按本文正式冻结，需四方使用同名、同层级 |
+| 2. message ID 映射 | 需根据真实 AgentBus / SourceMessage Inbox 契约核对 |
+| 3. UTC ISO-8601 | 可以冻结 |
+| 4. body 格式 | 原文透传已确认；`body_content_type` 需监听层 / Adapter 技术对齐 |
+| 5. code 目录 | 信息系统主数据是唯一事实源；同步方式需技术设计 |
+| 6. 技术异常 channel | 需要单独建设；不进入酒店用户任务体系 |
+| 7. Payment 非空附件 | 可以冻结 |
+| 8. manual_review validator | 可以冻结，并按各对象条件 Schema 校验 |
+| 9. Update room_items 三态 | 可以冻结 |
+| 10. Fit Booking Code 临时定位 | 已确认，可直接实施 |
+
+## 12. 开发推进建议
+
+后端可以继续进行领域模型与页面数据模型设计，不需要等待所有技术通道完成后才开始。
+
+但在正式写入站 validator 和完成端到端联调前，应完成以下技术对齐：
+
+1. 核对 `source_message_id` 与真实上游 message ID 的映射；
+2. 确认 `body_content_type` 的来源与取值；
+3. 确认 `dispatch_run_id`、超时和错误 channel；
+4. 确认主数据目录如何提供给 SuperAgent；
+5. 保证 SuperAgent、Adapter、MCP Schema 和信息系统使用同一份 V4 Schema。

docs/import/20260718/0718业务基线-Agent回调问题答复.md

@@ -0,0 +1,275 @@
+# 0718 业务基线：Agent 回调结构说明
+
+> 以下是 0718 确认的目标业务契约，不代表旧 Agent 和当前 0711 P0 接口已经完成改造。
+
+## 1. 最终回调是否仍为 `source_message + message_events[]`？
+
+是。
+
+一封当前邮件对应一个结果包：
+
+```json
+{
+  "source_message": {},
+  "message_events": []
+}
+```
+
+规则：
+
+- `source_message` 在包级只出现一次。
+- `message_events[]` 可以包含同一订单的多个事件，也可以包含不同订单的事件。
+- 信息系统根据每个事件的 `target_order` 聚合同订单、拆分不同订单。
+- `message_events` 是当前工作字段名，最终需要与 Adapter、MCP Schema 和信息系统入站 DTO 统一冻结。
+
+## 2. 每个 Event 是否有稳定的订单标识？
+
+每个具体业务 Event 都必须有稳定的 `target_order`。
+
+不再使用旧的 `case_keys`。
+
+```json
+{
+  "target_order": {
+    "booking_type": "GROUP",
+    "locator_type": "GROUP_CODE",
+    "locator_value": "LLTQ260510QVIPA"
+  }
+}
+```
+
+合法定位组合：
+
+| 场景 | `booking_type` | `locator_type` | `locator_value` |
+|---|---|---|---|
+| Group 的所有业务 | `GROUP` | `GROUP_CODE` | Group Code，即 Block Name |
+| Fit New Booking | `FIT` | `BOOKING_CODE` | Booking Code |
+| 已创建 Fit 的 Update / Cancel / Trace / Payment | `FIT` | `CONFIRMATION_NUMBER` | Confirmation Number |
+
+如果 Agent 已识别出具体业务，但定位参数缺失或无法确定：
+
+- 未解决的定位字段为 `null`；
+- 该 Event 输出 `manual_review: true`；
+- 不输出候选订单数组、`case_keys` 或复杂缺失原因。
+
+S10 纯通知是例外，不需要 `target_order`。
+
+## 3. Trace、Payment、Rooming List 是独立 Event 还是 Booking Event 的子结构？
+
+都是独立 Event，与 Booking Event 平级放在 `message_events[]` 中。
+
+```json
+{
+  "message_events": [
+    {
+      "event_type": "UPDATE_BOOKING",
+      "target_order": {}
+    },
+    {
+      "event_type": "TRACE_RESERVATION_NOTES",
+      "target_order": {}
+    },
+    {
+      "event_type": "PAYMENT",
+      "target_order": {}
+    }
+  ]
+}
+```
+
+它们不是 `NEW_BOOKING` 或 `UPDATE_BOOKING` 下的子结构。
+
+信息系统通过相同的 `target_order` 判断这些 Event 属于同一订单，并生成同一订单下的多张独立任务卡。每张卡有自己的状态和“确认”按钮，互不阻塞。
+
+业务限制：
+
+- Trace 可以与 New 或 Update 同时出现，Cancel 不带 Trace。
+- Rooming List 只适用于 Group。
+- Payment 只适用于已有订单，即 Update 场景。
+
+## 4. 同一封邮件、同一订单的多个 Event，Agent 是否保证使用同一订单标识？
+
+是，这是 Agent 输出契约的强制要求。
+
+同一订单的所有 Event 必须输出完全一致的：
+
+```text
+booking_type + locator_type + locator_value
+```
+
+例如同一 Group 订单的 Update、Trace 和 Payment 都必须使用同一个 Group Code：
+
+```json
+{
+  "booking_type": "GROUP",
+  "locator_type": "GROUP_CODE",
+  "locator_value": "LLTQ260510QVIPA"
+}
+```
+
+不需要额外增加父子关系、Event 关联索引或 `same_order_id`。
+
+如果 Agent 无法获得稳定订单标识，应保留对应 Event，并设置 `manual_review: true`，不能自行猜测订单。
+
+## 5. 纯通知如何返回？
+
+纯通知统一使用 `S10`，不再使用 S99、Fallback 或 `Need Manual Review`。
+
+业务语义为：
+
+```json
+{
+  "route_code": "S10",
+  "source_message": {},
+  "message_events": []
+}
+```
+
+其中 `route_code` 是当前建议字段名，最终需要与 Adapter/MCP Schema 冻结。
+
+S10 规则：
+
+- 只返回 S10 类型标识和完整 `source_message`。
+- 不返回 Basic Information、房间信息或其他业务 Event。
+- 不需要 `target_order`、Account 或业务参数。
+- 不进入人工复核，语义上 `manual_review=null`。
+- 前端只显示“邮件展示”卡。
+- 用户查看后点击“确认”，任务完成。
+- 纯通知任务不存在“人工终止”。
+
+## 6. Agent 技术异常如何返回？
+
+Agent 技术异常不应转换成 S10、人工复核或任何业务 Event。
+
+需要区分两种情况：
+
+### 业务参数不完整
+
+Agent 已经识别出具体业务类型，只是参数缺失或无法确定：
+
+```json
+{
+  "event_type": "UPDATE_BOOKING",
+  "manual_review": true
+}
+```
+
+这种情况正常回调信息系统并生成对应业务卡。
+
+### 技术异常
+
+例如：
+
+- Agent 输出不是合法 JSON；
+- 输出不符合 Schema；
+- Adapter 转换失败；
+- MCP 提交失败；
+- Agent 或 Skill 执行异常。
+
+这类情况不生成用户业务任务，也不回调一份伪装成正常业务结果的 Payload。
+
+如果系统需要记录，应走独立的技术失败状态、日志或告警通道，不进入 `message_events[]`，前端不展示预订任务卡。
+
+## 7. 附件字段以及 Payment 如何关联凭证？
+
+附件统一放在包级：
+
+```json
+{
+  "source_message": {
+    "attachments": [
+      {
+        "id": "att-1",
+        "name": "payment-slip.jpg",
+        "content_type": "image/jpeg",
+        "url": "https://upstream-storage/...",
+        "size": 251524
+      }
+    ]
+  }
+}
+```
+
+附件字段：
+
+| 字段 | 是否必需 | 说明 |
+|---|---|---|
+| `id` | 是 | 包内稳定附件引用 |
+| `name` | 是 | 原始文件名 |
+| `content_type` | 是 | MIME 类型 |
+| `url` | 是 | 上游邮件监听或文件存储层提供 |
+| `size` | 否 | 上游有值时原样传递 |
+
+Agent 只转发附件 URL，不负责生成、拼接或刷新 URL。
+
+Payment Event 使用附件 ID 指向具体凭证：
+
+```json
+{
+  "event_type": "PAYMENT",
+  "target_order": {},
+  "account_code": "ACCOUNT_CODE",
+  "attachment_ids": ["att-1", "att-2"],
+  "manual_review": null
+}
+```
+
+规则：
+
+- 多张付款凭证放在一个 Payment Event 中。
+- 凭证之间没有业务顺序。
+- Payment Event 不重复传文件名、URL或完整附件对象。
+- `attachment_ids` 是当前建议字段名，最终联调时需要与 Adapter/MCP Schema 冻结。
+
+## 8. Basic Information 的 Account、Market、Source 由谁提供？
+
+职责划分如下：
+
+- Agent 只输出 `account_code`。
+- Agent 可以根据邮件发件人识别 Account。
+- Market 和 Source 不由 Agent 输出。
+- 信息系统根据 Account 目录自动带出 Market 和 Source。
+
+```json
+{
+  "account_code": "ACCOUNT_CODE"
+}
+```
+
+如果 Agent 无法可靠确定 Account：
+
+```json
+{
+  "account_code": null,
+  "manual_review": true
+}
+```
+
+前端规则：
+
+- Account、Market、Source 都是信息系统已有目录中的受控选项。
+- 不允许自由文本输入，也不存在 Manual 选项。
+- 用户可以通过选择器修改 Account。
+- Account 改变后，信息系统自动带出对应的 Market 和 Source。
+- Market 和 Source 仍允许用户从信息系统已有值中改选。
+- Agent 不需要输出选项列表或 Account、Market、Source 的联动规则。
+
+## 开发结论
+
+前端可以按照以下关系建模：
+
+```text
+source_message
+    └── 提供邮件展示及附件资源
+
+message_events[]
+    ├── 每个具体业务 Event 都有 target_order
+    ├── 同一 target_order 聚合到同一订单
+    ├── 每个 Event 对应一张独立任务卡
+    └── 每张任务卡独立确认和维护状态
+
+S10
+    └── 只显示邮件展示卡
+```
+
+需要注意：`message_events`、S10 discriminator 和 `attachment_ids` 是当前建议字段名，正式联调前需要由 Agent、Adapter、MCP Schema 和信息系统入站接口统一冻结。