实现M002 V4持久化基线

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

@@ -478,7 +478,7 @@ M002 V4 CP2 设计文档已落地：
 
 仍需后续 checkpoint 实现：
 
-- V4 表结构和 Repository 落地，包括 V4 订单任务表、V4 任务卡表和 V4 来源通知表。
+- V4 表结构和 Repository 落地已完成第一版：新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，并提供 Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和 version 乐观锁更新基础方法。
 - V4 入站写入新模型，真正创建 SourceMessage 展示卡、Basic Information 卡和业务卡。
 - V4 查询接口、卡片确认 / 复核 / 锁定、同订单阻塞和业务审计。
 - V4 前端页面模型、任务详情字段矩阵和目录校验完全切换。

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

@@ -6,7 +6,7 @@
 | --- | --- |
 | 文档版本 | 1.4 |
 | 日期 | 2026-07-18 |
-| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线，CP2 订单任务与多卡领域模型设计及关键决策已落文档，完整 V4 多卡代码仍需后续 checkpoint |
+| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线、CP2 多卡模型设计和 CP3 持久化基线，完整 V4 多卡入站写入与接口仍需后续 checkpoint |
 | 适用范围 | 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`。该文档只代表后续开发方案，不代表表结构、接口或前端页面已经实现。
+V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP3，表结构、Entity、Mapper、Repository 基线已经实现；SuperAgent 入站写入新模型、V4 前端查询接口和卡片写操作接口仍未实现。
 
 当前已确认开发阶段数据可以清空，因此 M002 V4 后续可以按新模型重建，不要求兼容旧任务数据、旧草稿、旧 OPERA 模拟、旧 `S000/S999`、旧 Fallback 或旧 `case_keys`。
 
@@ -735,6 +735,6 @@ AI 回调包
 - V4 新数据不再保存后端草稿；用户只提交最终确认或复核解阻。
 - 卡片确认后锁定，错误修正后续通过审计和未来纠错流程表达，不覆盖原确认。
 - 技术异常只进入 AI transition / 技术运行记录，不进入用户可处理卡。
-- 后续建议新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，继续复用 SourceMessage、AI batch、AI transition、Reservation Order 和业务审计表。
+- CP3 已新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，继续复用 SourceMessage、AI batch、AI transition、Reservation Order 和业务审计表。
 
-CP2 尚未实现代码、接口、Flyway 或前端页面。后续开发应从 CP3 表结构和 Repository 开始。
+CP3 只完成表结构、Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和基础乐观锁更新。后续开发应从 CP4 入站写入新模型开始，并继续补 V4 查询接口、卡片确认 / 复核、S10 ack 和前端页面。

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

@@ -4,17 +4,19 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.1 |
+| 文档版本 | 0.2 |
 | 日期 | 2026-07-18 |
-| 状态 | CP2 设计文档，尚未写代码 |
+| 状态 | CP2 设计已确认；CP3 表结构、Entity、Mapper、Repository 基线已实现 |
 | 适用范围 | M002 V4 入站后的订单任务、多卡、状态、查询和写操作设计 |
-| 不适用范围 | Java 实现、Flyway migration、真实 PMS / OPERA / OHIP、前端页面视觉稿、历史数据迁移 |
+| 不适用范围 | V4 入站写入新模型、V4 前端查询接口、卡片确认 / 复核接口、真实 PMS / OPERA / OHIP、前端页面视觉稿、历史数据迁移 |
 
 ## 1. 文档定位
 
 M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路由适配和 AI transition 最小落库。CP1 仍然把可映射的 V4 event 临时接入 M002 V3 的订单 / 任务 / 任务卡链路。
 
-本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。本文只描述设计，不代表代码已经实现。
+本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。
+
+截至 CP3，后端已实现本文第 10、11 节中的持久化基线：新增 `workflow_reservation_v4_order_task`、`workflow_reservation_v4_task_card`、`workflow_reservation_v4_source_notification` 三张表，以及对应 Entity、Mapper、Repository 和基础测试。CP3 仍未把 SuperAgent V4 入站结果写入这些新表，也未开放 V4 前端查询或写操作接口。
 
 后续如本文与 `M002-v4-agent-callback-field-contract.md` 的字段契约冲突，以字段契约为准；如与安全边界冲突，以 `security-access-control-boundary.md` 为准。
 
@@ -266,7 +268,7 @@ V4 当前不做 OPERA / PMS 执行，但仍需要保留同订单处理顺序，
 | `workflow_reservation_order` | 继续作为本地订单投影和订单列表数据源，但需要补 V4 所需 `BOOKING_CODE` 或 locator 相关能力 |
 | `workflow_reservation_audit_log` | 继续保存卡片确认、复核、订单归属确认等业务审计 |
 
-### 10.2 建议新增表：`workflow_reservation_v4_order_task`
+### 10.2 已新增表：`workflow_reservation_v4_order_task`
 
 一条记录表示一个 `source_message_id + order_ref` 形成的 V4 订单任务。
 
@@ -277,6 +279,7 @@ V4 当前不做 OPERA / PMS 执行，但仍需要保留同订单处理顺序，
 | `source_message_id` | SourceMessage Inbox 内部 ID |
 | `ai_batch_id` | AI 回调批次 ID |
 | `order_ref` | V4 包内订单引用 |
+| `order_context_index` | `order_contexts[]` 中的一基序号，用于同一 SourceMessage 下稳定排序 |
 | `order_id` | 绑定的本地订单投影 ID |
 | `target_booking_type` | `GROUP` / `FIT` |
 | `target_locator_type` | `GROUP_CODE` / `BOOKING_CODE` / `CONFIRMATION_NUMBER` |
@@ -284,15 +287,18 @@ V4 当前不做 OPERA / PMS 执行，但仍需要保留同订单处理顺序，
 | `target_resolution_status` | `RESOLVED` / `UNRESOLVED` / `CONFLICT` |
 | `order_task_status` | 落库快照，仅保存 `OPEN` / `COMPLETED`；`BLOCKED` 由查询响应实时派生 |
 | `source_received_at` | 来源邮件接收 UTC 时间，用于排序 |
+| `version` | 乐观锁版本 |
 | `created_at` / `updated_at` | UTC 创建和更新时间 |
+| `logic_deleted_at` / `logic_deleted_reason` | 逻辑删除时间和原因，CP3 第一版只预留字段，Repository 默认排除逻辑删除记录 |
 
 建议唯一约束：
 
 ```text
-uk_v4_order_task_source_ref(hotel_id, source_message_id, order_ref)
+uk_reservation_v4_order_task_source_ref(hotel_id, source_message_id, order_ref)
+uk_reservation_v4_order_task_source_index(hotel_id, source_message_id, order_context_index)
 ```
 
-### 10.3 建议新增表：`workflow_reservation_v4_task_card`
+### 10.3 已新增表：`workflow_reservation_v4_task_card`
 
 一条记录表示 V4 订单任务下的一张卡。
 
@@ -317,11 +323,12 @@ uk_v4_order_task_source_ref(hotel_id, source_message_id, order_ref)
 | `confirmed_by` / `confirmed_at` | 确认人和确认 UTC 时间 |
 | `version` | 乐观锁版本 |
 | `created_at` / `updated_at` | UTC 创建和更新时间 |
+| `logic_deleted_at` / `logic_deleted_reason` | 逻辑删除时间和原因，CP3 第一版只预留字段，Repository 默认排除逻辑删除记录 |
 
 建议唯一约束：
 
 ```text
-uk_v4_task_card_order_task_sort(hotel_id, v4_order_task_id, card_sort_order, source_event_index)
+uk_reservation_v4_task_card_slot(hotel_id, v4_order_task_id, card_sort_order, source_event_index)
 ```
 
 约束说明：
@@ -330,7 +337,7 @@ uk_v4_task_card_order_task_sort(hotel_id, v4_order_task_id, card_sort_order, sou
 - event 业务卡使用一基 `source_event_index`。
 - 同一个订单任务下，固定卡片顺序 + `source_event_index` 必须唯一，防止入站重试或幂等异常重复创建同一张卡。
 
-### 10.4 建议新增表：`workflow_reservation_v4_source_notification`
+### 10.4 已新增表：`workflow_reservation_v4_source_notification`
 
 一条记录表示一个 S10 来源通知。它不挂订单任务、不创建订单、不进入订单列表，只用于任务列表 / 工作台和纯通知详情页。
 
@@ -348,11 +355,12 @@ uk_v4_task_card_order_task_sort(hotel_id, v4_order_task_id, card_sort_order, sou
 | `source_received_at` | 来源邮件接收 UTC 时间，用于任务列表 / 工作台排序 |
 | `version` | 乐观锁版本，用于确认按钮并发控制 |
 | `created_at` / `updated_at` | UTC 创建和更新时间 |
+| `logic_deleted_at` / `logic_deleted_reason` | 逻辑删除时间和原因，CP3 第一版只预留字段，Repository 默认排除逻辑删除记录 |
 
 建议唯一约束：
 
 ```text
-uk_v4_source_notification_message_batch(hotel_id, source_message_id, ai_batch_id)
+uk_reservation_v4_notification_message_batch(hotel_id, source_message_id, ai_batch_id)
 ```
 
 ### 10.5 暂不新增的表
@@ -370,7 +378,7 @@ uk_v4_source_notification_message_batch(hotel_id, source_message_id, ai_batch_id
 
 ### 11.1 domain
 
-建议新增：
+已新增：
 
 - `ReservationV4OrderTaskEntity`：映射 `workflow_reservation_v4_order_task`。
 - `ReservationV4TaskCardEntity`：映射 `workflow_reservation_v4_task_card`。
@@ -380,7 +388,7 @@ Entity 字段必须有中文注释，说明字段业务含义、来源和状态
 
 ### 11.2 mapper
 
-建议新增：
+已新增：
 
 - `ReservationV4OrderTaskMapper`
 - `ReservationV4TaskCardMapper`
@@ -390,22 +398,26 @@ Mapper 只放 MyBatis-Plus 基础访问和必要语义化查询。自定义方
 
 ### 11.3 repository
 
-建议新增：
+已新增：
 
 - `ReservationV4WorkflowRepository`
 - `MybatisReservationV4WorkflowRepository`
 - `ReservationV4SourceNotificationRepository`
 - `MybatisReservationV4SourceNotificationRepository`
 
-Repository 负责封装：
+CP3 Repository 已封装：
 
 - 按 SourceMessage + order_ref 幂等创建订单任务。
-- 创建 Basic Information / SourceMessage / Event 卡。
+- 按 `order_context_index` 保留同一 SourceMessage 下多个 `order_contexts[]` 的稳定顺序。
+- 创建 Basic Information / SourceMessage / Event 卡的基础插入方法；非 event 卡 `source_event_index` 固定写入 `0`。
 - 按 SourceMessage + AI batch 幂等创建 S10 来源通知。
 - 查询订单任务详情和卡片列表。
 - 查询来源通知列表和详情。
-- 卡片确认、锁定、复核解阻的乐观锁更新。
-- 来源通知确认的乐观锁更新。
+- 卡片状态的 version 乐观锁更新基础方法。
+- 来源通知状态的 version 乐观锁更新基础方法。
+- event 卡必须传入正数一基 `source_event_index`；漏传会拒绝写入，避免被误当成非 event 卡。
+
+CP3 尚未实现卡片确认、复核解阻、订单归属确认、来源通知 ack 的业务 Service 和 API；这些仍属于后续 checkpoint。
 
 Service 不直接访问 Mapper。