Files

2026-07-22 23:43:54 +07:00

8.6 KiB

Raw Blame History

TH Hotel MCP Submit Payload Mapping

1. 文档信息

项目	内容
文档版本	0.3
日期	2026-07-22
状态	当前有效：M002 V4-only
适用范围	`th_hotel_submit_task_results` 的 M002 V4 payload adapter、schema validator 和一次提交规则

2. 核心原则

th_hotel_submit_task_results 只接收 M002 V4 任务结果包。MCP 层只做 transport 形态校验和 V4 根结构防错，不重新解释业务含义、不调用 Skill、不根据字段名猜测任务类型。

当前开发阶段已确认不维护 V2/V3 submit 兼容。旧 source_message + message_events[] + case_candidates[]、旧结构化 S10/S99、source_message_id + ai_task_results[] 都不会再通过 MCP submit 写入业务层。

目标链路：

SuperAgent M002 V4 业务结果
  -> MCP Submit Payload Adapter
  -> ReservationAiTaskIntakeService V4 入站
  -> V4 order task / V4 task card / V4 source notification
  -> MCP tool result

实现位置：

server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/service/SuperAgentMcpSubmitPayloadAdapter.java
server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/service/impl/SuperAgentMcpSubmitPayloadAdapterImpl.java

3. 支持的输入形态

形态	判断方式	处理方式
V4 普通业务包	根字段包含 `route_code=null`、`source_message`、`order_contexts[]`、`message_events[]`	MCP adapter 校验根结构和 V4 `source_message` 后原样透传；业务入站层创建 V4 订单任务和任务卡
V4 来源通知包	根字段包含 `route_code=S10/S99`、`source_message`、空 `order_contexts[]`、空 `message_events[]`	MCP adapter 校验根结构和 V4 `source_message` 后原样透传；业务入站层创建 V4 来源通知

不再支持的输入形态：

旧形态	示例特征	当前处理
V3 业务根	`case_candidates`、`extraction_warnings`、`unhandled_current_intents`、旧 `source_message.from`	返回 `MCP_SUBMIT_V4_REQUIRED`，不调用业务写入 Service
V3 S10/S99	`handler_type`、`result_type=source_message_review_notification`、旧 `source_message.received_at`	返回 `MCP_SUBMIT_V4_REQUIRED`，不调用业务写入 Service
V2 任务结果	顶层 `source_message_id + ai_task_results[]`	返回 `MCP_SUBMIT_V4_REQUIRED`，不调用业务写入 Service

未知根字段会在 MCP 层被拒绝，错误码为 MCP_SUBMIT_PAYLOAD_INVALID。

4. V4 根结构

{
  "route_code": null,
  "source_message": {},
  "order_contexts": [],
  "message_events": []
}

字段规则：

字段	规则
`route_code`	必须存在；普通业务为 `null`，来源通知为 `S10` 或 `S99`
`source_message`	必须存在；结构见本文第 5 节
`order_contexts[]`	必须存在且为数组；普通业务至少一条，来源通知为空数组
`message_events[]`	必须存在且为数组；普通业务至少一条，来源通知为空数组

MCP adapter 不再映射 source_event_index。V4 message_events[] 的数组顺序就是业务处理顺序；业务层使用数组位置派生一基 event index。

5. source_message

{
  "source_message_id": "mail-20260722-0001",
  "conversation_id": "thread-001",
  "subject": "Update Booking",
  "sender": "agent@example.test",
  "sent_at": "2026-07-22T08:00:00Z",
  "body": "Please update the booking.",
  "body_content_type": "text/plain",
  "attachments": []
}

字段规则：

字段	规则
`source_message_id`	必填非空；必须来自 AgentBus 原始 payload 的外部消息 ID，对应 `platform_source_message_inbox.external_message_id`
`conversation_id`	可缺省；出现时必须为字符串或 `null`
`subject`	必须出现，可为 `null`
`sender`	必须出现，可为 `null`
`sent_at`	必须出现，可为 `null`；时间点使用 UTC ISO-8601
`body`	必须出现，可为 `null`；当前邮件原文，不摘要、不翻译、不重排
`body_content_type`	必填；只能为 `text/plain` 或 `text/html`
`attachments[]`	必填数组；附件结构见第 6 节

旧 V3 的 from、cc、received_at、source_channel 不再属于 MCP submit 契约。hotel_id、source_provider、source_channel 也不需要 SuperAgent 传入。

6. attachments

{
  "id": "att-1",
  "name": "payment-slip.jpg",
  "content_type": "image/jpeg",
  "url": "https://upstream-storage.example/payment-slip.jpg",
  "size": 251524
}

字段规则：

字段	规则
`id`	必填非空；包内稳定附件引用
`name`	必填非空；原始文件名
`content_type`	必填非空；MIME 类型
`url`	必填非空；上游文件 URL，普通 V4 task detail 不直接返回
`size`	可省略或为 `null`；有值时必须是数字

Payment 事件只能通过 attachment_ids[] 引用 source_message.attachments[].id，不能复制完整附件对象或按文件名猜测。

7. 成功示例

7.1 普通业务

{
  "route_code": null,
  "source_message": {
    "source_message_id": "mail-mcp-v4-business-001",
    "conversation_id": "thread-mcp-v4-business-001",
    "subject": "Group booking and payment",
    "sender": "agent@example.test",
    "sent_at": "2026-07-18T02:10:00Z",
    "body": "Please create group GRP-MCP-V4-001 and note payment attached.",
    "body_content_type": "text/plain",
    "attachments": [
      {
        "id": "att-pay-1",
        "name": "payment-slip.jpg",
        "content_type": "image/jpeg",
        "url": "https://upstream-storage.example/payment-slip.jpg",
        "size": 251524
      }
    ]
  },
  "order_contexts": [
    {
      "order_ref": "order-1",
      "basic_information": {
        "account_code": "QBD_TRAVEL",
        "manual_review": null
      }
    }
  ],
  "message_events": [
    {
      "order_ref": "order-1",
      "event_type": "NEW_BOOKING",
      "target_order": {
        "booking_type": "GROUP",
        "locator_type": "GROUP_CODE",
        "locator_value": "GRP-MCP-V4-001"
      },
      "arrival_date": "2026-07-26",
      "departure_date": "2026-07-29",
      "rate_code": "GRPA2-850UP",
      "booking_scenario": "STANDARD",
      "room_items": [
        {
          "room_type_code": "RM2",
          "room_count": 2
        }
      ],
      "manual_review": null
    },
    {
      "order_ref": "order-1",
      "event_type": "PAYMENT",
      "target_order": {
        "booking_type": "GROUP",
        "locator_type": "GROUP_CODE",
        "locator_value": "GRP-MCP-V4-001"
      },
      "attachment_ids": ["att-pay-1"],
      "manual_review": null
    }
  ]
}

7.2 S99 来源通知

{
  "route_code": "S99",
  "source_message": {
    "source_message_id": "mail-mcp-v4-s99-001",
    "conversation_id": "thread-mcp-v4-s99-001",
    "subject": "Cannot form material package",
    "sender": "guest@example.test",
    "sent_at": "2026-07-18T02:10:00Z",
    "body": "The input does not contain enough business material.",
    "body_content_type": "text/plain",
    "attachments": []
  },
  "order_contexts": [],
  "message_events": []
}

8. 错误码

错误码	中文说明
`MCP_SUBMIT_V4_REQUIRED`	MCP submit 收到的不是 M002 V4 根结构，通常是旧 V2/V3 payload
`MCP_SUBMIT_PAYLOAD_INVALID`	已具备 V4 根字段，但字段类型、未知字段或 V4 `source_message` / `attachments` 结构不符合 MCP transport 校验
`SOURCE_MESSAGE_NOT_FOUND`	V4 `source_message.source_message_id` 无法匹配 SourceMessage Inbox
`SOURCE_MESSAGE_AMBIGUOUS`	同一系统酒店下外部 `source_message_id` 匹配多条 Inbox
`ADAPTER_CONTRACT_ERROR`	V4 包或 event 通过 MCP transport，但不满足业务入站契约，业务层记录 adapter contract error

MCP adapter 校验失败时不会调用业务写入 Service，不会创建 AI batch、V4 order task、V4 card、V4 source notification 或旧任务。

9. 诊断

MCP 入站诊断表仍保存：

arguments_json：SuperAgent 调用 MCP tool 的原始 arguments。
adapted_payload_json：MCP adapter 后交给业务入站层的 payload；V4-only 模式下通常与 arguments 相同。
mapping_diagnostics_json：当前 V4-only 模式下为空对象；旧 V3 事件 ID 映射已经废弃。
safe_error_code / safe_error_summary：安全错误摘要。

排障时先对比 arguments_json 和 adapted_payload_json。如果二者均为 V4 且业务层返回 ADAPTER_CONTRACT_ERROR，说明问题在 SuperAgent V4 业务契约内容或业务校验；如果错误为 MCP_SUBMIT_V4_REQUIRED，说明 SuperAgent 仍在按旧 schema 输出。

8.6 KiB Raw Blame History Unescape Escape

TH Hotel MCP Submit Payload Mapping

1. 文档信息

2. 核心原则

3. 支持的输入形态

4. V4 根结构

5. source_message

6. attachments

7. 成功示例

7.1 普通业务

7.2 S99 来源通知

8. 错误码

9. 诊断

8.6 KiB

Raw Blame History