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

# M002 SuperAgent 查询上下文接口最小字段定义

> 文档状态：阶段记录。本文记录 SuperAgent 查询上下文接口 1、2 的最小字段落地过程。
> 当前对外接口总契约以 `../integrations/superagent-api-contract.md` 为准；
> 如字段、错误码、鉴权或请求范围出现重复描述，以总契约和当前代码实现为准。

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.3 |
| 日期 | 2026-07-08 |
| 状态 | 第一版后端实现依据与落地记录 |
| 适用范围 | 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` 中说明。
- SuperAgent 允许作为全局上下文查询方按任意业务 key 查询；`source_message_id` 和 `source_event_index` 在查询阶段对本系统没有业务作用，第一版接收但忽略，不做格式校验，也不作为查询边界。
- 导入契约没有显式要求 `hotel_id`，本系统订单、任务和 AI 过渡表仍按 `hotel_id` 隔离。M005 后 SuperAgent 默认不传 `hotel_id`，后端按平台酒店表唯一 `ACTIVE` 酒店解析；兼容旧调用传入时必须与系统酒店一致。

## 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 通用请求头

查询接口 1、2 已复用 SuperAgent 任务结果接收接口的 HMAC-SHA256 鉴权规则。签名规则、secret、timestamp 窗口、nonce 防重放和请求体大小配置与任务结果接收接口保持一致。

| Header | 是否必填 | 中文说明 |
| --- | --- | --- |
| `Content-Type` | 是 | 固定 `application/json` |
| `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 |

时间约定：

- 请求 Header `X-TH-Hotel-SuperAgent-Timestamp` 必须是带时区的 UTC ISO-8601 时间，例如 `2026-07-08T03:00:00Z`。
- 响应中的 `created_at`、`last_updated_at`、`occurred_at` 等时间点统一返回带 `Z` 的 ISO-8601 UTC 时间。
- `source_message_id`、`source_event_index` 第一版仅兼容接收，不参与查询范围过滤；时间统一不依赖这两个字段是否已在本系统落库。

规范签名串：

```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 通用响应包

成功响应：

```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`，响应中的内部 SourceMessage Inbox ID；查询请求中若出现同名字段则视为 SuperAgent 透传字段，后端忽略
- `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 | SuperAgent 默认不传；后端解析系统酒店后用于隔离 `workflow_reservation_*` 表 |
| `source_message_id` | 否 | SuperAgent 透传的外部来源消息 ID | 全局上下文查询可不传；传入时后端接收但忽略，不做格式校验 |
| `source_event_index` | 否 | SuperAgent 透传的 current 事件序号 | 全局上下文查询可不传；传入时后端接收但忽略，不做正整数校验 |
| `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` | 是 | 任务来源内部 SourceMessage Inbox 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` |

说明：响应字段中的 `source_message_id` 来自 `workflow_reservation_task.source_message_id`，表示本系统内部 SourceMessage Inbox ID；它不同于查询请求和任务结果通知请求中 SuperAgent 透传的外部来源消息 ID。

第一版 `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 | SuperAgent 默认不传；后端解析系统酒店后用于隔离订单和任务 |
| `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` | 是 | 首次创建订单的内部 SourceMessage Inbox 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 当前可稳定提供

| 能力 | 当前来源 |
| --- | --- |
| 按“后端解析出的酒店 ID + GROUP_CODE”查询 ACTIVE 订单 | `workflow_reservation_order.order_key_type`、`active_business_key` |
| 按“后端解析出的酒店 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 可按“后端解析出的酒店 ID + group_code”或“后端解析出的酒店 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。

仍未落地能力：

- 接口 3 `query_file_parse_context`。
- 接口 4 `query_parent_task_context`，后续改为订单及其下面任务查询后再定义。
- 附件解析、OCR、Excel、voucher、rooming list 解析。
- 真实 OPERA / OHIP 对象投影。