# 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。