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

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

@@ -12,6 +12,7 @@
 | P0 | 任务列表接口 `GET /api/reservation/tasks` | 任务列表菜单、订单详情任务入口 | 已完成第一版，已补来源邮件会话字段和 `order_status` 筛选 |
 | P0 | 订单详情接口 `GET /api/reservation/orders/{orderId}` | 订单详情页 | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段和 V4 `order_overview` / `next_v4_action` / `related_source_messages[]` / `v4_order_tasks[].cards[]`，前端订单详情总览页已接入 |
 | P0 | 任务详情读取接口 `GET /api/reservation/tasks/{taskId}` | 任务详情页动态渲染 | 已完成第一版，已补来源邮件字段和 3.0 字段元数据 |
+| Done | V4 订单任务详情接口 `GET /api/reservation/order-tasks/{orderTaskId}` | V4 任务详情页 | 已完成第一版；页面展示顺序调整为 Basic Information、业务卡、SourceMessage Display，来源邮件正文通过 SourceMessage conversation 接口读取当前触发邮件 |
 | P0 | 任务详情操作接口 | 任务详情保存、确认、OPERA、审计 | 已完成；前端可直接接入 |
 | P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
 | 联调 | 演示数据 seed 接口 `POST /api/system/reservation/demo-data` | 本地 / test 前端页面看效果 | 已完成；仅 dev/test 受控使用 |
@@ -32,6 +33,7 @@
 | `GET /api/reservation/tasks` | 已完成第一版，已补来源邮件会话字段和所属订单状态筛选 | 可以 | `order_status` 按任务所属订单状态过滤；不传时保持当前全部任务列表行为。 |
 | `GET /api/reservation/orders/{orderId}` | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段、V4 总览和 V4 `v4_order_tasks[]` 时间线，前端订单详情总览页已接入 | 可以 | 暂无；`include_tasks=false` 时旧 `tasks[]`、V4 `v4_order_tasks[]` 和 `related_source_messages[]` 都返回空数组，`order_overview` 为空快照，`next_v4_action.action_type=NONE`。 |
 | `GET /api/reservation/tasks/{taskId}` | 已完成第一版，已补任务顶层来源邮件字段和 `fields[]` 3.0 元数据 | 可以 | 当前 Controller 不接收 `hotel_id`；如后续多酒店隔离需要前端显式传酒店上下文，请后端补可选入参或确认按 taskId 全局唯一即可。 |
+| `GET /api/reservation/order-tasks/{orderTaskId}` | 已完成第一版；Room Information 展示模型、复核态字段白名单和 Payment 附件安全摘要待补齐 | 可以，但 Room Information 业务化展示、复核态整卡编辑和 Payment 预览需后端补模型 / 摘要后再完整联动 | V4 任务详情页展示顺序为 Basic Information、业务卡、SourceMessage Display；Trace 卡 `department_code` 第一版固定为 `FO` / `HSK` / `FO+HSK` 三个下拉值，不调用 Department lookup，不开放自由输入。Room Information 下一阶段由后端返回业务展示模型：New 展示最终值，Update 展示 `change_summary[]` 和合并后的最终值，Cancel 展示本地订单投影只读；Nights 后端按酒店本地日期派生，Breakfast 前端为含早勾选框，Group Booking Status 显示 `TEN-Tentative` / `DEF-Definite` / `INQ-Inquiry`；New Booking 最终订单投影字段 `group_block_name` / `fit_name` 可编辑，Group 默认来自 `target_order.locator_value` 且 `locator_type=GROUP_CODE`，Fit 默认来自 `guest_name ?? target_order.locator_value`，但 Agent 原始 `target_order.locator_value` 只读且不被用户编辑回写。`REVIEW_REQUIRED` 仍是原业务卡复核态，问题字段红字提示，按钮统一显示“确认卡片”，前端内部调用 `review-resolution`。Rooming List 卡第一版只做事项确认，前端展示标题、状态、目标订单信息和“确认卡片”按钮，不做名单 rows、附件预览、Excel 生成或 PMS 导入。本接口仍不直接返回邮件正文或附件 URL。来源邮件卡正文限定为当前触发该 V4 order task 的那封 SourceMessage 正文，前端用 `source_message_summary.source_message_id` 调用 `GET /api/source-messages/{sourceMessageId}/conversation` 后定位当前邮件，默认长度折叠并可展开；缺少 `SOURCE_MESSAGE_ORIGINAL_READ` 或会话接口失败时降级展示安全摘要。Payment 卡下一阶段建议返回 `payment_attachments[]` 安全摘要，供前端展示图片缩略图 / 非图片文件列表；`attachment_ids[]` 第一版只读，不支持前端增删、替换或重新选择附件集合；实际大图预览和下载 URL 仍走 SourceMessage conversation。 |
 | `PUT /api/reservation/tasks/{taskId}/draft` | 已完成 | 可以 | 当前 Controller 不接收 `hotel_id`；如写操作需要酒店上下文幂等 / 权限校验，请后端补可选入参或请求体字段。 |
 | `POST /api/reservation/tasks/{taskId}/confirm` | 已完成 | 可以 | 当前 Controller 不接收 `hotel_id`；如写操作需要酒店上下文幂等 / 权限校验，请后端补可选入参或请求体字段。 |
 | `GET /api/reservation/tasks/{taskId}/audits` | 已完成 | 可以 | 当前 Controller 不接收 `hotel_id`；如审计查询需要酒店上下文隔离，请后端补可选入参。 |
@@ -43,13 +45,13 @@
 | `GET /api/source-messages/{id}` | 已完成单条安全摘要 | 可以 | 不能替代邮件会话全文接口。 |
 | `GET /api/source-messages/{id}/original` | 已完成单封原文权限读取 | 谨慎接入 | 必须带 Bearer token，需要同时拥有 `SOURCE_MESSAGE_READ` 和 `SOURCE_MESSAGE_ORIGINAL_READ`；只能读单封邮件，不能返回同一 conversation 全量邮件。 |
 | `GET /api/reservation/orders` | 已完成第一版 | 可以 | 默认查询全部订单状态；订单列表待处理展示使用 `open_work_item_count`；V4 普通业务已停止双写旧任务，旧 `open_task_count` 仅作为历史诊断计数。 |
-| `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版，已补 `html_body_sanitized` 和 `html_render_mode` | 可以 | 必须带 Bearer token，需要同时拥有 `SOURCE_MESSAGE_READ` 和 `SOURCE_MESSAGE_ORIGINAL_READ`；返回完整 text/html、后端清洗后的 HTML、媒体外链和关联订单 / 任务摘要；前端不传原文读取 key，页面展示优先使用 `html_body_sanitized`。 |
+| `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版，已补 `html_body_sanitized` 和 `html_render_mode` | 可以 | 必须带 Bearer token，需要同时拥有 `SOURCE_MESSAGE_READ` 和 `SOURCE_MESSAGE_ORIGINAL_READ`；返回完整 text/html、后端清洗后的 HTML、媒体外链和关联订单 / 任务摘要；前端不传原文读取 key，页面展示优先使用 `html_body_sanitized`。V4 Payment 卡图片大图预览和非图片下载也复用该权限链路，只能使用当前触发 SourceMessage 且被 `attachment_ids[]` 引用的附件。 |
 | `POST /api/system/reservation/demo-data` | 已完成 | 仅本地 / test 联调可用 | 默认关闭，必须后端配置访问口令；不能作为生产页面接口。 |
 | `POST /api/system/debug/eml-superagent-runs` | 已完成第一版 | 仅 dev/test Debug 页面可用 | 默认关闭，必须后端配置访问口令、阿里云 OSS 和 SuperAgent Open API；Debug 服务自身只展示 SuperAgent 结果，不直接创建订单和任务；如 SuperAgent 通过正式回调 / MCP 写入业务结果，V4 smoke 必须创建 V4 order task / cards，不再创建旧 `workflow_reservation_task`；已能识别旧 S000/S999 和新结构化 S10/S99。 |
 | `GET /api/source-message-conversations/{externalConversationId}` | 未发现后端实现 | 不可以 | 历史讨论过的候选路径，当前不提供；前端统一使用 `GET /api/source-messages/{sourceMessageId}/conversation`。 |
 | `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 历史候选路径，当前不提供。旧 S000/S999 和 V3 S10/S99 兼容数据通过 `SOURCE_MESSAGE_ONLY` 任务展示；V4 S10/S99 新数据走 V4 工作台和 `/api/reservation/source-notifications/{notificationId}`，不要再请求本候选路径。 |
 | `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |
-| `GET /api/reservation/lookups/accounts` / `room-types` / `rate-codes` | M002 V4 CP11 已实现 | 可以 | 用于 V4 任务卡下拉 / 搜索选择；Bearer token + `RESERVATION_TASK_READ` + 酒店访问权；支持 `hotel_id`、`keyword`、`page_num`、`page_size`，第一版只返回 ACTIVE 目录。 |
+| `GET /api/reservation/lookups/accounts` / `room-types` / `rate-codes` | M002 V4 CP11 已实现；Rate Code Account 范围过滤待补齐 | 可以，但 Rate Code 需后端新增过滤参数后再改前端联动 | 用于 V4 任务卡下拉 / 搜索选择；Bearer token + `RESERVATION_TASK_READ` + 酒店访问权；Account / Room Type 支持 `hotel_id`、`keyword`、`page_num`、`page_size`，只返回 ACTIVE 目录。Rate Code 下一阶段必须新增 `account_code`、`booking_type=GROUP/FIT` 必填过滤，只返回当前 Account + GROUP/FIT 适用候选。 |
 
 ## 3. 任务列表 / 工作台接口字段补齐
 
@@ -330,7 +332,7 @@ GET /api/reservation/orders/{orderId}
 | `result_type` / `ai_task_type` / `route_code` / `system_process_category` | V3 路由展示字段，和任务列表字段语义一致。 |
 | `order_overview` | V4 订单详情当前确认快照，只从已确认 V4 卡片派生；未确认 AI 建议不会进入这里。 |
 | `order_overview.account_code` / `account_name` / `market_code` / `source_code` | 来自已确认 Basic Information 卡；为空表示 Basic Information 尚未确认或无可靠确认值。 |
-| `order_overview.arrival_date` / `departure_date` / `rate_code` / `room_items[]` | 来自已确认 Room Information 卡；后出现的已确认卡会覆盖前面同字段。 |
+| `order_overview.arrival_date` / `departure_date` / `rate_code` / `room_items[]` | 来自已确认 Room Information 卡；后出现的已确认卡会覆盖前面同字段。下一阶段 Room Information 展示模型实现后，可继续从确认快照派生 `nights`、`breakfast_included` 和 Group Booking Status。 |
 | `order_overview.trace_card_status` / `rooming_list_card_status` / `payment_card_status` | 当前订单下对应业务卡最新状态，方便订单详情页展示是否还有待处理事项。 |
 | `order_overview.latest_confirmed_at` | 当前订单 V4 卡片最近确认 UTC 时间。 |
 | `next_v4_action` | 订单详情页下一步处理入口，口径与订单列表 V4 入口一致；前端点击后跳 `/reservation/order-tasks/{order_task_id}`。 |
@@ -511,11 +513,14 @@ GET /api/source-message-conversations/{externalConversationId}
 
 - 该接口已经完成权限收口：请求必须带 `Authorization: Bearer <access_token>`，当前用户必须同时拥有 `SOURCE_MESSAGE_READ` 和 `SOURCE_MESSAGE_ORIGINAL_READ`，后端会按 SourceMessage 实际所属酒店校验访问权。
 - “全部邮件”指同一个 `externalConversationId` 下的历史邮件、当前邮件和后续回复，不是只展示任务对应的单封来源邮件。
+- V4 任务详情页的 `SOURCE_MESSAGE_DISPLAY` 卡如果展示正文，只展示当前触发该 V4 order task 的那一封 SourceMessage；前端应按入口 `sourceMessageId` 在 `messages[]` 中定位对应 `id`，不要把整条会话全部铺在任务详情卡片里。
+- V4 Payment 卡如果展示付款凭证附件，前端先用任务详情里的 `payment_attachments[]` 安全摘要渲染 UI：图片显示缩略图，点击后通过本接口取得受控 `externalUrl` 打开大图预览；非图片统一展示文件名、类型、大小和下载按钮，不在卡片内嵌 PDF / Word / Excel 预览。
 - 邮件会话详情页需要展示完整正文或清洗后的 HTML、附件、内联图片、发件人展示值、发送 / 接收时间、主题和关联订单 / 任务。
 - 前端不在页面上做业务截断或隐藏；但仍只调用本项目后端接口，不直接访问邮箱、AgentBus、数据库或外部附件 URL Secret。
 - 原文读取审计由后端在该业务接口内部处理，actor 使用当前登录用户稳定 ID；前端不保存或传递 `X-TH-Hotel-Source-Original-Read-Key` 一类受控访问 key。
 - 2026-07-08 后端已新增 `html_body_sanitized` 和 `html_render_mode`；前端页面展示邮件 HTML 时应优先使用 `html_body_sanitized`，`html_body` 只作为原始内容兼容字段，不建议生产直渲。
 - 第一版仅处理 HTML 内容清洗；附件和内联图片 URL 来自本系统 OSS 服务，暂不做额外拦截或代理转换。
+- Payment 卡预览 / 下载匹配必须使用后端返回的附件 ID / `externalMediaId`，不能按文件名猜测；前端不得把 `externalUrl` 放进确认 payload、日志、错误上报、URL query 或 localStorage。
 
 建议入参：
 
@@ -1193,4 +1198,6 @@ POST /api/reservation/tasks/{taskId}/order-binding
 - `manual-review-resolutions` 成功响应中的 `opera_operations[]` 数量请后端最终确认；前端不写死两条，只按返回内容刷新展示。
 - 系统管理菜单树增强接口已完成：`GET /api/admin/menus/tree`、`PUT /api/admin/menus/tree-order`。
 - Manual Invoice 第一阶段的客户 / 联系人目录来源、模板初始文件、VAT 配置和生成记录是否必须落库，已在 M009 中列为开发前确认项。
-- V4 真实目录与 Lookup API 第一版已在后端 CP11 落地，前端 CP12 已接入 `GET /api/reservation/lookups/accounts`、`GET /api/reservation/lookups/room-types`、`GET /api/reservation/lookups/rate-codes` 用于 V4 字段选择控件。前端按 `options_source` 选择接口，空列表 / stale / warnings 只做非阻塞提示，确认和复核仍只提交 code；真实 PMS 同步、目录管理后台和 SuperAgent 目录机器接口仍后置。
+- V4 真实目录与 Lookup API 第一版已在后端 CP11 落地，前端 CP12 已接入 `GET /api/reservation/lookups/accounts`、`GET /api/reservation/lookups/room-types`、`GET /api/reservation/lookups/rate-codes` 用于 V4 字段选择控件。前端按 `options_source` 选择接口，空列表 / stale / warnings 只做非阻塞提示，确认和复核仍只提交 code；Rate Code 下一阶段已确认要按 Account + `booking_type` 过滤，前端需等后端新增 `account_code`、`booking_type` 参数和适用性校验后再联动，不能自行硬编码 OWNER RATE Excel；真实 PMS 同步、目录管理后台扩展和 SuperAgent 目录机器接口仍后置。
+- V4 Payment 附件预览下一阶段已确认：后端需补 `payment_attachments[]` 安全摘要；前端图片缩略图 + 点击大图预览，非图片文件列表 + 下载；预览和下载仍走 SourceMessage conversation 原文权限链路。`attachment_ids[]` 第一版作为 Agent 返回的只读业务事实，前端只展示并确认卡片，不做附件集合编辑。
+- V4 复核态交互已确认：`REVIEW_REQUIRED` 不新建独立复核任务卡，仍在原业务卡内编辑当前卡 `fields[]` 白名单业务字段；问题字段红字提示；主按钮文案统一为“确认卡片”，但前端内部调用 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution`。