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-12 14:53:54 +08:00
parent bf796946f9
commit eee37315a0
18 changed files with 789 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/project/go-live-notes.md
View File

@@ -131,6 +131,7 @@
| `SUPERAGENT_TASK_RESULT_CLOCK_SKEW_SECONDS` | 否 | 请求时间允许偏移，默认 `300` 秒。上线前确认本系统、SuperAgent 和 AgentBus 所在机器时间已通过 NTP 同步。 |
| `SUPERAGENT_TASK_RESULT_NONCE_TTL_SECONDS` | 否 | nonce 防重放窗口，默认 `600` 秒。 |
| `SUPERAGENT_TASK_RESULT_MAX_BODY_BYTES` | 否 | SuperAgent 入站请求体最大字节数，默认 `1048576`。 |
| `SUPERAGENT_TEST_ALLOW_LEGACY_INTERNAL_SOURCE_MESSAGE_ID` | 否 | 仅用于本地 / test 旧夹具兼容内部 SourceMessage ID；正式联调和生产不得开启。 |
注意：

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

@@ -99,7 +99,7 @@ X-TH-Hotel-SuperAgent-Signature: sha256=<lowercase-hex-signature>
| 外部来源消息 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 写入业务表。
SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID，也不需要为任务结果通知传数据库层 provider/channel。任务结果通知接口收到外部 `source_message_id` 后，后端先解析系统酒店，再使用 `hotel_id + external_message_id` 反查唯一 Inbox 记录，最后用内部 ID 写入业务表；真实 provider/channel 以 SourceMessage Inbox 入库值为准。
查询接口 1、2 在 SuperAgent 查询阶段不依赖当前邮件是否已经入库。若请求体兼容旧契约传入 `source_message_id` 或 `source_event_index`，第一版后端会接收但忽略，不校验它们的格式，也不把它们作为查询边界。
@@ -626,8 +626,8 @@ V3 字段说明：
| --- | --- | --- |
| `hotel_id` | 否 | 酒店上下文 ID；SuperAgent 默认不传，后端解析系统酒店后用于反查 SourceMessage Inbox 幂等键。若兼容旧契约传入，单酒店阶段必须与系统酒店一致。 |
| `source_message_id` | 是 | SuperAgent / Main Agent 原样带回的外部来源消息 ID，对应 AgentBus `source.external_message_id`，一次请求只能有一个 |
| `source_provider` | 否 | 来源提供方，第一版缺省为 `AGENTBUS` |
| `source_channel` | 否 | 来源渠道，第一版缺省为 `EMAIL` |
| `source_provider` | 否 | V2 兼容字段；通常不传。写入定位不使用该字段，真实 provider 以 SourceMessage Inbox 入库值为准 |
| `source_channel` | 否 | V2 兼容字段；通常不传。写入定位不使用该字段，AgentBus 邮件真实入库渠道可能是 `OUTLOOK` |
| `ai_task_results[]` | 是 | AI 拆分出的任务结果列表，必须保留数组顺序 |
| `ai_task_results[].source_event_index` | 是 | AI current 事件序号 |
| `ai_task_results[].catalog_code` | 是 | Skill 目录代码 |
@@ -638,7 +638,7 @@ V3 字段说明：
| `ai_task_results[].case_keys` | 否 | 订单关联候选键 |
| `ai_task_results[].extracted_fields` | 否 | 业务字段主体 |
正式联调时，SuperAgent 不需要传 `hotel_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 正式契约。
正式联调时，SuperAgent 不需要传 `hotel_id`。后端通过系统酒店和外部 `source_message_id` 查找唯一 `platform_source_message_inbox.external_message_id`，真实 provider/channel 以 Inbox 入库值为准。如果没有找到，返回 `SOURCE_MESSAGE_NOT_FOUND`；如果同一系统酒店下匹配到多条，返回 `SOURCE_MESSAGE_AMBIGUOUS`。本地旧夹具允许在缺少 `hotel_id` 时使用内部数字 SourceMessage ID，但该兼容路径不作为 SuperAgent 正式契约。
`informational_message` 结构化任务仅用于历史兼容。新数据如果是纯信息类邮件或无法形成业务素材包，应优先使用 V3 结构化 `S10/S99`；旧联调或兼容场景仍可使用下面的 `S000/S999` 文本请求体。
@@ -664,7 +664,7 @@ S999,mail-20260708-0001
| `S999` | 入口阶段无法形成业务素材包，不需要进入业务执行。 |
| `mail-20260708-0001` | 外部来源消息 ID，对应 SourceMessage Inbox 的 `external_message_id`。 |
S000/S999 不在 body 里传 `hotel_id`，后端使用平台酒店表唯一 `ACTIVE` 酒店查询 SourceMessage Inbox。命中后创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务：任务列表可见，订单列表不可见，不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA，也不参与同订单任务执行顺序阻塞。该文本格式仅为兼容路径，新数据优先使用结构化 `S10/S99`。
S000/S999 不在 body 里传 `hotel_id`，后端使用平台酒店表唯一 `ACTIVE` 酒店和外部消息 ID 查询 SourceMessage Inbox。命中后创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务：任务列表可见，订单列表不可见，不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA，也不参与同订单任务执行顺序阻塞。该文本格式仅为兼容路径，新数据优先使用结构化 `S10/S99`。
### 8.6 成功响应
@@ -796,6 +796,7 @@ V3 `adapter_contract_error` 响应中的 `items[]` 不会包含 `order_id` / `ta
| `SYSTEM_HOTEL_AMBIGUOUS` | 409 | 单酒店阶段平台酒店表存在多家 `ACTIVE` 酒店 |
| `HOTEL_ACCESS_DENIED` | 403 | 显式传入的 `hotel_id` 与系统酒店或当前用户授权酒店不一致 |
| `SOURCE_MESSAGE_NOT_FOUND` | 404 | 任务结果通知或会话锚点引用的外部来源消息尚未写入 SourceMessage Inbox |
| `SOURCE_MESSAGE_AMBIGUOUS` | 409 | 任务结果通知的外部来源消息在同一系统酒店下匹配到多条 Inbox 记录，后端拒绝随机选择 |
| `missing_source_message_id` | 400 | V3 请求缺少 `source_message.source_message_id`，响应体为 typed `infrastructure_input_error` |
## 10. HMAC 上线配置
@@ -811,6 +812,7 @@ V3 `adapter_contract_error` 响应中的 `items[]` 不会包含 `order_id` / `ta
| `SUPERAGENT_TASK_RESULT_CLOCK_SKEW_SECONDS` | 否 | 请求时间允许偏移，默认 `300` 秒 |
| `SUPERAGENT_TASK_RESULT_NONCE_TTL_SECONDS` | 否 | nonce 防重放保存时间，默认 `600` 秒 |
| `SUPERAGENT_TASK_RESULT_MAX_BODY_BYTES` | 否 | 请求体最大字节数，默认 `1048576` |
| `SUPERAGENT_TEST_ALLOW_LEGACY_INTERNAL_SOURCE_MESSAGE_ID` | 否 | 仅 test 本地旧夹具兼容内部 SourceMessage ID；正式 dev / test 联调和 prod 不应开启 |
上线注意事项：

2
docs/project/integrations/superagent-mcp/integration-guide.md
View File

@@ -130,6 +130,8 @@ REST request
5. 必要时调用 `th_hotel_list_message_conversation_tasks` 查询同一邮件会话下已有任务。
6. 最终只在明确产出任务结果时调用 `th_hotel_submit_task_results`。
写入工具里的 `source_message_id` 必须来自 AgentBus payload 的 `source.external_message_id`。SuperAgent 不需要传数据库层 provider/channel；TH Hotel 后端按系统酒店和外部消息 ID 匹配唯一 SourceMessage Inbox，真实 channel 可能是 `OUTLOOK`。
## 9. 当前 checkpoint
当前 checkpoint：

2
docs/project/integrations/superagent-mcp/test-cases.md
View File

@@ -91,6 +91,8 @@
| MCP-T05-005 | 缺省 hotel id | 不传 `hotel_id`，source message 属于系统酒店 | 后端按系统唯一 ACTIVE 酒店写入成功 |
| MCP-T05-006 | 重复提交同一幂等任务 | 使用相同幂等信息 | 不重复创建业务任务 |
| MCP-T05-007 | hotel id 不一致 | 显式传非系统酒店 `hotel_id` | 返回 `HOTEL_ID_MISMATCH` |
| MCP-T05-008 | source message 入库渠道为 OUTLOOK | 不传 `source_channel`，只传外部 `source_message_id` | 后端按真实 Inbox 渠道写入成功 |
| MCP-T05-009 | source message 多渠道重复 | 同一酒店存在相同外部 `source_message_id` 的多条 Inbox | 返回 `SOURCE_MESSAGE_AMBIGUOUS` |
写入验证：

11
docs/project/integrations/superagent-mcp/tools.md
View File

@@ -18,8 +18,8 @@
| 字段 | 默认值 | 中文说明 |
| --- | --- | --- |
| `hotel_id` | 后端解析 | SuperAgent 默认不传；单酒店阶段由 TH Hotel 后端从 `platform_hotel` 唯一 `ACTIVE` 酒店解析，兼容旧调用传入时必须与系统酒店一致。 |
| `source_provider` | `AGENTBUS` | 来源提供方 |
| `source_channel` | `EMAIL` | 来源渠道 |
| `source_provider` | 通常不传 | 查询类工具可作为隔离条件；写入工具不要求 SuperAgent 传数据库 provider。 |
| `source_channel` | 通常不传 | 查询类工具可作为隔离条件；写入工具不要求 SuperAgent 传数据库 channel，AgentBus 邮件真实入库渠道可能是 `OUTLOOK`。 |
通用返回建议：
@@ -336,6 +336,7 @@ POST /api/ai-query/v1/message-conversation/messages
- SuperAgent 已完成当前邮件的最终任务拆分。
- 已确认外部 `source_message_id` 来自 AgentBus payload；`hotel_id` 由 TH Hotel 后端解析。
- 不需要为写入工具传数据库层 `source_provider` / `source_channel`；后端会按系统酒店和外部消息 ID 匹配真实 Inbox 记录。
- 需要把 AI 任务结果交给 TH Hotel 后端进入人工确认流程。
### 7.3 不应使用
@@ -359,11 +360,11 @@ POST /api/ai-query/v1/message-conversation/messages
},
"source_provider": {
"type": ["string", "null"],
"description": "来源提供方，默认 AGENTBUS"
"description": "兼容字段；写入工具通常不需要传，后端写入定位不使用该字段"
},
"source_channel": {
"type": ["string", "null"],
"description": "来源渠道，默认 EMAIL"
"description": "兼容字段；写入工具通常不需要传，后端写入定位不使用该字段，AgentBus 实际入库渠道可能是 OUTLOOK"
},
"source_message_id": {
"type": "string",
@@ -392,6 +393,8 @@ POST /api/ai-query/v1/message-conversation/messages
- `ai_task_results[]` 内部字段较多，完整结构以 `superagent-api-contract.md` 第 8 节为准。
- MCP endpoint 不应重排 `ai_task_results[]`。
- `source_message_id` 必须是 AgentBus payload 的 `source.external_message_id`，不是内部 `platform_source_message_inbox.id`；写入工具不要求 SuperAgent 知道 Inbox 的真实 channel。
- 同一系统酒店下如果外部 `source_message_id` 匹配多条 Inbox，业务 Service 返回 `SOURCE_MESSAGE_AMBIGUOUS`，MCP tool result 应原样保留该错误码和 message。
- 如后续需要强 schema 校验，可在 MCP endpoint 内复制 REST 契约中的细粒度字段约束。
### 7.5 输出

14
docs/project/requirements/M002-order-task-workflow-v3.md
View File

@@ -70,13 +70,13 @@ V3 以以下资料和决策为输入：
后端处理时按以下路径反查：
```text
系统酒店 + source_provider + source_channel + source_message.source_message_id
系统酒店 + source_message.source_message_id
→ platform_source_message_inbox.external_message_id
→ platform_source_message_inbox.id
→ workflow / task / transition 表内部 source_message_id 外键
```
V3 第一版继续使用单酒店阶段的系统默认酒店；后续多酒店或权限收口时再扩展显式酒店上下文。
V3 第一版继续使用单酒店阶段的系统默认酒店；后续多酒店或权限收口时再扩展显式酒店上下文。SuperAgent 不需要传数据库层 provider/channel，`source_message.source_channel=Email` 只是上游消息渠道语义；后端以 SourceMessage Inbox 的真实入库 provider/channel 为准。同一系统酒店下如果出现多条相同 `external_message_id`，后端返回 `SOURCE_MESSAGE_AMBIGUOUS`，不随机选择。
### 4.2 缺少 source_message_id
@@ -181,7 +181,9 @@ V3 第一版必须保存并支持以下路由类别：
- `Note`、`Allotment Maintenance`、`update_allotment_control_block` 仅历史兼容，不允许新数据生成。
- 当前 producer 不允许再生成 `normal_task/manual_review + Cancel Booking + linked_parent_release_after_child_split`。
- `relationship_type=linked_parent_release_after_child_split` 只用于 Parent / Child 关联和 Preflight，不再决定 `task_subtype`。
- 旧 V2 兼容 `ai_task_results[]` 若继续提交 `Cancel Booking + linked_parent_release_after_child_split`，也按当前 producer 契约错误处理。
- 旧 V2 兼容 `ai_task_results[]` 若继续提交 `Cancel Booking + linked_parent_release_after_child_split`，按请求级 `ADAPTER_CONTRACT_ERROR` 拒绝，不创建业务任务，也不创建 AI transition。
- Parent 只提供 `group_code` 或只提供 `block_code` 时，adapter 可以在派生副本中补齐另一边用于路由和落库；原始 payload 不回写。
- Parent 的 `group_code` 与 `block_code` 原始候选冲突时不猜测。若 SuperAgent 已输出 `manual_review.reason_code=target_object_unclear` 且 `context_used.parent_identity_candidates[]` 非空，创建同卡 type-known manual review；否则写入 adapter contract error。
P0.1 Parent Group 路由规则：
@@ -189,8 +191,11 @@ P0.1 Parent Group 路由规则：
| --- | --- | --- |
| Child Group 创建 | `normal_task/manual_review + New Booking + new_group_block` | 创建 New Booking 业务任务 |
| Parent Group 完整释放 / 取消 | `normal_task/manual_review + Cancel Allotment + cancel_allotment_control_block` | 创建 Cancel Allotment 业务任务卡 |
| 旧 Parent split 新入站 | `Cancel Booking + linked_parent_release_after_child_split` | `adapter_contract_error`，不创建业务任务 |
| 旧 Parent split 新入站 | V3 `Cancel Booking + linked_parent_release_after_child_split` | 按 event 写入 `adapter_contract_error`，不创建业务任务 |
| 旧 Parent split V2 兼容入口 | V2 `ai_task_results[]` 中的 `Cancel Booking + linked_parent_release_after_child_split` | 请求级 `ADAPTER_CONTRACT_ERROR` 拒绝，不创建业务任务 / AI transition |
| 重复 Parent 候选 | 同一 Parent Group 再次输出合法 Parent 候选 | 第二个及后续 Parent 写入 `adapter_contract_error` |
| Parent key 单边缺失 | `group_code` 或 `block_code` 仅有一边 | 在派生副本中补齐另一边，继续创建 Cancel Allotment 业务任务卡 |
| Parent key 候选冲突 | 双 key 无法安全归一，且 `target_object_unclear + parent_identity_candidates[]` 完整 | 创建 Cancel Allotment 同卡人工复核任务 |
| 历史旧 payload 只读展示 | `Cancel Booking + linked_parent_release_after_child_split` | reader / adapter 展示层可归一为 Cancel Allotment，不改写原 payload |
### 7.2 方案 C：AI 三元组和系统处理分类分离
@@ -422,6 +427,7 @@ V3 P0.1 不做以下事项：
- 结构化 `S10/S99` 入站处理，复用 `SOURCE_MESSAGE_ONLY` 只读特殊任务。
- 40 条 P0.1 路由枚举 / 稳定配置。
- V3 业务根 `source_message + message_events[]` 基础解析；能派生到稳定路由的 event 创建业务任务，无法派生的 event、显式 `contract_errors`、根 `missing_fields`、不完整 `manual_review`、当前 producer 旧 Parent Cancel Booking 和不完整 parent split 候选只落 `adapter_contract_error` transition。
- P0.1 Parent split 已支持单边 Parent key 归一；Parent key 候选冲突且符合 `target_object_unclear + parent_identity_candidates[]` 时进入同卡 type-known manual review，不再误判为 adapter contract error。
- `unhandled_current_intents[]` 只落 `UNHANDLED_CURRENT_INTENT` transition，不创建订单和任务，也不伪装成 adapter 契约错误。
- AI transition 最小保存 `route_code`、`system_process_category`、`adapter_error_code`、`adapter_error_message`。
- 任务列表、订单任务时间线和任务详情顶层透出 `result_type`、`ai_task_type`、`task_subtype`、`route_code`、`system_process_category`。

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

@@ -41,7 +41,7 @@
- 本接口只做技术校验和系统接收，不替代用户确认和 OPERA 模拟操作。
- `application/json` 用于 V3 结构化 `S10/S99`、V3 业务根或 V2 `normal_task` / `manual_review` 兼容结构化任务。
- `text/plain` 用于旧 `S000,source_message_id` / `S999,source_message_id` 特殊入口结果兼容。
- P0.1 后，V3 业务根中的完整 Parent split 父事件必须使用 `event_type=Cancel Allotment` 和 `task_subtype=cancel_allotment_control_block`；当前新入站不接受 `Cancel Booking + linked_parent_release_after_child_split` 作为合法业务任务，旧 V2 `ai_task_results[]` 兼容入口也不能继续提交该三元组。
- P0.1 后，V3 业务根中的完整 Parent split 父事件必须使用 `event_type=Cancel Allotment` 和 `task_subtype=cancel_allotment_control_block`；当前新入站不接受 `Cancel Booking + linked_parent_release_after_child_split` 作为合法业务任务。V3 `message_events[]` 中的旧三元组按 event 写入 adapter contract error；旧 V2 `ai_task_results[]` 兼容入口提交该三元组时按请求级 `ADAPTER_CONTRACT_ERROR` 拒绝。
### 2.1 SourceMessage ID 口径
@@ -50,13 +50,13 @@
后端正式处理路径：
```text
hotel_id + source_provider(默认 AGENTBUS) + source_channel(默认 EMAIL) + source_message_id
系统酒店 + 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 调用不得依赖该兼容路径。
数据库 `workflow_*` 表中的 `source_message_id` 仍然保存内部 SourceMessage Inbox ID。只有对外接口的 `source_message_id` 使用外部来源消息 ID。任务结果通知不要求 SuperAgent 传数据库层 `source_provider` / `source_channel`；后端按系统酒店和外部消息 ID 查唯一 Inbox 记录，真实 provider/channel 以 SourceMessage Inbox 入库值为准。无 `hotel_id` 时仅兼容本地旧夹具使用内部数字 ID，正式 SuperAgent 调用不得依赖该兼容路径。
## 3. 鉴权方案
@@ -171,10 +171,10 @@ JSON 请求体沿用 AI 导入文档定义的聚合结构。
| 字段 | 是否必填 | 中文说明 |
| --- | --- | --- |
| `hotel_id` | 是 | 酒店上下文 ID，用于反查 SourceMessage Inbox 幂等键 |
| `hotel_id` | 否 | 酒店上下文 ID；SuperAgent 默认不传，单酒店阶段由后端解析系统酒店 |
| `source_message_id` | 是 | 外部来源消息 ID，对应 AgentBus `source.external_message_id`；一次请求只能有一个 |
| `source_provider` | 否 | 来源提供方，第一版缺省为 `AGENTBUS` |
| `source_channel` | 否 | 来源渠道，第一版缺省为 `EMAIL` |
| `source_provider` | 否 | V2 兼容字段；通常不传。写入定位不使用该字段，真实 provider 以 SourceMessage Inbox 入库值为准 |
| `source_channel` | 否 | V2 兼容字段；通常不传。写入定位不使用该字段，AgentBus 邮件真实入库渠道可能是 `OUTLOOK` |
| `ai_task_results[]` | 是 | AI 拆分出的任务结果列表，必须保留数组顺序 |
| `extraction_warnings[]` | 否 | 抽取警告；不直接等同于业务任务 |
@@ -227,7 +227,7 @@ S999,mail-20260708-0001
处理规则：
- 第一版使用系统默认酒店反查 SourceMessage Inbox，不要求文本 body 携带 `hotel_id`。
- 后端按 `默认酒店 + AGENTBUS + EMAIL + external_message_id` 查询 SourceMessage。
- 后端按 `默认酒店 + external_message_id` 查询唯一 SourceMessage；真实 provider/channel 以 Inbox 入库值为准。
- 命中后创建 `SOURCE_MESSAGE_ONLY` 只读任务。
- 任务列表可见，订单列表不可见。
- 不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA。
@@ -243,7 +243,7 @@ S999,mail-20260708-0001
- 鉴权签名合法。
- 请求体大小不超过限制。
- JSON body 可解析；S000/S999 文本 body 必须符合 `结果码,source_message_id`。
- JSON body 中 `hotel_id` 存在。仅本地旧夹具兼容缺少 `hotel_id` 且 `source_message_id` 为内部数字 ID 的调用。
- JSON body 中 `hotel_id` 可不传；正式 REST / MCP 调用由后端解析系统酒店。仅本地旧夹具在显式开启兼容开关时允许缺少 `hotel_id` 且 `source_message_id` 为内部数字 ID 的调用。
- S000/S999 文本 body 第一版使用系统默认酒店，不读取 `hotel_id`。
- 顶层只有一个 `source_message_id`。
- `source_message_id` 对应的外部来源消息已经写入 SourceMessage Inbox。
@@ -253,6 +253,8 @@ S999,mail-20260708-0001
- 同一个请求内 `source_event_index` 和数组顺序可保存。
- 关键字符串长度不超过数据库限制。
- V3 P0.1 Parent split 当前合法结构必须是 `Cancel Allotment + cancel_allotment_control_block`；`Cancel Booking + linked_parent_release_after_child_split` 属于当前 producer 契约错误，只能作为历史 payload 只读兼容。
- Parent 只提供 `case_keys.group_code` 或只提供 `case_keys.block_code` 时，后端会在 adapter 派生副本中补齐另一边，不回写原始 payload。
- Parent `case_keys.group_code` 与 `case_keys.block_code` 原始候选冲突时，SuperAgent 应输出 `manual_review.reason_code=target_object_unclear` 和非空 `context_used.parent_identity_candidates[]`；后端会创建同卡 type-known manual review。缺少该复核结构时按 adapter contract error 处理。
- 同一个 Parent split cluster 只能有一个 Parent 候选；重复 Parent 候选不创建第二张业务任务卡。
### 5.2 不在本接口判断
@@ -459,6 +461,7 @@ S000 / S999 文本结果创建成功时，同样返回 `201 Created`。这类结
| 409 | `SYSTEM_HOTEL_AMBIGUOUS` | 单酒店阶段平台酒店表存在多家 ACTIVE 酒店 |
| 400 | `SOURCE_MESSAGE_REQUIRED` | `source_message_id` 缺失 |
| 404 | `SOURCE_MESSAGE_NOT_FOUND` | 外部来源消息尚未写入 SourceMessage Inbox |
| 409 | `SOURCE_MESSAGE_AMBIGUOUS` | 同一系统酒店下存在多条相同外部 `source_message_id` 的 Inbox 记录，后端拒绝随机选择 |
| 400 | `TASK_RESULTS_EMPTY` | `ai_task_results[]` 为空 |
| 400 | `TASK_RESULT_UNSUPPORTED_TYPE` | `result_type` 或 `task_type` 不可识别 |
| 400 | `DUPLICATE_TASK_RESULT_ITEM` | 同一请求内 item 重复 |

7
docs/project/requirements/M002-v3-p0.1-parent-group-routing-update.md
View File

@@ -82,6 +82,7 @@ S10、S99、Fallback、unhandled display = 4 条
- Parent 的 `requires_downstream_hard_validation=true`。
- Parent 的 `case_keys.group_code` 与 `case_keys.block_code` 必须同时存在且完全相等；只取得一边时复制到另一边。
- Parent 的 `extracted_fields.parent_group_code` 必须与归一后的 Parent code 一致。
- Parent 的 `case_keys.group_code` 与 `case_keys.block_code` 原始候选冲突时，adapter 不猜测目标对象；如 SuperAgent 已输出 `manual_review.reason_code=target_object_unclear` 且 `context_used.parent_identity_candidates[]` 非空，则创建同卡 type-known manual review，否则写入 adapter contract error。
- Parent 的 `related_source_event_indices[]` 必须与 `extracted_fields.child_group_codes[]` 数量一致、顺序一一对应，并指向同根 `message_events[]` 中的 Child New Booking。
如果当前 producer 输出：
@@ -126,10 +127,12 @@ Cancel Booking
- 路由枚举为 40 条。
- 旧 `linked_parent_release_after_child_split` 不再是当前合法 route definition。
- 当前入站 `Cancel Booking + linked_parent_release_after_child_split` 记录为 `adapter_contract_error`，不创建业务任务；该规则同时适用于 V3 `message_events[]` 和旧 V2 兼容 `ai_task_results[]`。
- 当前 V3 `message_events[]` 入站 `Cancel Booking + linked_parent_release_after_child_split` 按 event 记录 `adapter_contract_error` transition，不创建业务任务。
- 旧 V2 兼容 `ai_task_results[]` 若提交 `Cancel Booking + linked_parent_release_after_child_split`，按请求级 `ADAPTER_CONTRACT_ERROR` 拒绝，不创建业务任务，也不创建 AI transition。
- 当前入站 `Cancel Allotment + cancel_allotment_control_block + linked_parent_release_after_child_split` 可以创建 `CANCEL_ALLOTMENT` 业务卡。
- 同一个 Parent split cluster 重复提交 Parent 候选时，后续重复 Parent 记录为 `adapter_contract_error`，不再创建第二张 Parent 任务卡。
- Parent 双 key 不一致时不猜测，进入 type-known manual review 或 adapter contract error，不能改成普通 Cancel Booking。
- Parent 只提供 `group_code` 或只提供 `block_code` 时，adapter 可在派生副本中补齐另一边；原始 payload 不回写。
- Parent 双 key 不一致时不猜测，满足 `target_object_unclear + parent_identity_candidates[]` 时进入 type-known manual review，否则进入 adapter contract error，不能改成普通 Cancel Booking。
- Parent `child_group_codes[]` 与 `related_source_event_indices[]` 数量、顺序和 Child New Booking 目标一致。
- 普通 FIT / Group Block 的 `Cancel Booking` 不受影响。
- 旧历史数据只读兼容，不迁移、不改写原 payload。

4
server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/service/impl/SuperAgentMcpServiceImpl.java
View File

@@ -358,8 +358,8 @@ public class SuperAgentMcpServiceImpl implements SuperAgentMcpService {
private Map<String, Object> submitTaskResultsSchema() {
Map<String, Object> propertiesMap = new LinkedHashMap<>();
propertiesMap.put("hotel_id", stringField("可选酒店上下文 ID；缺省由 TH Hotel 后端解析系统酒店"));
propertiesMap.put("source_provider", nullableStringField("来源提供方，默认 AGENTBUS"));
propertiesMap.put("source_channel", nullableStringField("来源渠道，默认 EMAIL"));
propertiesMap.put("source_provider", nullableStringField("兼容字段；写入工具通常不需要传，后端写入定位不使用该字段"));
propertiesMap.put("source_channel", nullableStringField("兼容字段；写入工具通常不需要传，后端写入定位不使用该字段，AgentBus 实际入库渠道可能是 OUTLOOK"));
propertiesMap.put("source_message_id", stringField("外部来源消息 ID，对应 AgentBus source.external_message_id"));
propertiesMap.put("ai_task_results", Map.of(
"type", "array",

18
server/src/main/java/cn/nianxx/thhotel/platform/message/repository/MybatisSourceMessageInboxRepository.java
View File

@@ -157,6 +157,24 @@ public class MybatisSourceMessageInboxRepository implements SourceMessageInboxRe
return Optional.ofNullable(entity).map(this::toSnapshot);
}
/**
* 根据酒店和外部邮件 ID 查询所有候选 Inbox 记录，调用方负责处理零条或多条的业务语义。
*/
@Override
public List<SourceMessageInboxSnapshot> findByExternalMessageId(String hotelId, String externalMessageId) {
if (!hasText(hotelId) || !hasText(externalMessageId)) {
return List.of();
}
return inboxMapper.selectList(Wrappers.<SourceMessageInboxEntity>lambdaQuery()
.eq(SourceMessageInboxEntity::getHotelId, trim(hotelId))
.eq(SourceMessageInboxEntity::getExternalMessageId, trim(externalMessageId))
.orderByDesc(SourceMessageInboxEntity::getReceivedAt)
.orderByDesc(SourceMessageInboxEntity::getId))
.stream()
.map(this::toSnapshot)
.toList();
}
/**
* 执行 SourceMessage 安全摘要分页查询，只读取列表和详情需要的索引字段。
*/

5
server/src/main/java/cn/nianxx/thhotel/platform/message/repository/SourceMessageInboxRepository.java
View File

@@ -50,6 +50,11 @@ public interface SourceMessageInboxRepository {
String channel,
String externalMessageId);
/**
* 按酒店和外部邮件 ID 查询 Inbox 快照，用于外部回调只携带 AgentBus external_message_id 的场景。
*/
List<SourceMessageInboxSnapshot> findByExternalMessageId(String hotelId, String externalMessageId);
/**
* 按查询条件分页读取 Inbox 快照，分页参数已经由 Service 层归一化。
*/

212
server/src/main/java/cn/nianxx/thhotel/workflows/reservation/service/impl/ReservationAiTaskIntakeServiceImpl.java
View File

@@ -39,6 +39,7 @@ import java.util.HexFormat;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
@@ -151,17 +152,21 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
private final ObjectMapper objectMapper;
private final SourceMessageInboxRepository sourceMessageInboxRepository;
private final ReservationAiWorkflowRepository workflowRepository;
private final boolean allowLegacyInternalSourceMessageId;
/**
* 注入 JSON 解析器、SourceMessage 查询边界和 Reservation 持久化边界。
* 注入 JSON 解析器、SourceMessage 查询边界、Reservation 持久化边界和本地旧夹具兼容开关。
*/
public ReservationAiTaskIntakeServiceImpl(
ObjectMapper objectMapper,
SourceMessageInboxRepository sourceMessageInboxRepository,
ReservationAiWorkflowRepository workflowRepository) {
ReservationAiWorkflowRepository workflowRepository,
@Value("${superagent.task-result.allow-legacy-internal-source-message-id:false}")
boolean allowLegacyInternalSourceMessageId) {
this.objectMapper = objectMapper;
this.sourceMessageInboxRepository = sourceMessageInboxRepository;
this.workflowRepository = workflowRepository;
this.allowLegacyInternalSourceMessageId = allowLegacyInternalSourceMessageId;
}
/**
@@ -370,7 +375,8 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
List<SuperAgentTaskResultItemResponse> responseItems = new ArrayList<>(itemCount);
Set<String> acceptedParentSplitCodes = new LinkedHashSet<>();
for (int index = 0; index < messageEvents.size(); index++) {
JsonNode event = messageEvents.get(index);
JsonNode rawEvent = messageEvents.get(index);
JsonNode event = normalizeV3ParentSplitEvent(rawEvent);
int arrayIndex = index + 1;
V3EventContractIssue contractIssue = inspectV3EventContractIssue(event, messageEvents);
if (contractIssue == null) {
@@ -381,9 +387,9 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
hotelId,
sourceMessageId,
batchId,
event,
rawEvent,
arrayIndex,
sourceEventIndex(event, arrayIndex),
sourceEventIndex(rawEvent, arrayIndex),
null,
contractIssue.code(),
contractIssue.message(),
@@ -396,16 +402,16 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
hotelId,
sourceMessageId,
batchId,
event,
rawEvent,
arrayIndex,
sourceEventIndex(event, arrayIndex),
sourceEventIndex(rawEvent, arrayIndex),
null,
"EVENT_ROUTE_UNSUPPORTED",
"message_events[" + index + "] 无法派生稳定路由。",
now));
continue;
}
ObjectNode item = normalizeV3EventToTaskResultItem(event, route, arrayIndex);
ObjectNode item = normalizeV3EventToTaskResultItem(rawEvent, event, route, arrayIndex);
responseItems.add(createItem(hotelId, sourceMessageId, batchId, item, arrayIndex, now));
}
for (int index = 0; index < unhandledIntents.size(); index++) {
@@ -636,31 +642,32 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
/**
* 将 V3 业务 event 转为旧任务结果 item 形态，复用现有订单、任务和任务卡创建逻辑。
* 将 V3 业务 event 转为旧任务结果 item 形态，业务列使用 adapter 派生 event，原始 event 保留在 v3_message_event。
*/
private ObjectNode normalizeV3EventToTaskResultItem(
JsonNode event,
JsonNode rawEvent,
JsonNode derivedEvent,
ReservationAiRouteDefinition route,
int arrayIndex) {
ObjectNode item = objectMapper.createObjectNode();
item.put("source_event_index", sourceEventIndex(event, arrayIndex));
item.put("source_event_index", sourceEventIndex(rawEvent, arrayIndex));
item.put("catalog_code", V3_CATALOG_CODE);
item.put("skill_id", V3_SKILL_ID);
item.put("result_type", route.resultType());
item.put("task_type", route.taskType());
item.put("task_subtype", route.taskSubtype());
copyIfPresent(event, item, "current_or_history");
copyIfPresent(event, item, "relevant_message_excerpt");
copyIfPresent(event, item, "case_keys");
copyIfPresent(event, item, "extracted_fields");
copyIfPresent(event, item, "manual_review");
copyIfPresent(event, item, "attachments");
copyIfPresent(event, item, "file_references");
copyIfPresent(event, item, "context_used");
copyIfPresent(event, item, "parent_source_event_index");
copyIfPresent(event, item, "linked_task_group_id");
copyIfPresent(event, item, "blocked_until_parent_completed");
item.set("v3_message_event", event);
copyIfPresent(rawEvent, item, "current_or_history");
copyIfPresent(rawEvent, item, "relevant_message_excerpt");
copyIfPresent(derivedEvent, item, "case_keys");
copyIfPresent(rawEvent, item, "extracted_fields");
copyIfPresent(rawEvent, item, "manual_review");
copyIfPresent(rawEvent, item, "attachments");
copyIfPresent(rawEvent, item, "file_references");
copyIfPresent(rawEvent, item, "context_used");
copyIfPresent(rawEvent, item, "parent_source_event_index");
copyIfPresent(rawEvent, item, "linked_task_group_id");
copyIfPresent(rawEvent, item, "blocked_until_parent_completed");
item.set("v3_message_event", rawEvent);
item.put("route_code", route.routeCode());
item.put("system_process_category", route.systemProcessCategory().name());
return item;
@@ -804,6 +811,36 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
return "linked_parent_release_after_child_split".equals(firstText(extractedFields, event, "relationship_type"));
}
/**
* 归一 Parent split 的 Parent Group key；只补齐 adapter 派生用副本，不修改请求原文。
*/
private JsonNode normalizeV3ParentSplitEvent(JsonNode event) {
if (event == null || !event.isObject() || !isLinkedParentReleaseCandidate(event)) {
return event;
}
ObjectNode normalizedEvent = event.deepCopy();
JsonNode caseKeysNode = normalizedEvent.path("case_keys");
if (!caseKeysNode.isObject()) {
return normalizedEvent;
}
ObjectNode caseKeys = (ObjectNode) caseKeysNode;
String groupCode = trimToNull(textAt(caseKeys, "group_code"));
String blockCode = trimToNull(textAt(caseKeys, "block_code"));
if (groupCode == null && blockCode != null) {
caseKeys.put("group_code", blockCode);
return normalizedEvent;
}
if (groupCode != null && blockCode == null) {
caseKeys.put("block_code", groupCode);
return normalizedEvent;
}
if (groupCode != null && blockCode != null && !groupCode.equals(blockCode)) {
caseKeys.putNull("group_code");
caseKeys.putNull("block_code");
}
return normalizedEvent;
}
/**
* 判断当前 producer 是否仍在输出旧 Parent Cancel Booking 组合。
*/
@@ -824,8 +861,8 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
if (!isLinkedParentReleaseCandidate(event)) {
return null;
}
String parentGroupCode = trimToNull(textAt(event.path("case_keys"), "group_code"));
if (parentGroupCode != null && !acceptedParentSplitCodes.add(parentGroupCode)) {
ParentSplitIdentity identity = parentSplitIdentity(event);
if (identity.normalizedParentCode() != null && !acceptedParentSplitCodes.add(identity.normalizedParentCode())) {
return new V3EventContractIssue(
"LINKED_PARENT_RELEASE_DUPLICATE_PARENT",
"同一个 Parent split cluster 只能有一个 Parent Cancel Allotment 候选。");
@@ -838,25 +875,25 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
*/
private boolean validLinkedParentReleaseCandidate(JsonNode event, JsonNode messageEvents) {
JsonNode extractedFields = event == null ? null : event.path("extracted_fields");
JsonNode caseKeys = event == null ? null : event.path("case_keys");
String parentGroupCode = trimToNull(textAt(caseKeys, "group_code"));
String parentBlockCode = trimToNull(textAt(caseKeys, "block_code"));
ParentSplitIdentity identity = parentSplitIdentity(event);
if (!("Cancel Allotment".equals(trimToNull(textAt(event, "event_type")))
&& "entire_allotment_control_block".equals(firstText(extractedFields, event, "cancel_scope"))
&& isBooleanTrue(extractedFields.path("parent_release_or_cancel_candidate"))
&& "parent_to_child_allocation_split".equals(firstText(extractedFields, event, "release_reason"))
&& parentGroupCode != null
&& parentGroupCode.equals(firstText(extractedFields, event, "parent_group_code"))
&& isBooleanTrue(extractedFields.path("allocation_split_from_parent"))
&& "New Booking".equals(trimToNull(textAt(event, "related_event_type")))
&& event != null
&& isBooleanTrue(event.path("requires_downstream_hard_validation"))
&& parentGroupCode != null
&& parentGroupCode.equals(parentBlockCode)
&& nonEmptyArray(extractedFields, "child_group_codes")
&& nonEmptyArray(event, "related_source_event_indices"))) {
return false;
}
if (!identity.targetObjectUnclearReview() && !validConcreteParentIdentity(identity, extractedFields)) {
return false;
}
if (identity.targetObjectUnclearReview() && !nonEmptyArray(event.path("context_used"), "parent_identity_candidates")) {
return false;
}
List<String> childGroupCodes = stringArrayValues(extractedFields.path("child_group_codes"));
List<String> relatedSourceEventIndices = stringArrayValues(event.path("related_source_event_indices"));
if (childGroupCodes.isEmpty()
@@ -888,6 +925,30 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
return true;
}
/**
* 校验普通 Parent split 事件是否已经具备明确 Parent Group identity。
*/
private boolean validConcreteParentIdentity(ParentSplitIdentity identity, JsonNode extractedFields) {
return identity.normalizedParentCode() != null
&& identity.normalizedParentCode().equals(identity.groupCode())
&& identity.normalizedParentCode().equals(identity.blockCode())
&& identity.normalizedParentCode().equals(trimToNull(textAt(extractedFields, "parent_group_code")));
}
/**
* 提取 Parent split identity，封装正常归一与 target_object_unclear 复核两种形态。
*/
private ParentSplitIdentity parentSplitIdentity(JsonNode event) {
JsonNode caseKeys = event == null ? null : event.path("case_keys");
String groupCode = trimToNull(textAt(caseKeys, "group_code"));
String blockCode = trimToNull(textAt(caseKeys, "block_code"));
String normalizedParentCode = groupCode != null && groupCode.equals(blockCode) ? groupCode : null;
boolean targetObjectUnclearReview = groupCode == null
&& blockCode == null
&& "target_object_unclear".equals(textAt(event == null ? null : event.path("manual_review"), "reason_code"));
return new ParentSplitIdentity(groupCode, blockCode, normalizedParentCode, targetObjectUnclearReview);
}
/**
* 接收 S000/S999 文本入口结果，创建只读来源消息任务，并隐藏其技术订单。
*/
@@ -914,13 +975,7 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
? requireText(defaultHotelId, "default_hotel_id", LENGTH_64)
: requireText(resolvedSourceMessage.hotelId(), "source_message.hotel_id", LENGTH_64);
SourceMessageInboxSnapshot sourceMessage = resolvedSourceMessage == null
? sourceMessageInboxRepository
.findByIdempotencyKey(
hotelId,
DEFAULT_SOURCE_PROVIDER,
DEFAULT_SOURCE_CHANNEL,
entryResult.externalSourceMessageId())
.orElseThrow(() -> error(HttpStatus.NOT_FOUND, "SOURCE_MESSAGE_NOT_FOUND", "SourceMessage 不存在。"))
? resolveExternalSourceMessageByHotel(hotelId, entryResult.externalSourceMessageId())
: resolvedSourceMessage;
String requestPayloadSha256 = sha256(rawBody == null ? "" : rawBody);
String batchIdempotencyKey = sha256(BATCH_KEY_PREFIX + "|" + sourceMessage.id() + "|" + requestPayloadSha256);
@@ -1575,22 +1630,21 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
if (requestHotelId != null && systemHotelId != null && !requestHotelId.equals(systemHotelId)) {
throw error(HttpStatus.BAD_REQUEST, "HOTEL_ID_MISMATCH", "请求 hotel_id 与系统酒店不一致。");
}
if (requestHotelId == null && isLongText(sourceMessageReference)) {
return resolveLegacyInternalSourceMessage(sourceMessageReference, systemHotelId);
}
String hotelId = requestHotelId == null ? systemHotelId : requestHotelId;
if (hotelId == null) {
return resolveLegacyInternalSourceMessage(sourceMessageReference, null);
if (allowLegacyInternalSourceMessageId) {
return resolveLegacyInternalSourceMessage(sourceMessageReference, null);
}
throw error(HttpStatus.BAD_REQUEST, "HOTEL_ID_REQUIRED", "使用外部 source_message_id 时 hotel_id 不能为空。");
}
validateLength(hotelId, "hotel_id", LENGTH_64);
String sourceProvider = optionalText(textAt(root, "source_provider"), "source_provider", LENGTH_32);
String sourceChannel = optionalText(textAt(root, "source_channel"), "source_channel", LENGTH_32);
String provider = sourceProvider == null ? DEFAULT_SOURCE_PROVIDER : sourceProvider;
String channel = sourceChannel == null ? DEFAULT_SOURCE_CHANNEL : sourceChannel;
SourceMessageInboxSnapshot sourceMessage = sourceMessageInboxRepository
.findByIdempotencyKey(hotelId, provider, channel, sourceMessageReference)
.orElseThrow(() -> error(HttpStatus.NOT_FOUND, "SOURCE_MESSAGE_NOT_FOUND", "SourceMessage 不存在。"));
return new ResolvedSourceMessage(sourceMessage, sourceMessageReference);
// 旧 V2 字段只做格式兼容校验；写入定位统一按系统酒店 + external_message_id 匹配真实 Inbox。
optionalText(textAt(root, "source_provider"), "source_provider", LENGTH_32);
optionalText(textAt(root, "source_channel"), "source_channel", LENGTH_32);
return resolveExternalSourceMessageReferenceByHotel(
hotelId,
sourceMessageReference,
requestHotelId == null && allowLegacyInternalSourceMessageId);
}
/**
@@ -1614,6 +1668,42 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
return new ResolvedSourceMessage(sourceMessage, responseSourceMessageId);
}
/**
* 按系统酒店和 AgentBus 外部邮件 ID 解析真实入库 SourceMessage，不要求 SuperAgent 了解数据库 provider/channel。
*/
private SourceMessageInboxSnapshot resolveExternalSourceMessageByHotel(String hotelId, String externalSourceMessageId) {
List<SourceMessageInboxSnapshot> candidates =
sourceMessageInboxRepository.findByExternalMessageId(hotelId, externalSourceMessageId);
if (candidates.isEmpty()) {
throw error(HttpStatus.NOT_FOUND, "SOURCE_MESSAGE_NOT_FOUND", "SourceMessage 不存在。");
}
if (candidates.size() > 1) {
throw error(HttpStatus.CONFLICT, "SOURCE_MESSAGE_AMBIGUOUS", "同一酒店下存在多个匹配的 SourceMessage。");
}
return candidates.get(0);
}
/**
* V2 写入优先按外部消息 ID 解析；仅在无显式 hotel_id 的旧本地夹具场景下兜底内部 SourceMessage ID。
*/
private ResolvedSourceMessage resolveExternalSourceMessageReferenceByHotel(
String hotelId,
String sourceMessageReference,
boolean allowLegacyInternalFallback) {
List<SourceMessageInboxSnapshot> candidates =
sourceMessageInboxRepository.findByExternalMessageId(hotelId, sourceMessageReference);
if (candidates.isEmpty()) {
if (allowLegacyInternalFallback && isLongText(sourceMessageReference)) {
return resolveLegacyInternalSourceMessage(sourceMessageReference, hotelId);
}
throw error(HttpStatus.NOT_FOUND, "SOURCE_MESSAGE_NOT_FOUND", "SourceMessage 不存在。");
}
if (candidates.size() > 1) {
throw error(HttpStatus.CONFLICT, "SOURCE_MESSAGE_AMBIGUOUS", "同一酒店下存在多个匹配的 SourceMessage。");
}
return new ResolvedSourceMessage(candidates.get(0), sourceMessageReference);
}
/**
* 判断来源消息引用是否为历史本地兼容的内部 SourceMessage ID。
*/
@@ -1823,13 +1913,8 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
}
validateLength(externalSourceMessageId, "source_message.source_message_id", LENGTH_256);
String hotelId = requireText(defaultHotelId, "default_hotel_id", LENGTH_64);
SourceMessageInboxSnapshot sourceMessage = sourceMessageInboxRepository
.findByIdempotencyKey(
hotelId,
DEFAULT_SOURCE_PROVIDER,
DEFAULT_SOURCE_CHANNEL,
externalSourceMessageId)
.orElseThrow(() -> error(HttpStatus.NOT_FOUND, "SOURCE_MESSAGE_NOT_FOUND", "SourceMessage 不存在。"));
SourceMessageInboxSnapshot sourceMessage =
resolveExternalSourceMessageByHotel(hotelId, externalSourceMessageId);
return new ResolvedSourceMessage(sourceMessage, externalSourceMessageId);
}
@@ -2221,6 +2306,17 @@ public class ReservationAiTaskIntakeServiceImpl implements ReservationAiTaskInta
) {
}
/**
* Parent split 父事件身份归一结果。target_object_unclear 代表已知卡型但目标对象需人工确认。
*/
private record ParentSplitIdentity(
String groupCode,
String blockCode,
String normalizedParentCode,
boolean targetObjectUnclearReview
) {
}
/**
* 将空白字符串转换为 null。
*/

2
server/src/main/resources/application-test.yml
View File

@@ -35,6 +35,8 @@ superagent:
task-result:
# test SuperAgent HMAC 密钥；优先使用 test 专属变量，兼容旧通用变量。
hmac-secret: ${SUPERAGENT_TEST_TASK_RESULT_HMAC_SECRET:${SUPERAGENT_TASK_RESULT_HMAC_SECRET:}}
# 仅用于旧本地测试夹具；正式 REST / MCP 联调不得依赖内部 SourceMessage ID。
allow-legacy-internal-source-message-id: ${SUPERAGENT_TEST_ALLOW_LEGACY_INTERNAL_SOURCE_MESSAGE_ID:true}
open-api:
# test Debug EML 调用 SuperAgent Open API；默认关闭，联调时显式开启。
enabled: ${SUPERAGENT_TEST_OPEN_API_ENABLED:${SUPERAGENT_OPEN_API_ENABLED:false}}

3
server/src/main/resources/db/migration/V19__add_source_message_external_message_lookup_index.sql Normal file
View File

@@ -0,0 +1,3 @@
-- M002 SuperAgent 任务结果回调：按系统酒店和外部邮件 ID 反查 SourceMessage Inbox。
CREATE INDEX idx_source_message_inbox_hotel_external_message
ON platform_source_message_inbox (hotel_id, external_message_id);

4
server/src/test/java/cn/nianxx/thhotel/integrations/mcp/superagent/control/SuperAgentMcpControllerTest.java
View File

@@ -132,6 +132,10 @@ class SuperAgentMcpControllerTest {
.andExpect(jsonPath("$.result.tools[4].name").value("th_hotel_submit_task_results"))
.andExpect(jsonPath("$.result.tools[4].inputSchema.required[0]").value("source_message_id"))
.andExpect(jsonPath("$.result.tools[4].inputSchema.required[1]").value("ai_task_results"))
.andExpect(jsonPath("$.result.tools[4].inputSchema.properties.source_provider.description")
.value(containsString("兼容字段")))
.andExpect(jsonPath("$.result.tools[4].inputSchema.properties.source_channel.description")
.value(containsString("OUTLOOK")))
.andExpect(jsonPath("$.result.tools[4].annotations.readOnlyHint").value(false))
.andExpect(jsonPath("$.result.tools[4].annotations.destructiveHint").value(true));
}

324
server/src/test/java/cn/nianxx/thhotel/workflows/reservation/control/SuperAgentTaskResultControllerTest.java
View File

@@ -42,7 +42,8 @@ import org.springframework.test.web.servlet.MvcResult;
"superagent.task-result.hmac-secret=test-superagent-secret",
"superagent.task-result.clock-skew-seconds=300",
"superagent.task-result.nonce-ttl-seconds=600",
"superagent.task-result.max-body-bytes=12000"
"superagent.task-result.max-body-bytes=12000",
"superagent.task-result.allow-legacy-internal-source-message-id=true"
})
@AutoConfigureMockMvc
@ActiveProfiles("test")
@@ -646,6 +647,17 @@ class SuperAgentTaskResultControllerTest {
.andExpect(jsonPath("$.error_code").value("SOURCE_MESSAGE_NOT_FOUND"));
}
@Test
void shouldRejectTextResultAsAmbiguousWhenExternalSourceMessageMatchesMultipleChannels() throws Exception {
String externalMessageId = "mail-s999-ambiguous-channel-001";
captureSourceMessage(externalMessageId, "HOTEL-TEST", "EMAIL");
captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
mockMvc.perform(signedPlainPost("S999," + externalMessageId, "nonce-s999-ambiguous-channel-001"))
.andExpect(status().isConflict())
.andExpect(jsonPath("$.error_code").value("SOURCE_MESSAGE_AMBIGUOUS"));
}
@Test
void shouldCreateReadOnlySourceMessageOnlyTaskForStructuredS10Result() throws Exception {
SourceMessageCaptureResult source = captureSourceMessage("mail-v3-s10-entry-result-001");
@@ -710,6 +722,29 @@ class SuperAgentTaskResultControllerTest {
assertThat(taskCount).isEqualTo(1L);
}
@Test
void shouldCreateStructuredS10ResultWhenSourceMessageStoredAsOutlookChannel() throws Exception {
String externalMessageId = "mail-v3-s10-outlook-channel-001";
SourceMessageCaptureResult source = captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = structuredS10Body(externalMessageId);
mockMvc.perform(signedPost(body, "nonce-v3-s10-outlook-channel-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.source_message_id").value(externalMessageId))
.andExpect(jsonPath("$.items[0].route_code").value("S10"))
.andExpect(jsonPath("$.items[0].system_process_category").value("SOURCE_MESSAGE_NOTIFICATION"));
Long transitionCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND result_type = 'source_message_review_notification'
AND route_code = 'S10'
AND system_process_category = 'SOURCE_MESSAGE_NOTIFICATION'
""", Long.class, source.inboxId());
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldCreateReadOnlySourceMessageOnlyTaskForStructuredS99Result() throws Exception {
SourceMessageCaptureResult source = captureSourceMessage("mail-v3-s99-entry-result-001");
@@ -931,6 +966,170 @@ class SuperAgentTaskResultControllerTest {
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldAcceptV2TaskResultWhenSourceMessageStoredAsOutlookChannelWithoutSourceChannel() throws Exception {
String externalMessageId = "mail-v2-task-result-outlook-channel-001";
SourceMessageCaptureResult source = captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = minimalBodyWithHotel(
externalMessageId,
"New Booking",
"normal_task",
"new_fit_reservation",
"""
"case_keys": {"confirmation_number": "CNF-V2-OUTLOOK-001"},
"extracted_fields": {"booking_object_type": "FIT Reservation"}
""");
mockMvc.perform(signedPost(body, "nonce-v2-task-result-outlook-channel-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(1))
.andExpect(jsonPath("$.items[0].route_code").value("R01_NEW_FIT_RESERVATION_NORMAL"));
Long transitionCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'R01_NEW_FIT_RESERVATION_NORMAL'
""", Long.class, source.inboxId());
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldAcceptV2TaskResultWhenLegacySourceChannelDoesNotMatchInboxChannel() throws Exception {
String externalMessageId = "mail-v2-task-result-legacy-email-channel-001";
SourceMessageCaptureResult source = captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = minimalBodyWithHotelAndSourceMetadata(
externalMessageId,
"AGENTBUS",
"EMAIL",
"New Booking",
"normal_task",
"new_fit_reservation",
"""
"case_keys": {"confirmation_number": "CNF-V2-LEGACY-EMAIL-001"},
"extracted_fields": {"booking_object_type": "FIT Reservation"}
""");
mockMvc.perform(signedPost(body, "nonce-v2-task-result-legacy-email-channel-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(1))
.andExpect(jsonPath("$.items[0].route_code").value("R01_NEW_FIT_RESERVATION_NORMAL"));
Long transitionCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'R01_NEW_FIT_RESERVATION_NORMAL'
""", Long.class, source.inboxId());
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldRejectV2TaskResultAsAmbiguousEvenWhenLegacySourceChannelProvided() throws Exception {
String externalMessageId = "mail-v2-task-result-ambiguous-legacy-channel-001";
captureSourceMessage(externalMessageId, "HOTEL-TEST", "EMAIL");
captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = minimalBodyWithHotelAndSourceMetadata(
externalMessageId,
"AGENTBUS",
"EMAIL",
"New Booking",
"normal_task",
"new_fit_reservation",
"""
"case_keys": {"confirmation_number": "CNF-V2-AMBIGUOUS-001"},
"extracted_fields": {"booking_object_type": "FIT Reservation"}
""");
mockMvc.perform(signedPost(body, "nonce-v2-task-result-ambiguous-legacy-channel-001"))
.andExpect(status().isConflict())
.andExpect(jsonPath("$.error_code").value("SOURCE_MESSAGE_AMBIGUOUS"));
}
@Test
void shouldPreferNumericExternalSourceMessageIdBeforeLegacyInternalId() throws Exception {
String externalMessageId = "1234567890123456789";
SourceMessageCaptureResult source = captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = minimalBody(
externalMessageId,
"New Booking",
"normal_task",
"new_fit_reservation",
"""
"case_keys": {"confirmation_number": "CNF-V2-NUMERIC-001"},
"extracted_fields": {"booking_object_type": "FIT Reservation"}
""");
mockMvc.perform(signedPost(body, "nonce-v2-task-result-numeric-external-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(1))
.andExpect(jsonPath("$.items[0].route_code").value("R01_NEW_FIT_RESERVATION_NORMAL"));
Long transitionCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'R01_NEW_FIT_RESERVATION_NORMAL'
""", Long.class, source.inboxId());
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldAcceptSourceMessageOnlyTextResultWhenSourceMessageStoredAsOutlookChannel() throws Exception {
String externalMessageId = "mail-s000-outlook-channel-001";
SourceMessageCaptureResult source = captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
mockMvc.perform(signedPlainPost("S000," + externalMessageId, "nonce-s000-outlook-channel-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(1))
.andExpect(jsonPath("$.items[0].system_process_category").value("SOURCE_MESSAGE_NOTIFICATION"));
Long transitionCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'S000'
AND system_process_category = 'SOURCE_MESSAGE_NOTIFICATION'
""", Long.class, source.inboxId());
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldCreateBusinessTaskFromV3BusinessRootWhenSourceMessageStoredAsOutlookChannel() throws Exception {
String externalMessageId = """
AAMkAGY5YWM5OTNlLTQ1OTktNDQ1Yi05NTk5LTgwNDIzNTAzY2Q4YgBGAAAAAAApDY1IkXlgT51ii6WOFxDvBwAuw1c78vBZRqpnmlmQMZnLAAAAAAEMAAAuw1c78vBZRqpnmlmQMZnLAAKAkhoCAAA=
""".trim();
SourceMessageCaptureResult source = captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = v3BusinessRootBody(externalMessageId, "CNF-V3-OUTLOOK-001");
mockMvc.perform(signedPost(body, "nonce-v3-business-root-outlook-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(1))
.andExpect(jsonPath("$.items[0].route_code").value("R01_NEW_FIT_RESERVATION_NORMAL"))
.andExpect(jsonPath("$.items[0].system_process_category").value("BUSINESS_TASK"));
Long transitionCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'R01_NEW_FIT_RESERVATION_NORMAL'
AND system_process_category = 'BUSINESS_TASK'
""", Long.class, source.inboxId());
assertThat(transitionCount).isEqualTo(1L);
}
@Test
void shouldRejectV3BusinessRootWhenExternalSourceMessageMatchesMultipleChannels() throws Exception {
String externalMessageId = "mail-v3-business-root-ambiguous-channel-001";
captureSourceMessage(externalMessageId, "HOTEL-TEST", "EMAIL");
captureSourceMessage(externalMessageId, "HOTEL-TEST", "OUTLOOK");
String body = v3BusinessRootBody(externalMessageId, "CNF-V3-AMBIGUOUS-001");
mockMvc.perform(signedPost(body, "nonce-v3-business-root-ambiguous-channel-001"))
.andExpect(status().isConflict())
.andExpect(jsonPath("$.error_code").value("SOURCE_MESSAGE_AMBIGUOUS"));
}
@Test
void shouldConfirmV3BusinessTaskWithoutLegacyVisibleReason() throws Exception {
captureSourceMessage("mail-v3-confirm-without-legacy-visible-reason-001");
@@ -2560,13 +2759,21 @@ class SuperAgentTaskResultControllerTest {
}
private SourceMessageCaptureResult captureSourceMessage(String externalMessageId, String hotelId) {
return captureSourceMessage(externalMessageId, hotelId, "EMAIL");
}
private SourceMessageCaptureResult captureSourceMessage(String externalMessageId, String hotelId, String channel) {
String providerFrameId = "frame-" + externalMessageId;
if (providerFrameId.length() > 128) {
providerFrameId = "frame-" + Integer.toHexString(externalMessageId.hashCode());
}
return captureService.capture(new CaptureSourceMessageCommand(
hotelId,
"AGENTBUS",
"EMAIL",
channel,
externalMessageId,
"thread-" + externalMessageId,
"frame-" + externalMessageId,
providerFrameId,
"session-m002",
Instant.parse("2026-07-07T08:00:00Z"),
"guest@example.test",
@@ -2686,6 +2893,44 @@ class SuperAgentTaskResultControllerTest {
""".formatted(sourceMessageId, resultType, taskType, taskSubtype, itemFields);
}
private String minimalBodyWithHotelAndSourceMetadata(
String sourceMessageId,
String sourceProvider,
String sourceChannel,
String taskType,
String resultType,
String taskSubtype,
String itemFields) {
return """
{
"hotel_id": "HOTEL-TEST",
"source_provider": "%s",
"source_channel": "%s",
"source_message_id": "%s",
"ai_task_results": [
{
"source_event_index": 1,
"catalog_code": "S01",
"skill_id": "S01_new_booking_skill",
"result_type": "%s",
"task_type": "%s",
"task_subtype": "%s",
"current_or_history": "current",
"visible_reason": "AI extracted a task result.",
"relevant_message_excerpt": "Please handle booking message.",
"attachments": [],
"file_references": [],
"context_used": {},
%s,
"additional_operations": [],
"idempotency_key": null
}
],
"extraction_warnings": []
}
""".formatted(sourceProvider, sourceChannel, sourceMessageId, resultType, taskType, taskSubtype, itemFields);
}
private String twoTaskBody(String sourceMessageId, String groupCode) {
return """
{
@@ -2820,6 +3065,79 @@ class SuperAgentTaskResultControllerTest {
""".formatted(externalSourceMessageId, confirmationNumber, arrivalDate, departureDate);
}
private String v3BusinessRootBody(String externalSourceMessageId, String confirmationNumber) {
return """
{
"source_message": {
"source_message_id": "%s",
"subject": "Outlook new booking",
"from": null,
"cc": [],
"received_at": null,
"source_channel": "Email"
},
"message_events": [
{
"event_type": "New Booking",
"event_role": "travel_agent_request",
"source_event_index": "E1",
"current_or_history": "current",
"case_keys": {
"group_code": null,
"confirmation_number": "%s",
"reservation_number": null,
"block_code": null
},
"relevant_message_excerpt": "Please create a new FIT reservation.",
"attachments": [],
"file_references": [],
"context_used": {},
"extracted_fields": {
"booking_object_type": "FIT Reservation",
"arrival_date": "2026-09-01"
},
"manual_review": null
}
],
"case_candidates": [],
"extraction_warnings": [],
"unhandled_current_intents": []
}
""".formatted(externalSourceMessageId, confirmationNumber);
}
private String structuredS10Body(String externalSourceMessageId) {
return """
{
"source_message": {
"source_message_id": "%s",
"subject": null,
"from": null,
"cc": [],
"received_at": null,
"source_channel": "Email"
},
"route_code": "S10",
"handler_type": "main_agent_outcome",
"result_type": "source_message_review_notification",
"current_or_history": "current",
"agent_assessment": {
"status": "no_booking_action_detected",
"reason_code": "no_booking_action_detected",
"automation_action": "none"
},
"notification": {
"required": true,
"notification_type": "source_message_review",
"show_source_message": true,
"requires_user_decision": true,
"visible_message": "未匹配到当前 Agent 支持的业务事件类型，请查看原邮件并决定是否需要回复或进行其他处理。"
},
"manual_review": null
}
""".formatted(externalSourceMessageId);
}
private String[] createReadyTaskWithTwoOperaOperations(
String externalMessageId,
String nonce,

103
server/src/test/java/cn/nianxx/thhotel/workflows/reservation/control/SuperAgentTaskResultP0FixtureRegressionTest.java
View File

@@ -304,6 +304,109 @@ class SuperAgentTaskResultP0FixtureRegressionTest {
assertThat(transitionCount).isEqualTo(3L);
}
@Test
void shouldNormalizeSingleParentBlockCodeAndCreateParentSplitTask() throws Exception {
ObjectNode root = fixture("parent_split_two_children.json").deepCopy();
useParentSplitBusinessKeys(root, "PARENT-2608-BLOCK", "CHILD-2608-BLOCK-A", "CHILD-2608-BLOCK-B");
convertParentSplitRootToP01(root);
ObjectNode parentEvent = (ObjectNode) root.path("message_events").get(2);
ObjectNode parentCaseKeys = (ObjectNode) parentEvent.path("case_keys");
parentCaseKeys.putNull("group_code");
parentCaseKeys.put("block_code", "PARENT-2608-BLOCK");
String externalId = "p0-parent-split-single-block-code-001";
SourceMessageCaptureResult source = captureSourceMessage(externalId);
mockMvc.perform(signedPost(withSourceMessageId(root, externalId), "nonce-p0-parent-single-block-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(3))
.andExpect(jsonPath("$.items[0].route_code").value("R02_NEW_GROUP_BLOCK_NORMAL"))
.andExpect(jsonPath("$.items[1].route_code").value("R02_NEW_GROUP_BLOCK_NORMAL"))
.andExpect(jsonPath("$.items[2].route_code").value("R08_CANCEL_ALLOTMENT_CONTROL_BLOCK_NORMAL"));
String parentCaseKeysJson = jdbcTemplate.queryForObject("""
SELECT case_keys_json
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'R08_CANCEL_ALLOTMENT_CONTROL_BLOCK_NORMAL'
""", String.class, source.inboxId());
JsonNode normalizedCaseKeys = objectMapper.readTree(parentCaseKeysJson);
assertThat(normalizedCaseKeys.path("group_code").asText()).isEqualTo("PARENT-2608-BLOCK");
assertThat(normalizedCaseKeys.path("block_code").asText()).isEqualTo("PARENT-2608-BLOCK");
String parentPayloadJson = jdbcTemplate.queryForObject("""
SELECT ai_payload_json
FROM workflow_reservation_ai_transition
WHERE source_message_id = ?
AND route_code = 'R08_CANCEL_ALLOTMENT_CONTROL_BLOCK_NORMAL'
""", String.class, source.inboxId());
JsonNode parentPayload = objectMapper.readTree(parentPayloadJson);
assertThat(parentPayload.path("case_keys").path("group_code").asText()).isEqualTo("PARENT-2608-BLOCK");
assertThat(parentPayload.path("v3_message_event").path("case_keys").path("group_code").isNull()).isTrue();
assertThat(parentPayload.path("v3_message_event").path("case_keys").path("block_code").asText())
.isEqualTo("PARENT-2608-BLOCK");
}
@Test
void shouldCreateParentSplitManualReviewWhenParentKeysConflict() throws Exception {
ObjectNode root = fixture("parent_split_two_children.json").deepCopy();
useParentSplitBusinessKeys(root, "PARENT-2608-CONFLICT", "CHILD-2608-CONFLICT-A", "CHILD-2608-CONFLICT-B");
convertParentSplitRootToP01(root);
ObjectNode parentEvent = (ObjectNode) root.path("message_events").get(2);
ObjectNode parentCaseKeys = (ObjectNode) parentEvent.path("case_keys");
parentCaseKeys.putNull("group_code");
parentCaseKeys.putNull("block_code");
ObjectNode contextUsed = (ObjectNode) parentEvent.path("context_used");
ArrayNode candidates = contextUsed.putArray("parent_identity_candidates");
candidates.addObject()
.put("field", "group_code")
.put("value", "PARENT-2608-CONFLICT-A")
.put("evidence_source", "subject");
candidates.addObject()
.put("field", "block_code")
.put("value", "PARENT-2608-CONFLICT-B")
.put("evidence_source", "attachment");
ObjectNode manualReview = parentEvent.putObject("manual_review");
manualReview.put("reason_code", "target_object_unclear");
manualReview.put("visible_reason", "Parent Group 的 group_code 与 block_code 原始候选冲突，请人工确认目标。");
manualReview.put("review_record_type", "business_event_review");
manualReview.putArray("missing_fields")
.add("/case_keys/group_code")
.add("/case_keys/block_code");
manualReview.putArray("blocking_points")
.add("Parent Group identity cannot be safely normalized.");
manualReview.putArray("conflicting_points")
.add("PARENT-2608-CONFLICT-A")
.add("PARENT-2608-CONFLICT-B");
manualReview.putArray("suggested_human_actions")
.add("confirm_parent_group_identity");
manualReview.putArray("evidence_to_check")
.add("parent_identity_candidates");
manualReview.putObject("known_fields");
String externalId = "p0-parent-split-key-conflict-001";
SourceMessageCaptureResult source = captureSourceMessage(externalId);
mockMvc.perform(signedPost(withSourceMessageId(root, externalId), "nonce-p0-parent-key-conflict-001"))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.accepted_count").value(3))
.andExpect(jsonPath("$.items[0].route_code").value("R02_NEW_GROUP_BLOCK_NORMAL"))
.andExpect(jsonPath("$.items[1].route_code").value("R02_NEW_GROUP_BLOCK_NORMAL"))
.andExpect(jsonPath("$.items[2].route_code").value("R08_CANCEL_ALLOTMENT_CONTROL_BLOCK_REVIEW"))
.andExpect(jsonPath("$.items[2].adapter_error_code").doesNotExist());
Long parentReviewTaskCount = jdbcTemplate.queryForObject("""
SELECT COUNT(*)
FROM workflow_reservation_task_card card
JOIN workflow_reservation_task task
ON task.id = card.task_id
JOIN workflow_reservation_ai_transition transition
ON transition.id = task.ai_transition_id
WHERE task.source_message_id = ?
AND transition.route_code = 'R08_CANCEL_ALLOTMENT_CONTROL_BLOCK_REVIEW'
AND task.result_type = 'manual_review'
""", Long.class, source.inboxId());
assertThat(parentReviewTaskCount).isEqualTo(1L);
}
@Test
void shouldFailClosedWhenCurrentProducerUsesLegacyParentCancelBooking() throws Exception {
ObjectNode root = fixture("parent_split_two_children.json").deepCopy();

132
server/src/test/java/cn/nianxx/thhotel/workflows/reservation/control/SuperAgentTaskResultStrictSourceMessageIdControllerTest.java Normal file
View File

@@ -0,0 +1,132 @@
package cn.nianxx.thhotel.workflows.reservation.control;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import cn.nianxx.thhotel.ThHotelApplication;
import cn.nianxx.thhotel.platform.message.common.request.CaptureSourceMessageCommand;
import cn.nianxx.thhotel.platform.message.common.result.SourceMessageCaptureResult;
import cn.nianxx.thhotel.platform.message.service.SourceMessageCaptureService;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;
import java.util.List;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;
@SpringBootTest(
classes = ThHotelApplication.class,
properties = {
"superagent.task-result.hmac-secret=test-superagent-secret",
"superagent.task-result.clock-skew-seconds=300",
"superagent.task-result.nonce-ttl-seconds=600",
"superagent.task-result.max-body-bytes=12000",
"superagent.task-result.allow-legacy-internal-source-message-id=false"
})
@AutoConfigureMockMvc
@ActiveProfiles("test")
class SuperAgentTaskResultStrictSourceMessageIdControllerTest {
private static final String ENDPOINT = "/api/integrations/superagent/task-results";
private static final String CLIENT_ID = "superagent-test-client";
private static final String SECRET = "test-superagent-secret";
@Autowired
private MockMvc mockMvc;
@Autowired
private SourceMessageCaptureService captureService;
@Test
void shouldRejectInternalSourceMessageIdWhenLegacyCompatibilityDisabled() throws Exception {
SourceMessageCaptureResult source = captureSourceMessage("mail-strict-external-id-only-001");
String body = """
{
"source_message_id": "%s",
"ai_task_results": [
{
"source_event_index": 1,
"catalog_code": "S01",
"skill_id": "S01_new_booking_skill",
"result_type": "normal_task",
"task_type": "New Booking",
"task_subtype": "new_fit_reservation",
"current_or_history": "current",
"visible_reason": "AI extracted a task result.",
"relevant_message_excerpt": "Please handle booking message.",
"attachments": [],
"file_references": [],
"context_used": {},
"case_keys": {},
"extracted_fields": {},
"additional_operations": [],
"idempotency_key": null
}
],
"extraction_warnings": []
}
""".formatted(source.inboxId());
String timestamp = Instant.now().toString();
String nonce = "nonce-strict-external-id-only-001";
mockMvc.perform(post(ENDPOINT)
.contentType(MediaType.APPLICATION_JSON)
.content(body)
.header("X-TH-Hotel-SuperAgent-Client-Id", CLIENT_ID)
.header("X-TH-Hotel-SuperAgent-Timestamp", timestamp)
.header("X-TH-Hotel-SuperAgent-Nonce", nonce)
.header("X-TH-Hotel-SuperAgent-Signature", signature(body, nonce, timestamp)))
.andExpect(status().isNotFound())
.andExpect(jsonPath("$.error_code").value("SOURCE_MESSAGE_NOT_FOUND"));
}
private SourceMessageCaptureResult captureSourceMessage(String externalMessageId) {
return captureService.capture(new CaptureSourceMessageCommand(
"HOTEL-TEST",
"AGENTBUS",
"OUTLOOK",
externalMessageId,
"thread-" + externalMessageId,
"frame-" + externalMessageId,
"session-m002",
Instant.parse("2026-07-07T08:00:00Z"),
"guest@example.test",
"M002 SuperAgent intake",
"Please handle booking message.",
"<html><body>Please handle booking message.</body></html>",
"{\"source\":{\"external_message_id\":\"" + externalMessageId + "\"}}",
"agentbus-outlook-v1",
List.of()
));
}
private String signature(String body, String nonce, String timestamp) throws Exception {
String canonical = "POST\n"
+ ENDPOINT
+ "\n"
+ timestamp
+ "\n"
+ nonce
+ "\n"
+ CLIENT_ID
+ "\n"
+ sha256(body);
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
return "sha256=" + HexFormat.of().formatHex(mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8)));
}
private String sha256(String body) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
return HexFormat.of().formatHex(digest.digest(body.getBytes(StandardCharsets.UTF_8)));
}
}