收口MCP提交为V4契约

docs/project/integrations/superagent-mcp/inbound-diagnostics.md

@@ -11,8 +11,9 @@
 
 ## 2. 背景
 
-SuperAgent 通过 MCP `th_hotel_submit_task_results` 提交业务结果时，当前后端会把 MCP
-`params.arguments` 转换为本系统 `ReservationAiTaskIntakeService` 可接收的业务 payload。
+SuperAgent 通过 MCP `th_hotel_submit_task_results` 提交业务结果时，当前后端只接受 M002 V4
+`params.arguments`，并把通过 V4 transport 校验的 payload 交给本系统
+`ReservationAiTaskIntakeService`。
 当业务入站失败时，如果只看到最终错误，例如 `SOURCE_MESSAGE_NOT_FOUND` 或
 `MCP_SUBMIT_PAYLOAD_INVALID`，很难判断问题来自：
 
@@ -54,7 +55,7 @@ platform_superagent_mcp_call_diagnostic
 | `raw_body_json` | 原始 MCP JSON-RPC 请求体，受控诊断字段 |
 | `arguments_json` | `params.arguments` 原始 JSON，受控诊断字段 |
 | `adapted_payload_json` | submit adapter 转换后送入业务入站层的 JSON；非 submit 或转换失败为空 |
-| `mapping_diagnostics_json` | submit adapter 事件索引映射诊断 |
+| `mapping_diagnostics_json` | submit adapter 诊断；V4-only 模式下通常为空对象，旧 V3 事件索引映射已废弃 |
 | `response_summary_json` | MCP 响应安全摘要，不保存完整查询结果或正文 |
 | `call_status` | `RECEIVED`、`SUCCEEDED`、`FAILED` |
 | `safe_error_code` | 安全错误码，例如 `SOURCE_MESSAGE_NOT_FOUND` |
@@ -71,11 +72,15 @@ platform_superagent_mcp_call_diagnostic
 | body 超限 | 不写诊断表，直接返回原有 body too large 错误 |
 | JSON 解析失败 | 鉴权通过后写入失败诊断，保存 body hash 和 raw body |
 | tools/list / query tool | 写入原始请求和参数，只保存响应安全摘要 |
-| submit adapter 成功 | 补写 `adapted_payload_json` 和 `mapping_diagnostics_json` |
+| submit adapter 成功 | 补写 `adapted_payload_json` 和 `mapping_diagnostics_json`；V4-only 模式下 `adapted_payload_json` 通常与 `arguments_json` 相同 |
 | submit adapter 失败 | 保留 `arguments_json`，记录 adapter 安全错误码 |
 | 业务入站失败 | 保留 `arguments_json` 和可用的 `adapted_payload_json`，记录业务安全错误码 |
 | 调用成功 | 标记 `SUCCEEDED`，保存响应安全摘要 |
 
+因此，鉴权通过且 body 未超限的旧 V2 / V3 submit payload 会写入本表，`call_status=FAILED`，
+`safe_error_code=MCP_SUBMIT_V4_REQUIRED`，`adapted_payload_json` 为空；这表示请求已被 MCP
+adapter 拒绝，没有进入业务入站 Service。
+
 ## 6. 排障 SQL
 
 按外部 SourceMessage ID 查询 SuperAgent 传入的原始 MCP 参数：
@@ -113,7 +118,7 @@ WHERE id = <diagnostic_id>;
 ## 7. 与现有链路关系
 
 - REST `POST /api/integrations/superagent/task-results` 仍使用现有 batch / transition 追踪。
-- MCP `th_hotel_submit_task_results` 会同时拥有 MCP 入站诊断和业务 batch / transition 追踪。
+- MCP `th_hotel_submit_task_results` 会同时拥有 MCP 入站诊断和业务 batch / transition 追踪；如果返回 `MCP_SUBMIT_V4_REQUIRED`，说明 SuperAgent 仍提交旧 V2/V3 schema，不会进入业务写入 Service。
 - Debug EML、AgentBus dispatch run 不改原逻辑；如果 SuperAgent 最终通过 MCP 回写，才进入本诊断表。
 - 第一版不新增前端页面和查询接口；DB 权限和运维访问由部署环境控制。