统一 SuperAgent 查询接口鉴权契约

docs/project/requirements/M002-ai-query-minimal-fields.md

@@ -4,8 +4,8 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.1 |
-| 日期 | 2026-07-07 |
+| 文档版本 | 0.2 |
+| 日期 | 2026-07-08 |
 | 状态 | 第一版后端实现依据与落地记录 |
 | 适用范围 | SuperAgent / Main Agent 调用本系统查询订单和任务上下文 |
 | 主要读者 | 后端、SuperAgent 对接方、测试、后续协作 agent |
@@ -32,7 +32,8 @@
 - `body_current` 才能触发业务动作；`body_thread` 只能作为目标绑定证据。
 - 如果查询 key 来自历史线程，调用方必须传 `target_key_source=body_thread_evidence` 和 `body_thread_used_only_as_evidence=true`。
 - 第一版不伪造 OPERA 字段。当前系统没有可靠来源的字段返回 `null`，并在 `warnings` 或 `hard_validation_warnings` 中说明。
-- 导入契约没有显式要求 `hotel_id`，但本系统订单、任务和 AI 过渡表均按 `hotel_id` 隔离。第一版建议请求体显式传 `hotel_id`；如果后续改为从鉴权或 `source_message_id` 解析酒店，需要在实现前统一。
+- SuperAgent 允许作为全局上下文查询方按任意业务 key 查询；`source_message_id` 和 `source_event_index` 只作为可选审计和排查字段，不作为查询边界。
+- 导入契约没有显式要求 `hotel_id`，但本系统订单、任务和 AI 过渡表均按 `hotel_id` 隔离。第一版请求体必须显式传 `hotel_id`。
 
 ## 3. Skill 对接口 1、2 的实际需要
 
@@ -58,14 +59,28 @@
 
 ### 4.1 通用请求头
 
-安全方向上建议后续复用 SuperAgent 服务到服务鉴权思路，具体签名规则可参考任务结果接收接口。当前已落地的最小字段版暂不启用 HMAC，只强制 `X-Request-Id`，接口补签名规则前不得把该接口暴露到不可信网络。
+查询接口 1、2 已复用 SuperAgent 任务结果接收接口的 HMAC-SHA256 鉴权规则。签名规则、secret、timestamp 窗口、nonce 防重放和请求体大小配置与任务结果接收接口保持一致。
 
 | Header | 是否必填 | 中文说明 |
 | --- | --- | --- |
 | `Content-Type` | 是 | 固定 `application/json` |
-| `X-Request-Id` | 是 | 调用方生成的请求 ID，用于日志串联 |
-| `X-AI-Trace-Id` | 否 | AI 运行链路 ID |
-| `X-Source-Message-Id` | 否 | 来源消息 ID，便于排查 |
+| `X-TH-Hotel-SuperAgent-Client-Id` | 是 | SuperAgent 调用方客户端 ID |
+| `X-TH-Hotel-SuperAgent-Timestamp` | 是 | UTC ISO-8601 时间 |
+| `X-TH-Hotel-SuperAgent-Nonce` | 是 | 每次请求唯一随机值，用于防重放 |
+| `X-TH-Hotel-SuperAgent-Signature` | 是 | HMAC 签名，格式 `sha256=<lowercase-hex>` |
+| `X-TH-Hotel-Request-Id` | 否 | 调用方生成的请求 ID，用于日志串联 |
+| `X-TH-Hotel-AI-Trace-Id` | 否 | AI 运行链路 ID |
+
+规范签名串：
+
+```text
+POST
+<request_path>
+<X-TH-Hotel-SuperAgent-Timestamp>
+<X-TH-Hotel-SuperAgent-Nonce>
+<X-TH-Hotel-SuperAgent-Client-Id>
+<lowercase-hex-sha256-of-raw-body>
+```
 
 ### 4.2 通用响应包
 
@@ -126,8 +141,8 @@ POST /api/ai-query/v1/case-context
 | 字段 | 是否必填 | 中文说明 | 当前系统来源或用途 |
 | --- | --- | --- | --- |
 | `hotel_id` | 是 | 酒店或业务上下文 ID | 用于隔离 `workflow_reservation_*` 表 |
-| `source_message_id` | 是 | 当前 SourceMessage ID | 串联来源消息、AI 过渡记录和任务 |
-| `source_event_index` | 是 | 当前 current 事件序号 | 和 AI 拆分结果保持一致 |
+| `source_message_id` | 否 | 当前 SourceMessage ID | 全局上下文查询可不传；传入时只做格式校验和排查辅助 |
+| `source_event_index` | 否 | 当前 current 事件序号 | 全局上下文查询可不传；传入时必须为正整数 |
 | `group_code` | 条件必填 | Group / Allotment 优先业务 key | 查询 `GROUP_CODE` 类型订单和 AI 过渡记录 |
 | `confirmation_number` | 条件必填 | FIT 优先业务 key | 查询 `CONFIRMATION_NUMBER` 类型订单和 AI 过渡记录 |
 | `reservation_no` | 否 | OPERA reservation no | 当前无可靠表源，第一版不作为主查询条件 |
@@ -440,10 +455,12 @@ POST /api/ai-query/v1/object-detail
 
 已落地能力：
 
-- 接口 1 可按 `hotel_id + group_code` 或 `hotel_id + confirmation_number` 查询订单上下文。
+- 接口 1 可按 `hotel_id + group_code` 或 `hotel_id + confirmation_number` 查询订单上下文，允许不传 `source_message_id` 和 `source_event_index` 的全局上下文查询。
 - 接口 1 返回 `matched_order_records`、`pending_or_open_tasks`、`active_workflows`、`terminated_records`、`target_object_validation` 和 `key_relationships`。
 - `active_workflows` 当前无独立表源，固定返回空数组。
 - 接口 2 支持 `ORDER:{order_id}` 查询本系统订单快照。
+- 查询接口 1、2 已启用与任务结果接收接口一致的 HMAC-SHA256 鉴权。
+- 查询接口错误响应统一返回 `success=false` 包装，非法 JSON、非法 `Content-Type` 和鉴权错误不会暴露 Secret、签名原文或完整请求体。
 - 对外 JSON 中内部长整型 ID 按字符串返回。
 - `reservation_no`、`block_id`、`room_items`、`rate_code_price` 等当前无可靠来源字段按本文约定返回 `null`、空数组或 warning。
 
@@ -451,6 +468,5 @@ POST /api/ai-query/v1/object-detail
 
 - 接口 3 `query_file_parse_context`。
 - 接口 4 `query_parent_task_context`，后续改为订单及其下面任务查询后再定义。
-- SuperAgent 查询接口的 HMAC 鉴权。当前第一版只要求 `X-Request-Id` 作为请求追踪头。
 - 附件解析、OCR、Excel、voucher、rooming list 解析。
 - 真实 OPERA / OHIP 对象投影。

docs/project/requirements/M002-order-task-workflow-v2.md

@@ -483,9 +483,9 @@ Fallback 处理规则：
 ## 18. 待确认问题
 
 - SuperAgent 创建任务接口的 URL、Method、Header、鉴权和错误响应格式。
-- SuperAgent 查询上下文接口 1、2 已实现最小字段版；接口 3 文件解析和接口 4 订单及任务查询仍需后续确认与实现，后续梳理未完成事项时必须持续提醒。
+- SuperAgent 查询上下文接口 1、2 已实现最小字段版，并已启用与任务结果接收接口一致的 HMAC；接口 3 文件解析和接口 4 订单及任务查询仍需后续确认与实现，后续梳理未完成事项时必须持续提醒。
 - `source_event_index`、批次 item index、`execution_order` 的最终编号规则是否都从 1 开始。
-- SuperAgent 查询上下文接口 3、4 的 URL、入参、返回字段和鉴权方式；接口 1、2 后续是否补 HMAC 鉴权也需确认。
+- SuperAgent 查询上下文接口 3、4 的 URL、入参、返回字段和鉴权方式。
 - `Message Notification` 是否需要在前端订单列表上单独标识为只读提醒。
 - OPERA 模拟结果中 Confirmation No.、Group Code、Block Code、Allotment Code 的具体字段路径。
 - 临时订单在无任务后是否立即逻辑删除，还是保留一段时间便于追溯。