适配 M002 V3 前端任务流与同卡复核

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

@@ -160,7 +160,7 @@ POST /api/auth/logout
   "reason": "确认 PMS 房型代码后解阻。",
   "field_overrides": [
     {
-      "field_pointer": "/extracted_fields/pms_room_type_code",
+      "field_pointer": "/extracted_fields/room_items/0/pms_room_type_code",
       "value": "RM3"
     }
   ]
@@ -168,11 +168,17 @@ POST /api/auth/logout
 ```
 
 - `field_pointer` 必须是 RFC 6901 JSON Pointer，并且只能指向当前任务卡可编辑字段；后端会映射到矩阵 `field_path`。非法或只读字段会返回 `TASK_REVIEW_POINTER_INVALID`。
-- 0711 P0 的房型复核可传 `/extracted_fields/room_items/{index}/pms_room_type_code`；当前后端矩阵仍是扁平字段，响应会映射为 `field_path=extracted_fields.pms_room_type_code`。前端展示时保留原始 `field_pointer`，业务字段写入和确认 payload 以返回的 `field_path` 为准。
+- 0711 P0 的房型字段主路径已迁移到 `room_items[0]`。任务详情 `fields[]` 中，房量、房型原文、PMS 房型代码分别返回：
+  - `field_path=extracted_fields.room_items.0.room_quantity`，`field_pointer=/extracted_fields/room_items/0/room_quantity`
+  - `field_path=extracted_fields.room_items.0.room_type_raw`，`field_pointer=/extracted_fields/room_items/0/room_type_raw`
+  - `field_path=extracted_fields.room_items.0.pms_room_type_code`，`field_pointer=/extracted_fields/room_items/0/pms_room_type_code`
+- `legacy_field_path` 仅用于前端过渡显示旧扁平字段；新页面保存草稿、最终确认和复核解阻应优先提交 `field_pointer` 或 P0 主 `field_path`。
+- 后端仍兼容旧提交 key：`extracted_fields.room_quantity`、`extracted_fields.room_type`、`extracted_fields.pms_room_type_code`，但响应会归一化到 P0 主 `field_path`。`confirmed_payload.legacy_field_values` / `draft_payload.legacy_field_values` 只供旧前端回显，不作为新逻辑判断依据。
+- 当前第一版只支持 `room_items[0]`；`/extracted_fields/room_items/1/...` 或更大下标不会自动落到 0。
 - 同一次请求不能重复提交同一字段；重复 `field_pointer` 或重复映射到同一 `field_path` 会返回 `TASK_REVIEW_POINTER_DUPLICATE`。
 - `confirmed_order_id` 第一版必须等于当前任务的 `order_id`；如果前端需要选择其他订单，仍属于后续“复核场景订单归属选择”细化，不要复用普通任务切换订单能力。
 - 解阻成功后返回 `task_status=READY`、`review_status=RESOLVED`、`review_resolution.field_overrides[]`、`confirmed_payload` 和两条 `opera_operations[]`。前端应刷新任务详情并显示 OPERA 模拟操作入口。
-- 解阻过程不改写 `ai_payload_json`；用户修正值保存在 `review_resolution` 和 `confirmed_payload.field_values` 中。
+- 解阻过程不改写 `ai_payload_json`；用户修正值保存在 `review_resolution`、`confirmed_payload.field_values` 和 `confirmed_payload.effective_payload` 中。`effective_payload` 是后端第一版嵌套结构，后续真实 OPERA 参数仍会在 OPERA 层重新组装。
 - `review_resolution.resolved_at` 是 UTC `Z` 时间点。
 - type-known manual review 不允许调用通用 `POST /api/reservation/tasks/{taskId}/confirm`；前端必须使用本节解阻接口，否则后端返回 `TASK_REVIEW_RESOLUTION_REQUIRED`。
 
@@ -210,7 +216,7 @@ Content-Type: application/json
 - 已完成 New Booking 任务和两条 OPERA 模拟成功记录。
 - OPERA 模拟失败任务，可在任务详情看到失败 attempt 和重试入口。
 - Fallback / manual_review 任务。
-- 历史 Message Notification 只读任务；旧 S000/S999 和新 S10/S99 特殊只读任务可通过 SuperAgent 回调补充，专用前端 fixture 仍可后续增加。
+- 历史 Message Notification 只读任务；旧 S000/S999 和新 S10/S99 特殊只读任务可通过 SuperAgent 回调补充，前端 fixture 已补 S10 和同卡人工复核最小样例。
 - 同一邮件会话下多封邮件、完整 HTML、附件外链和内联图片外链。
 
 ### 5.7 任务详情字段元数据接入注意

docs/project/frontend-backend/frontend-to-backend-api-requests.md

@@ -332,6 +332,23 @@ POST /api/system/reservation/demo-data
 | 复核场景订单归属确认 | 任务详情复核 | 已完成第一版 | 后端提供复核确认时的订单归属确认；当前第一版只能确认当前任务所属订单，后续如要选择其他订单需另行细化。 |
 | P0 fixtures 回归基线 | 联调回归 | 已完成第一版 | 后端已将 0711 P0 fixtures 纳入测试参考；前端对 S10/S99、同卡复核和只读诊断块的展示应继续按本节稳定字段接入。 |
 
+### 6.2 前端本轮接入状态（2026-07-11）
+
+本轮前端已按 M002 V3 P0 完成以下接入，后端不需要重复补接口：
+
+- 任务列表已按 `result_type`、`route_code`、`system_process_category` 识别 `source_message_review_notification`、`adapter_contract_error`、`unhandled_current_intent` 只读诊断任务；S10/S99 和旧 S000/S999 都不展示订单入口。
+- 任务详情已展示 `result_type`、`ai_task_type`、`task_subtype`、`route_code`、`system_process_category`、`review_status`、来源邮件入口、`source_message_only_result`、`manual_review`、`adapter_contract_errors[]` 和 `unhandled_intents[]`。
+- type-known `result_type=manual_review` 已在原业务任务卡展示复核状态和缺失字段，并调用 `POST /api/reservation/tasks/{taskId}/manual-review-resolutions` 解阻，不再创建第二张人工复核任务卡。
+- 第一版解阻 UI 已支持 `/extracted_fields/pms_room_type_code` 和 `/extracted_fields/room_items/0/pms_room_type_code` 两类 pointer，提交成功后刷新任务详情和审计流水。
+- 前端只读规则已收口：S10/S99、适配契约异常、未处理意图、前置任务阻塞和同卡人工复核待解阻状态都不显示保存草稿、确认任务、人工转换或 OPERA 执行 / 重试入口。
+- 前端 fixture 已补 V3 最小结构样例：`source_message` 完整对象、`message_events[]` 的 `event_role`、`current_or_history`、`source_event_index`、四字段 `case_keys`、`relevant_message_excerpt`、`attachments`、`file_references`、`context_used`、`extracted_fields`、`manual_review`。
+
+仍建议后端确认：
+
+- `GET /api/reservation/tasks` 是否会在结构化 S10/S99 行中稳定返回 `task_type=SOURCE_MESSAGE_ONLY`，或允许返回 `MESSAGE_NOTIFICATION` 并只依赖 `result_type/route_code/system_process_category`；前端当前两种都兼容。
+- `adapter_contract_error` / `unhandled_current_intent` 如果未来也作为独立列表行返回，请保持 `source_message_id` 可用，便于前端继续提供邮件会话入口。
+- 同卡人工复核解阻成功后是否一定返回 `opera_operations[]`。当前文档写“两条 OPERA 模拟操作”，前端实现按实际返回刷新，不假设固定数量。
+
 前端注意：不要把访问口令写入前端仓库、浏览器环境变量或构建产物；该接口只能由本地联调人员手动调用或由受控测试脚本调用。
 
 ## 7. 邮件会话详情接口
@@ -518,14 +535,14 @@ Content-Type: application/json
   "reason": "确认 PMS 房型代码后解阻。",
   "field_overrides": [
     {
-      "field_pointer": "/extracted_fields/pms_room_type_code",
+      "field_pointer": "/extracted_fields/room_items/0/pms_room_type_code",
       "value": "RM3"
     }
   ]
 }
 ```
 
-0711 P0 房型复核说明：前端可以提交 `/extracted_fields/room_items/{index}/pms_room_type_code`，后端第一版会兼容映射到当前矩阵字段 `extracted_fields.pms_room_type_code`。响应里的 `review_resolution.field_overrides[].field_pointer` 保留前端原始 pointer，`field_path` 和 `confirmed_payload.field_values` 使用当前后端矩阵字段。
+0711 P0 房型复核说明：前端应优先提交 `/extracted_fields/room_items/0/pms_room_type_code` 或任务详情 `fields[].field_path=extracted_fields.room_items.0.pms_room_type_code`。后端仍兼容旧扁平 key / pointer，但会归一化到 P0 主路径。响应里的 `review_resolution.field_overrides[].field_pointer` 保留前端原始 pointer，`field_path` 使用 P0 主路径，`legacy_field_path` 仅用于旧页面过渡。
 
 返回示例：
 
@@ -541,16 +558,29 @@ Content-Type: application/json
     "resolved_at": "2026-07-11T00:00:00Z",
     "field_overrides": [
       {
-        "field_pointer": "/extracted_fields/pms_room_type_code",
-        "field_path": "extracted_fields.pms_room_type_code",
+        "field_pointer": "/extracted_fields/room_items/0/pms_room_type_code",
+        "field_path": "extracted_fields.room_items.0.pms_room_type_code",
+        "legacy_field_path": "extracted_fields.pms_room_type_code",
         "value": "RM3"
       }
     ]
   },
   "confirmed_payload": {
-    "schema_version": "field_path-v1",
+    "schema_version": "field_matrix-p0-room-items-v1",
     "field_values": {
+      "extracted_fields.room_items.0.pms_room_type_code": "RM3"
+    },
+    "legacy_field_values": {
       "extracted_fields.pms_room_type_code": "RM3"
+    },
+    "effective_payload": {
+      "extracted_fields": {
+        "room_items": [
+          {
+            "pms_room_type_code": "RM3"
+          }
+        ]
+      }
     }
   },
   "opera_operations": [
@@ -568,7 +598,7 @@ Content-Type: application/json
 - type-known manual review 不能调用通用 `POST /api/reservation/tasks/{taskId}/confirm`；必须调用本节解阻接口，否则后端返回 `TASK_REVIEW_RESOLUTION_REQUIRED`。
 - `review_resolution.resolved_at` 是 UTC `Z` 时间点。
 - 解阻成功后刷新任务详情，按钮状态以新的 `task_status=READY` 和 `availability` 为准。
-- `confirmed_payload.field_values` 仍按矩阵 `field_path` 保存，不是 OPERA 最终参数。
+- `confirmed_payload.field_values` 按 P0 主 `field_path` 保存；`legacy_field_values` 是旧扁平兼容回显；`effective_payload` 是后端第一版嵌套结构，不是 OPERA 最终参数。
 
 建议返参增量示例：
 
@@ -797,3 +827,5 @@ POST /api/reservation/tasks/{taskId}/order-binding
 - 任务详情 `fields[]` 已由后端直接透出 P0 需要的 3.0 元数据；独立字段白名单接口后置。
 - 独立 Message Notification 页面继续后置；旧 S000/S999 和新 S10/S99 都先在任务列表和任务详情展示。
 - 邮件会话全文读取的审计策略由后端内部处理；前端不保存原文读取 key。
+- `GET /api/reservation/tasks` 结构化 S10/S99 行的 `task_type` 返回值请后端最终确认：前端已兼容 `SOURCE_MESSAGE_ONLY` 和 `MESSAGE_NOTIFICATION`，但文档口径最好稳定一个。
+- `manual-review-resolutions` 成功响应中的 `opera_operations[]` 数量请后端最终确认；前端不写死两条，只按返回内容刷新展示。

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

@@ -266,7 +266,8 @@ Agent payload 不可变。本系统在同一张卡上维护复核状态：
     "field_overrides": [
       {
         "field_pointer": "/extracted_fields/room_items/0/pms_room_type_code",
-        "field_path": "extracted_fields.pms_room_type_code",
+        "field_path": "extracted_fields.room_items.0.pms_room_type_code",
+        "legacy_field_path": "extracted_fields.pms_room_type_code",
         "value": "SU1"
       }
     ],
@@ -288,7 +289,15 @@ Agent payload 不可变。本系统在同一张卡上维护复核状态：
 - 订单归属确认可作为复核解阻的一部分保存；当前第一版只允许确认当前任务所属订单，不开放普通任务随意切换订单能力。
 - 全部缺失字段、订单归属、目录值和依赖校验通过后，才进入 Preflight / READY。
 
-当前 CP6 兼容说明：0711 P0 fixtures 中 `room_items[]` 已经是新结构，但后端第一版字段矩阵仍使用 `extracted_fields.room_type`、`extracted_fields.room_quantity`、`extracted_fields.pms_room_type_code` 等扁平字段。入站 payload 保留原始 `room_items[]`；后端在字段读取、展示、校验和确认 payload 组装时，从第一条 `room_items[]` 做扁平字段别名解析。解阻接口第一版仅接受 `/extracted_fields/room_items/0/pms_room_type_code` 兼容到当前扁平矩阵字段，其他数组下标不会被自动 alias；响应中的矩阵 `field_path` 仍返回当前后端字段 `extracted_fields.pms_room_type_code`。后续字段矩阵整体迁移时再取消这层兼容。
+当前字段矩阵迁移第一版说明：0711 P0 fixtures 中 `room_items[]` 已作为房型字段主结构。后端已将 New Booking 卡的房量、房型原文、PMS 房型代码主路径迁移为：
+
+| 语义 | 主 `field_path` | 主 `field_pointer` | 旧兼容 key |
+| --- | --- | --- | --- |
+| 房量 | `extracted_fields.room_items.0.room_quantity` | `/extracted_fields/room_items/0/room_quantity` | `extracted_fields.room_quantity` |
+| 房型原文 | `extracted_fields.room_items.0.room_type_raw` | `/extracted_fields/room_items/0/room_type_raw` | `extracted_fields.room_type` |
+| PMS 房型代码 | `extracted_fields.room_items.0.pms_room_type_code` | `/extracted_fields/room_items/0/pms_room_type_code` | `extracted_fields.pms_room_type_code` |
+
+入站 `ai_payload_json` 保留 SuperAgent 原始结构，不回写用户修正。任务详情 `fields[]` 中 `field_path` 和 `field_pointer` 以 P0 主结构为准，`legacy_field_path` 仅用于前端过渡展示。草稿保存、最终确认和同卡复核解阻可继续提交旧扁平 key，但后端会归一化到 P0 主 `field_path`；响应中的 `field_values` 使用主路径，`legacy_field_values` 提供旧扁平回显兼容，`effective_payload` 提供嵌套结构供后续 OPERA 参数组装使用。当前第一版只支持 `room_items[0]`，非 0 下标或不存在路径按 `TASK_REVIEW_POINTER_INVALID` / 字段校验错误处理，不自动映射。
 
 ### 9.3 后端第一版接口
 
@@ -305,7 +314,7 @@ Content-Type: application/json
   "reason": "确认 PMS 房型代码后解阻。",
   "field_overrides": [
     {
-      "field_pointer": "/extracted_fields/pms_room_type_code",
+      "field_pointer": "/extracted_fields/room_items/0/pms_room_type_code",
       "value": "RM3"
     }
   ]
@@ -316,9 +325,9 @@ Content-Type: application/json
 
 - `task_status=READY`。
 - `review_status=RESOLVED`。
-- `review_resolution.field_overrides[]` 同时返回 `field_pointer`、矩阵 `field_path` 和人工值。
+- `review_resolution.field_overrides[]` 同时返回 `field_pointer`、矩阵主 `field_path`、`legacy_field_path` 和人工值。
 - `review_resolution.resolved_at` 使用带 `Z` 的 UTC 时间点。
-- `confirmed_payload.field_values` 使用矩阵 `field_path` 保存，不按 `write_path` 生成 OPERA 参数。
+- `confirmed_payload.field_values` 使用 P0 主 `field_path` 保存，`legacy_field_values` 仅用于旧扁平字段过渡回显；`effective_payload` 是嵌套结构，不等同真实 OPERA 参数。
 - 自动生成第一版固定两条 OPERA 模拟操作。
 - 写入 `MANUAL_REVIEW_RESOLVE` 审计。
 - type-known manual review 不允许走通用 `POST /api/reservation/tasks/{taskId}/confirm`，否则会返回 `TASK_REVIEW_RESOLUTION_REQUIRED`。