huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5b4257b125421c098d1bfcd0a70eeb8f1e12dbfd
th-hotel-simple/docs/project/requirements/M002-v4-test-machine-smoke-checklist.md
andy f2c2616ab0 实现V4目录管理后台CP1后端
2026-07-19 17:56:08 +07:00

9.8 KiB
Raw Blame History

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 工作台

接口：

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 订单任务详情

接口：

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

接口：

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 确认

接口：

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 业务卡确认

接口：

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 复核解阻

接口：

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

接口：

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 时间线

接口：

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 冒烟

接口：

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

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 待测