接入M002V4订单任务多卡前端

docs/project/frontend-backend/README.md

@@ -45,6 +45,7 @@
 | SuperAgent 查询上下文接口 1、2 | `docs/project/requirements/M002-ai-query-minimal-fields.md` | 阶段记录，用于理解接口 1、2 的最小字段实现；如与总契约冲突，以总契约为准。 |
 | 订单任务主流程 V3 | `docs/project/requirements/M002-order-task-workflow-v3.md` | 当前开发基线，基于 0711 P0 冻结基线和 0712 P0.1 Parent Group 修订，覆盖 S10/S99、40 路由、方案 C、type-known manual review 同卡解阻和 fail-closed。 |
 | 任务卡字段控件契约 V1 | `docs/project/requirements/M002-task-field-control-contract-v1.md` | 后端已返回 `fields[]` 控件元数据，规定人工复核控件复用和前后端边界；前端待接入。 |
+| 订单任务多卡模型 V4 | `docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md` | 当前 V4 后端主入口；后端已开放工作台统一列表、V4 订单任务列表 / 详情、卡片确认、复核解阻、S10/S99 来源通知详情和 ack，前端页面接入仍按后续 checkpoint 跟进。 |
 | Manual Invoice 手工开票生成 | `docs/project/requirements/M009-manual-invoice-generation-v1.md` | 当前有效；后端 CP2 已支持无订单 / 无任务手工填写字段、填 Excel 模板、转 PDF、OSS 输出和生成记录。 |
 | Rooming List Excel 生成 | `docs/project/requirements/M010-rooming-list-excel-generation-v1.md` | 当前有效；后端 CP1 已支持前端上传来源名单并填写目标字段，同步生成 `.xlsx` 直接下载；前端 V1 已新增 `/reservation/rooming-lists/new`，按 Blob 下载处理，不落库、不上传 OSS。 |
 | 订单任务主流程 V2 | `docs/project/requirements/M002-order-task-workflow-v2.md` | 已实现阶段记录，保留用于理解当前代码中的 S000/S999、订单任务流转和 OPERA 模拟骨架。 |

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

@@ -461,6 +461,21 @@ RESERVATION_ROOMING_LIST_GENERATE
 - 页面不要把上传文件内容、客人名单、生成文件内容写入浏览器日志、埋点、错误上报、URL 或 localStorage。
 - 第一版没有 preview 接口、生成记录接口、OSS URL、历史下载和订单 / 任务预填；前端不要在页面上承诺这些能力。
 
+### 5.13 M002 V4 前端接入约束
+
+后端已提供以下 V4 查询和写接口，前端接入时按这些约束实现；在前端页面正式集成并完成联调前，不把 V4 前端页面视为完成：
+
+- `/reservation/tasks` 应使用 `GET /api/reservation/workbench-items` 作为默认工作台列表入口，展示 V4 订单任务和 S10/S99 来源通知混排摘要；当筛选工作项类型为订单任务时，改用 `GET /api/reservation/order-tasks`，仅发送后端当前支持的 `keyword`、`order_task_status`、`card_status`、`page_num`、`page_size`。
+- `/reservation/order-tasks/{orderTaskId}` 应使用 `GET /api/reservation/order-tasks/{orderTaskId}` 展示 `source_message_card`、`basic_information_card`、`business_cards[]`、`card_counts`、`order_task` 摘要和 `adapter_contract_errors[]` 只读诊断。
+- `/reservation/source-notifications/{notificationId}` 应使用 `GET /api/reservation/source-notifications/{notificationId}` 展示 S10/S99 来源通知详情，并通过 `POST /api/reservation/source-notifications/{notificationId}/ack` 确认已读 / 已处理。
+- V4 卡片确认应使用 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm`，请求带 `version`；前端只从当前卡 `fields[]` 中挑选 `editable=true`、`raw_readonly!=true`、`write_target` 指向确认 payload 的字段构造 `confirmed_payload`。
+- V4 复核解阻应使用 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution`，请求带 `version`；`field_overrides[]` 只使用当前卡 `fields[].field_pointer`，订单任务归属未解决时允许用户填写 `confirmed_order_id`。
+- 所有按钮应按后端 `availability.confirmable`、`availability.reviewable`、`availability.ackable` 和前端权限共同控制；不可操作原因优先展示 `readonly_reason_message`，否则按 `readonly_reason_code` 做友好映射。
+- `fields[].validation_errors` 应展示在对应字段旁边；接口返回 `V4_FIELD_VALIDATION_FAILED` 且 `details[]` 带嵌套路径时，前端应尝试定位到对应 field，定位不到则在当前卡片动作错误区展示。
+- `options_source` 第一版仍按前端固定种子渲染 Account / Room Type / Rate Code，不调用真实目录 lookup API。
+- 前端不展示 `ai_payload_json`、邮件完整正文、附件 URL、raw evidence 或 SuperAgent 原始 payload；来源邮件详情仍从邮件会话页面查看，卡片内仅展示后端普通接口返回的安全摘要、邮件片段和附件名称。
+- V4 主流程不调用旧 V2/V3 草稿、旧任务确认、旧同卡复核接口，也不展示 OPERA 模拟操作入口。
+
 ## 6. 不给前端直接调用的接口
 
 - `POST /api/system/reservation/demo-data` 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。
@@ -488,7 +503,7 @@ RESERVATION_ROOMING_LIST_GENERATE
 - 业务卡目录校验会递归检查 `business_fields` 下的嵌套结构。例如 `UPDATE_BOOKING` 的房型可能位于 `/business_fields/after/room_items/0/room_type_code`，错误详情会使用 `business_fields.after.room_items.0.room_type_code`；前端展示错误时优先用 `fields[].validation_errors`，接口 400 时可直接展示 `details[]`。
 - `review-resolution` 请求示例：`{"version":0,"reason":"确认房型映射","confirmed_order_id":"123456","field_overrides":[{"field_pointer":"/business_fields/room_items/0/pms_room_type_code","value":"RM2"}]}`。`confirmed_order_id` 在订单任务归属未解决时必填；如果订单任务已经绑定订单且 `target_resolution_status=RESOLVED`，只能不传或传当前同一个订单 ID，不能借该接口切换到其它订单。`field_pointer` 必须来自当前卡允许编辑的 `basic_information.*` 或 `business_fields.*` 叶子字段；展示 payload 有 `missing_fields[]` 时只提交清单里的 pointer，没有显式清单时只提交当前值为 `null` / 空字符串的未解决叶子字段；如果是目录校验错误，也可以提交后端 `fields[].validation_errors` 对应的字段 pointer。前端不要提交来源邮件、路由、`target_order`、`order_ref`、缺失字段清单、`manual_review`、raw evidence、校验诊断字段，也不能替换整个对象 / 数组。
 - V4 `fields[]` 第一版字段说明：Basic Information 固定返回 `/basic_information/account_code`、`/basic_information/market_code`、`/basic_information/source_code`；其中 Account `control_type=select`、`options_source=reservation_v4_account_catalog`，Market / Source 为只读派生字段。业务卡会按展示 payload 里的业务叶子字段返回字段白名单，例如 `/room_items/0/room_type_code` 或 `/business_fields/room_items/0/pms_room_type_code`；前端不要自行补未返回字段。
-- V4 CP8 仍没有独立目录 lookup API。前端第一版可先按后端文档固定种子渲染 Account / Room Type / Rate Code 选项；后续真实目录或管理后台目录接入时再切换为 lookup。
+- V4 CP8 仍没有独立目录 lookup API。前端第一版可先按后端文档固定种子渲染 Account / Room Type / Rate Code 选项；后续真实目录或管理后台目录接入时再切换为 lookup。用户提交确认或复核时只提交稳定 `code`，不要提交显示名、派生 Market / Source 或目录完整对象；后端确认前仍会重新校验目录。
 - V4 新模型确认口径是不保存后端草稿、卡片最终确认后锁定、技术异常不进入用户可处理卡、当前不生成 OPERA 模拟操作。Basic Information 必须先确认；其它业务卡第一版不强制逐张顺序确认。现有 V3 `draft`、`confirm`、`manual-review-resolutions` 和 OPERA 模拟接口仍只代表旧链路能力，不能直接等同 V4 多卡最终接口。
 - V4 S10/S99 已采用来源通知模型入库：新 V4 `route_code=S10/S99` 不再挂隐藏技术订单，也不再创建旧 `SOURCE_MESSAGE_ONLY` 任务；对应工作台 / 来源通知详情查询接口和 ack 写接口已开放。旧 `SOURCE_MESSAGE_ONLY` 只读任务仅代表 V3 S10/S99 和旧 S000/S999 兼容数据。
 - 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 路由修订均已完成。