新增SuperAgent MCP入站诊断链路

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

@@ -0,0 +1,128 @@
+# TH Hotel SuperAgent MCP 入站诊断链路
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档版本 | 0.1 |
+| 日期 | 2026-07-22 |
+| 状态 | 已落地第一版 |
+| 适用范围 | `POST /mcp` 的 SuperAgent MCP 请求排障、参数还原和安全审计 |
+
+## 2. 背景
+
+SuperAgent 通过 MCP `th_hotel_submit_task_results` 提交业务结果时，当前后端会把 MCP
+`params.arguments` 转换为本系统 `ReservationAiTaskIntakeService` 可接收的业务 payload。
+当业务入站失败时，如果只看到最终错误，例如 `SOURCE_MESSAGE_NOT_FOUND` 或
+`MCP_SUBMIT_PAYLOAD_INVALID`，很难判断问题来自：
+
+- SuperAgent 实际传入的 MCP 参数。
+- MCP submit adapter 的转换逻辑。
+- 本系统业务入站校验或数据状态。
+
+本 checkpoint 增加 MCP 入站诊断链路，只为联调排障和受控审计提供证据，不改变原有业务处理
+逻辑。
+
+## 3. 设计原则
+
+- 诊断记录不是业务事实，不参与订单、任务、卡片、来源通知或 OPERA 流转。
+- `/mcp` 原有鉴权、body size、tools/call、adapter、业务 Service 调用顺序不变。
+- 诊断写入失败时不得影响 MCP 原响应；只能记录安全 warn 日志。
+- 普通日志只输出诊断 ID、tool、外部 source message id、安全错误码和安全错误摘要。
+- 不在普通前端业务接口暴露 MCP 原始请求体、邮件正文、附件 URL、AI raw payload 或 Secret。
+- 查询类 MCP tool 的响应可能包含受控正文，第一版不保存完整响应，只保存响应安全摘要。
+
+## 4. 第一版诊断表
+
+新增表：
+
+```text
+platform_superagent_mcp_call_diagnostic
+```
+
+字段口径：
+
+| 字段 | 中文说明 |
+| --- | --- |
+| `id` | MCP 调用诊断 ID |
+| `jsonrpc_id` | JSON-RPC request id 的安全文本表示 |
+| `method_name` | JSON-RPC method，例如 `tools/call` |
+| `tool_name` | MCP tool 名称，例如 `th_hotel_submit_task_results` |
+| `mcp_client_id` | 调用方机器身份，第一版固定 `superagent-mcp` |
+| `request_body_bytes` | 原始请求体 UTF-8 字节数 |
+| `request_body_sha256` | 原始请求体 SHA-256，用于不暴露正文时定位同一次请求 |
+| `raw_body_json` | 原始 MCP JSON-RPC 请求体，受控诊断字段 |
+| `arguments_json` | `params.arguments` 原始 JSON，受控诊断字段 |
+| `adapted_payload_json` | submit adapter 转换后送入业务入站层的 JSON；非 submit 或转换失败为空 |
+| `mapping_diagnostics_json` | submit adapter 事件索引映射诊断 |
+| `response_summary_json` | MCP 响应安全摘要，不保存完整查询结果或正文 |
+| `call_status` | `RECEIVED`、`SUCCEEDED`、`FAILED` |
+| `safe_error_code` | 安全错误码，例如 `SOURCE_MESSAGE_NOT_FOUND` |
+| `safe_error_summary` | 安全错误摘要，不包含邮件正文、HTML、附件 URL 或 Secret |
+| `source_message_external_id` | 从 submit 入参中尽力提取的外部来源消息 ID |
+| `hotel_id` | 后端解析出的系统酒店 ID；解析失败时为空 |
+| `created_at` / `updated_at` | UTC 创建 / 更新时间 |
+
+## 5. 诊断写入时机
+
+| 阶段 | 行为 |
+| --- | --- |
+| 鉴权失败 | 不写诊断表，避免为未授权请求保存原始数据 |
+| body 超限 | 不写诊断表，直接返回原有 body too large 错误 |
+| JSON 解析失败 | 鉴权通过后写入失败诊断，保存 body hash 和 raw body |
+| tools/list / query tool | 写入原始请求和参数，只保存响应安全摘要 |
+| submit adapter 成功 | 补写 `adapted_payload_json` 和 `mapping_diagnostics_json` |
+| submit adapter 失败 | 保留 `arguments_json`，记录 adapter 安全错误码 |
+| 业务入站失败 | 保留 `arguments_json` 和可用的 `adapted_payload_json`，记录业务安全错误码 |
+| 调用成功 | 标记 `SUCCEEDED`，保存响应安全摘要 |
+
+## 6. 排障 SQL
+
+按外部 SourceMessage ID 查询 SuperAgent 传入的原始 MCP 参数：
+
+```sql
+SELECT
+    id,
+    created_at,
+    call_status,
+    method_name,
+    tool_name,
+    source_message_external_id,
+    safe_error_code,
+    safe_error_summary,
+    arguments_json,
+    adapted_payload_json,
+    mapping_diagnostics_json
+FROM platform_superagent_mcp_call_diagnostic
+WHERE source_message_external_id = '<external_message_id>'
+ORDER BY created_at DESC, id DESC;
+```
+
+按诊断 ID 查看一次请求的原始 envelope：
+
+```sql
+SELECT
+    id,
+    request_body_sha256,
+    raw_body_json,
+    response_summary_json
+FROM platform_superagent_mcp_call_diagnostic
+WHERE id = <diagnostic_id>;
+```
+
+## 7. 与现有链路关系
+
+- REST `POST /api/integrations/superagent/task-results` 仍使用现有 batch / transition 追踪。
+- MCP `th_hotel_submit_task_results` 会同时拥有 MCP 入站诊断和业务 batch / transition 追踪。
+- Debug EML、AgentBus dispatch run 不改原逻辑；如果 SuperAgent 最终通过 MCP 回写，才进入本诊断表。
+- 第一版不新增前端页面和查询接口；DB 权限和运维访问由部署环境控制。
+
+## 8. 安全说明
+
+`raw_body_json`、`arguments_json` 和 `adapted_payload_json` 可能包含 SuperAgent 产出的邮件摘录、
+客户姓名、业务线索或附件 ID，因此：
+
+- 不写入普通应用日志。
+- 不通过前端业务接口返回。
+- 不提交为测试夹具中的真实客户数据。
+- 生产使用时需要控制数据库访问权限，并在上线前确认保留周期。