huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

修正 SuperAgent 来源消息 ID 契约

Browse Source
This commit is contained in:
andy
2026-07-08 11:12:11 +08:00
parent fb82386fdb
commit b58c6baafe
12 changed files with 254 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/project/integrations/superagent-api-contract.md
View File

@@ -4,7 +4,7 @@
| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.1 |
| 文档版本 | 0.2 |
| 日期 | 2026-07-08 |
| 状态 | 第一版后端已实现接口契约 |
| 适用范围 | SuperAgent 调用本系统查询上下文、提交 AI 任务结果 |
@@ -73,9 +73,22 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
8. 查询接口校验 `Content-Type` 是否为 `application/json`。
9. 鉴权和协议校验通过后再解析业务 JSON。
## 3. 接口 1：查询订单上下文
## 3. SourceMessage ID 口径
### 3.1 请求
本系统存在两个容易混淆的 ID：
| 名称 | 中文说明 | 使用位置 |
| --- | --- | --- |
| 外部来源消息 ID | AgentBus 邮件 payload 中的 `source.external_message_id`，SuperAgent / Main Agent 在最终 JSON 中原样带回为 `source_message_id` | SuperAgent 任务结果通知接口入参和响应回显 |
| 内部 SourceMessage Inbox ID | `platform_source_message_inbox.id`，本系统数据库内部主键 | `workflow_*` 表的 `source_message_id` 外键、前端和运维排查 |
SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通知接口收到外部 `source_message_id` 后，后端使用 `hotel_id + provider + channel + external_message_id` 反查内部 Inbox 记录，再用内部 ID 写入业务表。
查询接口 1、2 在 SuperAgent 查询阶段不依赖当前邮件是否已经入库。若请求体兼容旧契约传入 `source_message_id` 或 `source_event_index`，第一版后端会接收但忽略，不校验它们的格式，也不把它们作为查询边界。
## 4. 接口 1：查询订单上下文
### 4.1 请求
| 项目 | 内容 |
| --- | --- |
@@ -85,13 +98,11 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| Content-Type | `application/json` |
| 业务动作 | 只读查询，不创建任务、不修改订单、不写 OPERA |
### 3.2 请求体
### 4.2 请求体
```json
{
"hotel_id": "HOTEL-TEST",
"source_message_id": "1900000000000000001",
"source_event_index": 1,
"group_code": "GRP-001",
"confirmation_number": null,
"reservation_no": null,
@@ -106,8 +117,6 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| 字段 | 是否必填 | 中文说明 |
| --- | --- | --- |
| `hotel_id` | 是 | 酒店上下文 ID |
| `source_message_id` | 否 | 当前 SourceMessage ID；全局上下文查询时可不传，只作为审计和排查字段 |
| `source_event_index` | 否 | 当前 AI 事件序号；全局上下文查询可不传，传入时必须为正整数 |
| `group_code` | 条件必填 | Group / Allotment 查询 key |
| `confirmation_number` | 条件必填 | FIT Confirmation Number 查询 key |
| `reservation_no` | 条件必填 | OPERA reservation no；当前系统无可靠表源，只传该字段时会返回人工复核原因 |
@@ -117,9 +126,9 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
`group_code`、`confirmation_number`、`reservation_no` 至少一个非空。当前稳定查询能力优先支持 `group_code` 和 `confirmation_number`。
全局上下文查询只依赖 `hotel_id + 业务 key`；`source_message_id` 和 `source_event_index` 仅用于审计、追踪或排查，不作为查询边界。
全局上下文查询只依赖 `hotel_id + 业务 key`；`source_message_id` 和 `source_event_index` 不作为查询边界，传入时也不会影响查询结果。
### 3.3 成功响应
### 4.3 成功响应
```json
{
@@ -152,7 +161,7 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
}
```
### 3.4 主要数据来源
### 4.4 主要数据来源
| 返回字段 | 来源 |
| --- | --- |
@@ -161,9 +170,9 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| `terminated_records[]` | 订单 `ENDED` / `LOGIC_DELETED`，任务 `FAILED` / `COMPLETED` |
| `active_workflows[]` | 当前无独立 workflow 表，固定空数组 |
## 4. 接口 2：查询对象详情
## 5. 接口 2：查询对象详情
### 4.1 请求
### 5.1 请求
| 项目 | 内容 |
| --- | --- |
@@ -173,7 +182,7 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| Content-Type | `application/json` |
| 业务动作 | 只读查询对象详情，不创建任务、不修改订单、不写 OPERA |
### 4.2 请求体
### 5.2 请求体
```json
{
@@ -191,7 +200,7 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| `object_id` | 是 | 查询对象 ID，第一版只支持 `ORDER:{order_id}` |
| `object_type` | 否 | 调用方对象类型提示，第一版不作为强校验 |
### 4.3 成功响应
### 5.3 成功响应
```json
{
@@ -237,9 +246,11 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
}
```
## 5. 接口 3：SuperAgent 通知 AI 任务结果
说明：接口 2 响应中的 `source_message_id` 当前是本系统内部 SourceMessage Inbox ID，用于对象溯源和排查；不要把该字段当作 SuperAgent 任务结果通知接口的外部 `source_message_id` 使用。
### 5.1 请求
## 6. 接口 3：SuperAgent 通知 AI 任务结果
### 6.1 请求
| 项目 | 内容 |
| --- | --- |
@@ -249,11 +260,12 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| Content-Type | `application/json` |
| 业务动作 | 接收 AI 任务结果，写入 AI 过渡层、订单、任务和任务卡 |
### 5.2 请求体
### 6.2 请求体
```json
{
"source_message_id": "1900000000000000001",
"hotel_id": "HOTEL-TEST",
"source_message_id": "mail-20260708-0001",
"ai_task_results": [
{
"source_event_index": 1,
@@ -287,7 +299,10 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| 字段 | 是否必填 | 中文说明 |
| --- | --- | --- |
| `source_message_id` | 是 | 本系统 SourceMessage ID，一次请求只能有一个 |
| `hotel_id` | 是 | 酒店上下文 ID，用于反查 SourceMessage Inbox 幂等键 |
| `source_message_id` | 是 | SuperAgent / Main Agent 原样带回的外部来源消息 ID，对应 AgentBus `source.external_message_id`，一次请求只能有一个 |
| `source_provider` | 否 | 来源提供方，第一版缺省为 `AGENTBUS` |
| `source_channel` | 否 | 来源渠道，第一版缺省为 `EMAIL` |
| `ai_task_results[]` | 是 | AI 拆分出的任务结果列表，必须保留数组顺序 |
| `ai_task_results[].source_event_index` | 是 | AI current 事件序号 |
| `ai_task_results[].catalog_code` | 是 | Skill 目录代码 |
@@ -298,12 +313,14 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| `ai_task_results[].case_keys` | 否 | 订单关联候选键 |
| `ai_task_results[].extracted_fields` | 否 | 业务字段主体 |
### 5.3 成功响应
正式联调时，后端通过 `hotel_id + source_provider(默认 AGENTBUS) + source_channel(默认 EMAIL) + source_message_id` 查找 `platform_source_message_inbox.external_message_id`。如果没有找到，返回 `SOURCE_MESSAGE_NOT_FOUND`。本地旧夹具允许在缺少 `hotel_id` 时使用内部数字 SourceMessage ID，但该兼容路径不作为 SuperAgent 正式契约。
### 6.3 成功响应
```json
{
"request_id": "req-003",
"source_message_id": "1900000000000000001",
"source_message_id": "mail-20260708-0001",
"batch_id": "1900000000000000200",
"idempotent_replay": false,
"accepted_count": 1,
@@ -324,9 +341,9 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
}
```
## 6. 错误响应
## 7. 错误响应
### 6.1 查询接口错误响应
### 7.1 查询接口错误响应
```json
{
@@ -343,7 +360,7 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
}
```
### 6.2 任务结果通知接口错误响应
### 7.2 任务结果通知接口错误响应
```json
{
@@ -354,7 +371,7 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
}
```
### 6.3 常见错误码
### 7.3 常见错误码
| 错误码 | HTTP 状态 | 中文说明 |
| --- | --- | --- |
@@ -368,9 +385,10 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| `REQUEST_BODY_INVALID` | 400 | JSON 不合法 |
| `QUERY_KEY_REQUIRED` | 400 | 查询接口缺少可用业务 key |
| `OBJECT_NOT_FOUND` | 404 | 对象详情查询目标不存在 |
| `SOURCE_MESSAGE_NOT_FOUND` | 400 | 任务结果通知引用的 SourceMessage 不存在 |
| `HOTEL_ID_REQUIRED` | 400 | 任务结果通知使用外部 `source_message_id` 时缺少 `hotel_id` |
| `SOURCE_MESSAGE_NOT_FOUND` | 404 | 任务结果通知引用的外部来源消息尚未写入 SourceMessage Inbox |
## 7. HMAC 上线配置
## 8. HMAC 上线配置
上线需要配置：