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