落定M002 V4 Agent回调字段契约

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 和信息系统入站接口统一冻结。