docs: 收口 V4 任务卡展示与确认口径

docs/project/requirements/M002-v4-agent-callback-field-contract.md

@@ -16,7 +16,7 @@
 
 本契约用于后续 M002 V4 主流程设计、后端领域建模、前端页面模型、Adapter / MCP Schema 对齐和 SuperAgent 联调。当前后端已按本文完成 V4 入站解析和多卡模型基线：能识别 V4 包、校验关键契约、保存 AI transition / 任务卡原始 payload，并把可映射的六类 event 写入 V4 订单任务和任务卡模型。
 
-V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP14 和停止旧任务双写 checkpoint，表结构、Entity、Mapper、Repository、SuperAgent V4 入站写入、V4 查询、普通卡片确认、S10/S99 ack、V4 复核解阻、数据库目录、Account / Room Type / Rate Code Lookup API、目录管理后台 CP1 后端接口、订单列表 V4 继续处理入口字段，以及 V4 普通业务不再创建旧 `workflow_reservation_task` 已实现。真实 PMS 同步仍后置，方案见 `M002-v4-real-catalog-lookup-api-design.md`。
+V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP14 和停止旧任务双写 checkpoint，表结构、Entity、Mapper、Repository、SuperAgent V4 入站写入、V4 查询、普通卡片确认、S10/S99 ack、V4 复核解阻、数据库目录、Account / Room Type / Rate Code Lookup API、目录管理后台 CP1 后端接口、订单列表 V4 继续处理入口字段，以及 V4 普通业务不再创建旧 `workflow_reservation_task` 已实现。下一阶段已确认 Rate Code 需要按订单级 Account + `booking_type`（GROUP / FIT）过滤和校验，当前实现仍是酒店级 Rate Code 目录；Room Information 卡需要补 New / Update / Cancel 展示模型、Nights / Breakfast 派生、Group Booking Status 和 Rooming List 确认联动，但这些不扩大 SuperAgent 输入字段；Payment 卡需要补付款凭证附件安全摘要和预览 / 下载联动；真实 PMS 同步仍后置，方案见 `M002-v4-real-catalog-lookup-api-design.md`。
 
 当前已确认开发阶段数据可以清空，因此 M002 V4 后续可以按新模型重建，不要求兼容旧任务数据、旧草稿、旧 OPERA 模拟、旧 `S000/S999`、旧 Fallback 或旧 `case_keys`。
 
@@ -154,7 +154,7 @@ SuperAgent、Adapter、MCP Schema 和信息系统最终必须使用完全相同
 
 URL 由上游邮件监听或文件存储层提供。Agent 只原样转发，不生成、拼接、刷新或签发 URL。
 
-Payment 只按 `attachment_ids[]` 引用附件，不在 Event 内复制文件名、类型、URL 或完整附件对象。
+Payment 只按 `attachment_ids[]` 引用附件，不在 Event 内复制文件名、类型、URL 或完整附件对象。前端 Payment 卡的缩略图、预览和下载由本系统根据 `attachment_ids[]` 匹配当前 SourceMessage 附件后展示；这不改变 SuperAgent 输入结构。
 
 ## 7. order_contexts
 
@@ -199,7 +199,7 @@ Agent 给出非空 `account_code`，但信息系统运行时目录不存在该
 - Market / Source：由 Account 派生，当前分别为 `LEISURE` / `TRAVEL_AGENT`。
 - SuperAgent 不需要输出 `market_code`、`source_code`、`account_name`，也不要输出显示名称替代 `account_code`。
 - 如果 SuperAgent 输出的 `account_code` 不在上述目录，后端会创建 `REVIEW_REQUIRED` Basic Information 卡，并在 `validation_errors_json` / 查询 `fields[].validation_errors` 中返回目录错误。
-- 如果 SuperAgent 输出的业务卡 `room_items[].room_type_code` 或 `rate_code` 不在当前酒店数据库目录，后端会创建 `REVIEW_REQUIRED` 业务卡，并在 `validation_errors_json` / 查询 `fields[].validation_errors` 中返回目录错误；用户可通过 V4 复核解阻接口提交对应字段 pointer 修正。
+- 如果 SuperAgent 输出的业务卡 `room_items[].room_type_code` 或 `rate_code` 不在当前酒店数据库目录，后端会创建 `REVIEW_REQUIRED` 业务卡，并在 `validation_errors_json` / 查询 `fields[].validation_errors` 中返回目录错误；下一阶段 `rate_code` 还必须属于该 `order_ref` 的 Basic Information Account + 当前 event `target_order.booking_type` 的适用关系，否则同样进入 `REVIEW_REQUIRED`。用户可通过 V4 复核解阻接口提交对应字段 pointer 修正。
 
 ## 8. message_events 公共字段
 
@@ -336,7 +336,7 @@ Fit 条件字段：
 | --- | --- | --- | --- |
 | `arrival_date` | Group / Fit | 是，可为 `null` | 入住日期，酒店本地日期 |
 | `departure_date` | Group / Fit | 是，可为 `null` | 离店日期，酒店本地日期 |
-| `rate_code` | Group / Fit | 是，可为 `null` | 订单级 Rate Code |
+| `rate_code` | Group / Fit | 是，可为 `null` | 订单级 Rate Code；下一阶段必须属于该订单 Account + `booking_type` 的适用范围 |
 | `room_items[]` | Group / Fit | 是 | 完整房型清单 |
 | `room_items[].room_type_code` | Group / Fit | 是，可为 `null` | 受控 RoomType code |
 | `room_items[].room_count` | Group / Fit | 是 | 房量，正整数 |
@@ -347,9 +347,10 @@ Fit 条件字段：
 
 - Group Code 已在 `target_order.locator_value`，同时作为 Block Name。
 - Fit Booking Code 已在 `target_order.locator_value`。
-- Agent 不输出 `booking_name`、独立 `booking_code`、Nights、Breakfast、Group Booking Status、Adult、Block ID 或 Confirmation Number。
+- Agent 不输出 `booking_name`、独立 `booking_code`、Nights、Breakfast、Group Booking Status、Adult、Block ID 或 Confirmation Number；这些属于本系统 Room Information 展示模型、系统派生字段、本地订单投影或未来 PMS 返回。New Booking 页面允许用户编辑最终订单投影字段 `group_block_name` / `fit_name`，但不改写 Agent 原始 `target_order.locator_value`。
 - `proposal` 不再使用布尔字段，改为 `booking_scenario=STANDARD | PROPOSAL`。
-- Adult 由信息系统按 RoomType 映射派生。
+- Adult 第一版不在 Room Information 卡展示。
+- New Group 的 Group Booking Status 由本系统默认 `TEN`，`booking_scenario` 只作为 Agent 场景参考，不映射 Group Booking Status。
 - `room_items=[]` 只能表示已识别 New 但完整房型清单未解决，并必须 `manual_review=true`。
 
 ## 12. UPDATE_BOOKING
@@ -399,7 +400,7 @@ Fit 条件字段：
 - 不使用空数组表达“无法形成完整房型清单”。
 - 如果修改后整笔订单不再保留任何房间，应按整单 `CANCEL_BOOKING` 处理，而不是提交空的 Update 房型清单。
 - Rate Code 不允许出现在 Update。若 Agent 仍输出，按业务契约错误处理，不能静默忽略后继续执行。
-- Before、原订单和完整最新订单由信息系统查单后生成，不由 Agent 输出。
+- Before、原订单和完整最新订单由信息系统查单后生成，不由 Agent 输出。Room Information 展示模型中的 `change_summary[]`、最终值、Nights 和 Breakfast 由本系统按本地订单投影 + Agent `after` 合并后派生。
 
 ## 13. CANCEL_BOOKING
 
@@ -423,7 +424,7 @@ Fit 条件字段：
 - `CANCEL_BOOKING` 本身已经表示整单取消。
 - 不输出 `cancel_scope`、`cancel_reason`、`after` 或当前订单快照。
 - 减少房量、删除房型、修改日期或修改 Fit Name 属于 Update，不是 Cancel。
-- 当前订单快照由信息系统查单后只读展示。
+- 当前订单快照由信息系统查单后只读展示。Cancel 的 Room Information 卡只读显示本地订单投影，不由 Agent 输出当前值。
 
 ## 14. TRACE_RESERVATION_NOTES
 
@@ -462,7 +463,7 @@ Fit 条件字段：
 | `trace_items[]` | Trace | 是 | 同一订单一张 Trace 卡，卡内多条事项 |
 | `item_type` | Trace item | 是 | `GENERAL` 或 `EXTRA_BED` |
 | `text` | GENERAL | 是，可为 `null` | 普通备注内容 |
-| `department_code` | GENERAL / EXTRA_BED | 是 | 信息系统受控部门或组合部门 code |
+| `department_code` | GENERAL / EXTRA_BED | 是 | 第一版固定为 `FO` / `HSK` / `FO+HSK`，分别表示前厅、客房和前厅 + 客房组合 |
 | `target_room_type_code` | EXTRA_BED | 是，可为 `null` | 加床目标房型 |
 | `extra_bed_room_count` | EXTRA_BED | 是 | 加床房间数量 |
 
@@ -470,7 +471,7 @@ Fit 条件字段：
 
 - EXTRA_BED 不输出自由 `content`；信息系统固定显示 `SET EXTRA BED`。
 - EXTRA_BED 不输出 `adult_after_extra_bed`；信息系统按当前 / 基础 Adult +1 计算，页面确认前允许用户纠正。
-- Department code 由 Agent 必传，值来自信息系统维护的受控部门目录或组合目录。
+- Department code 由 Agent 必传。第一版先固定为 `FO`、`HSK`、`FO+HSK` 三个值，不接受自由文本；正式 Department 目录和 lookup API 后续单独扩展。
 - 加床目标房型不在当前订单时，Trace 卡不能确认，并提示用户核对目标房型和订单关联。
 - 只有订单定位本身不可信时，才触发共享查单门槛阻断整个订单上下文。
 
@@ -498,7 +499,8 @@ Fit 条件字段：
 - 不输出 `rows[]`、逐人名单、同住分组、18 列、Excel 或 PMS 导入参数。
 - 当前也不要求 Rooming List Event 单独输出 `attachment_ids[]`。
 - 原附件已经在包级 `source_message.attachments[]`，只在邮件展示卡查看。
-- 页面固定展示 12 个必填字段表头的标准表格示意，当前内容不代表附件已经真实转换。
+- 页面第一版只展示 Rooming List 事项卡和“确认卡片”按钮；用户确认表示已人工处理该事项。
+- Rooming List 卡确认不代表名单已解析、Excel 已生成或 PMS 已导入。
 - 未来取得 PMS API 后，按真实接口重新冻结住客与执行参数，不直接恢复历史草案中的 `rows[]`。
 
 ## 16. PAYMENT
@@ -528,6 +530,7 @@ Fit 条件字段：
 - 一笔订单多份凭证放在同一个 Payment Event。
 - `attachment_ids[]` 没有业务顺序。
 - Payment 不输出 `account_code`、金额、付款日期、付款人、交易号、银行账号、付款状态、Department 或完整附件对象。
+- Payment 卡展示层下一阶段可由后端补 `payment_attachments[]` 安全摘要：图片显示缩略图并支持点击大图预览，非图片显示文件列表并提供下载；附件外链不进入 V4 任务详情普通 payload，只能通过 SourceMessage 原文权限链路读取。
 
 没有任何凭证附件时，不能创建正常的空 Payment 卡：
 
@@ -629,17 +632,18 @@ true
 
 ## 20. 受控 code 目录
 
-Account、RoomType、RateCode、Department 的目录由信息系统或其主数据服务统一维护，并作为唯一事实源。
+Account、RoomType、RateCode 的目录由信息系统或其主数据服务统一维护，并作为唯一事实源。Department 第一版先固定 `FO`、`HSK`、`FO+HSK` 三个 code；正式 Department 目录、系统管理维护和 lookup API 后续单独扩展。
 
 规则：
 
-- SuperAgent 只能输出目录中已有的稳定 code。
+- SuperAgent 只能输出目录中已有的稳定 code；Trace `department_code` 在 Department 目录未正式落地前只能输出 `FO`、`HSK`、`FO+HSK`。
+- SuperAgent 输出 `rate_code` 时必须结合当前 `order_ref` 的 `basic_information.account_code` 和 event `target_order.booking_type` 判断候选范围；本阶段只要求 Account + GROUP/FIT，不要求按房型、入住日期或价格计算。
 - 不允许输出自由文本或自行创造 code。
 - Agent 无法可靠匹配时，按对应业务字段的未解决规则处理。
 - Agent 输出非空 code、但信息系统目录不存在该值时，属于目录校验或契约问题。
 - Market 和 Source 由信息系统根据订单级 `account_code` 派生，不由 Agent 输出。
 
-当前项目接受“SuperAgent 确定后把目录给本系统”的落地方式。第一阶段已用固定种子目录完成开发闭环；真实目录、系统管理维护、PMS / OPERA / OHIP 同步、前端 lookup API、缓存、权限和兜底策略已在 `M002-v4-real-catalog-lookup-api-design.md` 中设计。该设计不改变 SuperAgent V4 输入契约：SuperAgent 仍只输出稳定 code，不输出显示名或自由文本。
+当前项目接受“SuperAgent 确定后把目录给本系统”的落地方式。第一阶段已用固定种子目录完成开发闭环；真实目录、系统管理维护、PMS / OPERA / OHIP 同步、前端 lookup API、缓存、权限和兜底策略已在 `M002-v4-real-catalog-lookup-api-design.md` 中设计。Account 范围 Rate Code 不改变 SuperAgent V4 输入结构：SuperAgent 仍只输出稳定 `rate_code`，不输出显示名、价格或目录完整对象；适用性由本系统后端目录服务最终校验。
 
 ## 21. 后端 V4 建模建议
 
@@ -691,7 +695,7 @@ AI 回调包
 1. SuperAgent、Adapter、MCP Schema 和信息系统 DTO 使用同一份 V4 Schema。
 2. `body_content_type` 的来源是 AgentBus / 邮件监听层还是 Adapter 派生。
 3. `dispatch_run_id`、超时、错误 channel 和技术失败查询入口如何落地。
-4. Account、RoomType、RateCode、Department 目录如何提供给 SuperAgent，仍需在真实目录实现后确认是离线目录包还是独立机器接口。
+4. Account、RoomType、RateCode 目录如何提供给 SuperAgent，仍需在真实目录实现后确认是离线目录包还是独立机器接口；Department 暂按 `FO`、`HSK`、`FO+HSK` 固定枚举处理。
 5. 如需 `event_id` 或幂等键，应作为 transport 字段设计，不作为业务页面字段。
 
 ## 24. 当前开发结论
@@ -717,6 +721,8 @@ AI 回调包
 - V4 `route_code=S10/S99` 写入 `workflow_reservation_v4_source_notification` 来源通知模型；旧 `SOURCE_MESSAGE_ONLY` 只读特殊任务仅保留给 V3 S10/S99 和旧 S000/S999 兼容数据。
 - 普通业务包要求 `route_code=null`，并按 `message_events[]` 数组顺序处理。
 - 第一版识别六类 `event_type`：`NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT`。
+- `ROOM_INFORMATION` 卡只由 `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING` 触发；Nights、Breakfast、Group Booking Status、Block ID、Confirmation Number 和本地当前值展示均由本系统后端展示模型派生或查询，不扩大 SuperAgent 输出字段。
+- `ROOMING_LIST` 第一版只表达 Rooming List 事项需要人工处理，确认卡片即表示人工已处理；不承载名单解析、附件预览、Excel 生成或 PMS 导入语义。
 - 能映射到现有稳定任务卡的 event 会创建业务任务，并在 `ai_payload_json` 中保存 `v4_source_message`、`v4_order_context`、`v4_message_event`、`route_code`、系统处理分类和 `field_contract_version=20260718-v4`。
 - V4 入站校验和路由已拆分为独立 Validator / Router，主业务 service 只负责编排、幂等和落库。
 - V4 包级契约错误在 SourceMessage 可定位时只写 `adapter_contract_error` transition，不创建订单、任务或用户可处理卡。
@@ -741,13 +747,14 @@ AI 回调包
 - `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm` 确认 V4 卡片，强制 Bearer 登录、`RESERVATION_TASK_CONFIRM`、酒店访问权和 version 并发校验。
 - `POST /api/reservation/source-notifications/{notificationId}/ack` 确认 V4 S10/S99 来源通知已读 / 已处理，强制 Bearer 登录、`RESERVATION_TASK_CONFIRM`、酒店访问权和 version 并发校验。
 - CP7 已完成 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution` 复核解阻和复核场景订单归属确认。
-- CP8 已完成 Account / Room Type / Rate Code 目录校验和 V4 任务卡 `fields[]` 白名单；CP11 已把固定种子导入数据库目录并开放 Account / Room Type / Rate Code lookup API；CP13 已完成目录管理后台 CP1；CP14 已在 `GET /api/reservation/orders` 补齐 V4 下一步处理入口字段。真实 PMS 同步仍未实现。
+- CP8 已完成 Account / Room Type / Rate Code 目录校验和 V4 任务卡 `fields[]` 白名单；CP11 已把固定种子导入数据库目录并开放 Account / Room Type / Rate Code lookup API；CP13 已完成目录管理后台 CP1；CP14 已在 `GET /api/reservation/orders` 补齐 V4 下一步处理入口字段。Account + booking type 过滤 Rate Code 已确认为下一阶段待实现；真实 PMS 同步仍未实现。
 
 当前仍未完成：
 
-- 普通 V4 业务包暂时仍保留旧 V3 任务状态、草稿和 OPERA 模拟骨架兼容，便于前端过渡；V4 写接口和前端页面完成后再逐步废弃旧链路。
+- Account + booking type 过滤 Rate Code 的后端 lookup / 适用性校验和前端联动。
+- Payment 卡付款凭证附件安全摘要、图片缩略图 / 大图预览、非图片文件列表 + 下载联动。
 - 尚未接入真实 PMS / OPERA / OHIP。
-- 尚未改造前端 V4 页面模型。
+- SuperAgent 目录机器接口和生产目录同步方案仍后置。
 
 ## 26. 后端 CP2 设计文档状态