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

实现 V4 卡片确认和来源通知确认

Browse Source
This commit is contained in:
andy
2026-07-19 10:40:23 +07:00
parent 9404a0e5c1
commit fdb16cc4c1
19 changed files with 1190 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/project/requirements/M002-order-task-workflow-v3.md
View File

@@ -477,12 +477,12 @@ M002 V4 CP2 设计文档已落地：
- 文档路径：`docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md`。
- 设计内容：SourceMessage 邮件展示卡、S10/S99 来源通知、`source_message_id + order_ref` 订单任务、Basic Information 独立卡、每个 V4 event 的业务卡、卡片确认 / 复核 / 锁定、同订单阻塞、表结构草案和后续接口草案。
- 已确认：V4 工作台统一列表新开 `/api/reservation/workbench-items`，业务订单任务新开 `/api/reservation/order-tasks/**`，S10/S99 来源通知使用 `/api/reservation/source-notifications/**`；S10/S99 采用来源通知模型；`FIT + BOOKING_CODE` 不建 ACTIVE 唯一约束，匹配多条进人工复核；Basic Information 必须先确认，其它业务卡第一版不强制逐张确认；Account / Market / Source 目录第一版使用后端固定种子数据。
- 当前状态：CP3 表结构 / Repository、CP4 入站写入新模型和 CP5 查询接口已完成；V4 卡片确认 / 复核、S10/S99 ack 和前端页面仍未实现。
- 当前状态：CP3 表结构 / Repository、CP4 入站写入新模型、CP5 查询接口和 CP6 普通卡片确认 / S10/S99 ack 已完成；V4 复核接口和前端页面仍未实现。
仍需后续 checkpoint 实现：
- V4 表结构和 Repository 落地已完成第一版：新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，并提供 Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和 version 乐观锁更新基础方法。
- V4 入站写入新模型已完成第一版：真正创建 SourceMessage 展示卡、Basic Information 卡、业务卡和 S10/S99 来源通知。
- V4 卡片确认 / 复核 / 锁定、S10/S99 ack、同订单阻塞写侧校验和业务审计。
- V4 复核解阻、复核场景订单归属确认和前端页面模型切换。
- V4 前端页面模型、任务详情字段矩阵和目录校验完全切换。
- 真实 OPERA / OHIP、普通任务任意切换订单、字段矩阵从当前扁平结构整体迁移到 0711 P0 新结构、历史旧 Parent Cancel Booking payload 批量迁移。

12
docs/project/requirements/M002-v4-agent-callback-field-contract.md
View File

@@ -6,7 +6,7 @@
| --- | --- |
| 文档版本 | 1.5 |
| 日期 | 2026-07-19 |
| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线、CP2 多卡模型设计、CP3 持久化基线、CP4 入站写入新模型和 CP5 查询接口，V4 写接口仍需后续 checkpoint |
| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线、CP2 多卡模型设计、CP3 持久化基线、CP4 入站写入新模型、CP5 查询接口和 CP6 普通卡片确认 / S10/S99 ack |
| 适用范围 | 0718 业务基线下，Agent → Adapter / MCP → 信息系统的业务回调字段 |
| 不适用范围 | 数据库表设计、前端视觉细节、真实 PMS API、技术失败后台重试、旧 M002 V3 数据兼容 |
@@ -16,7 +16,7 @@
本契约用于后续 M002 V4 主流程设计、后端领域建模、前端页面模型、Adapter / MCP Schema 对齐和 SuperAgent 联调。当前后端已按本文完成 V4 入站解析基线：能识别 V4 包、校验关键契约、保存 AI transition / 任务卡原始 payload，并把可映射的六类 event 先接入现有订单任务链路。
V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP5，表结构、Entity、Mapper、Repository 基线已经实现，SuperAgent V4 入站已经能写入 V4 订单任务、来源邮件展示卡、Basic Information 卡、业务卡和 S10/S99 来源通知；V4 工作台、订单任务列表 / 详情和来源通知详情查询接口已实现，卡片确认、复核和来源通知 ack 写接口仍未实现。
V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP6，表结构、Entity、Mapper、Repository 基线已经实现，SuperAgent V4 入站已经能写入 V4 订单任务、来源邮件展示卡、Basic Information 卡、业务卡和 S10/S99 来源通知；V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、普通卡片确认和 S10/S99 ack 写接口已实现，V4 复核写接口仍未实现。
当前已确认开发阶段数据可以清空，因此 M002 V4 后续可以按新模型重建，不要求兼容旧任务数据、旧草稿、旧 OPERA 模拟、旧 `S000/S999`、旧 Fallback 或旧 `case_keys`。
@@ -723,18 +723,20 @@ AI 回调包
- 合法 V4 event 按 `event_type` 创建 `ROOM_INFORMATION`、`TRACE_RESERVATION_NOTES`、`ROOMING_LIST` 或 `PAYMENT` 业务卡；event 契约错误只落 AI transition。
- V4 S10/S99 写入 `workflow_reservation_v4_source_notification`，状态为 `ACK_REQUIRED`。
当前 CP5 已完成：
当前 CP5 / CP6 已完成：
- `GET /api/reservation/workbench-items` 查询 V4 工作台统一列表，混排 V4 业务订单任务和 S10/S99 来源通知。
- `GET /api/reservation/order-tasks` 查询 V4 业务订单任务列表，不包含 S10/S99 来源通知。
- `GET /api/reservation/order-tasks/{orderTaskId}` 查询 V4 订单任务详情，按来源邮件展示卡、Basic Information 卡和业务卡拆分。
- `GET /api/reservation/source-notifications/{notificationId}` 查询 V4 S10/S99 来源通知详情。
- CP5 查询接口强制 Bearer 登录、`RESERVATION_TASK_READ` 和酒店访问权；不返回邮件正文、附件 URL、`ai_payload_json` 或来源通知原始 payload。
- `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm` 确认 V4 卡片，强制 Bearer 登录、`RESERVATION_TASK_CONFIRM`、酒店访问权和 version 并发校验。
- `POST /api/reservation/source-notifications/{notificationId}/ack` 确认 V4 S10/S99 来源通知已读 / 已处理，强制 Bearer 登录、`RESERVATION_TASK_CONFIRM`、酒店访问权和 version 并发校验。
当前仍未完成：
- 普通 V4 业务包暂时仍保留旧 V3 任务状态、草稿和 OPERA 模拟骨架兼容，便于前端过渡；V4 写接口和前端页面完成后再逐步废弃旧链路。
- V4 卡片确认、复核解阻和 S10/S99 来源通知 ack 写接口。
- V4 复核解阻写接口。
- 尚未接入真实 PMS / OPERA / OHIP。
- 尚未改造前端 V4 页面模型。
@@ -754,4 +756,4 @@ AI 回调包
- 技术异常只进入 AI transition / 技术运行记录，不进入用户可处理卡。
- CP3 已新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，继续复用 SourceMessage、AI batch、AI transition、Reservation Order 和业务审计表。
CP3 只完成表结构、Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和基础乐观锁更新。CP4 已把 V4 回调写入新模型。CP5 已开放查询接口。后续开发应继续补卡片确认 / 复核、S10/S99 ack 和前端页面。
CP3 只完成表结构、Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和基础乐观锁更新。CP4 已把 V4 回调写入新模型，CP5 已开放查询接口，CP6 已开放普通卡片确认和 S10/S99 ack。后续开发应继续补 V4 复核和前端页面。

29
docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md
View File

@@ -4,11 +4,11 @@
| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.3 |
| 文档版本 | 0.4 |
| 日期 | 2026-07-19 |
| 状态 | CP2 设计已确认；CP3 表结构、Entity、Mapper、Repository 基线已实现；CP4 入站写入新模型已实现；CP5 查询接口已实现 |
| 状态 | CP2 设计已确认；CP3 表结构、Entity、Mapper、Repository 基线已实现；CP4 入站写入新模型已实现；CP5 查询接口已实现；CP6 卡片确认和 S10/S99 ack 已实现 |
| 适用范围 | M002 V4 入站后的订单任务、多卡、状态、查询和写操作设计 |
| 不适用范围 | 卡片确认 / 复核接口、S10/S99 ack 接口、真实 PMS / OPERA / OHIP、前端页面视觉稿、历史数据迁移 |
| 不适用范围 | V4 复核接口、真实 PMS / OPERA / OHIP、前端页面视觉稿、历史数据迁移 |
## 1. 文档定位
@@ -16,7 +16,7 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。
截至 CP5，后端已实现本文第 10、11 节中的持久化基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情和来源通知详情查询接口；V4 卡片确认、复核和来源通知 ack 写接口仍未开放。
截至 CP6，后端已实现本文第 10、11 节中的持久化基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、V4 卡片确认接口和 S10/S99 来源通知 ack 接口；V4 复核写接口仍未开放。
后续如本文与 `M002-v4-agent-callback-field-contract.md` 的字段契约冲突，以字段契约为准；如与安全边界冲突，以 `security-access-control-boundary.md` 为准。
@@ -26,7 +26,7 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
| --- | --- | --- |
| 入站识别 | 已识别 `route_code`、`source_message`、`order_contexts[]`、`message_events[]` | CP4 已把有合法 event 的 `order_ref` 建成订单任务聚合；CP5 已开放 V4 安全查询接口 |
| SourceMessage | 已按 `source_message.source_message_id` 反查 SourceMessage Inbox | CP4 已固定生成普通业务包内邮件展示卡；邮件正文完整读取仍走 SourceMessage 会话接口 |
| Basic Information | 已写入 V4 Basic Information 独立卡 | 目录校验、确认 / 复核写接口仍待 CP6 / CP7 |
| Basic Information | 已写入 V4 Basic Information 独立卡 | CP6 已支持确认并锁定；目录校验和复核写接口仍待后续 checkpoint |
| 业务 Event | 可映射 event 临时创建旧 `workflow_reservation_task`，并已额外创建 V4 业务卡 | 旧任务链路仍作前端过渡兼容，后续 V4 查询和写接口完成后再逐步废弃 |
| 技术错误 | 已落 `adapter_contract_error` transition | 已符合目标方向：不创建用户可处理卡 |
| 草稿 / READY / OPERA | 仍复用 V3 草稿、READY 和 OPERA 模拟骨架 | V4 新数据确认口径是不保存草稿、确认后锁定、当前不生成 OPERA |
@@ -417,7 +417,7 @@ CP3 Repository 已封装：
- 来源通知状态的 version 乐观锁更新基础方法。
- event 卡必须传入正数一基 `source_event_index`；漏传会拒绝写入，避免被误当成非 event 卡。
CP5 尚未实现卡片确认、复核解阻、订单归属确认、来源通知 ack 的业务 Service 和 API；这些仍属于后续 checkpoint。
CP6 已实现普通卡片确认和 S10/S99 来源通知 ack 的业务 Service 和 API；V4 复核解阻、复核场景订单归属确认仍属于后续 checkpoint。
Service 不直接访问 Mapper。
@@ -427,10 +427,10 @@ Service 不直接访问 Mapper。
- `ReservationV4TaskIntakeService`：已实现，V4 入站从 AI transition 落 V4 订单任务、卡片和 S10/S99 来源通知。
- `ReservationV4OrderTaskQueryService`：前端查询订单任务列表和详情。
- `ReservationV4TaskCardCommandService`：处理卡片确认、复核和订单归属确认。
- `ReservationV4SourceNotificationService`：处理 S10/S99 来源通知查询和确认。
- `ReservationV4CommandService`：已实现卡片确认和 S10/S99 来源通知确认；后续继续承接 V4 复核和订单归属确认。
- `ReservationV4SourceNotificationService`：来源通知查询已并入 V4 查询服务，确认已并入 V4 命令服务。
当前 `ReservationAiTaskIntakeServiceImpl` 已在 V4 分支调用 `ReservationV4TaskIntakeService` 完成新模型写入；后续查询、确认和复核仍应继续拆到独立 V4 service，避免主入站类继续膨胀。
当前 `ReservationAiTaskIntakeServiceImpl` 已在 V4 分支调用 `ReservationV4TaskIntakeService` 完成新模型写入；查询和确认已拆到独立 V4 service，后续复核仍应继续留在 V4 命令侧，避免主入站类继续膨胀。
## 12. 前端查询接口
@@ -578,7 +578,7 @@ GET /api/reservation/orders/{orderId}/order-tasks
用于订单详情页展示 V4 订单任务时间线。旧 `GET /api/reservation/orders/{orderId}` 可以在过渡期继续返回 V3 `tasks[]`。
## 13. 前端写操作接口草案
## 13. 前端写操作接口
### 13.1 确认卡片
@@ -590,10 +590,14 @@ POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm
请求要点：
- 只提交当前卡允许编辑的字段。
- 请求 JSON 必须携带 `version`；`confirmed_payload` 可选，未传时后端使用当前展示 payload 作为确认快照。
- 只提交当前卡允许编辑的字段或当前卡确认快照。
- 不提交草稿。
- 必须带 `version` 做并发校验。
- 后端确认后卡片 `CONFIRMED` 并锁定。
- 返回刷新后的 `GET /api/reservation/order-tasks/{orderTaskId}` 详情结构。
- Basic Information 必须先确认；业务卡第一版不强制逐张顺序确认。
- `SOURCE_MESSAGE_DISPLAY`、`CONFIRMED`、`REVIEW_REQUIRED` 卡不能通过该接口确认。
### 13.2 复核并确认卡片
@@ -625,6 +629,7 @@ S10/S99 已确认采用来源通知模型，不继续复用隐藏技术订单或
- 必须带 `version` 做并发校验。
- 确认后 `notification_status=ACKED`，写确认人和 UTC 确认时间。
- 重复提交已确认通知应返回幂等成功或明确的已确认状态，不允许回退到 `ACK_REQUIRED`。
- 返回刷新后的 `GET /api/reservation/source-notifications/{notificationId}` 详情结构。
## 14. 旧 V3 / V2 兼容和废弃边界
@@ -681,7 +686,7 @@ AI 原始 payload、邮件正文、附件 URL 和技术 trace 不应直接进入
| M002-V4-CP3 | V4 表结构和基础 Repository | 新增 V4 order task / card / source notification 表、Entity、Mapper、Repository、测试 |
| M002-V4-CP4 | V4 入站落新模型 | 已完成：SuperAgent V4 回调创建订单任务、Basic Information 卡、业务卡、邮件展示卡和 S10/S99 来源通知 |
| M002-V4-CP5 | V4 查询接口 | 已完成：工作台统一列表、订单任务列表、订单任务详情和来源通知详情查询接口；订单详情 V4 专属时间线后续再做 |
| M002-V4-CP6 | V4 卡片确认和复核 | 不保存草稿，支持确认、复核、锁定、审计、阻塞规则和 S10/S99 来源通知确认 |
| M002-V4-CP6 | V4 卡片确认和 S10/S99 ack | 已完成：不保存草稿，支持普通卡片确认、确认后锁定、Basic Information 前置约束、同订单前置任务写侧阻塞、业务审计、version 并发校验和 S10/S99 来源通知确认；V4 复核接口后置 |
| M002-V4-CP7 | 受控目录第一版 | Account、RoomType、RateCode、Department 固定目录或版本化快照校验 |
| M002-V4-CP8 | V4 前端契约收口 | 字段、控件、availability、错误展示和旧任务入口切换 |
| M002-V4-CP9 | 旧 V3 / V2 能力收口评估 | 明确哪些兼容入口可以关闭，哪些仍保留只读历史 |