实现 V4 复核解阻接口

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

@@ -16,7 +16,7 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
 
 本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。
 
-截至 CP6，后端已实现本文第 10、11 节中的持久化基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、V4 卡片确认接口和 S10/S99 来源通知 ack 接口；V4 复核写接口仍未开放。
+截至 CP7，后端已实现本文第 10、11 节中的持久化基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、V4 卡片确认接口、S10/S99 来源通知 ack 接口，以及 V4 `REVIEW_REQUIRED` 卡复核解阻接口。
 
 后续如本文与 `M002-v4-agent-callback-field-contract.md` 的字段契约冲突，以字段契约为准；如与安全边界冲突，以 `security-access-control-boundary.md` 为准。
 
@@ -171,8 +171,12 @@ V4 新数据不再提供后端草稿保存。前端可以在页面本地维护
 
 - 不改写 AI 原始 payload。
 - 用户修正写入 `review_resolution_json` 和 `confirmed_payload_json`。
-- 目录值必须来自信息系统受控目录。
+- CP7 第一版只校验 JSON Pointer 是否指向当前卡允许编辑字段；目录值必须来自信息系统受控目录的校验放到受控目录 checkpoint。
 - 通过校验后卡片直接进入 `CONFIRMED`，不再进入 V3 `READY` 状态。
+- `field_overrides[].field_pointer` 必须是当前卡 `display_payload_json` 中允许编辑的 RFC 6901 JSON Pointer；第一版只允许 `basic_information.*` 或 `business_fields.*` 下已经存在的叶子标量字段，不允许替换对象或数组。
+- 来源消息、路由、订单定位关系、诊断、缺失字段清单、`manual_review`、raw evidence 等只读字段不得提交。
+- 如果订单任务归属未解决，复核请求必须提交 `confirmed_order_id`；后端按当前订单任务酒店校验该订单存在、非逻辑删除且不是系统隐藏订单。
+- `availability.reviewable=true` 且 `card_status=REVIEW_REQUIRED` 时，前端可以展示复核提交入口；普通确认接口仍拒绝 `REVIEW_REQUIRED` 卡。
 
 ### 7.4 Basic Information 目录规则
 
@@ -222,6 +226,8 @@ V4 CP2 只设计复核场景下的订单归属确认，不开放普通任务任
 - 订单归属确认必须写业务审计。
 - 若确认到其他订单，原临时订单可在无其它任务引用时逻辑删除。
 - 已确认锁定卡片不能通过该接口二次迁移订单。
+- CP7 第一版只支持在复核解阻请求中提交 `confirmed_order_id` 完成一次性归属确认；不提供普通任务任意切换订单接口。
+- 如果确认到的订单下存在更早未完成 V4 订单任务，后端拒绝当前复核提交，避免绕过同订单阻塞规则。
 
 ## 9. 同订单阻塞规则
 
@@ -611,8 +617,15 @@ POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution
 
 - 提交 `field_overrides[]`。
 - 可提交复核场景订单归属确认。
+- 请求 JSON 必须携带卡片 `version`；可选 `reason` 写入业务审计摘要；`confirmed_order_id` 表示复核场景确认后的本地订单 ID。
+- 如果订单任务当前 `order_id=null` 或 `target_resolution_status!=RESOLVED`，`confirmed_order_id` 必填；后端会按订单任务所属酒店查询并校验真实可见订单。
+- `field_overrides[]` 每项包含 `field_pointer` 和 `value`；`field_pointer` 只允许指向当前卡展示 payload 中的可编辑业务字段，不允许指向 `source_message`、`route_code`、`card_type`、`target_order`、`order_ref`、`missing_fields`、`manual_review`、`raw_evidence`、`validation_errors` 等只读诊断字段。
+- 第一版允许的写入容器是 `basic_information` 和 `business_fields`；只能改已存在的叶子标量或 `null` 字段，不能替换整个对象、数组或新增未知字段。
+- Basic Information 必须先确认；如果 Basic Information 自身是 `REVIEW_REQUIRED`，允许通过本接口先复核并确认 Basic。
+- 解阻过程不改写 `ai_payload_json`；用户修正写入 `review_resolution_json`，最终确认快照写入 `confirmed_payload_json`。
 - 校验通过后直接 `CONFIRMED`。
 - 写业务审计。
+- 返回刷新后的 `GET /api/reservation/order-tasks/{orderTaskId}` 详情结构；对应卡片 `review_status=RESOLVED`、`confirmed_by` 和 `confirmed_at` 会返回。
 
 ### 13.3 S10/S99 通知确认
 
@@ -687,10 +700,11 @@ 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 ack | 已完成：不保存草稿，支持普通卡片确认、确认后锁定、Basic Information 前置约束、同订单前置任务写侧阻塞、业务审计、version 并发校验和 S10/S99 来源通知确认；V4 复核接口后置 |
-| M002-V4-CP7 | 受控目录第一版 | Account、RoomType、RateCode、Department 固定目录或版本化快照校验 |
-| M002-V4-CP8 | V4 前端契约收口 | 字段、控件、availability、错误展示和旧任务入口切换 |
-| M002-V4-CP9 | 旧 V3 / V2 能力收口评估 | 明确哪些兼容入口可以关闭，哪些仍保留只读历史 |
+| M002-V4-CP6 | V4 卡片确认和 S10/S99 ack | 已完成：不保存草稿，支持普通卡片确认、确认后锁定、Basic Information 前置约束、同订单前置任务写侧阻塞、业务审计、version 并发校验和 S10/S99 来源通知确认 |
+| M002-V4-CP7 | V4 复核解阻与订单归属确认 | 已完成：支持 `REVIEW_REQUIRED` 卡字段修正、复核说明、复核场景订单归属确认、version 并发校验、直接 `CONFIRMED`、审计和 availability.reviewable |
+| M002-V4-CP8 | 受控目录第一版 | Account、RoomType、RateCode、Department 固定目录或版本化快照校验 |
+| M002-V4-CP9 | V4 前端契约收口 | 字段、控件、availability、错误展示和旧任务入口切换 |
+| M002-V4-CP10 | 旧 V3 / V2 能力收口评估 | 明确哪些兼容入口可以关闭，哪些仍保留只读历史 |
 
 ## 17. 已确认设计决策