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