实现V4目录管理后台CP1后端
This commit is contained in:
andy
@@ -4,11 +4,11 @@
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档版本 | 0.2 |
|
||||
| 文档版本 | 0.3 |
|
||||
| 日期 | 2026-07-19 |
|
||||
| 状态 | CP11 已落地第一版数据库目录与 lookup API；后续真实 PMS 同步和目录管理后台继续后置 |
|
||||
| 状态 | CP11 已落地第一版数据库目录与 lookup API；目录管理后台 CP1 已落地后端接口；真实 PMS 同步继续后置 |
|
||||
| 适用范围 | M002 V4 Account、Market、Source、Room Type、Rate Code 目录来源、数据模型、前端 lookup、缓存、酒店隔离、权限和失败兜底 |
|
||||
| 不适用范围 | 真实 OPERA / OHIP 写操作、真实价格计算、前端页面实现、SuperAgent Prompt 修改、目录管理后台、SuperAgent 机器目录接口 |
|
||||
| 不适用范围 | 真实 OPERA / OHIP 写操作、真实价格计算、前端页面实现、SuperAgent Prompt 修改、目录同步任务、SuperAgent 机器目录接口 |
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
@@ -19,7 +19,7 @@ M002 V4 CP8 已实现第一版固定种子目录校验；M002 V4 CP11 已把该
|
||||
- Room Type / Rate Code 第一版使用当前酒店数据库目录校验和字段选项提示。
|
||||
- 目录错误会让对应 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` 初始化目录。不再在运行时代码中把固定种子作为全局目录事实。`workflow_reservation_catalog_sync_run`、真实 PMS / OPERA / OHIP 同步、目录管理后台和 SuperAgent 机器目录供给接口继续后置。
|
||||
本文记录真实目录和 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 机器目录供给接口继续后置。
|
||||
|
||||
后续若本文与 `M002-v4-agent-callback-field-contract.md` 的 Agent 输入字段冲突，以 Agent 字段契约为准；若与 `security-access-control-boundary.md` 的接口权限冲突，以安全边界为准。
|
||||
|
||||
@@ -29,11 +29,11 @@ CP11 之前固定种子实现位于后端 `ReservationV4DirectoryService` 和 `F
|
||||
|
||||
| 目录 | 当前用途 | 当前固定值 | 当前限制 |
|
||||
| --- | --- | --- | --- |
|
||||
| Account | Basic Information 可选目录；SuperAgent 和用户提交都使用稳定 code | `QBD_TRAVEL`、`LIAN_TAI`、`HANATOUR_TD` | 已进入数据库初始化目录，仍不是 PMS 全量 Account，管理后台后置 |
|
||||
| Account | Basic Information 可选目录；SuperAgent 和用户提交都使用稳定 code | `QBD_TRAVEL`、`LIAN_TAI`、`HANATOUR_TD` | 已进入数据库初始化目录，仍不是 PMS 全量 Account；后台 CP1 可新增、启用 / 停用 |
|
||||
| Market | 由 Account 派生的订单级 Market | 当前 Account 均派生 `LEISURE` | 已进入通用代码目录，前端仍不直接编辑 |
|
||||
| Source | 由 Account 派生的订单级 Source | 当前 Account 均派生 `TRAVEL_AGENT` | 已进入通用代码目录，前端仍不直接编辑 |
|
||||
| Room Type | 房型 code 校验和字段选项提示 | `TWN`、`KING`、`DBL`、`SGL`、`TRP`、`RM1`、`RM2`、`RM3` | 已进入数据库初始化目录，仍不是 PMS 全量房型 |
|
||||
| Rate Code | Rate Code 校验和字段选项提示 | `BAR`、`RACK`、`PACKAGE`、`GROUP`、`FIT` | 已进入数据库初始化目录，不按日期、账号、房型过滤，不含价格 |
|
||||
| Room Type | 房型 code 校验和字段选项提示 | `TWN`、`KING`、`DBL`、`SGL`、`TRP`、`RM1`、`RM2`、`RM3` | 已进入数据库初始化目录，仍不是 PMS 全量房型；后台 CP1 可新增、启用 / 停用 |
|
||||
| Rate Code | Rate Code 校验和字段选项提示 | `BAR`、`RACK`、`PACKAGE`、`GROUP`、`FIT` | 已进入数据库初始化目录，不按日期、账号、房型过滤，不含价格；后台 CP1 可新增、启用 / 停用 |
|
||||
|
||||
当前固定种子只能支撑开发和演示闭环，不能作为生产长期事实源。
|
||||
|
||||
@@ -139,7 +139,7 @@ uk_reservation_catalog_code(hotel_id, catalog_type, code)
|
||||
|
||||
如果接 PMS / OPERA / OHIP 同步，建议记录每次同步运行。
|
||||
|
||||
CP11 本轮没有创建该表。原因是当前不接真实 PMS / OPERA / OHIP 同步，暂时没有同步运行事实可记录；后续做同步 worker 或目录管理后台时，再新增该表和对应 Repository。
|
||||
CP11 本轮没有创建该表。原因是当前不接真实 PMS / OPERA / OHIP 同步，暂时没有同步运行事实可记录；CP13 目录管理后台 CP1 也只维护系统管理目录项，不产生外部同步运行事实。后续做 PMS / OPERA / OHIP 同步 worker 时，再新增该表和对应 Repository。
|
||||
|
||||
| 字段 | 中文说明 |
|
||||
| --- | --- |
|
||||
@@ -432,13 +432,34 @@ Market / Source 第一版不作为用户可编辑字段，不建议给普通业
|
||||
|
||||
### 12.2 目录维护权限
|
||||
|
||||
目录维护不在本 checkpoint 实现。后续如果做系统管理维护，建议新增：
|
||||
目录管理后台 CP1 已实现后端接口。该能力属于 `FRONTEND_ADMIN`，使用管理后台错误响应和管理审计，不复用普通 lookup 权限。
|
||||
|
||||
```text
|
||||
RESERVATION_CATALOG_MANAGE
|
||||
```
|
||||
|
||||
用于 Account、Market、Source、临时 Room Type、Rate Code 的系统管理维护页面。写操作必须记录管理审计或业务配置审计。
|
||||
已实现接口：
|
||||
|
||||
| 接口 | 中文说明 | 权限 | 酒店隔离 | 审计 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `GET /api/admin/reservation/catalogs/accounts` | Account 管理列表 | `RESERVATION_CATALOG_MANAGE` | `hotel_id` 必须在当前用户可访问酒店内；不传时使用默认酒店 | 只读不写审计 |
|
||||
| `POST /api/admin/reservation/catalogs/accounts` | 新增 Account | `RESERVATION_CATALOG_MANAGE` | 按请求 `hotel_id` 校验 | 写平台管理审计 |
|
||||
| `PUT /api/admin/reservation/catalogs/accounts/{accountId}/status` | 启用 / 停用 Account | `RESERVATION_CATALOG_MANAGE` | 按记录所属酒店校验 | 状态实际变化时写平台管理审计；相同状态幂等返回，不新增审计 |
|
||||
| `GET /api/admin/reservation/catalogs/room-types` | Room Type 管理列表 | `RESERVATION_CATALOG_MANAGE` | 同上 | 只读不写审计 |
|
||||
| `POST /api/admin/reservation/catalogs/room-types` | 新增 Room Type | `RESERVATION_CATALOG_MANAGE` | 按请求 `hotel_id` 校验 | 写平台管理审计 |
|
||||
| `PUT /api/admin/reservation/catalogs/room-types/{catalogId}/status` | 启用 / 停用 Room Type | `RESERVATION_CATALOG_MANAGE` | 按记录所属酒店校验 | 状态实际变化时写平台管理审计；相同状态幂等返回，不新增审计 |
|
||||
| `GET /api/admin/reservation/catalogs/rate-codes` | Rate Code 管理列表 | `RESERVATION_CATALOG_MANAGE` | 同上 | 只读不写审计 |
|
||||
| `POST /api/admin/reservation/catalogs/rate-codes` | 新增 Rate Code | `RESERVATION_CATALOG_MANAGE` | 按请求 `hotel_id` 校验 | 写平台管理审计 |
|
||||
| `PUT /api/admin/reservation/catalogs/rate-codes/{catalogId}/status` | 启用 / 停用 Rate Code | `RESERVATION_CATALOG_MANAGE` | 按记录所属酒店校验 | 状态实际变化时写平台管理审计；相同状态幂等返回，不新增审计 |
|
||||
|
||||
CP1 限制：
|
||||
|
||||
- 新增目录默认 `ACTIVE`，`source_system=SYSTEM_MANAGED`。
|
||||
- 管理列表可按 `status=ACTIVE/DISABLED` 过滤；普通 lookup 仍只返回 `ACTIVE`。
|
||||
- Account 新增时 `market_code`、`source_code` 必须是当前酒店 `ACTIVE` 的 Market / Source code。
|
||||
- Market / Source 独立管理页面暂不做，仍沿用当前初始化目录。
|
||||
- 停用目录不会回滚已确认历史卡片，但新确认 / 复核会按当前 ACTIVE 目录校验。
|
||||
- 后续如做前端管理页面，应在系统设置下使用该权限码控制入口。
|
||||
|
||||
### 12.3 第三方接口边界
|
||||
|
||||
@@ -476,20 +497,20 @@ SuperAgent 当前不调用本 lookup API。SuperAgent 目录供给后续有两
|
||||
| --- | --- | --- |
|
||||
| M002-V4-CP11 | DB 管理目录与 Lookup API V1 | 新增 Account / Code 目录表、Repository、DirectoryService DB 实现、Account / Room Type / Rate Code lookup 查询接口、权限和测试 |
|
||||
| M002-V4-CP12 | 前端 Lookup 接入 | V4 卡片字段渲染按 `options_source` 调用 lookup，替换固定种子硬编码选项，处理 stale / warning / 空目录 |
|
||||
| M002-V4-CP13 | 目录管理后台 V1 | Account / Market / Source 管理，临时 Room Type / Rate Code 管理，`RESERVATION_CATALOG_MANAGE` 权限和管理审计 |
|
||||
| M002-V4-CP13 | 目录管理后台 V1 | CP1 已完成 Account / Room Type / Rate Code 后端列表、新增、启用 / 停用接口、`RESERVATION_CATALOG_MANAGE` 权限和管理审计；前端页面、Market / Source 独立管理后置 |
|
||||
| M002-V4-CP14 | PMS / OPERA / OHIP 目录同步 | 同步 Adapter、同步 run 表、失败重试、最后成功快照、同步状态管理入口 |
|
||||
| M002-V4-CP15 | SuperAgent 目录供给 | 明确目录版本如何给 SuperAgent，必要时新增机器目录接口或导出包 |
|
||||
|
||||
CP11 已作为后端第一步落地，因为它不依赖真实 PMS，也能让前端后续不再硬编码当前固定种子。
|
||||
CP11 已作为后端第一步落地，因为它不依赖真实 PMS，也能让前端后续不再硬编码当前固定种子。CP13 CP1 继续沿用本地目录表，不接真实 PMS，也不改变 SuperAgent 输入契约。
|
||||
|
||||
## 15. 仍需确认的问题
|
||||
|
||||
1. Account 的第一版真实维护入口是否放在现有系统管理后台，还是先用导入 SQL / Excel 导入。
|
||||
1. Account 的第一版真实维护入口后端已放在系统管理后台接口；前端菜单和页面布局仍需后续确认。
|
||||
2. Account code 是否继续使用本系统定义的稳定 code，例如 `QBD_TRAVEL`，还是必须对齐 PMS profile code。
|
||||
3. Market / Source 是否只允许随 Account 派生，还是未来允许用户在 Basic Information 中单独改选。
|
||||
4. Room Type 第一版真实目录是否先由系统管理维护，还是等 PMS / OHIP 同步后再替换。
|
||||
4. Room Type 第一版后端已支持系统管理维护；后续是否仍要接 PMS / OHIP 同步替换为主来源待确认。
|
||||
5. Rate Code 第一版是否只校验 code，还是需要按 `booking_type`、`account_code`、入住日期过滤。
|
||||
6. 生产是否允许 `FIXED_SEED` 作为兜底，还是只允许 dev/test 使用。
|
||||
7. SuperAgent 是否需要读取目录；如果需要，是离线给目录包，还是新增 HMAC 机器接口。
|
||||
|
||||
在这些问题未确认前，CP11 仍可以先按 DB 管理目录 + 前端 lookup 查询实现，不接真实 PMS，也不替换 SuperAgent 输入契约。
|
||||
在这些问题未确认前，当前实现仍按 DB 管理目录 + 前端 lookup 查询 + 后台 CP1 手工维护闭环推进，不接真实 PMS，也不替换 SuperAgent 输入契约。
|
||||
|
||||
Reference in New Issue
Block a user