huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

实现V4数据库目录与Lookup接口

Browse Source
This commit is contained in:
andy
2026-07-19 14:36:11 +07:00
parent 145511620c
commit 88f98a0eb6
39 changed files with 2075 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/project/requirements/M002-v4-agent-callback-field-contract.md
View File

@@ -6,7 +6,7 @@
| --- | --- |
| 文档版本 | 1.5 |
| 日期 | 2026-07-19 |
| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线、CP2 多卡模型设计、CP3 持久化基线、CP4 入站写入新模型、CP5 查询接口和 CP6 普通卡片确认 / S10/S99 ack |
| 状态 | 当前 V4 字段基线；后端已完成 CP1-CP8，真实目录与 Lookup API 设计已落文档 |
| 适用范围 | 0718 业务基线下，Agent → Adapter / MCP → 信息系统的业务回调字段 |
| 不适用范围 | 数据库表设计、前端视觉细节、真实 PMS API、技术失败后台重试、旧 M002 V3 数据兼容 |
@@ -16,7 +16,7 @@
本契约用于后续 M002 V4 主流程设计、后端领域建模、前端页面模型、Adapter / MCP Schema 对齐和 SuperAgent 联调。当前后端已按本文完成 V4 入站解析基线：能识别 V4 包、校验关键契约、保存 AI transition / 任务卡原始 payload，并把可映射的六类 event 先接入现有订单任务链路。
V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP6，表结构、Entity、Mapper、Repository 基线已经实现，SuperAgent V4 入站已经能写入 V4 订单任务、来源邮件展示卡、Basic Information 卡、业务卡和 S10/S99 来源通知；V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、普通卡片确认和 S10/S99 ack 写接口已实现，V4 复核写接口仍未实现。
V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP11，表结构、Entity、Mapper、Repository、SuperAgent V4 入站写入、V4 查询、普通卡片确认、S10/S99 ack、V4 复核解阻、数据库目录和 Account / Room Type / Rate Code Lookup API 已实现。真实 PMS 同步和目录管理后台仍后置，方案见 `M002-v4-real-catalog-lookup-api-design.md`。
当前已确认开发阶段数据可以清空，因此 M002 V4 后续可以按新模型重建，不要求兼容旧任务数据、旧草稿、旧 OPERA 模拟、旧 `S000/S999`、旧 Fallback 或旧 `case_keys`。
@@ -193,13 +193,13 @@ Agent 给出非空 `account_code`，但信息系统运行时目录不存在该
不同 `order_ref` 可以对应不同 Account。
后端 CP8 第一版已落地固定种子目录：
后端 CP11 第一版已落地当前酒店数据库目录：
- Account：`QBD_TRAVEL`、`LIAN_TAI`、`HANATOUR_TD`。
- Market / Source：由 Account 派生，当前分别为 `LEISURE` / `TRAVEL_AGENT`。
- SuperAgent 不需要输出 `market_code`、`source_code`、`account_name`，也不要输出显示名称替代 `account_code`。
- 如果 SuperAgent 输出的 `account_code` 不在上述目录，后端会创建 `REVIEW_REQUIRED` Basic Information 卡，并在 `validation_errors_json` / 查询 `fields[].validation_errors` 中返回目录错误。
- 如果 SuperAgent 输出的业务卡 `room_items[].room_type_code` 或 `rate_code` 不在上述固定目录，后端会创建 `REVIEW_REQUIRED` 业务卡，并在 `validation_errors_json` / 查询 `fields[].validation_errors` 中返回目录错误；用户可通过 V4 复核解阻接口提交对应字段 pointer 修正。
- 如果 SuperAgent 输出的业务卡 `room_items[].room_type_code` 或 `rate_code` 不在当前酒店数据库目录，后端会创建 `REVIEW_REQUIRED` 业务卡，并在 `validation_errors_json` / 查询 `fields[].validation_errors` 中返回目录错误；用户可通过 V4 复核解阻接口提交对应字段 pointer 修正。
## 8. message_events 公共字段
@@ -639,7 +639,7 @@ Account、RoomType、RateCode、Department 的目录由信息系统或其主数
- Agent 输出非空 code、但信息系统目录不存在该值时，属于目录校验或契约问题。
- Market 和 Source 由信息系统根据订单级 `account_code` 派生，不由 Agent 输出。
当前项目接受“SuperAgent 确定后把目录给本系统”的落地方式。第一阶段可以先以固定种子目录或版本化目录快照对齐；后续如需在线查询或目录同步接口，再另开需求。
当前项目接受“SuperAgent 确定后把目录给本系统”的落地方式。第一阶段已用固定种子目录完成开发闭环；真实目录、系统管理维护、PMS / OPERA / OHIP 同步、前端 lookup API、缓存、权限和兜底策略已在 `M002-v4-real-catalog-lookup-api-design.md` 中设计。该设计不改变 SuperAgent V4 输入契约：SuperAgent 仍只输出稳定 code，不输出显示名或自由文本。
## 21. 后端 V4 建模建议
@@ -674,7 +674,7 @@ AI 回调包
| `source_message_id` 映射 | 本项目按 SourceMessage Inbox 的 `external_message_id` 处理 |
| 时间格式 | UTC ISO-8601，例如 `2026-07-18T02:10:00Z` |
| 正文格式 | 单一 `body` + `body_content_type=text/plain/text/html` |
| code 目录 | 信息系统主数据是唯一事实源，目录同步方式后置 |
| code 目录 | 信息系统数据库目录是唯一运行时事实源；当前目录由固定种子初始化导入，真实 PMS 同步与管理维护见 `M002-v4-real-catalog-lookup-api-design.md` |
| 技术异常 channel | 需要独立建设，不进入酒店用户任务体系；当前先保留设计空间 |
| Payment 附件 | 正常 Payment 必须 `attachment_ids.length > 0` |
| `manual_review` validator | 按各对象条件 Schema 校验，必须能由可识别未解决字段解释 |
@@ -682,7 +682,7 @@ AI 回调包
| Fit Booking Code 临时定位 | 当前无 Confirmation Number 时可用 Booking Code 查本地订单投影；第一版不建立 ACTIVE 唯一约束，匹配多条进入人工复核 |
| V4 前端资源路径 | 新开 `/api/reservation/order-tasks/**`，不扩展旧 `/api/reservation/tasks/**` 作为 V4 主入口 |
| Basic Information 前置 | Basic Information 必须先确认；业务卡之间第一版不强制逐张顺序确认 |
| Account 目录 | 第一版使用信息系统后端固定种子数据 |
| Account 目录 | 第一版使用当前酒店数据库 Account 目录；`FIXED_SEED_IMPORT` 仅表示初始化来源，不代表运行时代码固定兜底 |
## 23. 后续仍需技术对齐
@@ -691,7 +691,7 @@ AI 回调包
1. SuperAgent、Adapter、MCP Schema 和信息系统 DTO 使用同一份 V4 Schema。
2. `body_content_type` 的来源是 AgentBus / 邮件监听层还是 Adapter 派生。
3. `dispatch_run_id`、超时、错误 channel 和技术失败查询入口如何落地。
4. Account、RoomType、RateCode、Department 目录如何提供给 SuperAgent，以及目录版本如何管理。
4. Account、RoomType、RateCode、Department 目录如何提供给 SuperAgent，仍需在真实目录实现后确认是离线目录包还是独立机器接口。
5. 如需 `event_id` 或幂等键，应作为 transport 字段设计，不作为业务页面字段。
## 24. 当前开发结论
@@ -741,7 +741,7 @@ AI 回调包
- `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm` 确认 V4 卡片，强制 Bearer 登录、`RESERVATION_TASK_CONFIRM`、酒店访问权和 version 并发校验。
- `POST /api/reservation/source-notifications/{notificationId}/ack` 确认 V4 S10/S99 来源通知已读 / 已处理，强制 Bearer 登录、`RESERVATION_TASK_CONFIRM`、酒店访问权和 version 并发校验。
- CP7 已完成 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution` 复核解阻和复核场景订单归属确认。
- CP8 已完成 Account 固定目录校验、Market / Source 派生、Room Type / Rate Code 第一版固定种子校验和 V4 任务卡 `fields[]` 白名单。
- CP8 已完成 Account / Room Type / Rate Code 目录校验和 V4 任务卡 `fields[]` 白名单；CP11 已把固定种子导入数据库目录并开放 Account / Room Type / Rate Code lookup API。真实 PMS 同步和目录管理后台仍未实现。
当前仍未完成：