收口MCP提交为V4契约

docs/project/integrations/superagent-api-contract.md

@@ -4,9 +4,9 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.10 |
-| 日期 | 2026-07-20 |
-| 状态 | 当前代码契约已支持 V4 订单任务 + 多卡入站、V4 S10/S99 来源通知、V2 `ai_task_results[]` 兼容、V3 业务根兼容、旧 S000/S999 兼容、M011 Booking Excel 调 SuperAgent 前预处理增强和单酒店 hotel_id 后端解析 |
+| 文档版本 | 0.11 |
+| 日期 | 2026-07-22 |
+| 状态 | 当前代码契约已支持 V4 订单任务 + 多卡入站、V4 S10/S99 来源通知、REST 历史 V2 `ai_task_results[]` / V3 业务根兼容、旧 S000/S999 兼容、M011 Booking Excel 调 SuperAgent 前预处理增强和单酒店 hotel_id 后端解析；MCP `th_hotel_submit_task_results` 已收口为 M002 V4-only，不再接受 V2/V3 submit payload |
 | 适用范围 | SuperAgent 调用本系统查询上下文、查询邮件会话、提交 AI 任务结果 |
 | 主要读者 | SuperAgent 对接方、后端、测试、运维 |
 
@@ -714,9 +714,9 @@ V3 字段说明：
 
 当前已支持的 V3 行为：
 
-- 如果通过 MCP `th_hotel_submit_task_results` 调用，MCP adapter 会在进入业务入站服务前按 `message_events[]` 顺序把 Agent 内部事件 ID 映射为本系统一基 `source_event_index`，并校验 `related_source_event_index`、`parent_source_event_index` 和 `related_source_event_indices[]` 是否悬空或重复；成功响应会额外返回 `mapping_diagnostics`，该诊断不写入业务 JSON。
-- MCP adapter 只拦 transport 层问题，例如未知字段、缺失或重复 `source_event_index`、关系引用悬空或重复、V2 item schema 不完整；V3 event 的业务契约问题，例如 unsupported `event_type`、不完整 `case_keys`、不完整 `manual_review`，继续由业务入站层保存为 `adapter_contract_error` transition。
-- MCP 路径缺失 `source_message.source_message_id` 或整个 `source_message` 时，保留业务入站层 `MISSING_SOURCE_MESSAGE_ID` 错误语义。
+- 仅 REST 历史兼容路径仍可接收 V3 业务根；MCP `th_hotel_submit_task_results` 已收口为 V4-only，旧 V3 payload 会返回 `MCP_SUBMIT_V4_REQUIRED`。
+- REST 历史兼容路径中，V3 event 的业务契约问题，例如 unsupported `event_type`、不完整 `case_keys`、不完整 `manual_review`，继续由业务入站层保存为 `adapter_contract_error` transition。
+- REST 历史兼容路径缺失 `source_message.source_message_id` 或整个 `source_message` 时，保留业务入站层 `MISSING_SOURCE_MESSAGE_ID` 错误语义。
 - 40 条 P0.1 路由进入后端枚举 / 稳定配置。
 - `route_code` 是稳定代码，不因路由总数从 42 调整为 40 而重编号；联调方不要按数字连续性判断合法性。
 - V3 结构化 `S10/S99` 兼容路径创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见；V4 新入站不走该模型，改用来源通知。
@@ -788,13 +788,13 @@ V3 字段说明：
 | `ai_task_results[].source_event_index` | 是 | AI current 事件序号 |
 | `ai_task_results[].catalog_code` | 是 | Skill 目录代码 |
 | `ai_task_results[].skill_id` | 是 | Skill 标识 |
-| `ai_task_results[].result_type` | 是 | 当前代码契约接受 `normal_task`、`manual_review`；`informational_message` 仅历史兼容；MCP 路径会在 adapter 层校验 |
+| `ai_task_results[].result_type` | 是 | 当前 REST 历史兼容契约接受 `normal_task`、`manual_review`；`informational_message` 仅历史兼容；MCP submit 已不接受 V2 `ai_task_results[]` |
 | `ai_task_results[].task_type` | 是 | AI 原始任务类型 |
 | `ai_task_results[].task_subtype` | 否 | 业务动作 subtype |
 | `ai_task_results[].case_keys` | 否 | 订单关联候选键 |
 | `ai_task_results[].extracted_fields` | 否 | 业务字段主体 |
 
-正式联调时，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 正式契约。
+正式联调时，SuperAgent 不需要传 `hotel_id`。后端通过系统酒店和外部 `source_message_id` 查找唯一 `platform_source_message_inbox.external_message_id`，真实 provider/channel 以 Inbox 入库值为准。如果没有找到，返回 `SOURCE_MESSAGE_NOT_FOUND`；如果同一系统酒店下匹配到多条，返回 `SOURCE_MESSAGE_AMBIGUOUS`。本节为 REST 历史兼容说明；MCP submit 已不接受顶层 `source_message_id + ai_task_results[]`。
 
 `informational_message` 结构化任务仅用于历史兼容。新数据如果是纯信息类邮件或无法形成业务素材包，应优先使用 V4 `S10/S99` 来源通知；V3 结构化 `S10/S99` 和下面的 `S000/S999` 文本请求体仅作为旧联调或兼容路径。
 
@@ -958,6 +958,8 @@ V3 `adapter_contract_error` 响应中的 `items[]` 不会包含 `order_id` / `ta
 | `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` |
+| `MCP_SUBMIT_V4_REQUIRED` | 200 tool error | MCP `th_hotel_submit_task_results` 收到的不是 M002 V4 根结构，例如旧 V2/V3 payload |
+| `MCP_SUBMIT_PAYLOAD_INVALID` | 200 tool error | MCP submit 已具备 V4 根字段，但 transport 字段类型、未知字段或 V4 `source_message` / `attachments` 结构无效 |
 
 ## 10. HMAC 上线配置