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

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

文档信息

项目	内容
文档版本	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 第一版仅兼容接收，不参与查询范围过滤；时间统一不依赖这两个字段是否已在本系统落库。

规范签名串：

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

成功响应：

{
  "success": true,
  "request_id": "req-001",
  "trace_id": "trace-001",
  "data": {},
  "warnings": [],
  "error": null
}

失败响应：

{
  "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 路径

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 最小响应示例

{
  "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 路径

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 最小响应示例

{
  "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 对象投影。