实现M002 V4持久化基线

docs/project/README.md

@@ -45,8 +45,8 @@
 | `requirements/M002-order-task-workflow-v2.md` | 阶段记录 | M002 订单任务主流程 V2，记录当前已阶段实现的 AI 过渡层、S000/S999 兼容、订单任务流转、任务确认和 OPERA 模拟骨架。 |
 | `requirements/M002-order-task-workflow-v3.md` | 当前有效 | M002 订单任务主流程 V3，基于 2026-07-11 P0 冻结基线和 2026-07-12 P0.1 Parent Group 修订，记录 S10/S99、40 路由、方案 C、type-known manual review 同卡解阻和 fail-closed 边界。 |
 | `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 和校验口径；后端已完成 V4 入站解析 CP1，完整 V4 多卡主流程仍待后续实现。 |
-| `requirements/M002-v4-order-task-card-domain-model-cp2.md` | 当前有效 | M002 V4 CP2 订单任务与多卡领域模型设计，记录 SourceMessage 展示卡、来源通知模型、订单任务、Basic Information 卡、业务卡、状态、表设计草案、已确认业务决策和后续开发 checkpoint。 |
+| `requirements/M002-v4-agent-callback-field-contract.md` | 当前有效 | M002 V4 Agent 回调字段契约，基于 2026-07-18 业务基线和最新答复，冻结 `source_message`、`order_contexts`、`message_events`、订单级 Basic Information、六类 Event、S10 和校验口径；后端已完成 V4 入站解析 CP1 和 CP3 持久化基线，完整 V4 多卡主流程仍待后续实现。 |
+| `requirements/M002-v4-order-task-card-domain-model-cp2.md` | 当前有效 | M002 V4 CP2 订单任务与多卡领域模型设计，并记录 CP3 表结构、Entity、Mapper、Repository 已落地状态；后续仍需实现 V4 入站写入新模型、查询接口、卡片确认 / 复核和前端页面。 |
 | `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 模拟结果表。 |
@@ -91,6 +91,6 @@
 - 接口暴露、权限、酒店隔离和审计边界以 `security-access-control-boundary.md` 为总检查清单；具体 SuperAgent / MCP / AgentBus 请求响应契约仍以 `integrations/` 下对应文档为准。
 - AI-NSES 的通用标准以 `../import/reusable/ai-native-software-engineering-standard.md` 为复用来源；本项目采用方式以 `ai-native-adoption.md` 为准。
 - M002 V1 只作为历史参考；V2 记录当前阶段实现；后续 M002 新开发以 `requirements/M002-order-task-workflow-v3.md` 为开发基线。
-- 2026-07-18 导入的业务基线已形成 `requirements/M002-v4-agent-callback-field-contract.md` 字段契约；M002 V4 入站解析 CP1 已落地，V4 订单任务 + 多卡领域模型设计和关键业务决策见 `requirements/M002-v4-order-task-card-domain-model-cp2.md`，后续仍需实现表结构、入站落库、查询接口、卡片确认 / 复核和前端页面模型。
+- 2026-07-18 导入的业务基线已形成 `requirements/M002-v4-agent-callback-field-contract.md` 字段契约；M002 V4 入站解析 CP1 已落地，V4 订单任务 + 多卡领域模型设计和关键业务决策见 `requirements/M002-v4-order-task-card-domain-model-cp2.md`；M002 V4 CP3 已落地 V4 订单任务、任务卡、来源通知表结构和 Repository 基线，后续仍需实现入站写入新模型、查询接口、卡片确认 / 复核和前端页面模型。
 - 前端展示 / 编辑字段以 2026-07-11 P0 冻结基线中的前端字段表、0712 字段控件说明和 `requirements/M002-task-field-control-contract-v1.md` 为白名单和控件契约基线；后端完整校验和 OPERA 映射仍以任务卡完整矩阵、0711 runtime 契约和后端规则为准。
 - 时间点语义以 `backend-time-design.md` 为准；数据库时间点按 UTC 理解，API 返回带 `Z` 的 UTC 时间，页面再按酒店或用户时区展示。

docs/project/frontend-backend/backend-to-frontend-notes.md

@@ -458,6 +458,7 @@ RESERVATION_ROOMING_LIST_GENERATE
 - V4 `PAYMENT.attachment_ids[]` 不匹配、`UPDATE_BOOKING` 携带 `rate_code` 等问题会出现在任务详情同批次的 `adapter_contract_errors[]` 只读诊断块中，不展示保存、确认、执行或重试按钮。
 - 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 工作台统一列表草案为 `GET /api/reservation/workbench-items`，业务订单任务草案为 `/api/reservation/order-tasks/**`，S10 来源通知详情草案为 `GET /api/reservation/source-notifications/{notificationId}`，但当前还没有实现，不要提前接入草案路径。
+- M002 V4 CP3 已新增 V4 订单任务、任务卡、S10 来源通知三张表和 Repository 基线；这只是后端持久层准备，不代表 V4 工作台、订单任务详情、卡片确认或 S10 ack API 已经可用。前端当前仍不要调用 CP2 草案路径。
 - V4 新模型确认口径是不保存后端草稿、卡片最终确认后锁定、技术异常不进入用户可处理卡、当前不生成 OPERA 模拟操作。Basic Information 必须先确认；其它业务卡第一版不强制逐张顺序确认。现有 V3 `draft`、`confirm`、`manual-review-resolutions` 和 OPERA 模拟接口仍只代表旧链路能力，不能直接等同 V4 多卡最终接口。
 - V4 S10 后续采用来源通知模型：任务列表 / 工作台展示，进入纯通知详情页后只显示邮件展示卡和确认按钮；不再挂隐藏技术订单，不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。当前代码里旧 `SOURCE_MESSAGE_ONLY` 只读任务仍属于过渡实现。
 - M002 V3 的结构化 `S10/S99` 入站、40 条 P0.1 路由枚举 / 稳定配置、`UNHANDLED_CURRENT_INTENT`、`adapter_contract_error` transition 最小落库、任务列表 / 订单时间线 / 任务详情 V3 路由字段和只读诊断块透出、type-known manual review 同卡解阻第一版、typed infrastructure error、P0 fixtures 回归基线和 Parent Group / Cancel Allotment 路由修订均已完成。

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。