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

feat(reservation): solidify booking email v0.1 intake

Browse Source
This commit is contained in:
鲨鱼辣椒 committed 2026-08-08 16:02:09 +08:00
1 parent 9f29b59c26
commit d91cd717df
61 files changed
+13961 -377
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md
+15 -10
View File
@@ -6,7 +6,7 @@
| --- | --- |
| 文档版本 | 0.9 |
| 日期 | 2026-07-21 |
| 状态 | CP2 设计已确认；CP3-CP8、CP11、CP13、CP14、V4 业务审计查询、停止 V4 普通业务双写旧任务、Room Information 后端展示模型和 Payment 附件安全摘要后端第一版已实现 |
| 状态 | CP2 设计已确认；CP3-CP8、CP11、CP13、CP14、V4 业务审计查询、停止 V4 普通业务双写旧任务、Room Information 后端展示模型、BR00 辅助订单事件 companion Room 和 Payment 附件安全摘要后端第一版已实现 |
| 适用范围 | M002 V4 入站后的订单任务、多卡、状态、查询和写操作设计 |
| 不适用范围 | 真实 PMS / OPERA / OHIP、前端页面视觉稿、生产历史数据迁移 |
@@ -16,7 +16,7 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。
截至 CP14、V4 业务审计查询、停止旧任务双写、Room Information 后端展示模型、Rooming List 确认自动 DEF 后端联动和 Payment 附件安全摘要后端第一版，后端已实现本文第 10、11、12 节中的持久化和查询基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包只创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡，不再创建旧 `workflow_reservation_task`；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、订单详情 V4 订单任务时间线、V4 卡片确认接口、S10/S99 来源通知 ack 接口、V4 `REVIEW_REQUIRED` 卡复核解阻接口、V4 订单任务 / 来源通知审计查询接口、当前酒店数据库目录校验、卡片 `fields[]` 白名单、Account / Room Type / Rate Code lookup API、目录管理后台 CP1、订单列表 V4 继续处理入口字段、Room Information New / Update / Cancel 第一版业务展示模型、Rooming List 确认触发 Group Booking Status 自动置 `DEF`，以及 Payment 卡 `payment_attachments[]` 安全摘要。2026-07-21 OWNER RATE `RATECODE (2)` 只读整理已确认：Room Type 第一阶段只维护 `RM2`、`RM3`、`RM4`、`SU1`、`SU2`、`SU3` 六个稳定 code，不建 Account -> Room Type 关系；Rate Code 第一阶段暂不建立 Account 适用关系，Q.B.D / LIAN TAI 的 40 个规范化 Rate Code 作为酒店级目录候选。真实 PMS 同步继续后置，设计见 `M002-v4-real-catalog-lookup-api-design.md`。
截至 CP14、V4 业务审计查询、停止旧任务双写、Room Information 后端展示模型、Rooming List 确认无跨卡副作用和 Payment 附件安全摘要后端第一版，后端已实现本文第 10、11、12 节中的持久化和查询基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包只创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡，不再创建旧 `workflow_reservation_task`；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、订单详情 V4 订单任务时间线、V4 卡片确认接口、S10/S99 来源通知 ack 接口、V4 `REVIEW_REQUIRED` 卡复核解阻接口、V4 订单任务 / 来源通知审计查询接口、当前酒店数据库目录校验、卡片 `fields[]` 白名单、Account / Room Type / Rate Code lookup API、目录管理后台 CP1、订单列表 V4 继续处理入口字段、Room Information New / Update / Cancel 第一版业务展示模型、Rooming List 确认不修改 Group Booking Status，以及 Payment 卡 `payment_attachments[]` 安全摘要。2026-07-21 OWNER RATE `RATECODE (2)` 只读整理已确认：Room Type 第一阶段只维护 `RM2`、`RM3`、`RM4`、`SU1`、`SU2`、`SU3` 六个稳定 code，不建 Account -> Room Type 关系；Rate Code 第一阶段暂不建立 Account 适用关系，Q.B.D / LIAN TAI 的 40 个规范化 Rate Code 作为酒店级目录候选。真实 PMS 同步继续后置，设计见 `M002-v4-real-catalog-lookup-api-design.md`。
2026-07-22 后，MCP `th_hotel_submit_task_results` 也已与本文模型对齐：MCP submit 只接受 M002 V4 包级结构，旧 V2/V3 submit payload 返回 `MCP_SUBMIT_V4_REQUIRED`，不会绕回旧 `workflow_reservation_task` 模型。
@@ -59,7 +59,8 @@ order_contexts[]
message_events[]
-> 每个 event 按 order_ref 挂到对应订单任务
-> 每个 event 创建 1 张业务任务卡
-> 每个 event 创建 1 张原生业务任务卡
-> 仅含 Trace / Rooming List / Payment 时，订单任务额外创建 1 张共享 companion Room
target_order
-> 用于订单任务绑定本地订单投影
@@ -91,7 +92,7 @@ V4 package / event contract error
| `SOURCE_MESSAGE_DISPLAY` | `source_message` | 否 | 否 | 普通业务包内固定展示当前邮件和附件入口 |
| `SOURCE_MESSAGE_NOTIFICATION` | `route_code=S10` | 是，仅确认已读 | 否 | 纯通知邮件，只需要用户确认已读 / 已处理 |
| `BASIC_INFORMATION` | `order_contexts[].basic_information` | 是 | 是 | 订单级 Account / Market / Source 卡，第一版 Agent 只给 `account_code` |
| `ROOM_INFORMATION` | `NEW_BOOKING` / `UPDATE_BOOKING` / `CANCEL_BOOKING` | 是 | 是 | 房型信息卡，卡内按 New / Update / Cancel 展示最终值、差异和系统派生字段 |
| `ROOM_INFORMATION` | `NEW_BOOKING` / `UPDATE_BOOKING` / `CANCEL_BOOKING`；或仅含辅助订单事件时的 companion Room | 是 | 是 | 房型信息卡；生命周期事件展示最终值/差异，Trace / Rooming List / Payment companion Room 展示同订单 current-only 上下文 |
| `TRACE_RESERVATION_NOTES` | `TRACE_RESERVATION_NOTES` | 是 | 是 | Trace 卡，卡内可有普通备注和加床备注多条事项 |
| `ROOMING_LIST` | `ROOMING_LIST` | 是 | 否 | 第一版只做事项确认；不在 Agent 回调里保存名单 rows，不生成 Excel，不导入 PMS |
| `PAYMENT` | `PAYMENT` | 是 | 第一版主要确认附件关联 | 付款凭证卡；业务事实仍是 `attachment_ids[]` 引用包级附件，展示层可返回匹配后的附件安全摘要 |
@@ -102,6 +103,7 @@ V4 package / event contract error
- 来源邮件展示卡不是 event，普通业务包内只读，不参与订单执行阻塞。
- S10/S99 采用来源通知模型：任务列表 / 工作台可见，点击进入纯通知详情页；只显示邮件展示卡和确认按钮，不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
- 同一 `order_ref` 下如果有多个相同 `event_type`，第一版按 event 数组项分别建卡；页面排序按固定卡片顺序，再按 `source_event_index` 排序。
- 同一订单任务已有 `NEW_BOOKING`、`UPDATE_BOOKING` 或 `CANCEL_BOOKING` 的 Room 时，不再为 Trace / Rooming List / Payment 复制 Room；若订单任务只含这三类辅助事件，则按接收顺序用首个事件生成一张共享 companion Room，并保留原始 `event_type`、transition 与 `source_event_index`。
## 6. 状态设计
@@ -633,7 +635,8 @@ V4 任务详情页的 `SOURCE_MESSAGE_DISPLAY` 固定展示在 Basic Information
Room Information 卡展示模型：
- `ROOM_INFORMATION` 卡只由 `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING` 三类 event 触发；`TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT` 不触发房型信息卡。
- `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING` 各自生成生命周期 Room；仅含 `TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT` 的订单任务额外生成一张共享 companion Room，因此六类可定位订单事项都有 Basic + Room 双区块。
- auxiliary companion Room 保留原辅助 `event_type`，但不把辅助 payload 解释成房间变更：`current_values` 与 `final_values` 取同订单已确认投影，`proposed_values={}`、`change_summary=[]`。Trace / Rooming List / Payment 原生卡、确认动作和副作用保持独立。
- SuperAgent 仍只输出字段契约中的业务字段。Nights、Breakfast、Group Booking Status、Block ID、Confirmation Number 和 Adult 不由 SuperAgent 输出；其中 Adult 第一版不在卡内展示。
- 后端已在 `GET /api/reservation/order-tasks/{orderTaskId}` 的 Room Information 业务卡 `display_payload.room_information` 中补稳定展示模型，结构为 `event_type`、`booking_type`、`current_values`、`proposed_values`、`final_values`、`change_summary[]`、`group_booking_status_options[]`。前端按该展示模型渲染业务 UI，不再从 Agent raw payload / `target_order` 自行推导；如果存量或调试数据里已经持久化为稳定 `room_information.final_values` 模型，后端会按该稳定模型归一化展示和复核，不再回退到 Agent raw 推导。`fields[]` 继续作为确认 / 复核的可编辑字段白名单。`fields[].write_target` 对前端只表达请求体目标，例如 `confirmed_payload` 或 `review_resolution.field_overrides`，不暴露后端内部列名。
- `fields[]` 的 Room Information 主路径统一为 `/room_information/final_values/...`，例如 `/room_information/final_values/arrival_date`、`/room_information/final_values/room_items/0/room_type_code`。确认接口收到该结构时，后端会从展示模型派生 `confirmed_payload_json.room_information.final_values`，并重新计算 `nights`、`breakfast_included` 和 `group_booking_status_label`；只读字段、Agent `target_order`、Adult 和前端注入字段不会写入确认快照。`REVIEW_REQUIRED` 状态下，当前卡白名单内业务字段可以返回 `editable=true` 并允许同一 pointer 走 `review-resolution`，不再限定只能修空值、`missing_fields[]` 或目录错误字段。
@@ -642,8 +645,8 @@ Room Information 卡展示模型：
- `CANCEL_BOOKING`：不使用 Agent 输出当前订单快照；后端从本地订单投影读取当前值并只读展示，用户只确认整单取消。Cancel 卡不允许编辑 Group Booking Status、Breakfast、日期、Rate Code 或房型房量。
- `nights` 由后端按酒店本地业务日期计算：`departure_date - arrival_date`，不涉及时区和 UTC；日期缺失、非法或离店早于入住时，`nights` 为空。第一版确认校验要求日期必填，后续如需更严格营业日规则另开 checkpoint。
- `breakfast_included` 是卡片展示和确认使用的布尔字段。Group 固定含早，前端显示勾选且只读；Fit 按 Rate Code 派生，Rate Code 包含 `RB` 时含早，包含 `RO` 时不含早；如果 Rate Code 无法派生，前端显示必填勾选框，由用户确认是否含早。
- Group Booking Status 仅 Group 显示，稳定 code 为 `TEN`、`DEF`、`INQ`，前端显示 `TEN-Tentative`、`DEF-Definite`、`INQ-Inquiry`。New Group 默认 `TEN`；`booking_scenario=STANDARD | PROPOSAL` 仅保留为 Agent 场景参考，不映射 Group Booking Status。`NEW_BOOKING` / `UPDATE_BOOKING` 确认前可手动改选，`CANCEL_BOOKING` 只读。
- `ROOMING_LIST` 卡确认时，如果同订单为 Group，后端已把 Group Booking Status 自动置为 `DEF`，即使此前为 `TEN` 或 `INQ`；该自动变更写入 `V4_ROOMING_LIST_AUTO_DEF` 业务审计，并且刷新任务详情时 Room Information 的 `display_payload.room_information.final_values`、`confirmed_payload.room_information.final_values` 都以后端 DEF 后的确认快照为准。当前订单详情 `order_overview` 不返回 Group Booking Status 字段，仍只展示既有确认快照字段。Fit 不显示也不变更 Group Booking Status。
- Group Booking Status 仅 Group 显示，稳定 code 为 `TEN`、`DEF`、`INQ`，前端显示 `TEN-Tentative`、`DEF-Definite`、`INQ-Inquiry`。New Group 默认 `TEN`；`booking_scenario=STANDARD | PROPOSAL` 仅保留为 Agent 场景参考，不映射 Group Booking Status。`NEW_BOOKING` / `UPDATE_BOOKING` 与三类 auxiliary companion Room 确认前可手动改选，`CANCEL_BOOKING` 只读。
- `ROOMING_LIST` 卡确认只更新当前事项卡和订单任务派生状态；无论 Group 或 Fit，均不修改同订单 Room Information、Group Booking Status、订单快照或其他业务卡。当前订单详情 `order_overview` 继续只展示既有确认快照字段。
- `target_order.locator_value` 不作为前端可编辑字段，也不在普通任务详情的 Basic Information 或普通业务卡 `display_payload` / `confirmed_payload` 中返回；订单归属错误时通过 V4 复核选择正确订单或创建正确订单投影，不直接改写 Agent 原始 `target_order.locator_value`。但 New Booking 创建 / 确认的最终订单投影字段允许编辑：Group 显示并允许编辑 `group_block_name`，默认值来自 Agent `target_order.locator_value` 且 `locator_type=GROUP_CODE`；Fit 显示并允许编辑 `fit_name`，默认值来自 `guest_name ?? target_order.locator_value`。用户修改这些字段只影响本系统最终订单投影和确认快照，不回写 Agent 原始定位字段。普通业务卡还会移除邮件 HTML、raw evidence、附件原始 URL 和 PMS 原始响应等敏感字段。
- Block ID 和 Confirmation Number 第一版只读；存在本地投影或未来 PMS 结果时展示，否则为空。Block ID 仅 Group 显示，Confirmation Number 仅 Fit 显示。
@@ -655,8 +658,9 @@ V4 任务详情页第一版字段白名单：
| `ROOM_INFORMATION` / `NEW_BOOKING` | `group_block_name` 或 `fit_name`、`arrival_date`、`departure_date`、`rate_code`、`room_items[].room_type_code`、`room_items[].room_count`、Group 的 `group_booking_status`、无法从 Fit Rate Code 派生时的 `breakfast_included` | `nights`、Group 固定 `breakfast_included=true`、Fit 可由 Rate Code 派生的 `breakfast_included`、Adult、Block ID、Confirmation Number、Agent 原始 `target_order` |
| `ROOM_INFORMATION` / `UPDATE_BOOKING` | 修改后的 `arrival_date`、`departure_date`、`room_items[].room_type_code`、`room_items[].room_count`、Group 的 `group_booking_status`、无法从 Fit Rate Code 派生时的 `breakfast_included` | 当前值、本次变化摘要、`nights` 差异、Rate Code、Adult、Block ID、Confirmation Number、Agent 原始 `target_order` |
| `ROOM_INFORMATION` / `CANCEL_BOOKING` | 无；用户只确认取消事项 | 本地订单投影当前值、`nights`、`breakfast_included`、Group Booking Status、Rate Code、房型房量、Block ID、Confirmation Number |
| `ROOM_INFORMATION` / `TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT` | `names_text`、Group 的 `group_code` / `group_name`、`arrival_date`、`departure_date`、`room_items[].room_type_code`、`room_items[].room_count`、Group 的 `group_booking_status`、无法从 Fit Rate Code 派生时的 `breakfast_included` | 同订单 current-only 上下文、`proposed_values={}`、`change_summary=[]`、`nights`、Rate Code、Adult、Block ID、Confirmation Number、Agent 原始 `target_order`；Rate Code 沿用现有仅 New 可写策略 |
| `TRACE_RESERVATION_NOTES` | GENERAL：`trace_items[].text`、`trace_items[].department_code`；EXTRA_BED：`trace_items[].target_room_type_code`、`trace_items[].extra_bed_room_count`、`trace_items[].department_code` | `department_code` 第一版只允许 `FO`、`HSK`、`FO+HSK`，字段返回 `fixed_options[]` 三个固定选项，不允许自由文本；`target_room_type_code` 校验当前酒店 Room Type 目录；`extra_bed_room_count` 必须为正整数；不返回或确认 `content`、`target_order`、邮件正文、附件 URL、raw evidence 或 AI 原始 payload |
| `ROOMING_LIST` | 无；用户只确认 Rooming List 事项 | 来源邮件正文和附件摘要通过底部 `SOURCE_MESSAGE_DISPLAY` 查看；确认后 Group 自动置为 `DEF` |
| `ROOMING_LIST` | 无；用户只确认 Rooming List 事项 | 来源邮件正文和附件摘要通过底部 `SOURCE_MESSAGE_DISPLAY` 查看；确认不改变其他业务事实 |
| `PAYMENT` | 无；用户只确认附件关联事项 | `attachment_ids[]`、`payment_attachments[]` 安全摘要、图片缩略图、文件名、类型、大小、预览 / 下载可用性 |
| `SOURCE_MESSAGE_DISPLAY` | 无 | 当前触发该 V4 order task 的 SourceMessage 正文，只读且默认长度折叠，可展开全文 |
@@ -665,7 +669,7 @@ Rooming List 卡事项确认规则：
- Rooming List 卡第一版只做事项确认，不做名单解析、附件预览、Excel 生成或 PMS 导入。
- `ROOMING_LIST` event 不输出 `rows[]`、逐人名单、同住分组、18 列、Excel 或 PMS 导入参数，也不要求单独输出 `attachment_ids[]`。
- 页面应展示卡片标题、状态、目标订单信息和“确认卡片”按钮；如需查看来源内容，仍通过本订单任务底部的 `SOURCE_MESSAGE_DISPLAY` 查看当前触发 SourceMessage 正文和附件摘要。
- 用户点击“确认卡片”表示已人工处理该 Rooming List 事项；该确认会更新 V4 卡片状态和订单任务派生状态；如果同订单为 Group 且存在可更新的已确认 Room Information 快照，后端同时覆盖该快照里的 `group_booking_status=DEF` 和 `group_booking_status_label=DEF-Definite`，不改变 Agent 原始 payload，并写入可通过 V4 订单任务审计接口查询的 `V4_ROOMING_LIST_AUTO_DEF` 摘要。没有可更新投影时确认仍成功，只记录安全审计提示，不临时创建不完整 Room Information。该动作不代表 M010 Rooming List Excel 已生成，也不代表 PMS / OPERA / OHIP 已执行。
- 用户点击“确认卡片”表示已人工处理该 Rooming List 事项；该确认只更新当前 V4 卡片状态和订单任务派生状态，不改变 Agent 原始 payload、Room Information 确认快照、Group Booking Status 或其他订单事实。该动作不代表 M010 Rooming List Excel 已生成，也不代表 PMS / OPERA / OHIP 已执行。
- 独立 Rooming List Excel 生成能力仍属于 M010 `/reservation/rooming-lists/new` 工具页面，第一版不嵌入 V4 Rooming List 卡。
Payment 卡附件展示规则：
@@ -941,8 +945,9 @@ AI 原始 payload、邮件正文、附件 URL 和技术 trace 不应直接进入
| M002-V4-CP14.6 | Payment 附件预览 | 已完成前后端第一版：Payment 卡返回付款凭证附件安全摘要，不返回 URL；前端通过 SourceMessage 原文权限链路做图片缩略图 / 大图预览和非图片下载 |
| M002-V4-CP14.7 | Rooming List 事项确认卡 | 已完成前端轻量展示：Rooming List 卡第一版只展示事项和确认按钮，不解析名单、不预览附件、不生成 Excel、不导入 PMS |
| M002-V4-CP14.8 | Room Information 展示模型 | 已完成前后端第一版：后端返回 `display_payload.room_information` 稳定展示模型；前端按 New / Update / Cancel 业务表单展示最终值、差异、Nights、Breakfast、Group Booking Status 和本地订单投影；Adult 不显示 |
| M002-V4-CP14.9 | Rooming List 确认自动 DEF | 已完成后端第一版：确认 `ROOMING_LIST` 卡时，Group 同订单存在可更新 Room Information 确认快照则自动置 `DEF` 并写审计；Fit 不变更；无投影不造脏数据 |
| M002-V4-CP14.9 | Rooming List 确认无跨卡副作用 | 2026-08-08 已纠偏：确认 `ROOMING_LIST` 只更新本卡和订单任务派生状态；Group/Fit 均不改 Group Booking Status、Room Information 确认快照或其他业务卡。 |
| M002-V4-CP14.10 | 复核态卡片字段白名单和统一确认交互 | 已完成前端第一版：`REVIEW_REQUIRED` 保持原业务卡内编辑，问题字段红字提示，前端按钮显示“确认卡片”但调用 `review-resolution`；后端 `fields[]` 返回当前卡业务字段白名单，复核写入不再只限空值或目录错误字段 |
| M002-V4-CP14.11 | BR00 辅助订单事件双区块 | 已完成前后端：独立 Trace / Rooming List / Payment 订单任务各补一张共享 companion Room；同组已有生命周期 Room 时去重；详情与确认使用 current-only 模型，原生辅助卡行为不变 |
| M002-V4-CP15 | V4 业务审计查询 | 已完成：`GET /api/reservation/order-tasks/{orderTaskId}/audits` 和 `GET /api/reservation/source-notifications/{notificationId}/audits` 返回卡片确认、复核解阻和来源通知 ack 的脱敏审计流水 |
| M002-V4-CP15.1 | 订单详情 V4 化后端补齐 | 已完成：`GET /api/reservation/orders/{orderId}` 返回 `order_overview`、`next_v4_action`、`related_source_messages[]` 和 `v4_order_tasks[].cards[]`，支撑订单总览页 |
| M002-V4-CP16 | PMS / OPERA / OHIP 目录同步 | 同步 Adapter、同步 run、最后成功快照、失败重试和同步状态管理入口 |