实现V4目录管理后台CP1后端

2026-07-19 17:56:08 +07:00
parent 22767e194d
commit f2c2616ab0
23 changed files with 1958 additions and 31 deletions
--- a/docs/project/README.md
+++ b/docs/project/README.md
@@ -47,7 +47,8 @@
 | `requirements/M002-task-field-control-contract-v1.md` | 当前有效 | M002 任务卡字段控件契约 V1，记录任务详情 `fields[]` 控件元数据、人工复核控件复用和前后端开发边界。 |
 | `requirements/M002-v4-agent-callback-field-contract.md` | 当前有效 | M002 V4 Agent 回调字段契约，基于 2026-07-18 业务基线和最新答复，冻结 `source_message`、`order_contexts`、`message_events`、订单级 Basic Information、六类 Event、S10/S99 和校验口径；后端已完成 V4 入站解析、持久化、查询、确认、复核和当前酒店数据库目录校验。 |
 | `requirements/M002-v4-order-task-card-domain-model-cp2.md` | 当前有效 | M002 V4 CP2 订单任务与多卡领域模型设计，并记录 CP3-CP8 表结构、入站写入、查询、确认、复核和目录校验已落地状态；CP11 已完成 DB 目录与 lookup API，后续仍需前端页面、目录管理后台和真实 PMS 同步。 |
-| `requirements/M002-v4-real-catalog-lookup-api-design.md` | 当前有效 | M002 V4 真实目录与 Lookup API 设计及 CP11 实现记录，记录 Account、Market、Source、Room Type、Rate Code 从固定种子导入数据库、前端 lookup API、权限、缓存后置、PMS / OPERA / OHIP 同步后置和失败兜底。 |
+| `requirements/M002-v4-real-catalog-lookup-api-design.md` | 当前有效 | M002 V4 真实目录与 Lookup API 设计及 CP11 / CP13 CP1 实现记录，记录 Account、Market、Source、Room Type、Rate Code 从固定种子导入数据库、前端 lookup API、目录管理后端接口、权限、缓存后置、PMS / OPERA / OHIP 同步后置和失败兜底。 |
+| `requirements/M002-v4-test-machine-smoke-checklist.md` | 当前有效 | M002 V4 测试机冒烟清单，覆盖登录、酒店权限、V4 工作台、订单任务详情、lookup、确认、复核解阻、S10/S99 ack、订单详情 V4 时间线和目录管理 CP1 排查点。 |
 | `requirements/M002-superagent-task-result-api-contract.md` | 阶段记录 | M002 SuperAgent 任务结果入站接口契约阶段记录；对外总契约以 `integrations/superagent-api-contract.md` 为准。 |
 | `requirements/M002-ai-query-minimal-fields.md` | 阶段记录 | M002 SuperAgent 查询上下文接口 1、2 最小字段落地记录；对外总契约以 `integrations/superagent-api-contract.md` 为准。 |
 | `requirements/M002-backend-data-model-design.md` | 阶段记录 | M002 后端数据模型设计，记录 AI 过渡层、订单、任务、任务卡、审计和 OPERA 模拟结果表。 |
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -61,6 +61,12 @@
 | `GET /api/reservation/lookups/accounts` | 查询 V4 Account 目录 | 必须带 Bearer token，需要 `RESERVATION_TASK_READ`，支持 `hotel_id`、`keyword`、`page_num`、`page_size`；返回统一 wrapper：`hotel_id`、`catalog_type=ACCOUNT`、`catalog_source`、`catalog_version`、`stale`、`items[]`、`page`、`warnings[]`。`keyword` 无匹配时 `items=[]` / `page.total=0`，但只要酒店未过滤目录存在，`catalog_source/catalog_version` 仍保持真实目录元数据，不代表目录未初始化。前端在 `options_source=reservation_v4_account_catalog` 时调用，只提交 `items[].code`，Market / Source 以后端确认派生结果为准。 |
 | `GET /api/reservation/lookups/room-types` | 查询 V4 Room Type 目录 | 必须带 Bearer token，需要 `RESERVATION_TASK_READ`，支持 `hotel_id`、`keyword`、`page_num`、`page_size`；第一版只返回当前酒店 `ACTIVE` 房型目录，不接日期过滤，不代表 PMS 全量房型。`keyword` 无匹配时按空选项处理，不要当作目录不可用。前端在 `options_source=reservation_v4_room_type_catalog` 时调用。 |
 | `GET /api/reservation/lookups/rate-codes` | 查询 V4 Rate Code 目录 | 必须带 Bearer token，需要 `RESERVATION_TASK_READ`，支持 `hotel_id`、`keyword`、`page_num`、`page_size`；第一版只返回当前酒店 `ACTIVE` Rate Code，`pricing_available=false` 表示后端未接真实价格，不要据此展示价格。`keyword` 无匹配时按空选项处理，不要当作目录不可用。前端在 `options_source=reservation_v4_rate_code_catalog` 时调用。 |
+| `GET /api/admin/reservation/catalogs/accounts` | 管理后台 Account 目录列表 | 必须带 Bearer token，需要 `RESERVATION_CATALOG_MANAGE` 和目标酒店访问权；支持 `hotel_id`、`keyword`、`status=ACTIVE/DISABLED`、`page_num`、`page_size`；返回 `items[] + page`，包含 `id`、`account_code`、`account_name`、`market_code`、`source_code`、`status`、`catalog_source`、`external_account_id`、`catalog_version`、`metadata_json`、`version`、`created_at`、`updated_at`。 |
+| `POST /api/admin/reservation/catalogs/accounts` | 管理后台新增 Account 目录 | 必须带 `RESERVATION_CATALOG_MANAGE`；请求 `hotel_id`、`account_code`、`account_name`、`market_code`、`source_code`，可选 `external_account_id`、`catalog_version`、`metadata_json`；后端校验 Market / Source 当前酒店 ACTIVE，新增后默认 `ACTIVE`、`catalog_source=SYSTEM_MANAGED`，写管理审计。 |
+| `PUT /api/admin/reservation/catalogs/accounts/{accountId}/status` | 管理后台启用 / 停用 Account | 必须带 `RESERVATION_CATALOG_MANAGE`；请求 `{"status":"ACTIVE"}` 或 `{"status":"DISABLED"}`；按记录所属酒店校验访问权；停用后普通 Account lookup 不再返回；如果提交的状态和当前状态一致，后端幂等返回当前记录，不新增管理审计。 |
+| `GET /api/admin/reservation/catalogs/room-types` / `GET /api/admin/reservation/catalogs/rate-codes` | 管理后台 Room Type / Rate Code 目录列表 | 必须带 `RESERVATION_CATALOG_MANAGE`；支持 `hotel_id`、`keyword`、`status`、`page_num`、`page_size`；返回 `items[] + page`，包含 `id`、`catalog_type`、`code`、`display_name`、`status`、`catalog_source`、`external_id`、`sort_order`、`catalog_version`、`metadata_json`、`version`、`created_at`、`updated_at`。 |
+| `POST /api/admin/reservation/catalogs/room-types` / `POST /api/admin/reservation/catalogs/rate-codes` | 管理后台新增 Room Type / Rate Code | 必须带 `RESERVATION_CATALOG_MANAGE`；请求 `hotel_id`、`code`、`display_name`，可选 `external_id`、`sort_order`、`catalog_version`、`metadata_json`；新增后默认 `ACTIVE`、`catalog_source=SYSTEM_MANAGED`，写管理审计。 |
+| `PUT /api/admin/reservation/catalogs/room-types/{catalogId}/status` / `PUT /api/admin/reservation/catalogs/rate-codes/{catalogId}/status` | 管理后台启用 / 停用 Room Type / Rate Code | 必须带 `RESERVATION_CATALOG_MANAGE`；请求 `{"status":"ACTIVE"}` 或 `{"status":"DISABLED"}`；按记录所属酒店校验；停用后对应普通 lookup 不再返回；如果提交的状态和当前状态一致，后端幂等返回当前记录，不新增管理审计。 |
 | `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm` | 确认 V4 订单任务卡 | 必须带 Bearer token，需要 `RESERVATION_TASK_CONFIRM`，请求 JSON 带 `version`，可选 `confirmed_payload`；Basic Information 必须先确认，业务卡第一版不强制逐张顺序确认；前端只提交当前卡 `fields[]` 中可编辑字段，后端以展示快照为基准合并，未开放字段会被忽略；确认前会按当前酒店数据库目录校验 Account / Room Type / Rate Code，嵌套字段错误会返回如 `business_fields.after.room_items.0.room_type_code` 的路径，失败返回 `V4_FIELD_VALIDATION_FAILED`；确认后卡片 `CONFIRMED`、写 `confirmed_payload_json/confirmed_at/confirmed_by` 并锁定，重复确认返回错误；成功返回刷新后的订单任务详情。 |
 | `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution` | V4 复核解阻并确认卡片 | 必须带 Bearer token，需要 `RESERVATION_MANUAL_REVIEW_RESOLVE`，仅用于 `card_status=REVIEW_REQUIRED`；请求 JSON 带 `version`，可选 `field_overrides[]` 和 `reason`；订单任务归属未解决时 `confirmed_order_id` 必填，且必须是当前酒店下真实可见订单；目录错误字段可按 `validation_errors_json` / `fields[].validation_errors` 指向的 pointer 修正；成功后卡片 `CONFIRMED`、`review_status=RESOLVED`，写 `review_resolution_json/confirmed_payload_json/confirmed_at/confirmed_by` 并返回刷新后的订单任务详情。 |
 | `POST /api/reservation/source-notifications/{notificationId}/ack` | 确认 V4 S10/S99 来源通知已读 / 已处理 | 必须带 Bearer token，需要 `RESERVATION_TASK_CONFIRM`，请求 JSON 带 `version`；仅允许 `route_code=S10/S99`；确认后 `notification_status=ACKED`，写 `ack_by/ack_at`，成功返回刷新后的来源通知详情；重复 ack 返回当前已确认状态且不新增审计；该动作不创建订单、不参与订单阻塞。 |
@@ -100,6 +106,7 @@
 | `POST /api/system/debug/eml-superagent-runs` | 新增 Debug EML 上传到 SuperAgent 调试接口，并补齐独立 Debug 外部消息 ID、原始 Message-ID 保留、安全 HTML 字段和入口通知识别。 | 只用于调试页面；请求为 multipart/form-data；必须传 `X-TH-Hotel-Debug-Upload-Key`，但该 key 不能写进前端源码、构建产物、URL、localStorage 或错误上报；SuperAgent 返回旧 S000/S999 或新 S10/S99 入口通知时都不应被前端视为 JSON 解析失败。 |
 | `GET /api/reservation/workbench-items` / `/api/reservation/order-tasks/**` / `/api/reservation/source-notifications/{notificationId}` | 新增 M002 V4 CP5 查询接口，并在 CP6 打开卡片确认 / 来源通知 ack availability。 | 这是 V4 新模型前端主入口；前端应按每张卡或通知返回的 `availability.confirmable`、`availability.ackable`、`readonly_reason_code` 控制按钮。工作台条目已返回 `created_at` / `updated_at` 作为排序兜底和调试字段；前端不要继续从旧 `/api/reservation/tasks/**` 推断 V4 多卡详情。 |
 | `GET /api/reservation/lookups/accounts` / `/room-types` / `/rate-codes` | 新增 M002 V4 CP11 数据库目录 lookup。 | 前端从任务详情 `fields[].options_source` 选择调用哪个 lookup；只提交返回项的 `code`，不要提交显示名、派生 Market / Source、目录完整对象或前端自造 code。`warnings[]` 非空时可做非阻塞提示。 |
+| `GET/POST/PUT /api/admin/reservation/catalogs/...` | 新增 M002 V4 目录管理后台 CP1 后端接口。 | 仅供系统设置 / 管理后台页面使用，必须带 `RESERVATION_CATALOG_MANAGE`；支持 Account、Room Type、Rate Code 列表、新增、启用 / 停用；停用后普通 lookup 不再返回该目录项。 |

 V4 CP5 分页注意：`page_num` 从 1 开始，后端第一版安全上限为 100；`page_size` 最大 100。超出上限时后端按上限处理并在 `page.page_num` / `page.page_size` 中返回实际使用值。`order_task_status` 和 `card_status` 是稳定枚举查询参数，前端不要传中文文案或自造状态码。

@@ -495,13 +502,13 @@ RESERVATION_ROOMING_LIST_GENERATE

 - 普通任务切换订单接口继续后置。
 - M002 V4 入站解析与数据模型基线已完成第一版：后端可接收 `source_message + order_contexts[] + message_events[]`，识别 `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT`，并保存 V4 原始 payload、`route_code`、系统处理分类和 `field_contract_version=20260718-v4`。前端暂不需要直接调用 V4 回调接口。
- M002 V4 CP5 已完成查询接口：普通 V4 业务包可通过 `/api/reservation/workbench-items`、`/api/reservation/order-tasks`、`/api/reservation/order-tasks/{orderTaskId}` 查看；V4 S10/S99 来源通知可通过 `/api/reservation/source-notifications/{notificationId}` 查看。M002 V4 CP6 已开放普通卡片确认和 S10/S99 ack 写接口；M002 V4 CP7 已开放 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution` 复核解阻接口；M002 V4 CP8 已开放 V4 卡片 `fields[]` 白名单和目录校验；M002 V4 CP11 已把固定种子迁移到数据库目录，并开放 Account / Room Type / Rate Code lookup API。
+- M002 V4 CP5 已完成查询接口：普通 V4 业务包可通过 `/api/reservation/workbench-items`、`/api/reservation/order-tasks`、`/api/reservation/order-tasks/{orderTaskId}` 查看；V4 S10/S99 来源通知可通过 `/api/reservation/source-notifications/{notificationId}` 查看。M002 V4 CP6 已开放普通卡片确认和 S10/S99 ack 写接口；M002 V4 CP7 已开放 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution` 复核解阻接口；M002 V4 CP8 已开放 V4 卡片 `fields[]` 白名单和目录校验；M002 V4 CP11 已把固定种子迁移到数据库目录，并开放 Account / Room Type / Rate Code lookup API；目录管理后台 CP1 已开放 Account / Room Type / Rate Code 后端列表、新增、启用 / 停用接口。
 - V4 任务卡的 `display_payload_json` 只保留后端白名单展示字段；`ai_payload_json` 才包含完整 SuperAgent 原始 event。后续 V4 查询接口不得把 `ai_payload_json`、附件 URL 或 raw evidence 直接给普通页面渲染；前端对来源消息卡附件字段仍做 URL-like 文本兜底脱敏。
 - V4 可映射 event 现阶段仍保留现有任务详情结构作为过渡兼容；任务详情中若出现 `field_contract_version=20260718-v4` 或 AI payload 内的 `v4_source_message`、`v4_order_context`、`v4_message_event`，前端第一版只读展示即可，不要据此假定完整 V4 多卡页面已经完成。
 - V4 `PAYMENT.attachment_ids[]` 不匹配、`UPDATE_BOOKING` 携带 `rate_code` 等问题会出现在任务详情同批次的 `adapter_contract_errors[]` 只读诊断块中，不展示保存、确认、执行或重试按钮。该字段只返回白名单诊断字段，不返回完整 AI payload、邮件正文、附件 URL 或 raw evidence。
 - V4 包级契约错误只会保存在 AI transition 中，不会出现在普通任务列表；V4 event 级契约错误如果同批次存在其它业务任务，前端仍按任务详情里的 `adapter_contract_errors[]` 只读展示诊断信息。
 - M002 V4 CP2 订单任务与多卡领域模型设计已落到 `docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md`：后续前端 V4 页面应围绕 `order_task + source_message_card + basic_information_card + business_cards[]` 设计；V4 工作台统一列表、业务订单任务列表 / 详情和 S10/S99 来源通知详情已实现。
- M002 V4 CP3 已新增 V4 订单任务、任务卡、S10/S99 来源通知三张表和 Repository 基线；M002 V4 CP4 已把正式 V4 回调写入这些表；M002 V4 CP5 已开放查询；M002 V4 CP6 已开放普通卡片确认和 S10/S99 ack；M002 V4 CP7 已开放复核解阻与复核场景订单归属确认；M002 V4 CP8 已开放目录校验和 V4 任务卡 `fields[]` 字段白名单；M002 V4 CP11 已新增目录表、数据库种子和 lookup API。
+- M002 V4 CP3 已新增 V4 订单任务、任务卡、S10/S99 来源通知三张表和 Repository 基线；M002 V4 CP4 已把正式 V4 回调写入这些表；M002 V4 CP5 已开放查询；M002 V4 CP6 已开放普通卡片确认和 S10/S99 ack；M002 V4 CP7 已开放复核解阻与复核场景订单归属确认；M002 V4 CP8 已开放目录校验和 V4 任务卡 `fields[]` 字段白名单；M002 V4 CP11 已新增目录表、数据库种子和 lookup API；目录管理后台 CP1 已新增 `RESERVATION_CATALOG_MANAGE` 后端接口。
 - V4 订单任务和卡片 `availability` 已新增 `reviewable`。当前语义：`REVIEW_REQUIRED` 卡如果未被 Basic Information 或前置订单任务阻塞，会返回 `read_only=false`、`editable=true`、`confirmable=false`、`reviewable=true`、`readonly_reason_code=PROCESSABLE`；前端应调用 `review-resolution`，不要调用普通 `confirm`。
 - CP11 起 V4 入站阶段按当前酒店数据库目录做校验：Account 缺失或不存在时 Basic Information 卡直接 `REVIEW_REQUIRED`；业务卡已有 `room_items[].room_type_code` 或 `rate_code` 但不在当前酒店目录时，业务卡也会直接 `REVIEW_REQUIRED`，错误会回显在 `fields[].validation_errors`。
 - CP8 确认接口也按 `fields[]` 白名单收口：前端可以只提交用户修改过的可编辑字段，不建议整包回传 `display_payload`。后端会从当前卡展示快照生成确认快照，并只合并可写叶子字段；来源邮件、路由、`target_order`、`order_ref`、`manual_review`、校验诊断字段以及前端额外注入字段不会写入 `confirmed_payload_json`。
--- 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.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 输入契约。
--- a/docs/project/requirements/M002-v4-test-machine-smoke-checklist.md
+++ b/docs/project/requirements/M002-v4-test-machine-smoke-checklist.md
@@ -0,0 +1,270 @@
+# M002 V4 测试机冒烟清单
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档版本 | 0.1 |
+| 日期 | 2026-07-19 |
+| 状态 | 测试机 V4 前后端联调冒烟清单 |
+| 适用范围 | 登录、酒店权限、V4 工作台、V4 订单任务详情、目录 lookup、卡片确认、复核解阻、S10/S99 ack、订单详情 V4 时间线 |
+| 不适用范围 | 真实 OPERA / OHIP、目录同步、旧 V2/V3 全量回归、前端视觉验收 |
+
+## 1. 测试前置
+
+1. 测试机后端使用最新包，Flyway 至少执行到 V24。
+2. `platform_hotel` 单酒店阶段只能有一家 `ACTIVE` 酒店，测试常用 `HOTEL-TEST`。
+3. 测试账号可以登录，并拥有目标酒店访问权。
+4. 普通 V4 业务测试账号至少需要：
+   - `RESERVATION_TASK_READ`
+   - `RESERVATION_ORDER_READ`
+   - `RESERVATION_TASK_CONFIRM`
+   - `RESERVATION_MANUAL_REVIEW_RESOLVE`
+5. 目录管理测试账号需要：
+   - `RESERVATION_CATALOG_MANAGE`
+   - 目标酒店访问权
+6. 当前酒店已存在 Account、Room Type、Rate Code 目录。若为空，先检查 `workflow_reservation_catalog_account` 和 `workflow_reservation_catalog_code`。
+7. 准备三类 V4 测试数据：
+   - 普通业务包：至少包含 Basic Information 和一张业务卡。
+   - `REVIEW_REQUIRED` 业务包：例如未知 Account、未知 Room Type 或缺失字段。
+   - S10/S99 来源通知：不创建订单任务，只进入来源通知模型。
+
+## 2. 冒烟步骤
+
+### 2.1 登录与酒店权限
+
+步骤：
+1. 打开前端登录页。
+2. 使用测试账号登录。
+3. 选择或确认当前酒店为 `HOTEL-TEST`。
+
+期望：
+- 登录成功后前端能拿到 Bearer token。
+- 当前酒店在用户可访问酒店列表中。
+- 使用无酒店权限账号访问 V4 接口时返回 `HOTEL_ACCESS_DENIED`。
+
+常见失败：
+- `AUTH_TOKEN_REQUIRED`：前端未带 Bearer token。
+- `AUTH_SESSION_INVALID`：token 过期或后端重启导致会话失效。
+- `HOTEL_ACCESS_DENIED`：用户没有目标酒店访问权，或请求 `hotel_id` 与当前账号不匹配。
+
+### 2.2 V4 工作台
+
+接口：
+
+```text
+GET /api/reservation/workbench-items?hotel_id=HOTEL-TEST&page_num=1&page_size=20
+```
+
+期望：
+- 普通 V4 业务订单任务可见。
+- S10/S99 来源通知可见。
+- 列表不返回邮件正文、附件 URL、AI 原始 payload。
+- 默认排序为最新来源消息在前；同一来源时间下按更新时间、创建时间和数字 ID 稳定倒序。
+
+常见失败：
+- 列表为空：先确认 SuperAgent 回调是否写入 V4 表，或是否只有旧 V2/V3 数据。
+- S10/S99 不可见：检查 `workflow_reservation_v4_source_notification` 是否有记录。
+
+### 2.3 V4 订单任务详情
+
+接口：
+
+```text
+GET /api/reservation/order-tasks/{orderTaskId}
+```
+
+期望：
+- 返回 `order_task`、`source_message_summary`、`source_message_card`、`basic_information_card`、`business_cards[]`、`card_counts`、`availability`。
+- Basic Information 卡在未确认前应可确认。
+- 业务卡在 Basic Information 未确认前应只读，`readonly_reason_code` 能说明原因。
+- `fields[]` 是前端展示和编辑白名单，前端不自行补字段。
+
+常见失败：
+- 详情 404：检查 `orderTaskId` 是否来自 V4 工作台，不要拿旧任务 ID 调 V4 详情。
+- 卡片无法确认：先看 `availability` 和 `readonly_reason_code`。
+
+### 2.4 Account / Room Type / Rate Code Lookup
+
+接口：
+
+```text
+GET /api/reservation/lookups/accounts?hotel_id=HOTEL-TEST&keyword=QBD
+GET /api/reservation/lookups/room-types?hotel_id=HOTEL-TEST&keyword=RM2
+GET /api/reservation/lookups/rate-codes?hotel_id=HOTEL-TEST&keyword=GROUP
+```
+
+期望：
+- 三个接口均要求 Bearer token 和 `RESERVATION_TASK_READ`。
+- 只返回当前酒店 `ACTIVE` 目录项。
+- `keyword` 查不到时 `items=[]`，但不代表目录未初始化；应结合 `catalog_source`、`catalog_version`、`warnings[]` 判断。
+- 前端确认 / 复核时只提交 `code`，不要提交显示名或目录完整对象。
+
+常见失败：
+- 查不到新增目录：确认目录状态是否为 `ACTIVE`。
+- 前端提交未知 code 后 400：以后端目录校验为准，重新选择 lookup 返回项。
+
+### 2.5 Basic Information 确认
+
+接口：
+
+```text
+POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm
+```
+
+期望：
+- 请求带当前卡片 `version`。
+- Basic Information 确认成功后卡片状态进入 `CONFIRMED`。
+- 确认后卡片锁定，不允许重复确认。
+- 业务卡的可处理性随详情刷新更新。
+
+常见失败：
+- `V4_CARD_BASIC_INFORMATION_REQUIRED`：前端先确认了业务卡，应先确认 Basic Information。
+- `V4_FIELD_VALIDATION_FAILED`：Account 不存在、Room Type / Rate Code 不在当前酒店 ACTIVE 目录。
+- 版本冲突：刷新详情后使用最新 `version`。
+
+### 2.6 业务卡确认
+
+接口：
+
+```text
+POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm
+```
+
+期望：
+- Basic Information 已确认后，普通业务卡可确认。
+- 第一版不强制所有业务卡逐张顺序确认。
+- 成功后卡片 `CONFIRMED`，写入 `confirmed_payload_json`、`confirmed_at`、`confirmed_by`。
+
+常见失败：
+- 目录字段错误：看接口 `details[]` 和卡片 `fields[].validation_errors`，按字段 pointer 修正。
+- 只读卡无法确认：检查是否是来源邮件展示卡、技术错误卡或 S10/S99 通知。
+
+### 2.7 REVIEW_REQUIRED 复核解阻
+
+接口：
+
+```text
+POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution
+```
+
+期望：
+- 只用于 `card_status=REVIEW_REQUIRED` 的 V4 卡。
+- 请求带当前卡片 `version`。
+- `field_overrides[].field_pointer` 必须来自当前卡可编辑字段。
+- 订单归属未解决时，`confirmed_order_id` 必须是当前酒店真实可见订单。
+- 成功后卡片进入 `CONFIRMED`，`review_status=RESOLVED`。
+
+常见失败：
+- `TASK_REVIEW_POINTER_INVALID` 或 V4 对应非法 pointer 错误：前端提交了只读字段、对象根节点或不存在字段。
+- `HOTEL_ACCESS_DENIED`：确认的订单或任务不属于当前用户酒店。
+- 复核后仍失败：检查修正后的 Account / Room Type / Rate Code 是否在 ACTIVE 目录中。
+
+### 2.8 S10/S99 来源通知 Ack
+
+接口：
+
+```text
+POST /api/reservation/source-notifications/{notificationId}/ack
+```
+
+期望：
+- 只用于 V4 `route_code=S10/S99` 来源通知。
+- 请求带当前通知 `version`。
+- 成功后 `notification_status=ACKED`，写 `ack_by`、`ack_at`。
+- 重复 ack 幂等返回当前状态，不新增业务任务或订单。
+
+常见失败：
+- 通知详情 404：确认从 V4 工作台拿的是来源通知 ID，不是订单任务 ID。
+- ack 按钮不显示：检查详情 `availability.ackable`。
+
+### 2.9 订单详情 V4 时间线
+
+接口：
+
+```text
+GET /api/reservation/orders/{orderId}
+```
+
+期望：
+- 返回旧 `tasks[]` 兼容字段。
+- 返回 V4 `v4_order_tasks[]` 时间线。
+- 每项包含 `order_task_id`、`order_ref`、`order_task_status`、`card_counts`、`source_message_summary`、`source_received_at`、`created_at`、`updated_at`、`latest_activity_at`。
+- S10/S99 来源通知不进入订单列表，也不进入订单详情 V4 时间线。
+
+常见失败：
+- 时间线为空：确认该 V4 订单任务是否已经绑定到当前订单。
+- 订单详情打不开：检查订单所属酒店和当前用户酒店访问权。
+
+## 3. 目录管理后台 CP1 冒烟
+
+接口：
+
+```text
+GET /api/admin/reservation/catalogs/accounts
+POST /api/admin/reservation/catalogs/accounts
+PUT /api/admin/reservation/catalogs/accounts/{accountId}/status
+
+GET /api/admin/reservation/catalogs/room-types
+POST /api/admin/reservation/catalogs/room-types
+PUT /api/admin/reservation/catalogs/room-types/{catalogId}/status
+
+GET /api/admin/reservation/catalogs/rate-codes
+POST /api/admin/reservation/catalogs/rate-codes
+PUT /api/admin/reservation/catalogs/rate-codes/{catalogId}/status
+```
+
+期望：
+- 全部接口要求 Bearer token、`RESERVATION_CATALOG_MANAGE` 和目标酒店访问权。
+- 列表支持 `hotel_id`、`keyword`、`status`、`page_num`、`page_size`。
+- 新增目录默认 `ACTIVE`，`catalog_source=SYSTEM_MANAGED`。
+- 停用后管理列表仍可按 `status=DISABLED` 查到，但普通 lookup 不再返回。
+- 启用后普通 lookup 恢复返回。
+
+常见失败：
+- `ADMIN_PERMISSION_DENIED`：角色未配置 `RESERVATION_CATALOG_MANAGE`。
+- `RESERVATION_CATALOG_CONFLICT`：当前酒店已有相同 code。
+- `RESERVATION_CATALOG_INVALID_REQUEST`：状态、JSON、必填字段或 Market / Source code 不合法。
+
+## 4. 排查 SQL
+
+```sql
+SELECT hotel_id, account_code, account_name, market_code, source_code, status, source_system, catalog_version, updated_at
+FROM workflow_reservation_catalog_account
+WHERE hotel_id = 'HOTEL-TEST'
+ORDER BY account_code;
+
+SELECT hotel_id, catalog_type, code, display_name, status, source_system, catalog_version, updated_at
+FROM workflow_reservation_catalog_code
+WHERE hotel_id = 'HOTEL-TEST'
+ORDER BY catalog_type, sort_order, code;
+
+SELECT id, hotel_id, order_ref, order_task_status, source_message_id, created_at, updated_at
+FROM workflow_reservation_v4_order_task
+WHERE hotel_id = 'HOTEL-TEST'
+ORDER BY updated_at DESC, id DESC;
+
+SELECT id, hotel_id, route_code, notification_status, source_message_id, created_at, updated_at
+FROM workflow_reservation_v4_source_notification
+WHERE hotel_id = 'HOTEL-TEST'
+ORDER BY updated_at DESC, id DESC;
+```
+
+## 5. 冒烟结论记录
+
+建议每次测试机发版后记录：
+
+| 项目 | 结果 | 备注 |
+| --- | --- | --- |
+| 登录与酒店权限 | 待测 |  |
+| V4 工作台 | 待测 |  |
+| V4 订单任务详情 | 待测 |  |
+| Account Lookup | 待测 |  |
+| Room Type Lookup | 待测 |  |
+| Rate Code Lookup | 待测 |  |
+| Basic Information 确认 | 待测 |  |
+| 业务卡确认 | 待测 |  |
+| REVIEW_REQUIRED 复核解阻 | 待测 |  |
+| S10/S99 ack | 待测 |  |
+| 订单详情 V4 时间线 | 待测 |  |
+| 目录管理 CP1 | 待测 |  |
--- a/docs/project/security-access-control-boundary.md
+++ b/docs/project/security-access-control-boundary.md
@@ -85,6 +85,7 @@
 | `/api/admin/permissions` | `FRONTEND_ADMIN` | 已强制登录和 `SYSTEM_ROLE_MANAGE` | 保持只读；前端不能自造权限码 | 不需要写审计 |
 | `/api/admin/menus/**` | `FRONTEND_ADMIN` | 已强制登录和 `SYSTEM_MENU_MANAGE`；`GET /tree`、`PUT /tree-order` 已沿用该权限 | 保持；菜单可见性不替代后端权限；批量树排序只允许修改 `parent_id` 和 `sort_order`，`sort_order` 为空时按请求顺序生成稳定排序 | 写操作必须记录管理审计，树排序审计记录调整前后的父级和排序；树查询不写审计 |
 | `/api/admin/hotels/**` | `FRONTEND_ADMIN` | 已强制登录和 `HOTEL_MANAGE` | 保持；单酒店阶段只能一家 `ACTIVE` | 写操作必须记录管理审计 |
+| `/api/admin/reservation/catalogs/**` | `FRONTEND_ADMIN` | 已实现目录管理后台 CP1；强制登录、`RESERVATION_CATALOG_MANAGE` 和目标酒店访问权 | 保持；第一版只开放 Account、Room Type、Rate Code 列表、新增、启用 / 停用；Market / Source 独立管理和真实 PMS 同步后置；停用目录不再进入普通 lookup | 新增和状态实际变化必须记录管理审计；重复提交相同状态按幂等返回，不新增审计；列表查询不写审计；不得返回 PMS 原始响应、Secret 或外部同步错误详情 |
 | `GET /api/admin/audits` | `FRONTEND_ADMIN` | 已强制登录和 `SYSTEM_ADMIN_CONSOLE_ACCESS` | 保持；不返回 Secret、密码或 token | 查询审计不再写审计 |

 ### 3.5 调试和系统接口
@@ -136,7 +137,7 @@
 | `RESERVATION_AUDIT_READ` | 查看业务审计流水 | 任务审计列表 |
 | `RESERVATION_INVOICE_GENERATE` | 生成 Reservation Proforma Invoice | Manual Invoice 生成、未来任务 / 订单预填生成 |
 | `RESERVATION_ROOMING_LIST_GENERATE` | 生成 Reservation Rooming List Excel | Rooming List 上传名单并生成 `.xlsx` 下载 |
-| `RESERVATION_CATALOG_MANAGE` | 维护 Reservation 受控目录 | 后续 Account、Market、Source、临时 Room Type / Rate Code 目录管理后台；当前尚未实现 |
+| `RESERVATION_CATALOG_MANAGE` | 维护 Reservation 受控目录 | 已用于 `/api/admin/reservation/catalogs/**`；第一版支持 Account、Room Type、Rate Code 管理，Market / Source 独立管理后置 |
 | `SOURCE_MESSAGE_READ` | 查看来源邮件安全摘要 | SourceMessage 列表、详情、会话摘要 |
 | `SOURCE_MESSAGE_ORIGINAL_READ` | 查看邮件正文、HTML 和附件外链 | original / conversation 完整正文；必须叠加 `SOURCE_MESSAGE_READ` 使用 |
 | `SYSTEM_DEBUG_EML_RUN` | 使用 Debug EML 调试链路 | Debug EML 上传、查询、stream |