修正SuperAgent任务结果来源消息定位

2026-07-12 14:53:54 +08:00
parent bf796946f9
commit eee37315a0
18 changed files with 789 additions and 86 deletions
--- a/docs/project/go-live-notes.md
+++ b/docs/project/go-live-notes.md
@@ -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；正式联调和生产不得开启。 |

 注意：

--- a/docs/project/integrations/superagent-api-contract.md
+++ b/docs/project/integrations/superagent-api-contract.md
@@ -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 不应开启 |

 上线注意事项：

--- a/docs/project/integrations/superagent-mcp/integration-guide.md
+++ b/docs/project/integrations/superagent-mcp/integration-guide.md
@@ -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：
--- a/docs/project/integrations/superagent-mcp/test-cases.md
+++ b/docs/project/integrations/superagent-mcp/test-cases.md
@@ -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` |

 写入验证：

--- a/docs/project/integrations/superagent-mcp/tools.md
+++ b/docs/project/integrations/superagent-mcp/tools.md
@@ -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 输出
--- a/docs/project/requirements/M002-order-task-workflow-v3.md
+++ b/docs/project/requirements/M002-order-task-workflow-v3.md
@@ -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`。
--- a/docs/project/requirements/M002-superagent-task-result-api-contract.md
+++ b/docs/project/requirements/M002-superagent-task-result-api-contract.md
@@ -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 重复 |
--- a/docs/project/requirements/M002-v3-p0.1-parent-group-routing-update.md
+++ b/docs/project/requirements/M002-v3-p0.1-parent-group-routing-update.md
@@ -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。