修复MCP任务结果提交契约校验

docs/project/integrations/superagent-mcp/submit-payload-mapping.md

@@ -4,7 +4,7 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.1 |
+| 文档版本 | 0.2 |
 | 日期 | 2026-07-12 |
 | 状态 | 已落地第一版 |
 | 适用范围 | `th_hotel_submit_task_results` 的 V3/P0.1 payload adapter、schema validator 和一次提交规则 |
@@ -34,13 +34,15 @@ server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/service/impl/
 
 | 形态 | 判断方式 | 处理方式 |
 | --- | --- | --- |
-| V3 业务根 | 同时包含 `source_message` 和 `message_events` | 先校验根结构、source message、event 必填字段和关系索引，再按 `message_events[]` 顺序映射 `source_event_index` |
-| V3 S10/S99 入口通知 | 同时包含 `source_message` 和 `route_code` | 校验 S10/S99 根字段和 source message 后透传给业务入站服务 |
-| V2 兼容任务结果 | 包含 `ai_task_results` | 保留旧 `source_message_id + ai_task_results[]` 兼容路径 |
+| V3 业务根 | 包含 `message_events` | 校验根结构、source message、event transport 字段和关系索引，再按 `message_events[]` 顺序映射 `source_event_index`；event 业务合法性仍交给业务入站层落 `adapter_contract_error` |
+| V3 S10/S99 入口通知 | 包含 `route_code` 或入口通知 `result_type` | 校验 S10/S99 根字段和 source message 后透传给业务入站服务 |
+| V2 兼容任务结果 | 包含 `ai_task_results` | 保留旧 `source_message_id + ai_task_results[]` 兼容路径，并在 MCP 层校验完整 item schema |
 
 未知根字段会在 MCP 层被拒绝，错误码为 `MCP_SUBMIT_PAYLOAD_INVALID`。
 
-`source_message_id` 缺失属于既有基础设施输入错误，MCP adapter 不改写该错误通道；业务入站服务会返回 `MISSING_SOURCE_MESSAGE_ID`。
+`source_message_id` 缺失或整个 `source_message` 缺失属于既有基础设施输入错误，MCP adapter 不改写该错误通道；业务入站服务会返回 `MISSING_SOURCE_MESSAGE_ID`。
+
+V3 业务根和 S10/S99 如果携带 MCP schema 中的兼容字段 `hotel_id`、`source_provider`、`source_channel`，adapter 会接受并在转交业务入站层前移除。业务定位仍以系统酒店和 `source_message.source_message_id` 为准。
 
 ## 4. source_message_id 定义
 
@@ -72,10 +74,25 @@ MCP adapter 按 `message_events[]` 数组顺序生成一基数字索引：
 - `parent_source_event_index` 输出为数字。
 - `related_source_event_indices[]` 输出为字符串数字数组，保持原顺序。
 - 悬空引用、重复引用、缺失事件 ID 都在 MCP 层拒绝。
+- MCP tool result 会返回 `mapping_diagnostics.source_event_index_mapping[]`，记录原始事件 ID 到本系统索引的映射；该诊断不写入 `workflow_reservation_ai_transition.ai_payload_json`。
 
 ## 6. ai_task_results[] 兼容 item schema
 
-V2 兼容路径仍保留，`ai_task_results[]` item 以 REST 总契约为准，第一版 MCP schema 只暴露 object，但业务入站会校验核心字段。
+V2 兼容路径仍保留，`ai_task_results[]` item 以 REST 总契约为准。当前 MCP `tools/list` 已暴露 item schema，adapter 也会在提交业务层前校验必填字段、字段类型、允许 `result_type`、未知字段和根级 `extraction_warnings`。
+
+必填字段：
+
+- `source_event_index`
+- `catalog_code`
+- `skill_id`
+- `result_type`
+- `task_type`
+
+允许的 `result_type`：
+
+- `normal_task`
+- `manual_review`
+- `informational_message`，仅历史兼容
 
 建议 item 结构：
 
@@ -216,6 +233,30 @@ MCP adapter 进入业务层前会把父事件关系映射为：
 }
 ```
 
+MCP tool result 同时返回非业务诊断：
+
+```json
+{
+  "mapping_diagnostics": {
+    "mapping_policy": "message_events_array_order_1_based",
+    "source_event_index_mapping": [
+      {
+        "original_source_event_index": "E_CHILD_1",
+        "mapped_source_event_index": 1
+      },
+      {
+        "original_source_event_index": "E_CHILD_2",
+        "mapped_source_event_index": 2
+      },
+      {
+        "original_source_event_index": "E_PARENT",
+        "mapped_source_event_index": 3
+      }
+    ]
+  }
+}
+```
+
 ## 9. 成功示例：跨 Child Trace
 
 当 Trace 覆盖完整 Parent split 的全部 Child 时，不能只绑定第一个 Child。业务结果应保留全部 Child 引用：
@@ -300,9 +341,14 @@ MCP adapter 会把它映射为：
 覆盖内容：
 
 - `tools/list` 暴露 V3 submit schema。
-- 缺失 `source_message_id` 保持既有 `MISSING_SOURCE_MESSAGE_ID` 错误。
+- `tools/list` 暴露 V2 `ai_task_results[]` item schema 和 V3 `relationship_type`。
+- 缺失 `source_message_id` 或整个 `source_message` 保持既有 `MISSING_SOURCE_MESSAGE_ID` 错误。
 - 未知根字段在业务层前被拒绝。
+- V2 item 缺必填字段在业务层前被拒绝。
 - 悬空 `related_source_event_indices` 在业务层前被拒绝。
 - 重复 `related_source_event_indices` 在业务层前被拒绝。
 - `E_CHILD_1/E_CHILD_2/E_PARENT` 按数组顺序映射为 `1/2/3`。
+- 跨 Child Trace 关系映射为完整 `["1", "2"]`，不压缩到第一个 Child。
+- S10/S99 可通过 MCP 写入工具创建只读来源消息任务。
+- V3 event 业务契约错误由业务入站层保存为 `adapter_contract_error` transition。
 - 合法 Parent split 只创建一个 AI batch，并返回 `accepted_count=3`。