实现 SuperAgent 查询上下文接口

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

@@ -0,0 +1,456 @@
+# M002 SuperAgent 查询上下文接口最小字段定义
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档版本 | 0.1 |
+| 日期 | 2026-07-07 |
+| 状态 | 第一版后端实现依据与落地记录 |
+| 适用范围 | SuperAgent / Main Agent 调用本系统查询订单和任务上下文 |
+| 主要读者 | 后端、SuperAgent 对接方、测试、后续协作 agent |
+
+## 1. 文档定位
+
+本文用于把导入文档中的查询接口契约，收敛为本项目当前可开发的第一版最小字段范围，并记录当前后端已落地的接口 1、接口 2 范围。
+
+导入契约中定义了四个只读查询接口：
+
+| 逻辑接口 | 原始定位 | 本项目第一版处理 |
+| --- | --- | --- |
+| `query_case_context` | 根据业务 key 查询订单、任务和终止上下文 | 已实现 |
+| `query_object_detail` | 根据对象 ID 查询更完整对象快照 | 已实现最小可用版 |
+| `query_file_parse_context` | 查询附件、OCR、Excel、voucher、rooming list 解析结果 | 当前系统没有附件解析能力，暂不实现 |
+| `query_parent_task_context` | 查询 linked task 的父任务上下文 | 后续改为“订单及其下面任务查询”后再定义 |
+
+本文只定义接口 1、接口 2 的最小请求字段、最小响应字段、字段用途和当前系统数据来源。
+
+## 2. 总原则
+
+- 两个接口都是只读接口，不创建任务、不写 OPERA、不修改订单、不确认字段。
+- 查询结果只作为 `routing_context` 或对象事实传给 Skill，不等同于最终业务结论。
+- `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` 解析酒店，需要在实现前统一。
+
+## 3. Skill 对接口 1、2 的实际需要
+
+| Skill | 接口 1：case-context 最小需要 | 接口 2：object-detail 最小需要 |
+| --- | --- | --- |
+| S01 New Booking | 判断同 key 是否已有 ACTIVE 订单、pending/open task、终止记录；判断是否允许继续生成 New Booking | 通常不需要。若同 key 已有对象，需要展示冲突对象摘要时可查 |
+| S02 Update Booking | 根据 `group_code` / `confirmation_number` 绑定既有对象；判断是否有前置未完成任务、终止记录或冲突对象 | 需要既有对象快照，支撑 before/after、状态是否可更新、日期/房型/房量/价格等事实 |
+| S03 Cancel Booking | 根据 key 定位待取消对象；判断对象是否存在、是否已终止、是否有前置未完成任务 | 需要对象状态、取消状态、是否可取消，以及对象展示摘要 |
+| S04 Voucher Received | 校验凭证能否绑定有效订单；如果无有效订单，是否存在可承接的待完善 New Booking 任务 | 可选，用于目标展示和硬校验，不负责解析凭证文件 |
+| S05 Rooming List | 校验名单目标 key 是否能绑定有效订单或待完善 New Booking 任务 | 可选，用于目标展示和硬校验；文件读取和名单解析不在接口 2 内 |
+| S06 Amend Group Code | 用旧 `group_code` 定位既有对象；判断改团号任务是否有明显阻断 | 可选，用于展示旧对象状态；新旧 group code 关系主要来自 Skill 输出 |
+| S07 Trace / Reservation Notes | 绑定目标对象；如果目标 key 只来自 history，需要保留 key 来源；如果是 linked task，父任务关系后续由接口 4 新定义 | extra bed 场景需要 `rate_code_price` 事实；当前拿不到时返回 `null` 和 warning |
+| S08 TA Recorder | 绑定 S05 已确认的目标 `group_code`；父任务关系后续由接口 4 新定义 | 可选，用于目标展示和附件绑定后的硬校验 |
+
+结论：
+
+- 接口 1 是 S01-S08 都可能使用的路由级上下文接口。
+- 接口 2 不是所有 Skill 都必须调用，主要服务 S02、S03、S07，S04/S05/S08 只在目标展示或硬校验时需要。
+- 接口 3 的文件解析能力当前不具备，不应为了满足导入契约而返回假解析结果。
+- 接口 4 的原始 parent task 语义和本系统后续需要不完全一致，先不实现，后续改成订单及任务查询。
+
+## 4. 通用请求与响应
+
+### 4.1 通用请求头
+
+安全方向上建议后续复用 SuperAgent 服务到服务鉴权思路，具体签名规则可参考任务结果接收接口。当前已落地的最小字段版暂不启用 HMAC，只强制 `X-Request-Id`，接口补签名规则前不得把该接口暴露到不可信网络。
+
+| Header | 是否必填 | 中文说明 |
+| --- | --- | --- |
+| `Content-Type` | 是 | 固定 `application/json` |
+| `X-Request-Id` | 是 | 调用方生成的请求 ID，用于日志串联 |
+| `X-AI-Trace-Id` | 否 | AI 运行链路 ID |
+| `X-Source-Message-Id` | 否 | 来源消息 ID，便于排查 |
+
+### 4.2 通用响应包
+
+成功响应：
+
+```json
+{
+  "success": true,
+  "request_id": "req-001",
+  "trace_id": "trace-001",
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+```
+
+失败响应：
+
+```json
+{
+  "success": false,
+  "request_id": "req-001",
+  "trace_id": "trace-001",
+  "data": null,
+  "warnings": [],
+  "error": {
+    "code": "BAD_REQUEST",
+    "message": "请求参数不合法",
+    "details": {}
+  }
+}
+```
+
+### 4.3 ID 序列化口径
+
+本系统数据库主键是 `BIGINT`。查询接口面向 SuperAgent / Main Agent 等外部运行环境，第一版建议对外 JSON 中的内部长整型 ID 使用字符串返回，避免 JavaScript 或其他运行时出现整数精度问题。
+
+适用字段包括：
+
+- `source_message_id`
+- `order_id`
+- `task_id`
+- `record_id`
+- `created_from_task_id`
+
+如果后端实现决定沿用 Spring 默认数字序列化，接口 1、接口 2 必须保持一致，并在实现前更新本文档示例。
+
+## 5. 接口 1：query_case_context
+
+### 5.1 路径
+
+```text
+POST /api/ai-query/v1/case-context
+```
+
+### 5.2 请求字段
+
+| 字段 | 是否必填 | 中文说明 | 当前系统来源或用途 |
+| --- | --- | --- | --- |
+| `hotel_id` | 是 | 酒店或业务上下文 ID | 用于隔离 `workflow_reservation_*` 表 |
+| `source_message_id` | 是 | 当前 SourceMessage ID | 串联来源消息、AI 过渡记录和任务 |
+| `source_event_index` | 是 | 当前 current 事件序号 | 和 AI 拆分结果保持一致 |
+| `group_code` | 条件必填 | Group / Allotment 优先业务 key | 查询 `GROUP_CODE` 类型订单和 AI 过渡记录 |
+| `confirmation_number` | 条件必填 | FIT 优先业务 key | 查询 `CONFIRMATION_NUMBER` 类型订单和 AI 过渡记录 |
+| `reservation_no` | 否 | OPERA reservation no | 当前无可靠表源，第一版不作为主查询条件 |
+| `object_type_hint` | 否 | 调用方推测的对象类型 | 只作为查询提示，不作为事实 |
+| `target_key_source` | 否 | key 来源：`body_current`、`body_thread_evidence`、`upstream_task_context`、`system_context` | 用于记录 current/history 边界 |
+| `body_thread_used_only_as_evidence` | 否 | key 是否只来自历史线程证据 | 为 true 时，后端仍只返回事实，不触发任何业务动作 |
+
+`group_code`、`confirmation_number`、`reservation_no` 至少应有一个非空。第一版实际可查询能力优先支持 `group_code` 和 `confirmation_number`。
+
+如果第一版请求只提供 `reservation_no`，后端不会把“查不到”解释为“可以创建新任务”，而是返回空事实列表，并在 `target_object_validation.needs_manual_review_reason` 中返回 `UNSUPPORTED_RESERVATION_NO_QUERY`，提示调用方转人工或等待后续 OPERA 投影表接入。
+
+### 5.3 响应字段
+
+#### `matched_order_records[]`
+
+返回当前系统中能通过 key 匹配到的订单摘要。
+
+| 字段 | 是否必返 | 中文说明 | 当前系统来源 |
+| --- | --- | --- | --- |
+| `object_id` | 是 | 查询对象 ID，第一版建议格式 `ORDER:{order_id}` | `workflow_reservation_order.id` |
+| `object_type` | 是 | 对象类型，第一版按 key 粗略映射 | `GROUP_CODE` 暂映射 `group_block`，`CONFIRMATION_NUMBER` 映射 `fit_reservation`，`TEMPORARY` 映射 `temporary_order` |
+| `order_id` | 是 | 本系统订单 ID | `workflow_reservation_order.id` |
+| `order_key_type` | 是 | 业务号类型 | `workflow_reservation_order.order_key_type` |
+| `group_code` | 否 | Group Code | 当 `order_key_type=GROUP_CODE` 时来自 `active_business_key` 或 `order_business_key` |
+| `confirmation_number` | 否 | Confirmation Number | 当 `order_key_type=CONFIRMATION_NUMBER` 时来自 `active_business_key` 或 `order_business_key` |
+| `temporary_order_code` | 是 | 临时订单编号 | `workflow_reservation_order.temporary_order_code` |
+| `display_name` | 是 | 用户可读展示名 | `workflow_reservation_order.display_name` |
+| `status` | 是 | 订单状态 | `workflow_reservation_order.order_status` |
+| `business_key_source` | 否 | 业务号来源 | `workflow_reservation_order.business_key_source` |
+| `source_table` | 是 | 来源表名 | 固定 `workflow_reservation_order` |
+| `last_updated_at` | 是 | 最近更新时间 | `workflow_reservation_order.updated_at` |
+
+第一版不在 `matched_order_records[]` 中强行返回 `block_id`、`reservation_no`、`room_items`、`rate_code_price`。这些字段如果后续有 OPERA 同步表或订单投影表，再进入接口 2。
+
+#### `pending_or_open_tasks[]`
+
+返回同 key 或同订单下尚未完成、需要 Skill 识别阻断关系的任务摘要。
+
+| 字段 | 是否必返 | 中文说明 | 当前系统来源 |
+| --- | --- | --- | --- |
+| `task_id` | 是 | 本系统任务 ID | `workflow_reservation_task.id` |
+| `order_id` | 是 | 任务当前挂靠订单 | `workflow_reservation_task.order_id` |
+| `source_message_id` | 是 | 任务来源消息 ID | `workflow_reservation_task.source_message_id` |
+| `source_event_index` | 是 | AI current 事件序号 | `workflow_reservation_ai_transition.source_event_index` |
+| `catalog_code` | 否 | Skill 目录代码 | `workflow_reservation_ai_transition.catalog_code` |
+| `skill_id` | 否 | Skill 标识 | `workflow_reservation_ai_transition.skill_id` |
+| `result_type` | 是 | AI 结果类型 | `workflow_reservation_task.result_type` |
+| `task_type` | 是 | AI 原始任务类型 | `workflow_reservation_task.ai_task_type` |
+| `system_task_type` | 是 | 系统主任务类型 | `workflow_reservation_task.system_task_type` |
+| `task_card_type` | 是 | 任务卡类型 | `workflow_reservation_task.task_card_type` |
+| `task_subtype` | 否 | 业务动作 subtype | `workflow_reservation_task.task_subtype` |
+| `task_status` | 是 | 任务状态 | `workflow_reservation_task.task_status` |
+| `queue_participation` | 是 | 是否参与订单执行队列 | `workflow_reservation_task.queue_participation` |
+| `execution_order` | 是 | 同订单执行顺序 | `workflow_reservation_task.execution_order` |
+| `parent_task_id` | 否 | 父任务 ID | `workflow_reservation_task.parent_task_id` |
+| `parent_source_event_index` | 否 | 父事件序号 | `workflow_reservation_task.parent_source_event_index` |
+| `linked_task_group_id` | 否 | 联动任务组 ID | `workflow_reservation_task.linked_task_group_id` |
+| `blocked_until_parent_completed` | 是 | 是否等待父任务完成 | `workflow_reservation_task.blocked_until_parent_completed` |
+| `last_updated_at` | 是 | 最近更新时间 | `workflow_reservation_task.updated_at` |
+
+第一版 `pending_or_open_tasks[]` 至少包含状态为 `PENDING_CONFIRM`、`READY`、`EXECUTING` 的任务。`FAILED` 在本系统第一版视为结束状态，不阻塞后续任务。
+
+#### `active_workflows[]`
+
+导入契约要求路由上下文覆盖 active workflow。当前本系统没有独立 workflow 表，订单任务流转事实保存在订单、任务和 OPERA 模拟操作表中。
+
+第一版接口保留该字段，但默认返回空数组；如果实现方希望表达“正在处理的工作流”，应优先通过 `pending_or_open_tasks[]` 返回，不额外编造 workflow 记录。
+
+| 字段 | 是否必返 | 中文说明 | 当前系统来源 |
+| --- | --- | --- | --- |
+| `active_workflows[]` | 是 | 活跃工作流摘要 | 第一版固定空数组 |
+
+#### `terminated_records[]`
+
+返回能影响 Skill 判断的终止记录摘要。
+
+| 字段 | 是否必返 | 中文说明 | 当前系统来源 |
+| --- | --- | --- | --- |
+| `record_type` | 是 | `order` 或 `task` | 系统派生 |
+| `record_id` | 是 | 订单 ID 或任务 ID | 对应表主键 |
+| `status` | 是 | 终止状态 | 订单 `ENDED` / `LOGIC_DELETED`，任务 `FAILED` / `COMPLETED` |
+| `reason` | 否 | 终止原因 | 订单 `logic_deleted_reason` 或任务 `last_failure_reason` |
+| `occurred_at` | 否 | 终止时间 | 订单 `ended_at` / `logic_deleted_at`，任务 `completed_at` |
+| `last_updated_at` | 是 | 最近更新时间 | 对应表 `updated_at` |
+
+#### `target_object_validation`
+
+返回后端可基于事实给出的目标对象校验摘要，但不返回“应该创建哪个任务”的最终结论。
+
+| 字段 | 是否必返 | 中文说明 |
+| --- | --- | --- |
+| `status` | 是 | `none`、`single`、`multiple`、`conflict` |
+| `matched_object_id` | 否 | 唯一匹配对象 ID |
+| `matched_object_type` | 否 | 唯一匹配对象类型 |
+| `can_create_new_booking_task` | 是 | 是否未发现明显阻断 New Booking 的对象或任务 |
+| `can_create_update_task` | 是 | 是否存在可更新目标且无明显阻断 |
+| `can_create_cancel_task` | 是 | 是否存在可取消目标且无明显阻断 |
+| `can_attach_voucher` | 是 | 是否存在有效目标或可承接的待完善 New Booking 任务 |
+| `can_attach_rooming_list` | 是 | 是否存在有效目标或可承接的待完善 New Booking 任务 |
+| `needs_manual_review_reason` | 否 | 后端发现多对象、冲突、终止等事实时的原因码 |
+
+#### `key_relationships`
+
+| 字段 | 是否必返 | 中文说明 |
+| --- | --- | --- |
+| `group_code_and_confirmation_same_object` | 否 | 同时传入两个 key 时，是否能证明属于同一对象 |
+| `relationship_evidence` | 否 | 证明关系的简短说明 |
+
+当前系统没有 Group Code 与 Confirmation Number 的关系表，大多数情况下该字段返回 `null`。
+
+### 5.4 最小响应示例
+
+```json
+{
+  "success": true,
+  "request_id": "req-001",
+  "trace_id": "trace-001",
+  "data": {
+    "matched_order_records": [
+      {
+        "object_id": "ORDER:1900000000000000100",
+        "object_type": "group_block",
+        "order_id": "1900000000000000100",
+        "order_key_type": "GROUP_CODE",
+        "group_code": "LT260417VIPA",
+        "confirmation_number": null,
+        "temporary_order_code": "TMP-20260707-0001",
+        "display_name": "LT260417VIPA",
+        "status": "ACTIVE",
+        "business_key_source": "AI_CANDIDATE",
+        "source_table": "workflow_reservation_order",
+        "last_updated_at": "2026-07-07T08:30:00Z"
+      }
+    ],
+    "pending_or_open_tasks": [],
+    "active_workflows": [],
+    "terminated_records": [],
+    "target_object_validation": {
+      "status": "single",
+      "matched_object_id": "ORDER:1900000000000000100",
+      "matched_object_type": "group_block",
+      "can_create_new_booking_task": false,
+      "can_create_update_task": true,
+      "can_create_cancel_task": true,
+      "can_attach_voucher": true,
+      "can_attach_rooming_list": true,
+      "needs_manual_review_reason": null
+    },
+    "key_relationships": {
+      "group_code_and_confirmation_same_object": null,
+      "relationship_evidence": ""
+    }
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+## 6. 接口 2：query_object_detail
+
+### 6.1 路径
+
+```text
+POST /api/ai-query/v1/object-detail
+```
+
+### 6.2 请求字段
+
+| 字段 | 是否必填 | 中文说明 | 当前系统来源或用途 |
+| --- | --- | --- | --- |
+| `hotel_id` | 是 | 酒店或业务上下文 ID | 用于隔离订单和任务 |
+| `object_id` | 是 | 接口 1 返回的对象 ID | 第一版支持 `ORDER:{order_id}` |
+| `object_type` | 否 | 对象类型提示 | 用于校验调用方预期和实际对象类型 |
+
+### 6.3 响应字段
+
+接口 2 返回的是对象详情快照。第一版先以本系统订单表为主，OPERA 同步类字段先作为 nullable 业务快照字段。
+
+#### 基础对象字段
+
+| 字段 | 是否必返 | 中文说明 | 当前系统来源 |
+| --- | --- | --- | --- |
+| `object_id` | 是 | 查询对象 ID | `ORDER:{workflow_reservation_order.id}` |
+| `object_type` | 是 | 对象类型 | 根据 `order_key_type` 派生 |
+| `order_id` | 是 | 本系统订单 ID | `workflow_reservation_order.id` |
+| `order_key_type` | 是 | 业务号类型 | `workflow_reservation_order.order_key_type` |
+| `group_code` | 否 | Group Code | `GROUP_CODE` 订单的 `active_business_key` 或 `order_business_key` |
+| `confirmation_number` | 否 | Confirmation Number | `CONFIRMATION_NUMBER` 订单的 `active_business_key` 或 `order_business_key` |
+| `reservation_no` | 否 | OPERA reservation no | 当前无可靠表源，返回 `null` |
+| `block_id` | 否 | OPERA block ID | 当前无可靠表源，返回 `null` |
+| `temporary_order_code` | 是 | 临时订单编号 | `workflow_reservation_order.temporary_order_code` |
+| `display_name` | 是 | 用户可读展示名 | `workflow_reservation_order.display_name` |
+| `status` | 是 | 订单状态 | `workflow_reservation_order.order_status` |
+| `source_message_id` | 是 | 首次创建订单的来源消息 | `workflow_reservation_order.source_message_id` |
+| `created_from_task_id` | 否 | 首次创建订单的任务 ID | `workflow_reservation_order.created_from_task_id` |
+| `created_at` | 是 | 创建时间 | `workflow_reservation_order.created_at` |
+| `last_updated_at` | 是 | 最近更新时间 | `workflow_reservation_order.updated_at` |
+
+#### 业务快照字段
+
+这些字段是 S02、S03、S07 后续会用到的最小业务事实，但当前系统没有完整 OPERA 投影表。第一版可以返回字段名和 `null` 值，同时在 `hard_validation_warnings[]` 中说明缺失原因。
+
+| 字段 | 是否必返 | Skill 用途 | 当前第一版 |
+| --- | --- | --- | --- |
+| `arrival_date` | 否 | S02 before/after、S04/S05 目标展示 | 当前无结构化订单投影，返回 `null` |
+| `departure_date` | 否 | S02 before/after、S04/S05 目标展示 | 当前无结构化订单投影，返回 `null` |
+| `nights` | 否 | S02 晚数修改判断 | 当前无结构化订单投影，返回 `null` |
+| `guest_count` | 否 | S02 人数修改判断 | 当前无结构化订单投影，返回 `null` |
+| `room_items[]` | 是 | S02 房型/房量 before/after，展示目标房型摘要 | 当前返回空数组 |
+| `room_items[].room_type` | 否 | 原始房型或系统房型 | 当前无可靠表源 |
+| `room_items[].pms_room_type_code` | 否 | PMS 房型代码 | 当前无可靠表源 |
+| `room_items[].room_quantity` | 否 | 房量 | 当前无可靠表源 |
+| `room_items[].rate_code` | 否 | Rate Code | 当前无可靠表源 |
+| `room_items[].rate_code_price` | 否 | S07 extra bed 改价事实来源 | 当前无可靠表源 |
+| `rate_code` | 否 | 对象级 Rate Code 摘要 | 当前无可靠表源 |
+| `rate_code_price` | 否 | S07 extra bed 使用，Skill 不自行猜 | 当前无可靠表源，返回 `null` |
+| `reservation_type` | 否 | S04 voucher 后续动作、S08 TA Recorder 展示 | 当前无可靠表源 |
+| `cancel_status` | 否 | S03 判断是否已取消 | 当前可根据订单状态粗略派生，真实 OPERA 取消状态后续补充 |
+| `can_update` | 是 | S02 是否存在明显更新阻断 | 根据订单状态和队列阻断粗略派生 |
+| `can_cancel` | 是 | S03 是否存在明显取消阻断 | 根据订单状态和队列阻断粗略派生 |
+| `hard_validation_warnings[]` | 是 | 告知 Skill 哪些事实当前无法确认 | 系统派生 |
+
+### 6.4 最小响应示例
+
+```json
+{
+  "success": true,
+  "request_id": "req-002",
+  "trace_id": "trace-001",
+  "data": {
+    "object_id": "ORDER:1900000000000000100",
+    "object_type": "group_block",
+    "order_id": "1900000000000000100",
+    "order_key_type": "GROUP_CODE",
+    "group_code": "LT260417VIPA",
+    "confirmation_number": null,
+    "reservation_no": null,
+    "block_id": null,
+    "temporary_order_code": "TMP-20260707-0001",
+    "display_name": "LT260417VIPA",
+    "status": "ACTIVE",
+    "source_message_id": "1900000000000000001",
+    "created_from_task_id": null,
+    "created_at": "2026-07-07T08:00:00Z",
+    "last_updated_at": "2026-07-07T08:30:00Z",
+    "arrival_date": null,
+    "departure_date": null,
+    "nights": null,
+    "guest_count": null,
+    "room_items": [],
+    "rate_code": null,
+    "rate_code_price": null,
+    "reservation_type": null,
+    "cancel_status": "not_cancelled",
+    "can_update": true,
+    "can_cancel": true,
+    "hard_validation_warnings": [
+      {
+        "code": "OPERA_PROJECTION_UNAVAILABLE",
+        "message": "当前系统尚未接入 OPERA 对象投影，日期、房型、房价等字段无法确认。"
+      }
+    ]
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+## 7. 第一版字段来源与缺口
+
+### 7.1 当前可稳定提供
+
+| 能力 | 当前来源 |
+| --- | --- |
+| 按 `hotel_id + GROUP_CODE` 查询 ACTIVE 订单 | `workflow_reservation_order.order_key_type`、`active_business_key` |
+| 按 `hotel_id + CONFIRMATION_NUMBER` 查询 ACTIVE 订单 | `workflow_reservation_order.order_key_type`、`active_business_key` |
+| 查询临时订单、终止订单、逻辑删除订单 | `workflow_reservation_order.order_status` |
+| 查询同订单任务队列 | `workflow_reservation_task.order_id`、`queue_participation`、`execution_order` |
+| 查询 pending/open task | `workflow_reservation_task.task_status` |
+| 查询 `source_event_index`、Skill、AI 原始任务类型 | `workflow_reservation_ai_transition` |
+| 判断 Message Notification 是否不阻塞 | `queue_participation=false` |
+
+### 7.2 当前不能稳定提供
+
+| 字段或能力 | 原因 | 第一版处理 |
+| --- | --- | --- |
+| `reservation_no` | 未接入 OPERA reservation 投影 | 返回 `null` |
+| `block_id` | 未接入 OPERA group block 投影 | 返回 `null` |
+| `arrival_date` / `departure_date` / `nights` | 订单表未保存结构化入住信息 | 返回 `null` |
+| `room_items[]` | 订单表未保存结构化房型/房量明细 | 返回空数组 |
+| `rate_code` / `rate_code_price` | 未接入 OPERA 或价格投影 | 返回 `null` 并 warning |
+| 凭证、OCR、Excel、rooming list 解析结果 | 当前无文件解析能力 | 接口 3 暂不实现 |
+| linked task 的父任务专用查询 | 后续改成订单及任务查询 | 接口 4 暂不实现 |
+
+## 8. 后续实现提醒
+
+- 实现接口 1、2 前，应先复用当前后端分层规范：`control`、`service`、`service.impl`、`domain`、`mapper`、`repository`、`common.request`、`common.result`、`common.dto`、`common.enums`。
+- Controller、Service、ServiceImpl 方法必须有中文注释；Entity 字段必须有中文注释。
+- 不要新增 `api`、`application`、`persistence` 包。
+- 不要为了导入契约中的 `block_id`、`reservation_no`、`rate_code_price` 等字段编造数据。
+- SuperAgent 查询上下文接口是之前排期靠后的事项，现在已有导入契约，后续梳理未完成事项时需要持续提醒。
+- 普通任务切换订单、用户身份/权限、前端页面、真实 OPERA/OHIP 仍不在本接口第一版范围内。
+
+## 9. 当前后端落地状态
+
+已落地接口：
+
+- `POST /api/ai-query/v1/case-context`
+- `POST /api/ai-query/v1/object-detail`
+
+已落地能力：
+
+- 接口 1 可按 `hotel_id + group_code` 或 `hotel_id + confirmation_number` 查询订单上下文。
+- 接口 1 返回 `matched_order_records`、`pending_or_open_tasks`、`active_workflows`、`terminated_records`、`target_object_validation` 和 `key_relationships`。
+- `active_workflows` 当前无独立表源，固定返回空数组。
+- 接口 2 支持 `ORDER:{order_id}` 查询本系统订单快照。
+- 对外 JSON 中内部长整型 ID 按字符串返回。
+- `reservation_no`、`block_id`、`room_items`、`rate_code_price` 等当前无可靠来源字段按本文约定返回 `null`、空数组或 warning。
+
+仍未落地能力：
+
+- 接口 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

@@ -14,7 +14,7 @@
 
 本文是 `M002-order-task-workflow-v1.md` 的第二版修正，目标是把本项目已经讨论确认的订单任务主流程，与 2026-07-06 导入的 AI 任务卡契约对齐。
 
-本文定义业务边界、数据语义和后续实现约束。当前后端已经按拆分 checkpoint 实现了 AI 结果接收、订单任务基础流转、任务草稿保存、最终确认、审计列表和 OPERA 模拟骨架；前端页面、真实 OPERA、普通任务切换订单和 SuperAgent 查询上下文接口仍未实现。
+本文定义业务边界、数据语义和后续实现约束。当前后端已经按拆分 checkpoint 实现了 AI 结果接收、订单任务基础流转、任务草稿保存、最终确认、审计列表、OPERA 模拟骨架，以及 SuperAgent 查询上下文接口 1、2 的最小字段版；前端页面、真实 OPERA、普通任务切换订单、查询接口 3 和查询接口 4 仍未实现。
 
 ## 2. 本版核心修正
 
@@ -471,7 +471,7 @@ Fallback 处理规则：
 
 本版暂不定义：
 
-- SuperAgent 查询上下文接口。
+- SuperAgent 查询上下文接口 3、4；接口 1、2 的第一版最小字段已单独定义并落地在 `M002-ai-query-minimal-fields.md`。
 - OPERA 模拟结果 JSON 字段名。
 - 真实 OHIP / OPERA 接口地址、鉴权和返回结构。
 - 前端具体页面布局和交互细节。
@@ -483,9 +483,9 @@ Fallback 处理规则：
 ## 18. 待确认问题
 
 - SuperAgent 创建任务接口的 URL、Method、Header、鉴权和错误响应格式。
-- SuperAgent 查询上下文接口暂不在本 checkpoint 实现，但 SuperAgent 侧已经在整理，后续梳理未完成事项时必须持续提醒。
+- SuperAgent 查询上下文接口 1、2 已实现最小字段版；接口 3 文件解析和接口 4 订单及任务查询仍需后续确认与实现，后续梳理未完成事项时必须持续提醒。
 - `source_event_index`、批次 item index、`execution_order` 的最终编号规则是否都从 1 开始。
-- SuperAgent 查询上下文接口的 URL、入参、返回字段和鉴权方式。
+- SuperAgent 查询上下文接口 3、4 的 URL、入参、返回字段和鉴权方式；接口 1、2 后续是否补 HMAC 鉴权也需确认。
 - `Message Notification` 是否需要在前端订单列表上单独标识为只读提醒。
 - OPERA 模拟结果中 Confirmation No.、Group Code、Block Code、Allotment Code 的具体字段路径。
 - 临时订单在无任务后是否立即逻辑删除，还是保留一段时间便于追溯。