docs: 收口 V4 任务卡展示与确认口径

2026-07-20 23:57:01 +07:00
parent c5b5ce6aab
commit c1163457a9
12 changed files with 253 additions and 98 deletions
--- a/docs/project/requirements/M002-v4-real-catalog-lookup-api-design.md
+++ b/docs/project/requirements/M002-v4-real-catalog-lookup-api-design.md
@@ -4,11 +4,11 @@

 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.3 |
-| 日期 | 2026-07-19 |
-| 状态 | CP11 已落地第一版数据库目录与 lookup API；目录管理后台 CP1 已落地后端接口；真实 PMS 同步继续后置 |
-| 适用范围 | M002 V4 Account、Market、Source、Room Type、Rate Code 目录来源、数据模型、前端 lookup、缓存、酒店隔离、权限和失败兜底 |
-| 不适用范围 | 真实 OPERA / OHIP 写操作、真实价格计算、前端页面实现、SuperAgent Prompt 修改、目录同步任务、SuperAgent 机器目录接口 |
+| 文档版本 | 0.4 |
+| 日期 | 2026-07-20 |
+| 状态 | CP11 已落地第一版数据库目录与 lookup API；目录管理后台 CP1 已落地后端接口；Account + booking type 过滤 Rate Code 和 Room Information 早餐派生已确认为下一阶段待实现契约；真实 PMS 同步继续后置 |
+| 适用范围 | M002 V4 Account、Market、Source、Room Type、Rate Code 目录来源、Room Information 早餐派生、数据模型、前端 lookup、缓存、酒店隔离、权限和失败兜底 |
+| 不适用范围 | 真实 OPERA / OHIP 写操作、真实价格计算、房型 / 日期 / 价格级 Rate Code 适用规则、前端页面实现、SuperAgent Prompt 修改、目录同步任务、SuperAgent 机器目录接口 |

 ## 1. 文档定位

@@ -16,7 +16,9 @@ M002 V4 CP8 已实现第一版固定种子目录校验；M002 V4 CP11 已把该

 - Basic Information 的 `account_code` 必须存在于当前酒店数据库 Account 目录。
 - Market / Source 由 Account 派生，不由 SuperAgent 输出。
- Room Type / Rate Code 第一版使用当前酒店数据库目录校验和字段选项提示。
+- Room Type 第一版使用当前酒店数据库目录校验和字段选项提示。
+- Rate Code 当前 CP11 实现仍是酒店级目录校验和字段选项提示；下一阶段已确认需要按订单级 Account + `booking_type`（`GROUP` / `FIT`）过滤候选和校验适用性。
+- Room Information 卡中 Breakfast 第一版由后端派生：Group 固定含早；Fit 按 Rate Code 中 `RB` / `RO` 判断，无法派生时要求用户在卡片中必填确认。
 - 目录错误会让对应 V4 卡片进入 `REVIEW_REQUIRED`，用户通过复核解阻选择合法 code。

 本文记录真实目录和 lookup API 的设计与 CP11 第一版实现。CP11 新增 `workflow_reservation_catalog_account`、`workflow_reservation_catalog_code` 两张表，并通过 Flyway 初始化 `HOTEL-TEST`、`HOTEL-DEV` 以及迁移执行时已存在的 `ACTIVE` 平台酒店的固定种子目录；同时新增 `ReservationV4CatalogBootstrapRunner`，在平台默认酒店由启动流程创建后，如果该酒店目录为空，会补一份 `FIXED_SEED_IMPORT` 初始化目录。不再在运行时代码中把固定种子作为全局目录事实。目录管理后台 CP1 已新增 Account、Room Type、Rate Code 后端查询、新增、启用 / 停用接口；`workflow_reservation_catalog_sync_run`、真实 PMS / OPERA / OHIP 同步、Market / Source 独立管理页面和 SuperAgent 机器目录供给接口继续后置。
@@ -33,7 +35,7 @@ CP11 之前固定种子实现位于后端 `ReservationV4DirectoryService` 和 `F
 | Market | 由 Account 派生的订单级 Market | 当前 Account 均派生 `LEISURE` | 已进入通用代码目录，前端仍不直接编辑 |
 | Source | 由 Account 派生的订单级 Source | 当前 Account 均派生 `TRAVEL_AGENT` | 已进入通用代码目录，前端仍不直接编辑 |
 | Room Type | 房型 code 校验和字段选项提示 | `TWN`、`KING`、`DBL`、`SGL`、`TRP`、`RM1`、`RM2`、`RM3` | 已进入数据库初始化目录，仍不是 PMS 全量房型；后台 CP1 可新增、启用 / 停用 |
-| Rate Code | Rate Code 校验和字段选项提示 | `BAR`、`RACK`、`PACKAGE`、`GROUP`、`FIT` | 已进入数据库初始化目录，不按日期、账号、房型过滤，不含价格；后台 CP1 可新增、启用 / 停用 |
+| Rate Code | Rate Code 校验和字段选项提示 | `BAR`、`RACK`、`PACKAGE`、`GROUP`、`FIT` | 已进入数据库初始化目录；当前实现仍是酒店级目录，下一阶段改为 Account + booking type 适用范围过滤；不按房型、日期或价格过滤；后台 CP1 可新增、启用 / 停用 |

 当前固定种子只能支撑开发和演示闭环，不能作为生产长期事实源。

@@ -47,6 +49,7 @@ CP11 之前固定种子实现位于后端 `ReservationV4DirectoryService` 和 `F
 4. 目录有来源、版本、更新时间和启停状态，便于排查 SuperAgent 输出 code 与系统目录不一致的问题。
 5. PMS / OPERA / OHIP 不稳定或暂未接入时，系统仍可使用最后一次成功目录快照或系统管理目录兜底。
 6. 固定种子目录可以作为 dev/test 或导入初始化兜底，但生产不应默认靠代码固定值。
+7. Rate Code 不再作为全酒店通用下拉；业务卡 Rate Code 候选必须先受当前订单 Basic Information 的 Account 和 event `booking_type` 限定。

 ## 4. 目录来源分层

@@ -55,7 +58,7 @@ CP11 之前固定种子实现位于后端 `ReservationV4DirectoryService` 和 `F
 | 阶段 | 来源 | 中文说明 | 适用目录 |
 | --- | --- | --- | --- |
 | Phase 0 | `FIXED_SEED_IMPORT` | CP11 已将固定种子通过 Flyway 和启动补种子流程导入数据库，不再作为运行时代码全局 Map | 当前 Account、Market、Source、Room Type、Rate Code |
-| Phase 1 | `SYSTEM_MANAGED` | 本系统数据库目录，由初始化脚本、管理后台或导入文件维护 | Account、Market、Source；也可临时维护 Room Type、Rate Code |
+| Phase 1 | `SYSTEM_MANAGED` / `IMPORT_FILE` | 本系统数据库目录，由初始化脚本、管理后台或受控导入文件维护；`IMPORT_FILE` 用于 OWNER RATE 等人工确认过的目录 / 适用关系导入 | Account、Market、Source；也可临时维护 Room Type、Rate Code 和 Account + booking type 的 Rate Code 适用关系 |
 | Phase 2 | `PMS_SYNC` | 后端从 PMS / OPERA / OHIP 同步目录到本系统本地表，业务查询只读本地快照 | Room Type、Rate Code 优先；Account、Market、Source 视 PMS 能力再接 |

 原则：
@@ -72,9 +75,9 @@ CP11 之前固定种子实现位于后端 `ReservationV4DirectoryService` 和 `F
 | Market | 本系统管理目录 | 可选同步 PMS market code 配置 | 否，随 Account 派生展示 | 前端不直接改 Market；修改 Account 后后端派生 Market |
 | Source | 本系统管理目录 | 可选同步 PMS source code 配置 | 否，随 Account 派生展示 | 前端不直接改 Source；修改 Account 后后端派生 Source |
 | Room Type | PMS / OPERA / OHIP 同步目录优先 | 同步酒店有效房型、展示名、人数、启停状态 | 是，业务卡选择房型 | 若 PMS 未接入，可临时由系统管理维护或固定种子初始化 |
-| Rate Code | PMS / OPERA / OHIP 同步目录优先 | 同步有效 Rate Plan / Rate Code；价格和日期适用规则后置 | 是，New Booking 选择 Rate Code | 第一版 lookup 只选 code，不做价格计算 |
+| Rate Code | PMS / OPERA / OHIP 同步目录优先；在 PMS 未接前可由系统管理或导入文件维护 Account 适用关系 | 同步有效 Rate Plan / Rate Code；Account、booking type、房型、日期和价格适用规则逐步扩展 | 是，New Booking 选择 Rate Code | 下一阶段先按 Account + GROUP/FIT 过滤候选，只选 code，不做价格计算 |

-Department 目录在 V4 字段契约中也会被 Trace 使用，但当前固定种子 CP8 尚未实现。后续可沿用本文模型扩展 `DEPARTMENT`，不放入本 checkpoint。
+Department 目录在 V4 字段契约中也会被 Trace 使用。当前任务详情页第一版先固定 `FO`、`HSK`、`FO+HSK` 三个 Department code，用于 Trace 卡下拉和 SuperAgent 输出约束；这不是正式数据库目录。后续可沿用本文模型扩展 `DEPARTMENT`、lookup API、系统管理维护和目录校验，不放入本 checkpoint。

 ## 6. 数据模型草案

@@ -135,7 +138,53 @@ Market、Source、Room Type、Rate Code 可先使用统一 code 表。
 uk_reservation_catalog_code(hotel_id, catalog_type, code)
 ```

-### 6.3 推荐表：`workflow_reservation_catalog_sync_run`
+### 6.3 推荐表：`workflow_reservation_rate_code_applicability`
+
+Rate Code 本身仍保存在 `workflow_reservation_catalog_code` 中，`catalog_type=RATE_CODE` 表示该 code 是当前酒店已知的 Rate Code；是否对某个 Account、GROUP/FIT 可用，由适用关系表表达。这样可以避免在 `metadata_json` 中写不可查询的业务规则，也避免前端硬编码 OWNER RATE Excel。
+
+本 checkpoint 只确认 Account + booking type 粒度，不纳入房型、日期和价格规则。后续如果需要按 Room Type 或入住日期进一步过滤，应在此表或独立价格规则表上扩展，不改变前端只提交稳定 `rate_code` 的基本原则。
+
+| 字段 | 中文说明 |
+| --- | --- |
+| `id` | 内部主键 ID |
+| `hotel_id` | 酒店 ID，必须和 Account、Rate Code 同酒店 |
+| `account_code` | Reservation Account 稳定 code，引用当前酒店 Account 目录 |
+| `booking_type` | `GROUP` / `FIT`；用于区分团队价和散客价候选 |
+| `rate_code` | Rate Code 稳定 code，引用当前酒店 `RATE_CODE` 目录 |
+| `status` | `ACTIVE` / `DISABLED`；普通 lookup 只返回 `ACTIVE` |
+| `source_system` | `SYSTEM_MANAGED` / `IMPORT_FILE` / `PMS_SYNC` / `FIXED_SEED_IMPORT` |
+| `catalog_version` | 适用关系版本，用于排查和前端非阻塞提示 |
+| `sort_order` | 同一 Account + booking type 下的默认展示排序 |
+| `metadata_json` | 扩展说明，例如导入文件行号、业务备注；不得作为唯一可查询条件 |
+| `version` | 乐观锁版本 |
+| `created_at` / `updated_at` | UTC 创建和更新时间 |
+| `logic_deleted_at` / `logic_deleted_reason` | 逻辑删除时间和原因 |
+
+建议唯一约束：
+
+```text
+uk_reservation_rate_code_applicability(hotel_id, account_code, booking_type, rate_code)
+```
+
+建议外键 / 逻辑校验：
+
+- `account_code` 必须存在于同酒店 `workflow_reservation_catalog_account` 且为 `ACTIVE`，否则不进入普通 lookup。
+- `rate_code` 必须存在于同酒店 `workflow_reservation_catalog_code` 且 `catalog_type=RATE_CODE`、`status=ACTIVE`，否则不进入普通 lookup。
+- 停用 Account 或 Rate Code 后，普通 Rate Code lookup 不再返回对应适用关系；已确认历史卡片不回滚。
+
+### 6.4 Rate Code 早餐派生
+
+Room Information 卡需要展示 `breakfast_included` 布尔字段，但该字段不由 SuperAgent 输出。
+
+第一版派生规则：
+
+- Group 固定含早，`breakfast_included=true`，前端显示勾选且只读。
+- Fit 根据最终 Rate Code 派生：Rate Code 中包含 `RB` 时 `breakfast_included=true`，包含 `RO` 时 `breakfast_included=false`。
+- Fit Rate Code 同时无法命中 `RB` / `RO` 时，后端应把 `breakfast_included` 标为未解决，前端显示必填勾选框，由用户确认是否含早。
+- 该规则只用于 Room Information 卡展示和确认，不代表真实价格计算，也不替代 PMS Rate Plan 规则。
+- 后续如果目录表显式维护早餐属性，可优先使用目录元数据；但普通前端仍消费布尔 `breakfast_included`，不要自行按 Rate Code 字符串猜测。
+
+### 6.5 推荐表：`workflow_reservation_catalog_sync_run`

 如果接 PMS / OPERA / OHIP 同步，建议记录每次同步运行。

@@ -168,6 +217,7 @@ workflows.reservation.service
    - findAccount(hotelId, accountCode)
    - isKnownRoomTypeCode(hotelId, roomTypeCode)
    - isKnownRateCode(hotelId, rateCode)
+    - isRateCodeApplicable(hotelId, accountCode, bookingType, rateCode)

 workflows.reservation.repository
  ReservationV4CatalogRepository
@@ -178,6 +228,7 @@ workflows.reservation.service
    - listAccounts(...)
    - listRoomTypes(...)
    - listRateCodes(...)
+    - listRateCodesByAccountAndBookingType(...)

 integrations.ohip / integrations.pms
  CatalogSyncAdapter
@@ -187,6 +238,7 @@ integrations.ohip / integrations.pms
 规则：

 - V4 入站、确认、复核只调用 `ReservationV4DirectoryService`。
+- Basic Information 的 `account_code` 先确认或在同次复核中修正后，业务卡 Rate Code 才能按该 Account + `booking_type` 做适用性校验。
 - 前端 lookup Controller 调用 `ReservationV4CatalogLookupService`，该服务同样只读本地目录表。
 - PMS / OHIP 同步 Adapter 只能写本地目录表或同步 run，不直接参与用户确认事务。
 - 如果目录服务不可用，确认接口 fail closed，不接受自由文本。
@@ -318,10 +370,12 @@ GET /api/reservation/lookups/rate-codes
 | 参数 | 必需 | 中文说明 |
 | --- | --- | --- |
 | `hotel_id` | 否 | 当前酒店 ID |
+| `account_code` | 是 | 已选择或已确认的 Reservation Account code；必须属于当前酒店 ACTIVE Account 目录 |
+| `booking_type` | 是 | `GROUP` / `FIT`；取自当前业务 event 的 `target_order.booking_type` |
 | `keyword` | 否 | 匹配 Rate Code 或显示名 |
 | `page_num` / `page_size` | 否 | 分页 |

-第一版固定只返回 `ACTIVE` Rate Code，不接 `booking_type`、`account_code`、`arrival_date` / `departure_date`，适用范围和价格过滤后置。
+下一阶段 Rate Code lookup 必须按 `account_code + booking_type` 返回 `ACTIVE` 且适用的 Rate Code。`account_code` 未传、无效或不属于当前酒店时返回 400；`booking_type` 非 `GROUP` / `FIT` 时返回 400；Account 合法但当前无适用 Rate Code 时返回空 `items[]`。前端在 Account 未选时不应拉全酒店 Rate Code。`arrival_date` / `departure_date`、房型和价格过滤后置。

 响应草案：

@@ -329,15 +383,17 @@ GET /api/reservation/lookups/rate-codes
 {
  "hotel_id": "HOTEL-TEST",
  "catalog_type": "RATE_CODE",
-  "catalog_source": "FIXED_SEED_IMPORT",
-  "catalog_version": "seed-20260719-v1",
+  "account_code": "QBD_TRAVEL",
+  "booking_type": "GROUP",
+  "catalog_source": "IMPORT_FILE",
+  "catalog_version": "owner-rate-20260720-v1",
  "stale": false,
  "items": [
    {
-      "code": "GROUP",
-      "display_name": "GROUP",
+      "code": "GRPA1",
+      "display_name": "GRPA1",
      "status": "ACTIVE",
-      "catalog_source": "FIXED_SEED_IMPORT",
+      "catalog_source": "IMPORT_FILE",
      "pricing_available": false
    }
  ],
@@ -353,7 +409,8 @@ GET /api/reservation/lookups/rate-codes
 前端用途：

 - `fields[].options_source=reservation_v4_rate_code_catalog` 时调用。
- 第一版只选 `rate_code`，不展示或计算真实价格。
+- 只能在当前订单 Basic Information 已有有效 Account，且当前业务 event 有 `booking_type` 时调用；Account 切换后必须清空或重新校验已选 Rate Code。
+- 下一阶段只选 `rate_code`，不展示或计算真实价格。
 - V4 契约仍禁止 `UPDATE_BOOKING` 携带 Rate Code；lookup API 不改变该规则。

 ### 8.4 Market / Source Lookup
@@ -370,7 +427,7 @@ Market / Source 第一版不作为用户可编辑字段，不建议给普通业
 | --- | --- | --- |
 | `reservation_v4_account_catalog` | `GET /api/reservation/lookups/accounts` | 渲染 Account 下拉 / 搜索选择，展示派生 Market / Source |
 | `reservation_v4_room_type_catalog` | `GET /api/reservation/lookups/room-types` | 渲染房型搜索选择 |
-| `reservation_v4_rate_code_catalog` | `GET /api/reservation/lookups/rate-codes` | 渲染 Rate Code 搜索选择 |
+| `reservation_v4_rate_code_catalog` | `GET /api/reservation/lookups/rate-codes?account_code=...&booking_type=...` | 渲染当前 Account + GROUP/FIT 适用的 Rate Code 搜索选择 |
 | `static_enum` | 使用 `fields[].enum_options` | 不调用 lookup |
 | `system_case_lookup` | 后续订单 / 任务对象 lookup | 不属于本目录 checkpoint |

@@ -423,7 +480,7 @@ Market / Source 第一版不作为用户可编辑字段，不建议给普通业
 | --- | --- | --- | --- | --- |
 | `GET /api/reservation/lookups/accounts` | `FRONTEND_USER` | `RESERVATION_TASK_READ` | 按用户可访问酒店校验 | 只读不写业务审计 |
 | `GET /api/reservation/lookups/room-types` | `FRONTEND_USER` | `RESERVATION_TASK_READ` | 按用户可访问酒店校验 | 只读不写业务审计 |
-| `GET /api/reservation/lookups/rate-codes` | `FRONTEND_USER` | `RESERVATION_TASK_READ` | 按用户可访问酒店校验 | 只读不写业务审计 |
+| `GET /api/reservation/lookups/rate-codes` | `FRONTEND_USER` | `RESERVATION_TASK_READ` | 按用户可访问酒店校验；`account_code` 和 `booking_type` 只能用于当前酒店目录过滤 | 只读不写业务审计 |

 复用 `RESERVATION_TASK_READ` 的原因：

@@ -480,14 +537,16 @@ SuperAgent 当前不调用本 lookup API。SuperAgent 目录供给后续有两
 2. 遍历每张卡 `fields[]`。
 3. 只有字段 `editable=true` 且 `control_type=select/lookup` 时才加载 lookup。
 4. 根据 `options_source` 选择 lookup 接口。
-5. 搜索输入做 debounce，不一次性拉全量。
-6. 显示 `stale=true` 或 `warnings[]` 时给用户非阻塞提醒。
-7. 用户提交确认或复核时只提交 code，不提交显示名、Market / Source 派生值或目录完整对象。
-8. 确认成功后以后端返回的 `confirmed_payload_json` / 刷新详情为准更新页面。
+5. Rate Code 字段必须先取得当前订单 Basic Information 的 Account 和当前业务 event 的 `booking_type`；缺任一条件时禁用或显示空态，不调用全酒店 Rate Code 全量查询。
+6. 搜索输入做 debounce，不一次性拉全量。
+7. 显示 `stale=true` 或 `warnings[]` 时给用户非阻塞提醒。
+8. 用户提交确认或复核时只提交 code，不提交显示名、Market / Source 派生值或目录完整对象。
+9. 确认成功后以后端返回的 `confirmed_payload_json` / 刷新详情为准更新页面。

 前端禁止：

 - 硬编码 PMS 房型或 Rate Code 全集。
+- 硬编码 OWNER RATE Excel 中 Account 到 Rate Code 的映射；该映射必须由后端目录 / 适用关系接口提供。
 - 把目录显示名当业务 code 提交。
 - 绕过 `fields[]` 自行补业务字段。
 - 使用 lookup API 给 SuperAgent、AgentBus 或 Debug 链路拼接输入。
@@ -501,6 +560,7 @@ SuperAgent 当前不调用本 lookup API。SuperAgent 目录供给后续有两
 | M002-V4-CP12 | 前端 Lookup 接入 | V4 卡片字段渲染按 `options_source` 调用 lookup，替换固定种子硬编码选项，处理 stale / warning / 空目录 |
 | M002-V4-CP13 | 目录管理后台 V1 | CP1 已完成 Account / Room Type / Rate Code 前后端列表、新增、启用 / 停用闭环、`RESERVATION_CATALOG_MANAGE` 权限和管理审计；Market / Source 独立管理后置 |
 | M002-V4-CP14 | 订单列表 V4 继续处理入口 | 已完成：订单列表返回 V4 下一步订单任务、卡片、动作类型、动作状态和 open 数，前端可优先跳 V4 订单任务详情 |
+| M002-V4-CP14.5 | Account 范围 Rate Code Lookup | 待实现：新增 Account + booking type 适用关系模型 / 导入种子，Rate Code lookup 接收 `account_code`、`booking_type`，确认和复核校验 Rate Code 适用性，前端联动 Account 后展示候选 |
 | M002-V4-CP15 | PMS / OPERA / OHIP 目录同步 | 同步 Adapter、同步 run 表、失败重试、最后成功快照、同步状态管理入口 |
 | M002-V4-CP16 | SuperAgent 目录供给 | 明确目录版本如何给 SuperAgent，必要时新增机器目录接口或导出包 |

@@ -512,7 +572,7 @@ CP11 已作为后端第一步落地，因为它不依赖真实 PMS，也能让
 2. Account code 是否继续使用本系统定义的稳定 code，例如 `QBD_TRAVEL`，还是必须对齐 PMS profile code。
 3. Market / Source 是否只允许随 Account 派生，还是未来允许用户在 Basic Information 中单独改选。
 4. Room Type 第一版后端已支持系统管理维护；后续是否仍要接 PMS / OHIP 同步替换为主来源待确认。
-5. Rate Code 第一版是否只校验 code，还是需要按 `booking_type`、`account_code`、入住日期过滤。
+5. Rate Code 已确认下一阶段按 `account_code + booking_type` 过滤；入住日期、房型和价格是否也要进入过滤仍待后续确认。
 6. 生产是否允许 `FIXED_SEED` 作为兜底，还是只允许 dev/test 使用。
 7. SuperAgent 是否需要读取目录；如果需要，是离线给目录包，还是新增 HMAC 机器接口。