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

16
docs/project/requirements/M002-ai-query-minimal-fields.md
View File

@@ -32,7 +32,7 @@
- `body_current` 才能触发业务动作；`body_thread` 只能作为目标绑定证据。
- 如果查询 key 来自历史线程，调用方必须传 `target_key_source=body_thread_evidence` 和 `body_thread_used_only_as_evidence=true`。
- 第一版不伪造 OPERA 字段。当前系统没有可靠来源的字段返回 `null`，并在 `warnings` 或 `hard_validation_warnings` 中说明。
- SuperAgent 允许作为全局上下文查询方按任意业务 key 查询；`source_message_id` 和 `source_event_index` 只作为可选审计和排查字段，不作为查询边界。
- SuperAgent 允许作为全局上下文查询方按任意业务 key 查询；`source_message_id` 和 `source_event_index` 在查询阶段对本系统没有业务作用，第一版接收但忽略，不做格式校验，也不作为查询边界。
- 导入契约没有显式要求 `hotel_id`，但本系统订单、任务和 AI 过渡表均按 `hotel_id` 隔离。第一版请求体必须显式传 `hotel_id`。
## 3. Skill 对接口 1、2 的实际需要
@@ -120,7 +120,7 @@ POST
适用字段包括：
- `source_message_id`
- `source_message_id`，响应中的内部 SourceMessage Inbox ID；查询请求中若出现同名字段则视为 SuperAgent 透传字段，后端忽略
- `order_id`
- `task_id`
- `record_id`
@@ -141,8 +141,8 @@ POST /api/ai-query/v1/case-context
| 字段 | 是否必填 | 中文说明 | 当前系统来源或用途 |
| --- | --- | --- | --- |
| `hotel_id` | 是 | 酒店或业务上下文 ID | 用于隔离 `workflow_reservation_*` 表 |
| `source_message_id` | 否 | 当前 SourceMessage ID | 全局上下文查询可不传；传入时只做格式校验和排查辅助 |
| `source_event_index` | 否 | 当前 current 事件序号 | 全局上下文查询可不传；传入时必须为正整数 |
| `source_message_id` | 否 | SuperAgent 透传的外部来源消息 ID | 全局上下文查询可不传；传入时后端接收但忽略，不做格式校验 |
| `source_event_index` | 否 | SuperAgent 透传的 current 事件序号 | 全局上下文查询可不传；传入时后端接收但忽略，不做正整数校验 |
| `group_code` | 条件必填 | Group / Allotment 优先业务 key | 查询 `GROUP_CODE` 类型订单和 AI 过渡记录 |
| `confirmation_number` | 条件必填 | FIT 优先业务 key | 查询 `CONFIRMATION_NUMBER` 类型订单和 AI 过渡记录 |
| `reservation_no` | 否 | OPERA reservation no | 当前无可靠表源，第一版不作为主查询条件 |
@@ -185,7 +185,7 @@ POST /api/ai-query/v1/case-context
| --- | --- | --- | --- |
| `task_id` | 是 | 本系统任务 ID | `workflow_reservation_task.id` |
| `order_id` | 是 | 任务当前挂靠订单 | `workflow_reservation_task.order_id` |
| `source_message_id` | 是 | 任务来源消息 ID | `workflow_reservation_task.source_message_id` |
| `source_message_id` | 是 | 任务来源内部 SourceMessage Inbox ID | `workflow_reservation_task.source_message_id` |
| `source_event_index` | 是 | AI current 事件序号 | `workflow_reservation_ai_transition.source_event_index` |
| `catalog_code` | 否 | Skill 目录代码 | `workflow_reservation_ai_transition.catalog_code` |
| `skill_id` | 否 | Skill 标识 | `workflow_reservation_ai_transition.skill_id` |
@@ -203,6 +203,8 @@ POST /api/ai-query/v1/case-context
| `blocked_until_parent_completed` | 是 | 是否等待父任务完成 | `workflow_reservation_task.blocked_until_parent_completed` |
| `last_updated_at` | 是 | 最近更新时间 | `workflow_reservation_task.updated_at` |
说明：响应字段中的 `source_message_id` 来自 `workflow_reservation_task.source_message_id`，表示本系统内部 SourceMessage Inbox ID；它不同于查询请求和任务结果通知请求中 SuperAgent 透传的外部来源消息 ID。
第一版 `pending_or_open_tasks[]` 至少包含状态为 `PENDING_CONFIRM`、`READY`、`EXECUTING` 的任务。`FAILED` 在本系统第一版视为结束状态，不阻塞后续任务。
#### `active_workflows[]`
@@ -336,7 +338,7 @@ POST /api/ai-query/v1/object-detail
| `temporary_order_code` | 是 | 临时订单编号 | `workflow_reservation_order.temporary_order_code` |
| `display_name` | 是 | 用户可读展示名 | `workflow_reservation_order.display_name` |
| `status` | 是 | 订单状态 | `workflow_reservation_order.order_status` |
| `source_message_id` | 是 | 首次创建订单的来源消息 | `workflow_reservation_order.source_message_id` |
| `source_message_id` | 是 | 首次创建订单的内部 SourceMessage Inbox ID | `workflow_reservation_order.source_message_id` |
| `created_from_task_id` | 否 | 首次创建订单的任务 ID | `workflow_reservation_order.created_from_task_id` |
| `created_at` | 是 | 创建时间 | `workflow_reservation_order.created_at` |
| `last_updated_at` | 是 | 最近更新时间 | `workflow_reservation_order.updated_at` |
@@ -455,7 +457,7 @@ POST /api/ai-query/v1/object-detail
已落地能力：
- 接口 1 可按 `hotel_id + group_code` 或 `hotel_id + confirmation_number` 查询订单上下文，允许不传 `source_message_id` 和 `source_event_index` 的全局上下文查询。
- 接口 1 可按 `hotel_id + group_code` 或 `hotel_id + confirmation_number` 查询订单上下文，允许不传 `source_message_id` 和 `source_event_index` 的全局上下文查询；即使传入这两个字段，后端也不把它们作为查询或校验条件。
- 接口 1 返回 `matched_order_records`、`pending_or_open_tasks`、`active_workflows`、`terminated_records`、`target_object_validation` 和 `key_relationships`。
- `active_workflows` 当前无独立表源，固定返回空数组。
- 接口 2 支持 `ORDER:{order_id}` 查询本系统订单快照。

6
docs/project/requirements/M002-backend-checkpoint-plan.md
View File

@@ -89,7 +89,7 @@ Controller、Service、Service 实现类的方法必须有中文注释。Entity
目标：
- 建立 AI 接收批次表和 AI 过渡表。
- 保存 `source_message_id + ai_task_results[] + extraction_warnings[]`。
- 保存外部 `source_message_id + ai_task_results[] + extraction_warnings[]`，并将外部来源消息 ID 反查为内部 SourceMessage Inbox ID 后落业务表。
- 实现系统生成幂等键，保证重复提交不重复创建记录。
建议范围：
@@ -98,13 +98,13 @@ Controller、Service、Service 实现类的方法必须有中文注释。Entity
- Entity、Mapper、Repository。
- 批次幂等键生成。
- item 幂等键生成。
- `source_message_id` 存在性校验。
- 外部 `source_message_id` 存在性校验：通过 `hotel_id + provider + channel + external_message_id` 查找 SourceMessage Inbox。
- 保存 AI 原始 JSON 和常用物理列。
验收标准：
- 同一请求重复提交返回幂等重放，不重复插入。
- 同一 `source_message_id` 不同请求体第一版返回 `409`。
- 同一外部 `source_message_id` 不同请求体第一版返回 `409`。
- 每个 item 保存 `array_index`、`source_event_index` 和 `execution_order`。
- 保存 `ai_payload_json`，用户后续修改不得覆盖该字段。

7
docs/project/requirements/M002-order-task-workflow-v2.md
View File

@@ -82,7 +82,7 @@ AI 聚合输出的顶层结构应包含：
| 字段 | 中文说明 |
| --- | --- |
| `source_message_id` | 关联的 SourceMessage ID |
| `source_message_id` | SuperAgent / Main Agent 原样带回的外部来源消息 ID，对应 AgentBus `source.external_message_id`，不是本系统内部 SourceMessage Inbox 主键 |
| `ai_task_results[]` | AI 拆分出的一个或多个任务结果，顺序必须保留 |
| `extraction_warnings[]` | 抽取警告，不直接等同于业务任务 |
@@ -108,7 +108,7 @@ AI 聚合输出的顶层结构应包含：
| `additional_operations` | AI 建议的附加动作 |
| `idempotency_key` | 幂等键，最终来源和生成规则待确认 |
待补充的 HTTP 契约包括 URL、Method、Header、鉴权、幂等策略、错误响应格式、是否允许重复推送同一个 `source_message_id`。
HTTP 契约已在 `docs/project/requirements/M002-superagent-task-result-api-contract.md` 和 `docs/project/integrations/superagent-api-contract.md` 中补充。正式契约要求任务结果通知携带 `hotel_id + source_message_id`，其中 `source_message_id` 是外部来源消息 ID；后端会反查内部 SourceMessage Inbox ID 后再写入 `workflow_*` 表。
## 6. AI 过渡层数据要求
@@ -131,7 +131,7 @@ AI 聚合输出的顶层结构应包含：
| 物理列 | 中文说明 |
| --- | --- |
| `source_message_id` | 来源消息 ID |
| `source_message_id` | 内部 SourceMessage Inbox ID，来自外部 `source_message_id` 反查后的 `platform_source_message_inbox.id` |
| `source_event_index` | AI 事件序号 |
| `catalog_code` | Skill 目录代码 |
| `skill_id` | Skill 标识 |
@@ -484,6 +484,7 @@ Fallback 处理规则：
- SuperAgent 创建任务接口的 URL、Method、Header、鉴权和错误响应格式。
- SuperAgent 查询上下文接口 1、2 已实现最小字段版，并已启用与任务结果接收接口一致的 HMAC；接口 3 文件解析和接口 4 订单及任务查询仍需后续确认与实现，后续梳理未完成事项时必须持续提醒。
- SuperAgent 任务结果通知中的 `source_message_id` 已确认是外部来源消息 ID，对应 AgentBus `source.external_message_id`；查询接口中的 `source_message_id` 和 `source_event_index` 第一版接收但忽略。
- `source_event_index`、批次 item index、`execution_order` 的最终编号规则是否都从 1 开始。
- SuperAgent 查询上下文接口 3、4 的 URL、入参、返回字段和鉴权方式。
- `Message Notification` 是否需要在前端订单列表上单独标识为只读提醒。

47
docs/project/requirements/M002-superagent-task-result-api-contract.md
View File

@@ -4,7 +4,7 @@
| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.1 |
| 文档版本 | 0.2 |
| 日期 | 2026-07-07 |
| 状态 | 后端接口契约草稿 |
| 适用范围 | SuperAgent / Main Agent 调用本系统提交 AI 任务结果 |
@@ -34,6 +34,21 @@
- SuperAgent 不直连数据库，只能通过本接口提交任务结果。
- 本接口只做技术校验和系统接收，不替代用户确认和 OPERA 模拟操作。
### 2.1 SourceMessage ID 口径
本接口请求体中的 `source_message_id` 是 SuperAgent / Main Agent 从通用溯源字段中原样带回的外部来源消息 ID，对应 AgentBus 邮件 payload 的 `source.external_message_id`，不是 `platform_source_message_inbox.id`。
后端正式处理路径：
```text
hotel_id + source_provider(默认 AGENTBUS) + source_channel(默认 EMAIL) + source_message_id
→ platform_source_message_inbox.external_message_id
→ platform_source_message_inbox.id
→ workflow_* 表 source_message_id 内部外键
```
数据库 `workflow_*` 表中的 `source_message_id` 仍然保存内部 SourceMessage Inbox ID。只有对外接口的 `source_message_id` 使用外部来源消息 ID。无 `hotel_id` 时仅兼容本地旧夹具使用内部数字 ID，正式 SuperAgent 调用不得依赖该兼容路径。
## 3. 鉴权方案
第一版使用 HMAC-SHA256 签名，做到简单、可实现、可防重放。
@@ -106,7 +121,8 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
```json
{
"source_message_id": "1900000000000000001",
"hotel_id": "HOTEL-TEST",
"source_message_id": "mail-20260708-0001",
"ai_task_results": [
{
"source_event_index": 1,
@@ -140,7 +156,10 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| 字段 | 是否必填 | 中文说明 |
| --- | --- | --- |
| `source_message_id` | 是 | 关联本系统 SourceMessage ID；一次请求只能有一个 |
| `hotel_id` | 是 | 酒店上下文 ID，用于反查 SourceMessage Inbox 幂等键 |
| `source_message_id` | 是 | 外部来源消息 ID，对应 AgentBus `source.external_message_id`；一次请求只能有一个 |
| `source_provider` | 否 | 来源提供方，第一版缺省为 `AGENTBUS` |
| `source_channel` | 否 | 来源渠道，第一版缺省为 `EMAIL` |
| `ai_task_results[]` | 是 | AI 拆分出的任务结果列表，必须保留数组顺序 |
| `extraction_warnings[]` | 否 | 抽取警告；不直接等同于业务任务 |
@@ -177,8 +196,9 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
- 鉴权签名合法。
- 请求体大小不超过限制。
- JSON 可解析。
- `hotel_id` 存在。仅本地旧夹具兼容缺少 `hotel_id` 且 `source_message_id` 为内部数字 ID 的调用。
- 顶层只有一个 `source_message_id`。
- `source_message_id` 对应的 SourceMessage 存在。
- `source_message_id` 对应的外部来源消息已经写入 SourceMessage Inbox。
- `ai_task_results[]` 是非空数组。
- `result_type` 属于允许值。
- `task_type` 属于当前系统可识别的稳定值或可进入 Fallback 处理。
@@ -214,7 +234,7 @@ request_payload_sha256 = sha256(raw_request_body)
batch_idempotency_key =
sha256(
"superagent-task-result-batch:v1"
+ "|" + source_message_id
+ "|" + source_message_internal_id
+ "|" + request_payload_sha256
)
```
@@ -222,7 +242,7 @@ sha256(
作用：
- 相同请求体重复提交时识别为幂等重放。
- 同一个 `source_message_id` 如果提交了不同请求体，不会被误认为同一个批次。
- 同一个外部 `source_message_id` 解析到的内部 SourceMessage 如果提交了不同请求体，不会被误认为同一个批次。
### 6.3 item 幂等键
@@ -232,7 +252,7 @@ sha256(
item_idempotency_key =
sha256(
"superagent-task-result-item:v1"
+ "|" + source_message_id
+ "|" + source_message_internal_id
+ "|" + source_event_index
+ "|" + array_index
+ "|" + catalog_code
@@ -255,7 +275,7 @@ sha256(
| 场景 | 处理方式 |
| --- | --- |
| 完全相同请求体重复提交 | 返回已有 batch 和 item，不重复创建任务 |
| 同一 `source_message_id` 不同请求体 | 作为潜在冲突处理，第一版建议拒绝并返回 `IDEMPOTENCY_CONFLICT`，除非后续明确支持重新抽取版本 |
| 同一外部 `source_message_id` 不同请求体 | 作为潜在冲突处理，第一版建议拒绝并返回 `IDEMPOTENCY_CONFLICT`，除非后续明确支持重新抽取版本 |
| 同一请求内 item 幂等键重复 | 拒绝请求，返回 `DUPLICATE_TASK_RESULT_ITEM` |
## 7. 系统映射规则
@@ -286,7 +306,7 @@ sha256(
```json
{
"request_id": "req-20260707-0001",
"source_message_id": "1900000000000000001",
"source_message_id": "mail-20260708-0001",
"batch_id": "1900000000000001001",
"idempotent_replay": false,
"accepted_count": 1,
@@ -315,7 +335,7 @@ sha256(
```json
{
"request_id": "req-20260707-0002",
"source_message_id": "1900000000000000001",
"source_message_id": "mail-20260708-0001",
"batch_id": "1900000000000001001",
"idempotent_replay": true,
"accepted_count": 1,
@@ -352,8 +372,9 @@ sha256(
| 409 | `AUTH_NONCE_REPLAY` | Nonce 重放 |
| 413 | `REQUEST_BODY_TOO_LARGE` | 请求体过大 |
| 400 | `INVALID_JSON` | JSON 不可解析 |
| 400 | `HOTEL_ID_REQUIRED` | 使用外部 `source_message_id` 时缺少 `hotel_id` |
| 400 | `SOURCE_MESSAGE_REQUIRED` | `source_message_id` 缺失 |
| 404 | `SOURCE_MESSAGE_NOT_FOUND` | SourceMessage 不存在 |
| 404 | `SOURCE_MESSAGE_NOT_FOUND` | 外部来源消息尚未写入 SourceMessage Inbox |
| 400 | `TASK_RESULTS_EMPTY` | `ai_task_results[]` 为空 |
| 400 | `TASK_RESULT_UNSUPPORTED_TYPE` | `result_type` 或 `task_type` 不可识别 |
| 400 | `DUPLICATE_TASK_RESULT_ITEM` | 同一请求内 item 重复 |
@@ -371,8 +392,8 @@ sha256(
- nonce 重放时返回 `409`。
- 签名错误时返回 `401`。
- 一个请求只能包含一个 `source_message_id`。
- `source_message_id` 不存在时返回 `404`。
- 外部 `source_message_id` 未匹配 SourceMessage Inbox 时返回 `404`。
- 相同请求重复提交不会重复创建任务。
- 同一 `source_message_id` 不同请求体重复提交返回 `409`。
- 同一外部 `source_message_id` 不同请求体重复提交返回 `409`。
- 成功接收后能保存 AI 过渡层记录，并返回 batch、task 和 order 标识。
- 日志和响应不暴露 secret、签名原文、完整邮件正文或附件 URL。