实现M002 V3字段控件契约后端第一版

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

@@ -4,9 +4,9 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 文档版本 | 0.2 |
-| 日期 | 2026-07-12 |
-| 状态 | 0712 P0.1 增量确认版；后端已完成 M002 V3 CP1-CP6 第一版，Parent Group / Cancel Allotment 路由按 P0.1 修订 |
+| 文档版本 | 0.3 |
+| 日期 | 2026-07-13 |
+| 状态 | 0712 P0.1 增量确认版；已完成任务卡字段控件契约 V1 后端第一版 |
 | 适用范围 | SourceMessage 之后的 SuperAgent 输出适配、任务路由、只读通知卡、人工复核同卡解阻、前后端协作边界 |
 | 主要读者 | 产品、后端、前端、测试、SuperAgent 对接方、后续协作 agent |
 
@@ -34,7 +34,9 @@ V3 以以下资料和决策为输入：
 | `docs/import/20260711/开发交付_P0冻结基线_2026-07-11/04_Known_Issues_非契约/` | P1/P2 未闭合范围，只用于识别暂缓和 fail-closed，不作为生产规则源 |
 | `docs/import/20260712/开发交付_P0_to_P0.1_增量修订说明_给开发Codex_2026-07-11.md` | Parent Group / Allotment 语义修订、40 路由、当前 producer 禁止旧 Parent Cancel Booking |
 | `docs/import/20260712/Agent 0711 1743/**` | P0.1 Main Agent prompt、booking-desk-event skill 和 references |
+| `docs/import/20260712/前端字段控件修改说明_给信息系统小伙伴Codex_2026-07-12.md` | 前端字段控件、人工复核编辑、只读证据和验收用例输入；本项目落地口径见 `M002-task-field-control-contract-v1.md` |
 | `docs/project/requirements/M002-v3-p0.1-parent-group-routing-update.md` | 本项目对 P0.1 增量的落地说明和验收清单 |
+| `docs/project/requirements/M002-task-field-control-contract-v1.md` | 本项目任务卡字段控件契约 V1，后端已扩展 `fields[]`，前端后续按该契约渲染字段和同卡复核输入 |
 
 本项目确认的产品决策：
 
@@ -323,6 +325,8 @@ Agent payload 不可变。本系统在同一张卡上维护复核状态：
 
 入站 `ai_payload_json` 保留 SuperAgent 原始结构，不回写用户修正。V3 `message_events[]` 归一化为任务卡时，会把 `relevant_message_excerpt` 同步到任务 item 根路径，便于旧字段矩阵读取证据字段。任务详情 `fields[]` 中 `field_path` 和 `field_pointer` 以 P0 主结构为准，`legacy_field_path` 仅用于前端过渡展示。草稿保存、最终确认的 `field_values` 可继续提交旧扁平 key；同卡复核解阻可提交 `field_pointer` 或 `field_path`，其中 `field_path` 可为 P0 主路径或旧扁平路径。后端会归一化到 P0 主 `field_path`；响应中的 `field_values` 使用主路径，`legacy_field_values` 提供旧扁平回显兼容，`effective_payload` 提供嵌套结构供后续 OPERA 参数组装使用。当前第一版只支持 `room_items[0]`，非 0 下标或不存在路径按 `TASK_REVIEW_POINTER_INVALID` / 字段校验错误处理，不自动映射。
 
+Parent / Allotment 的 `block_code` 是 SuperAgent 输入侧同义 key，本系统订单和任务卡第一版统一落到 `case_keys.group_code`。因此 Parent key 冲突进入 `target_object_unclear` 复核时，即使 `manual_review.missing_fields[]` 同时包含 `/case_keys/group_code` 和 `/case_keys/block_code`，任务详情只要求用户填写 `case_keys.group_code`；后端复核解阻会把 `/case_keys/block_code` 视为 `case_keys.group_code` 的别名进行缺失字段校验。`Cancel Allotment / cancel_allotment_control_block` 第一版复用旧 `Cancel Booking` 字段矩阵，后端确认和复核解阻时会派生 `extracted_fields.cancel_object_type=allotment_control_block`，并允许 P0.1 的 `extracted_fields.cancel_scope=entire_allotment_control_block`。
+
 ### 9.3 后端第一版接口
 
 ```text
@@ -392,6 +396,9 @@ Content-Type: application/json
 - P1/P2 fail-closed 返回时，前端展示稳定错误和源邮件入口，不让用户误以为可以确认执行。
 - Parent split 父事件展示为 `Cancel Allotment / cancel_allotment_control_block`，不再展示独立 Parent Cancel Booking 卡。
 - 任务列表筛选不提供 `linked_parent_release_after_child_split`；新开发阶段只展示 `S10/S99` 筛选，不再展示旧 `S000/S999` 筛选项。
+- 任务详情字段控件以 `M002-task-field-control-contract-v1.md` 为准：前端优先消费后端 `fields[]` 中的 `control_type`、`edit_scope`、`write_target`、`options_source`、`raw_readonly`，旧矩阵开关只作为兼容兜底。
+- type-known manual review 的 `missing_fields[]` 不应统一渲染为普通文本输入；前端应按 `field_pointer` 匹配 `fields[]`，复用对应字段控件并提交 `review_resolution.field_overrides[]`。
+- 前端不得自行硬编码 PMS 房型目录、Rate Code 全集、Fix Charge 枚举或 P1/P2 未冻结字段；选项来源未接入时按只读、容错或“目录待接入”处理。
 
 ## 12. 后端实施 checkpoint 建议
 
@@ -407,6 +414,7 @@ V3 建议拆成以下 checkpoint，避免一次性重构过大：
 | M002-V3-CP6 | P0 fixtures 回归 | 已完成第一版：引入 0711 P0 fixtures / validator 作为后端适配测试参考，覆盖 main_outcomes、candidate_gate、manual_review_resolution、source_identity_errors、parent_split_two_children、row_multiple_derived、allotment_scope；其中 candidate_gate 是 Main Agent 调 Skill 前契约，后端以 validator 和 fixture reference 固化，不作为任务结果回调直接建任务 |
 | M002-V3-CP7 | P0.1 Parent Group 路由修订 | 已完成：将 Parent split 父事件从旧 Cancel Booking 迁移为 Cancel Allotment，路由总数 42 → 40，并保留旧 payload 只读兼容 |
 | M002-V3-CP8 | MCP submit 稳定性 | 已完成 review 修正版：MCP `th_hotel_submit_task_results` 支持 V3 业务根、结构化 S10/S99 和 V2 兼容；V2 item 已暴露完整 schema 并在提交前校验；V3 按 `message_events[]` 顺序把 Agent 内部事件 ID 映射为本系统一基 `source_event_index`，返回 `mapping_diagnostics` 但不污染业务 JSON；MCP 层只拦 transport 问题，event 业务契约问题继续由业务入站层落 `adapter_contract_error` |
+| M002-V3-CP9 | 字段控件契约 V1 | 已完成后端第一版：`fields[]` 返回 `control_type/edit_scope/write_target/options_source/raw_readonly/control_hint`，覆盖 room_items、只读证据、S10/S99 只读卡和 type-known manual review 缺失字段控件；前端后续按契约接入 |
 
 ## 13. 明确不做
 
@@ -419,10 +427,11 @@ V3 P0.1 不做以下事项：
 - 不自动根据 `unhandled_current_intents[]` 创建业务任务卡。
 - 不用 P1/P2 Known Issues 自行发明字段或 schema。
 - 不移除历史 `S000/S999` 数据展示。
+- 不让前端绕过后端字段控件契约自行发明 PMS 房型、Rate Code、Fix Charge 或未冻结枚举。
 
 ## 14. 当前代码现状提醒
 
-截至 M002 V3 CP7 落地后，当前后端已经实现：
+截至 M002 V3 CP9 后端第一版落地后，当前后端已经实现：
 
 - `S000/S999` 文本结果兼容处理。
 - 结构化 `S10/S99` 入站处理，复用 `SOURCE_MESSAGE_ONLY` 只读特殊任务。
@@ -437,6 +446,10 @@ V3 P0.1 不做以下事项：
 - type-known manual review 创建在原业务任务卡上，任务详情返回 `review_status`、`review_resolution` 和 `manual_review`。
 - `POST /api/reservation/tasks/{taskId}/manual-review-resolutions` 支持字段修正、当前订单归属确认、JSON Pointer 到可编辑字段校验、READY 流转、confirmed payload 写入、两条 OPERA 模拟操作创建和审计记录。
 - `POST /api/reservation/tasks/{taskId}/manual-review-resolutions` 的 `field_overrides[]` 已支持 `field_pointer` 和 `field_path` 两种定位方式；`field_path` 可为 P0 主路径或旧扁平路径，成功后响应归一化到 P0 主 `field_path`。
+- 任务详情 `fields[]` 已新增 `control_type`、`edit_scope`、`write_target`、`options_source`、`raw_readonly`、`control_hint`，用于前端字段控件和同卡复核输入渲染。
+- `room_items[0]` 字段第一版已返回 P0 JSON Pointer 和控件契约：房量为 `number`，PMS 房型代码为 `select + active_pms_room_type_catalog`，房型原文 `room_type_raw` 作为 raw 证据只读。
+- type-known manual review 的缺失字段返回 `edit_scope=manual_review_only` 和 `write_target=review_resolution.field_overrides`；只读诊断字段、源邮件通知卡和 route/result/task 字段不返回可编辑控件。
+- `CANCEL_ALLOTMENT` 第一版复用字段矩阵中的 `Cancel Booking 卡 / cancel_allotment_control_block` 规则；Parent / Allotment 复核中 `/case_keys/block_code` 按 `case_keys.group_code` 别名处理，前端只需要提交任务详情 `fields[]` 暴露的 `case_keys.group_code`。后端会派生 `cancel_object_type=allotment_control_block` 并接受 `cancel_scope=entire_allotment_control_block`。
 - `source_message.source_message_id` 缺失时按 V3 typed `infrastructure_input_error` 结构响应。
 - 0711 P0 fixtures 已纳入后端回归测试参考，并补齐 S10/S99 严格契约、P0 type-known manual review 解阻、candidate_gate reference 和当前扁平字段矩阵兼容；Parent split 相关用例按 0712 P0.1 增量改为 Cancel Allotment。
 - `field_contract_version` 历史迁移已收紧：V18 只把没有 `draft_payload_json` 且没有 `confirmed_payload_json` 的 `code-v1` 任务卡标记为 `20260711-p0`；已经存在用户草稿或确认 payload 的历史任务卡保留旧版本，等待重新保存、确认或后续专项 backfill。