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

增加 SuperAgent 邮件会话查询接口

Browse Source
This commit is contained in:
andy
2026-07-09 15:25:26 +08:00
parent 6d2b3e8ccd
commit 0727dfb8d0
10 changed files with 1039 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -4,10 +4,10 @@
| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.2 |
| 日期 | 2026-07-08 |
| 状态 | 第一版后端已实现接口契约 |
| 适用范围 | SuperAgent 调用本系统查询上下文、提交 AI 任务结果 |
| 文档版本 | 0.3 |
| 日期 | 2026-07-09 |
| 状态 | 已增加邮件会话任务和受控正文查询接口 |
| 适用范围 | SuperAgent 调用本系统查询上下文、查询邮件会话、提交 AI 任务结果 |
| 主要读者 | SuperAgent 对接方、后端、测试、运维 |
## 联调参数区
@@ -17,7 +17,7 @@
| 参数 | 当前联调值 | 中文说明 |
| --- | --- | --- |
| `TH_HOTEL_API_BASE_URL` | `http://8.138.234.141:18087` | 本系统后端基础地址；本地联调用 8080，部署环境改为实际网关或服务地址。 |
| `HOTEL_ID` | `HOTEL-DEV` | 当前 dev profile 下 AgentBus 入库默认酒店 ID；调用三个 SuperAgent 接口时均应传入请求体 `hotel_id`。 |
| `HOTEL_ID` | `HOTEL-DEV` | 当前 dev profile 下 AgentBus 入库默认酒店 ID；调用五个 SuperAgent 接口时均应传入请求体 `hotel_id`。 |
| `SUPERAGENT_CLIENT_ID` | `superagent-debug` | SuperAgent 调用方 ID，对应 Header `X-TH-Hotel-SuperAgent-Client-Id`。 |
| `SUPERAGENT_HMAC_SECRET` | `th-hotel-superagent-debug-20260709-change-before-prod` | dev/test 联调临时 HMAC 密钥；生产上线前必须更换为新的高强度随机密钥。 |
@@ -103,6 +103,8 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
查询接口 1、2 在 SuperAgent 查询阶段不依赖当前邮件是否已经入库。若请求体兼容旧契约传入 `source_message_id` 或 `source_event_index`，第一版后端会接收但忽略，不校验它们的格式，也不把它们作为查询边界。
查询接口 3、4 面向已经入库的邮件会话：`external_conversation_id` 按 `hotel_id + source_provider + source_channel + external_conversation_id` 查询；`source_message_id` 表示外部来源消息 ID，可作为锚点反查该邮件所属会话。
## 4. 接口 1：查询订单上下文
### 4.1 请求
@@ -265,10 +267,171 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
说明：接口 2 响应中的 `source_message_id` 当前是本系统内部 SourceMessage Inbox ID，用于对象溯源和排查；不要把该字段当作 SuperAgent 任务结果通知接口的外部 `source_message_id` 使用。
## 6. 接口 3：SuperAgent 通知 AI 任务结果
## 6. 接口 3：查询邮件会话下所有任务
### 6.1 请求
| 项目 | 内容 |
| --- | --- |
| Method | `POST` |
| URL | `{TH_HOTEL_API_BASE_URL}/api/ai-query/v1/message-conversation/tasks` |
| request_path | `/api/ai-query/v1/message-conversation/tasks` |
| Content-Type | `application/json` |
| 业务动作 | 只读查询邮件会话下任务，不创建任务、不修改订单、不写 OPERA |
### 6.2 请求体
按外部邮件会话 ID 查询：
```json
{
"hotel_id": "<HOTEL_ID>",
"source_provider": "AGENTBUS",
"source_channel": "EMAIL",
"external_conversation_id": "thread-20260708-0001"
}
```
按外部来源消息 ID 作为锚点反查会话：
```json
{
"hotel_id": "<HOTEL_ID>",
"source_provider": "AGENTBUS",
"source_channel": "EMAIL",
"source_message_id": "mail-20260708-0001"
}
```
字段说明：
| 字段 | 是否必填 | 中文说明 |
| --- | --- | --- |
| `hotel_id` | 是 | 酒店上下文 ID |
| `source_provider` | 否 | 来源提供方，按会话 ID 查询和按 `source_message_id` 反查时都参与隔离，缺省为 `AGENTBUS` |
| `source_channel` | 否 | 来源渠道，按会话 ID 查询和按 `source_message_id` 反查时都参与隔离，缺省为 `EMAIL` |
| `external_conversation_id` | 条件必填 | 外部邮件会话 ID，对应 AgentBus `source.external_conversation_id` |
| `source_message_id` | 条件必填 | 外部来源消息 ID，对应 AgentBus `source.external_message_id`，不是内部 Inbox ID |
`external_conversation_id`、`source_message_id` 至少一个非空。两者同时传入时，第一版以后端直接按 `external_conversation_id` 查询为准。
### 6.3 成功响应
```json
{
"success": true,
"request_id": "req-003",
"trace_id": "trace-001",
"data": {
"hotel_id": "HOTEL-DEV",
"external_conversation_id": "thread-20260708-0001",
"task_count": 2,
"tasks": [
{
"task_id": "1900000000000000400",
"order_id": "1900000000000000300",
"external_source_message_id": "mail-20260708-0001",
"external_conversation_id": "thread-20260708-0001",
"source_received_at": "2026-07-08T01:00:00Z",
"source_event_index": 1,
"catalog_code": "S02",
"skill_id": "update_booking_amendment_skill",
"result_type": "normal_task",
"task_type": "Update Booking",
"system_task_type": "UPDATE_BOOKING",
"task_card_type": "UPDATE_BOOKING",
"task_subtype": "update_stay_dates",
"task_status": "PENDING_CONFIRM",
"queue_participation": true,
"execution_order": 1,
"parent_task_id": null,
"parent_source_event_index": null,
"linked_task_group_id": null,
"blocked_until_parent_completed": false,
"completed_at": null,
"task_created_at": "2026-07-08T01:01:00Z",
"task_updated_at": "2026-07-08T01:01:00Z"
}
]
},
"warnings": [],
"error": null
}
```
排序规则：
1. 先按邮件 `received_at` 正序。
2. 同一封邮件下，再按任务 `created_at` 正序。
3. 若时间相同，再按 `task_id` 正序稳定排序。
## 7. 接口 4：查询邮件会话下所有受控正文
### 7.1 请求
| 项目 | 内容 |
| --- | --- |
| Method | `POST` |
| URL | `{TH_HOTEL_API_BASE_URL}/api/ai-query/v1/message-conversation/messages` |
| request_path | `/api/ai-query/v1/message-conversation/messages` |
| Content-Type | `application/json` |
| 业务动作 | 只读查询邮件会话受控正文，不返回附件 URL 或原始未清洗 HTML |
### 7.2 请求体
请求体字段与接口 3 相同，可按 `external_conversation_id` 查询，也可按外部 `source_message_id` 锚点反查会话。
```json
{
"hotel_id": "<HOTEL_ID>",
"source_provider": "AGENTBUS",
"source_channel": "EMAIL",
"source_message_id": "mail-20260708-0001"
}
```
### 7.3 成功响应
```json
{
"success": true,
"request_id": "req-004",
"trace_id": "trace-001",
"data": {
"hotel_id": "HOTEL-DEV",
"external_conversation_id": "thread-20260708-0001",
"message_count": 2,
"messages": [
{
"external_source_message_id": "mail-20260708-0001",
"external_conversation_id": "thread-20260708-0001",
"sender_summary": "guest@example.test",
"subject": "Booking update",
"received_at": "2026-07-08T01:00:00Z",
"source_sent_at": "2026-07-08T00:59:00Z",
"text_body": "Please update arrival date...",
"html_body_sanitized": "<html><body>Please update arrival date...</body></html>",
"html_sanitize_required": true,
"html_render_mode": "SANITIZED_HTML"
}
]
},
"warnings": [],
"error": null
}
```
安全边界：
- `messages[]` 按邮件 `received_at` 正序返回。
- 不返回 `html_body` 原始未清洗 HTML。
- 不返回 `attachments`、`inline_images`、`external_url`、附件 URL 或 HTML 中的 `href/src` 外链属性。
- 后端读取正文时会写入 SourceMessage 原文访问审计。
## 8. 接口 5：SuperAgent 通知 AI 任务结果
### 8.1 请求
| 项目 | 内容 |
| --- | --- |
| Method | `POST` |
@@ -277,7 +440,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
| Content-Type | `application/json` |
| 业务动作 | 接收 AI 任务结果，写入 AI 过渡层、订单、任务和任务卡 |
### 6.2 请求体
### 8.2 请求体
```json
{
@@ -332,7 +495,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
正式联调时，后端通过 `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 成功响应
### 8.3 成功响应
```json
{
@@ -359,9 +522,9 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
}
```
## 7. 错误响应
## 9. 错误响应
### 7.1 查询接口错误响应
### 9.1 查询接口错误响应
```json
{
@@ -378,7 +541,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
}
```
### 7.2 任务结果通知接口错误响应
### 9.2 任务结果通知接口错误响应
```json
{
@@ -389,7 +552,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
}
```
### 7.3 常见错误码
### 9.3 常见错误码
| 错误码 | HTTP 状态 | 中文说明 |
| --- | --- | --- |
@@ -402,11 +565,13 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
| `REQUEST_CONTENT_TYPE_UNSUPPORTED` | 415 | `Content-Type` 不是 `application/json` |
| `REQUEST_BODY_INVALID` | 400 | JSON 不合法 |
| `QUERY_KEY_REQUIRED` | 400 | 查询接口缺少可用业务 key |
| `MESSAGE_CONVERSATION_QUERY_KEY_REQUIRED` | 400 | 会话查询缺少 `external_conversation_id` 或 `source_message_id` |
| `OBJECT_NOT_FOUND` | 404 | 对象详情查询目标不存在 |
| `HOTEL_ID_REQUIRED` | 400 | 三个 SuperAgent 接口缺少必填 `hotel_id` |
| `SOURCE_MESSAGE_NOT_FOUND` | 404 | 任务结果通知引用的外部来源消息尚未写入 SourceMessage Inbox |
| `MESSAGE_CONVERSATION_NOT_FOUND` | 404 | 外部邮件会话尚未写入 SourceMessage Inbox |
| `HOTEL_ID_REQUIRED` | 400 | 五个 SuperAgent 接口缺少必填 `hotel_id` |
| `SOURCE_MESSAGE_NOT_FOUND` | 404 | 任务结果通知或会话锚点引用的外部来源消息尚未写入 SourceMessage Inbox |
## 8. HMAC 上线配置
## 10. HMAC 上线配置
上线需要配置：