th-hotel-simple/docs/import/20260712/前端字段控件修改说明_给信息系统小伙伴Codex_2026-07-12.md

# 前端字段控件修改说明

## 给信息系统 / Adapter / Frontend Codex 的实施任务

日期：2026-07-12  
适用范围：任务卡展示、人工复核编辑、字段校验和同卡解阻  
不适用范围：Prompt、Skill、业务 references、MCP Server、Gateway、公开 JSON 业务规则重设计

---

## 0. 先读这些文件

请先从当前工作区根目录读取以下文件，再开始修改：

1. `prompt_skill_architecture_optimization_2026-07-12/README.md`
2. `prompt_skill_architecture_optimization_2026-07-12/01_PLAN/compatibility_invariants.md`
3. `prompt_skill_architecture_optimization_2026-07-12/03_VALIDATION/draft_validation_2026-07-12.md`
4. `outputs/黄哥codex读 2/README_先读_交给Codex.md`
5. `outputs/黄哥codex读 2/04_Adapter_Frontend_保持P0.1_40路由/任务卡前端字段变更与路由说明_3.0_to_current.md`
6. `outputs/黄哥codex读 2/04_Adapter_Frontend_保持P0.1_40路由/任务卡前端字段变更说明_3.0_to_当前版_2026-07-11.xlsx`
7. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/00-output-contract.md`
8. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/90-manual-review.md`
9. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/16-trace-notes.md`
10. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/31-allotment-control-block.md`
11. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/50-room-type-mapping.md`
12. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/51-rate-code.md`
13. `prompt_skill_architecture_optimization_2026-07-12/02_DRAFT/working/skills/booking-desk-event/references/52-fix-charge.md`

旧文件 `任务卡前端展示字段表 3.0(1).xlsx` 只作为历史基线，不得作为当前字段、路由和枚举的唯一来源。

如果上述交接文件或实际 Adapter/Frontend 源码不在当前工作区，请停止代码修改并报告缺失路径；不要根据旧 Excel 猜测当前字段。

---

## 1. 任务目标

把任务卡前端从旧版“是否输入 / 是否下拉”字段说明，升级为当前项目可执行的控件注册和人工复核编辑机制：

```text
Agent final result
  → adapter 按 event 派生任务卡
  → manual_review.missing_fields[] 指定可编辑字段
  → 前端展示对应控件
  → 用户修改
  → review_resolution.field_overrides[]
  → 重新校验依赖字段
  → Preflight
```

核心要求：

- 原 Agent payload 不可变。
- 用户覆盖值不得直接写回 Agent 原始 JSON。
- 不因为前端编辑而改变 `event_type`、业务 task type、task subtype 或关系语义。
- 不创建第二张 linked normal task。
- 只有同一业务卡的 `review_status` 从 `pending` 进入 `resolved` 后，才允许继续 Preflight。
- 邮件原文、附件、raw evidence、source ID、source event index 和关系索引只读。

当前项目的最新 Prompt/Skill 架构增量仍处于草案、未进入 `04_RELEASE` 状态；本任务只修改信息系统展示/编辑层，不把草案直接宣称为生产发布。

---

## 2. 修改范围

### 允许修改

- Adapter 的字段注册表 / 字段映射层。
- 任务卡展示组件和人工复核组件。
- 控件类型、编辑权限和字段校验逻辑。
- `review_status` / `review_resolution` 的前端交互。
- Adapter/Frontend 单元测试、契约测试和验收用例。
- 当前字段交接 MD/Excel 的控件列和实现说明。

### 不得修改

- `prompts/`、`skills/`、`booking-desk-event` Skill 业务裁决逻辑。
- 公开业务 JSON 根结构和既有五字段业务根。
- S10、S99、`infrastructure_input_error` 结构。
- 40 条 Adapter 路由数量和既有 task type/subtype 语义。
- MCP 工具名、MCP payload mapping、一次提交生命周期。
- `source_event_index` 的含义。
- Parent Group / Allotment 业务本体。
- 不得在前端新增 `Note`、`Allotment Maintenance` 或旧 Parent Cancel Booking 当前路由。

如果实现过程中发现必须改变上述内容，请先报告为“契约变更”，不要在前端代码中自行绕过。

---

## 3. 前端控件类型

字段注册表至少应支持以下 `control_type`。名称可按现有代码风格调整，但语义必须保持一致：

| `control_type` | 用途 |
|---|---|
| `readonly` | Agent 结果、raw evidence、路由、关系和审计字段 |
| `text` | Group Code、Confirmation No.、备注、旧/新 Group Code |
| `textarea` | 允许覆盖的业务备注；必须保留原始证据 |
| `number` | 房量、人数、PAX、结算价、附加费金额 |
| `date` | 入住日、离店日、服务日期、取消生效日期 |
| `lookup` | 可输入并检索当前系统目标对象的组合框 |
| `select` | 固定枚举或目录选择 |
| `multiselect` | 多部门、多标签、多项业务分类 |
| `structured_table` | `before_after[]`、`room_items[]`、`fix_charge_items[]`、`trace_items[]` |
| `workflow_state` | `review_status`、Resolve/重新校验等动作 |

字段注册表还应增加：

| 配置项 | 说明 |
|---|---|
| `edit_scope` | `never`、`manual_review_only`、`workflow_only`、`system_only` |
| `options_source` | 固定契约枚举、当前 PMS 目录、Rate 配置中心、无、待冻结 |
| `write_target` | `review_resolution.field_overrides`、系统状态、无 |
| `validation_rule` | 格式、必填、目录、依赖字段和 Preflight 前置校验 |
| `raw_readonly` | 是否必须保留原始值且禁止覆盖 |

示例：

```json
{
  "field_pointer": "/extracted_fields/pms_room_type_code",
  "control_type": "select",
  "edit_scope": "manual_review_only",
  "options_source": "active_pms_room_type_catalog",
  "write_target": "review_resolution.field_overrides",
  "raw_readonly": true,
  "validation_rule": "catalog_value_exists_and_is_active"
}
```

---

## 4. 字段控件实施矩阵

### 4.1 目标、身份和 Group Code

| 字段 | 控件 | 编辑范围 | 实施要求 |
|---|---|---|---|
| `case_keys.group_code` | `lookup` | `manual_review_only` | 可输入并检索候选；校验目标存在、唯一和当前业务卡匹配 |
| `case_keys.confirmation_number` | `lookup` 或 `text` | `manual_review_only` | 不使用固定下拉；允许粘贴后执行格式/目标校验 |
| `case_keys.reservation_number` | `lookup` 或 `text` | `manual_review_only` | 与当前事件对象类型匹配后才能提交 |
| Parent `case_keys.block_code` | `readonly` | `never` | 必须与 Parent `group_code` 相等；禁止独立编辑 |
| `extracted_fields.old_group_code` | `text` | `manual_review_only` | 与新 Group Code 成对必填 |
| `extracted_fields.new_group_code` | `text` | `manual_review_only` | 必须表达 old → new 方向关系 |
| `extracted_fields.target_key` | 不再作为主控件 | — | 当前应优先使用通用 `case_keys`；旧字段只做兼容迁移 |

### 4.2 日期、房量和房型

| 字段 | 控件 | 编辑范围 | 实施要求 |
|---|---|---|---|
| `extracted_fields.arrival_date` | `date` | `manual_review_only` | 使用 `YYYY-MM-DD`；修改后重新校验离店日和晚数 |
| `extracted_fields.departure_date` | `date` | `manual_review_only` | 必须晚于入住日；保留原始日期证据 |
| `extracted_fields.nights` | `readonly` | `never` | 由入住日和离店日计算，不直接输入 |
| `extracted_fields.date_evidence.*` | `readonly` | `never` | `hotel_date_raw`、`tour_date_raw`、`action_date_raw`、`sheet_month_year` 只读 |
| `extracted_fields.room_quantity` | `number` | `manual_review_only` | 整数、非负/正数规则按现有业务字段执行 |
| `extracted_fields.child_room_items[]` | `structured_table` | `manual_review_only` | 每个 Child 的房型、房量和 PMS code 分列；禁止单行自由文本 |
| `extracted_fields.room_type_raw` | `readonly` | `never` | 原始房型文本不可被用户覆盖 |
| `extracted_fields.pms_room_type_code` | `select` | `manual_review_only` | 只能从当前有效 PMS 房型目录选择；禁止自由输入 code |

Parent 原始房量汇总与 Child 房型/房量汇总可以因分配或房型重分配而不同。前端不得仅因数量不相等显示冲突、强制修改或自动创建人工复核。

### 4.3 业务路由和分类字段

以下字段是业务识别或 Adapter 路由判别字段，默认只读：

| 字段 | 控件 | 说明 |
|---|---|---|
| `event_type` | `readonly` | 前端不允许 New / Update / Cancel 之间切换 |
| `booking_object_type` | `readonly` | FIT、Group Block、Allotment / Control Block 由业务结果确定 |
| `cancel_object_type` | `readonly` 或同路由受控 `select` | Cancel Booking 只接受 FIT/普通 Group；Allotment 整块取消属于 Cancel Allotment |
| `cancel_scope` | `readonly` 或同路由受控 `select` | 不使用自由文本；不得用前端选择跨到另一张任务卡 |
| `update_actions[]` / 旧 `update_subtypes[]` | `readonly` 标签 | 当前 Update 统一走 `update_booking_amendment`；动作由结果派生，不能用下拉改路由 |
| `voucher_subtype` | `readonly` | `lian_tai_credit_voucher` 与 `Payment Evidence` 分开，不跨卡选择 |
| `list_evidence_type` | `readonly` 或复核时受控 `select` | 不允许通过它自行创建新任务类型 |
| `trace_subtype` | `readonly` | 由 `trace_items[]` 重新判断 `extra_bed` / `general_request` |

如果 `manual_review.missing_fields[]` 明确指向同一业务卡的分类字段，才可以显示受控选择；选择结果不得自动改变 `event_type` 或 Adapter 路由，除非项目另行冻结了跨路由 resolution 契约。

### 4.4 Update 和 Before/After

`extracted_fields.before_after[]` 使用 `structured_table`：

| 子字段 | 控件 |
|---|---|
| `field` | 当前支持字段的受控选择；不得任意输入路径 |
| `before` | 只读原值/证据值 |
| `after` | 按字段类型使用日期、数字、文字或目录选择 |
| `evidence` | 只读 |

如果 Update 类型和 subtype 已确定，但 before/after 不可靠，保留原 Update 卡并进入同卡人工复核；不能把它改成 Fallback，也不能创建第二张卡。

### 4.5 Rate Code 和结算价

| 字段 | 控件 | 实施要求 |
|---|---|---|
| `extracted_fields.rate_code_result.rate_code` | 配置驱动 `select/lookup` | 不得硬编码旧 3.0 的 20+ code 全集；从当前 Rate 配置中心加载 |
| `rate_code_raw` | `readonly` | 原始价格/Rate marker 只读；路径未冻结时不要自行发明公开路径 |
| `settlement_price` | `number` | 单独编辑；校验币种、精度、非负和业务依赖 |
| `manual_settlement_price_required` | `readonly` | AI/规则派生，不让用户直接改成 true/false |
| `manual_price_reason_code` / `price_evidence` | `readonly` | 用于解释和审计，不是输入项 |

如果 Rate Code 无法唯一确定，用户应选择当前有效目录值或填写允许的手工结算价；不能让用户输入一个未经配置的任意 Rate Code。

### 4.6 Fix Charge

`fix_charge_items[]` 必须做成 `structured_table`，不能压成一行输入。

| 子字段 | 控件 | 当前边界 |
|---|---|---|
| `charge_type` | `select` | 使用当前契约枚举，如 `fixed_charge`；不要继续使用旧表 `additional_charge` |
| `pricing_mode` | `select` | 使用当前契约 `unit` 等已冻结值；旧 `unit_price` 需迁移 |
| `amount` / `quantity` / `total_amount` | `number` | 不把多个金额拼成文本；不得前端自行推导未经契约支持的总价 |
| `currency` | `select` 或配置值 | 以当前系统货币目录为准 |
| `unit_basis` | `select` 或 `text` | 若枚举未冻结，先只读或容错，不猜选项 |
| `raw_text` / `evidence_source` | `readonly` | 保留原文和证据 |
| `requires_followup_tool` / `followup_tool_name` | `readonly` | 前端不得自行调用工具 |
| `additional_operations[]` | `readonly` / pending badge | 只展示待处理意图，不执行实际写入 |

### 4.7 Cancel

| 字段 | 控件 | 实施要求 |
|---|---|---|
| `cancel_object_type` | 默认 `readonly` | Cancel Booking 只显示 FIT/Group；Allotment 使用独立 Cancel Allotment 卡 |
| `cancel_scope` | 默认 `readonly` | 不允许自由文本；部分配额维护当前不支持 |
| `requested_cancel_effective_date` | `date` | 只有 `missing_fields[]` 指定时启用 |
| `cancellation_note` | `textarea` | 允许覆盖时必须保留原始邮件证据并记录 field override |

### 4.8 Voucher、Payment 和 Invoice

| 字段 | 控件 | 实施要求 |
|---|---|---|
| `voucher_attachment` / `file_reference` | `readonly` 文件展示 | 不允许改写输入文件引用 |
| `voucher_subtype` | `readonly` | Credit Voucher 与 Payment Evidence 分开路由 |
| `department_routing[]` | `multiselect` 或只读 | 当前路径仍需以实际 schema 为准；默认 Finance/pending 只展示，不执行确认 |
| `post_confirmation_intent` | `readonly` | 只表示待确认后的意图，不表示已确认或已执行 |
| Invoice 专属字段 | 默认 `readonly` | 当前详细 item schema 尚未完全冻结，不要自造输入字段 |

### 4.9 Trace、Parent 和关系字段

| 字段 | 控件 | 实施要求 |
|---|---|---|
| `extracted_fields.trace_text` | `readonly` | 保留完整原文，不允许直接编辑 |
| `trace_items[].category` | 固定枚举 `select` | 仅在明确 pointer/权限允许时修正 |
| `trace_items[].text_raw` | `readonly` | 原始补充信息不可改 |
| `trace_items[].service_date` | `date` | 只有需要且 pointer 明确时编辑 |
| `trace_items[].pax` | `number` | 缺失时可为空；不因缺失自动人工复核 |
| `trace_items[].notify_departments[]` | `multiselect` | 已知时可选 FO/HSK；不清楚时允许空数组 |
| `related_source_event_index` | `readonly` | 单一关系索引，只用于本次结果内部关联 |
| `related_source_event_indices[]` | `readonly` | Parent 或跨 Child Trace 的完整关系；禁止用户编辑索引 |
| `relationship_type` / `related_event_type` | `readonly` | 关系类型不选择任务卡 subtype |
| `requires_downstream_hard_validation` | `readonly` badge | 只展示系统硬校验要求 |

完整 Parent split 的全部 Child 补充请求仍使用现有 Trace 卡，通过 `related_source_event_indices[]` 展示全部 Child；不能只绑定 E1，也不能新增一个 Trace 路由。

### 4.10 Rooming List 和 TA Recorder

| 字段 | 控件 | 实施要求 |
|---|---|---|
| Rooming List target | `lookup` | 以通用 `case_keys` 为主；多个目标分开处理 |
| `list_evidence_type` | 默认只读 | 由证据识别，不允许任意切换卡型 |
| TA Recorder `group_code` | `lookup` / `text` | 只有缺失且 pointer 明确时编辑 |
| `ta_recorder_status` | `readonly` / `workflow_state` | 由信息系统后续状态更新，不是 AI 字段输入 |
| `source_rooming_list_task_id` | `readonly` 或隐藏 | 仅作 linked task 上下文 |

### 4.11 Manual Review 和系统字段

| 字段 | 控件 | 实施要求 |
|---|---|---|
| `manual_review.reason_code` | `readonly` badge | 不能由用户随意改原因 |
| `manual_review.visible_reason` | `readonly` | 只读说明 |
| `manual_review.blocking_points` | `readonly` list | 只读说明 |
| `manual_review.conflicting_points` | `readonly` list | 只读说明 |
| `manual_review.suggested_human_actions` | `readonly` list | 可转成页面操作提示，但不能直接当字段输入 |
| `manual_review.evidence_to_check` | `readonly` list | 引导查看证据 |
| `manual_review.known_fields` | `readonly` | 不直接编辑对象文本 |
| `manual_review.missing_fields[]` | 内部 pointer | 驱动控件，不作为普通输入框展示 |
| `review_status` | `workflow_state` | `pending → resolved`；只能通过完成字段校验后 Resolve |
| `review_resolution` | 系统生成、只读审计 | 保存 field overrides、用户和时间，不允许页面直接覆盖历史记录 |

### 4.12 只读字段

以下字段不得提供普通编辑控件：

- `source_message`、`source_message_id`、邮件主题、发件人、接收时间。
- `message_events[].event_type`、`event_role`、`current_or_history`、`source_event_index`。
- `attachments[]`、`file_references[]`、`context_used`、QBD sheet/row/highlight/raw evidence。
- `relevant_message_excerpt`、`text_raw`、`room_type_raw`、价格 raw marker。
- `unhandled_current_intents[]` 的原文和可见说明。
- S10、S99 和 `infrastructure_input_error` 的 route/status/error 字段。

---

## 5. 必须修正的旧 3.0 字段/枚举

请不要直接复制旧 Excel 的以下定义：

1. `Cancel Booking.cancel_object_type` 不再包含 `allotment_control_block`；整块 Parent/Allotment 取消使用 `Cancel Allotment`。
2. `Voucher Received.voucher_subtype` 不再包含 `bank_transfer_slip`；银行/现金/交易回执使用 `Payment Evidence`。
3. `Update Booking.extracted_fields.update_subtypes[]` 的旧长下拉不再作为路由选择；当前 Update 统一为 `update_booking_amendment`，动作只展示为结果标签。
4. `room_type` 不可作为自由修改后的唯一值；必须保留 raw，并用 PMS 目录选择 `pms_room_type_code`。
5. Rate Code 不得硬编码旧表中的完整 code 列表。
6. `Trace Text` 不得直接编辑原文。
7. Fix Charge 的旧 `additional_charge / unit_price` 与当前 `fixed_charge / unit` 语义不一致，必须以当前契约和实际 schema 为准。
8. `target_key`、`parent_source_event_index`、`post_confirm_action` 是旧字段/旧命名，需迁移到当前 `case_keys`、`related_source_event_index(es)` 和 `post_confirmation_intent`。
9. 不得继续生成或路由 `Note`、`Allotment Maintenance`、`Cancel Booking + linked_parent_release_after_child_split`。

---

## 6. 必须通过的验收用例

至少增加或复用以下测试：

| 编号 | 场景 | 必须验证 |
|---|---|---|
| UI-01 | generic `SUITE` 房型 | raw 只读；PMS code 使用当前目录下拉；未选时保留 manual review |
| UI-02 | 入住/离店日期修改 | 日期控件有效；`nights` 自动重算；非法日期阻止 Resolve |
| UI-03 | Rate Code | 不读取旧硬编码全集；使用配置目录；手工价独立数字输入 |
| UI-04 | Fix Charge | `fixed_charge/unit` 枚举正确；金额/数量为数字；raw/evidence 只读 |
| UI-05 | Cancel 路由 | `Cancel Booking` 不出现 Allotment；Allotment 使用 Cancel Allotment |
| UI-06 | Voucher/Payment | bank slip 不可从 Voucher 卡下拉选择；Payment Evidence 单独显示 |
| UI-07 | Update | 不允许用 `update_subtypes` 下拉切换业务卡型；before/after 结构化展示 |
| UI-08 | Parent key | Parent `group_code=block_code`；用户不能单独改 block_code |
| UI-09 | Parent split 房量差异 | Parent/Child 数量不等不自动显示冲突或人工复核 |
| UI-10 | 全 Child Trace | 使用现有 Trace 卡；展示完整 `related_source_event_indices[]`；不压缩到 E1 |
| UI-11 | raw evidence | 用户编辑后 raw 原文、附件引用和原 Agent payload 不变 |
| UI-12 | 同卡解阻 | 只创建一张卡；`pending → resolved → Preflight`；不创建第二张 normal task |
| UI-13 | 未知字段路径 | pointer 无法映射时 fail closed，不能临时创建任意输入控件 |
| UI-14 | S10/S99/基础设施错误 | 全部只读，不显示业务编辑控件 |

---

## 7. 交付要求

完成后请报告：

1. 实际修改的 Adapter/Frontend 文件。
2. 新增或更新的字段注册表及控件类型。
3. `missing_fields[] → control → field_overrides[]` 的实现位置。
4. 日期、房型、Rate Code、Fix Charge、Parent/Trace 关系校验位置。
5. 测试命令和测试结果。
6. 是否保持公开 JSON、40 路由和 MCP mapping 不变。
7. 未实现字段、路径不确定项和需要产品/业务确认的事项。

如果发现当前字段路径、item schema 或 Rate/Fix Charge 枚举仍未冻结，请保留只读/容错策略并报告，不要在前端自行发明新的公开字段。

---

## 最终边界

本任务的正确结果是：

```text
信息系统可以正确展示当前业务结果
信息系统只允许修改被 manual_review pointer 指定的业务字段
用户修改可审计、可校验、可回退到同一业务卡
原始 Agent 结果和证据不被覆盖
不新增业务路由、不改变 Prompt/Skill/MCP 契约
```