前端调整V4预订事项用户化展示

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

@@ -159,6 +159,8 @@ POST /api/auth/logout
 
 订单详情已经补齐并完成前端接入 V4 订单页总览字段：`order_overview`、`next_v4_action`、`related_source_messages[]` 和增强后的 `v4_order_tasks[].cards[]`。订单详情页定位为订单视角总览，不要在订单详情页直接编辑、确认或复核任务卡；点击 `next_v4_action.order_task_id` 或时间线 `order_task_id` 后进入 `/reservation/order-tasks/{orderTaskId}` 对应的 V4 订单任务详情页处理。
 
+订单详情页默认面向普通酒店员工，不面向开发 / 测试。页面标题、摘要和时间线区域应使用业务语言：`order_overview` 显示为“当前确认快照”或“订单信息总览”，`next_v4_action` 显示为“下一步处理”，`related_source_messages[]` 显示为“关联来源邮件”，`v4_order_tasks[]` 显示为“处理记录”或“来源邮件处理记录”，`cards[]` 显示为事项状态摘要。不要在默认主信息层级展示 `V4`、`order_id`、`order_task_id`、`card_id`、`source_message_id`、`action_type`、`action_status`、payload 字段名、route 或内部状态码；确需排查时只能放入折叠区或受控调试模式。订单详情主区域不展示确认 / 复核按钮，所有办理动作仍跳转到 V4 任务详情页。
+
 `order_overview` 只从已确认 V4 卡片派生：Basic Information 未确认时 Account / Market / Source 为空；Room Information 未确认时日期、Rate Code、房型房量为空。前端不要把未确认卡片 display payload 反推成订单事实。
 
 订单详情新增的 V4 `v4_order_tasks[]` 每项只返回订单任务安全摘要：
@@ -496,7 +498,15 @@ RESERVATION_ROOMING_LIST_GENERATE
 后端已提供以下 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/tasks` 默认面向普通酒店员工，页面名称和空态应使用“待处理预订事项”“预订事项”“暂无需要处理的预订事项”等业务语言，不直接显示“V4 工作台”“Order Task 列表”“任务卡列表”等技术描述。
+- 任务列表默认视图优先展示需要用户处理的事项，例如待确认、需要复核、待确认已读的来源通知；已完成事项保留筛选入口，但不作为默认工作队列。`ORDER_TASK` 显示为“预订事项”，`SOURCE_NOTIFICATION` 显示为“来源通知”或“需查看邮件”，不直接展示内部 `item_type` code。
+- 任务列表普通筛选建议为“全部”“待处理”“需要复核”“已完成”“来源通知”；技术筛选如 `item_type`、`order_task_status`、`card_status`、`route_code`、`system_process_category` 只能放在高级筛选或受控调试模式，不作为默认筛选文案。
+- 任务类型标签应映射为业务名称，例如新预订、修改预订、取消预订、付款凭证、跟进事项、房表事项；前端业务判断仍使用稳定 code，不使用展示文案反推类型。
 - `/reservation/order-tasks/{orderTaskId}` 应使用 `GET /api/reservation/order-tasks/{orderTaskId}` 展示 `basic_information_card`、`business_cards[]`、`source_message_card`、`card_counts`、`order_task` 摘要和 `adapter_contract_errors[]` 只读诊断；页面顺序固定为 Basic Information、业务卡、SourceMessage Display。
+- `/reservation/order-tasks/{orderTaskId}` 默认面向普通酒店员工，页面定位是“订单事项办理页”，不是“V4 任务卡模型调试页”。前端默认主标题、摘要和业务事项区域不得直接展示 `V4`、Task Card 模型、`order_task_id`、`card_id`、`order_ref`、`source_event_index`、`version`、JSON Pointer、`write_target`、payload 字段名、`route_code`、adapter 诊断或内部状态码；这些字段只能用于路由、提交、并发和排查，确需展示时放入折叠区或受控调试模式。
+- V4 任务详情普通用户文案应使用业务名称：Basic Information 展示为“预订基础信息”，Room Information 展示为“房型与日期”或“房型信息”，Payment 展示为“付款凭证”，Trace 展示为“跟进事项”，Rooming List 展示为“房表事项”，SourceMessage Display 展示为“来源邮件”。`PENDING_CONFIRM`、`REVIEW_REQUIRED`、`CONFIRMED`、`RESOLVED`、`OPEN`、`COMPLETED` 等稳定 code 只能作为业务判断依据，页面应映射为“待确认”“需要复核”“已确认”“复核已完成”“待处理”“已完成”等用户可理解文案。
+- V4 任务详情顶部摘要优先回答“这封邮件识别出了什么事项、当前还有什么要处理、下一步该点哪里”，不要把卡片数量、数据库 ID 或模型字段作为第一视觉层级。已完成事项可以折叠为摘要，待处理和需复核事项应突出；来源邮件固定在业务事项之后，默认折叠正文。
+- 每张事项卡的主动作按钮放在该事项卡右侧，和状态同区域展示；移动端空间不足时可放到卡片底部右对齐。不要做页面底部统一确认按钮，避免用户误以为一次确认整页。`REVIEW_REQUIRED` 仍显示“确认卡片”，但前端内部调用 `review-resolution`。
 - `/reservation/source-notifications/{notificationId}` 应使用 `GET /api/reservation/source-notifications/{notificationId}` 展示 S10/S99 来源通知详情，并通过 `POST /api/reservation/source-notifications/{notificationId}/ack` 确认已读 / 已处理。
 - V4 审计时间线应分别调用 `GET /api/reservation/order-tasks/{orderTaskId}/audits` 和 `GET /api/reservation/source-notifications/{notificationId}/audits`；按钮权限使用 `/api/auth/me.permissions[]` 中的 `RESERVATION_AUDIT_READ`。
 - V4 卡片确认应使用 `POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm`，请求带 `version`；前端只从当前卡 `fields[]` 中挑选 `editable=true`、`raw_readonly!=true`、`write_target=confirmed_payload` 的字段构造 `confirmed_payload`。
@@ -507,6 +517,7 @@ RESERVATION_ROOMING_LIST_GENERATE
 - Trace 卡第一版使用稳定业务展示模型：普通事项内容字段统一为 `trace_items[].text`，不要使用或提交 `trace_items[].content`；`GENERAL` 的可编辑字段为 `/trace_items/{index}/text` 和 `/trace_items/{index}/department_code`，`EXTRA_BED` 的可编辑字段为 `/trace_items/{index}/target_room_type_code`、`/trace_items/{index}/extra_bed_room_count` 和 `/trace_items/{index}/department_code`。`department_code` 固定下拉 `FO`、`HSK`、`FO+HSK`，后端在对应字段返回 `options_source=reservation_v4_trace_department_fixed` 和 `fixed_options[]`；`target_room_type_code` 使用 Room Type lookup，`extra_bed_room_count` 为正整数；确认和复核都只提交 `fields[]` 暴露的白名单 pointer，不要提交 `target_order`、邮件正文、附件 URL、raw evidence 或 Agent 原始 payload。
 - 前端不展示 `ai_payload_json`、附件 URL、raw evidence 或 SuperAgent 原始 payload；V4 任务详情页底部 `SOURCE_MESSAGE_DISPLAY` 可展示当前触发该 order task 的 SourceMessage 正文，但必须通过 `GET /api/source-messages/{sourceMessageId}/conversation` 读取并写原文读取审计，不能要求 `GET /api/reservation/order-tasks/{orderTaskId}` 直接返回正文。Payment 卡如展示付款凭证图片，也必须通过同一会话接口获取受控附件 URL：卡片内显示缩略图，点击打开大图预览；非图片只显示文件列表和下载。HTML 邮件优先渲染 `html_body_sanitized`，缺少原文权限或接口失败时降级为安全摘要和“查看邮件会话”入口。
 - V4 来源消息卡读取 `attachments`、`uploaded_media`、`file_references` 时，只允许展示附件名称、类型和大小等安全摘要；如果后端 payload 中异常出现 `https://`、`oss://`、`s3://` 等直接 URL 字符串，前端必须替换为“未命名附件”或隐藏，不得把 URL 渲染到普通业务页面。`SOURCE_MESSAGE_DISPLAY` 的邮件正文默认做长度折叠，用户可展开全文。
+- 技术折叠区或调试模式也必须遵守同一安全边界：不得展示邮件正文、HTML、附件 URL、AI 原始 payload、raw evidence、PMS 原始响应、Secret、Token 或跨酒店数据。若后续需要专门 Debug 视图，应按 `FRONTEND_DEBUG` 能力和安全边界另行登记，不要把 Debug 信息混入普通业务办理页。
 - V4 主流程不调用旧 V2/V3 草稿、旧任务确认、旧同卡复核接口，也不展示 OPERA 模拟操作入口。
 - 2026-07-20 测试机 smoke 注意：订单详情页依赖 `GET /api/reservation/orders/{orderId}` 返回 `order_overview`、`next_v4_action`、`related_source_messages[]` 和 `v4_order_tasks[].cards[]`。如果测试机响应仍只有旧 `order`、`tasks[]`、基础 `v4_order_tasks[]` 和 `warnings`，应先确认测试机后端是否部署了包含 M002 V4 CP15.1 的最新包；前端不要为了该旧响应重新做兼容逻辑，避免把部署问题固化成页面分支。
 

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

@@ -53,6 +53,30 @@
 | `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |
 | `GET /api/reservation/lookups/accounts` / `room-types` / `rate-codes` | M002 V4 CP11 已实现；M002-V4-owner-rate-catalog-data-alignment 已收敛 Room Type / Rate Code 数据；2026-07-21 结论是 Rate Code 第一阶段暂不做 Account 范围过滤 | 可以 | 用于 V4 任务卡下拉 / 搜索选择；Bearer token + `RESERVATION_TASK_READ` + 酒店访问权；Account / Room Type / Rate Code 支持 `hotel_id`、`keyword`、`page_num`、`page_size`，只返回 ACTIVE 目录。Room Type 当前固定初始化为 `RM2`、`RM3`、`RM4`、`SU1`、`SU2`、`SU3`；Rate Code 当前按酒店级目录返回 OWNER RATE 40 个规范化 code；未来如新增 Account 适用关系，再由后端扩展 `account_code` / `booking_type` 过滤参数。 |
 
+## 2.2 V4 工作台、订单详情和任务详情页用户化展示口径
+
+2026-07-21 已确认：V4 工作台 / 任务列表、订单详情页和任务详情页默认面向普通酒店员工，不面向开发 / 测试。当前后端 `GET /api/reservation/workbench-items`、`GET /api/reservation/order-tasks`、`GET /api/reservation/orders/{orderId}` 和 `GET /api/reservation/order-tasks/{orderTaskId}` 已返回前端完成第一版用户化展示所需的业务数据、订单确认快照、下一步入口、`fields[]` 白名单、`availability`、来源邮件摘要和安全 payload；本 checkpoint 原则上不要求后端新增接口或改变入站 / 确认 / 复核模型。
+
+前端下一轮 UX 重构应按以下口径实现：
+
+- 工作台 / 任务列表页面定位为“待处理预订事项列表”或“预订事项工作台”，不是“V4 模型工作台”。
+- 任务列表默认视图优先展示待确认、需要复核、待确认已读的来源通知；已完成事项保留筛选入口，不作为默认工作队列。
+- 任务列表普通筛选建议为“全部”“待处理”“需要复核”“已完成”“来源通知”。技术筛选如 `item_type`、`order_task_status`、`card_status`、`route_code`、`system_process_category` 可放入高级筛选或受控调试模式，不作为默认筛选文案。
+- `ORDER_TASK` 用户可见文案为“预订事项”，`SOURCE_NOTIFICATION` 用户可见文案为“来源通知”或“需查看邮件”；新预订、修改预订、取消预订、付款凭证、跟进事项、房表事项等任务类型应显示业务名称，不直接展示内部 code。
+- 列表行主动作使用“继续处理”“查看详情”“确认已读”等业务语言；空态使用“暂无需要处理的预订事项”，不显示内部模型空态。
+- 订单详情页定位为“订单总览页”，不是 V4 时间线调试页；`order_overview` 显示为“当前确认快照”或“订单信息总览”，`next_v4_action` 显示为“下一步处理”，`related_source_messages[]` 显示为“关联来源邮件”，`v4_order_tasks[]` 显示为“处理记录”或“来源邮件处理记录”，`cards[]` 显示为事项状态摘要。
+- 订单详情页标题优先显示订单业务名、Group Code、Confirmation Number 或用户可理解订单名称；不把数据库 `order_id`、V4 字段名、`order_task_id`、`card_id`、`source_message_id`、`action_type`、`action_status` 等作为主信息层级。订单详情不展示确认 / 复核按钮，所有办理动作仍跳转到任务详情页。
+- 页面定位为“订单事项办理页”，不是“V4 任务卡模型调试页”。
+- 主标题、顶部摘要和业务事项区域使用普通用户可理解文案，不直接展示 `V4`、Task Card 模型、`order_task_id`、`card_id`、`order_ref`、`source_event_index`、`version`、JSON Pointer、`write_target`、payload 字段名、`route_code` 或内部状态码。
+- 技术字段可以继续用于路由、提交、并发校验、错误定位和自动化测试；确需展示时只能放在“技术信息”折叠区或受控调试模式，不得占据默认主信息层级。
+- 用户可见业务名称建议：Basic Information = 预订基础信息；Room Information = 房型与日期 / 房型信息；Payment = 付款凭证；Trace = 跟进事项；Rooming List = 房表事项；SourceMessage Display = 来源邮件。
+- 用户可见状态建议：`PENDING_CONFIRM` = 待确认；`REVIEW_REQUIRED` = 需要复核；`CONFIRMED` = 已确认；`RESOLVED` = 复核已完成；`OPEN` = 待处理；`COMPLETED` = 已完成。前端业务判断仍使用稳定 code，不使用展示文案反推状态。
+- 顶部摘要应优先表达“这封邮件识别出了什么事项、当前还有什么要处理、下一步该点哪里”；已完成事项可以折叠为摘要，待处理和需复核事项应突出。
+- 每张事项卡的主动作按钮放在该事项卡右侧，和状态同区域展示；移动端空间不足时可放到卡片底部右对齐。不要做页面底部统一确认按钮。`PENDING_CONFIRM` 和 `REVIEW_REQUIRED` 的用户可见主按钮都叫“确认卡片”，但前端内部仍按状态分别调用普通确认或 `review-resolution`。
+- 来源邮件固定放在业务事项之后，默认折叠正文；正文、图片预览和非图片下载仍走 `GET /api/source-messages/{sourceMessageId}/conversation` 原文权限链路。
+
+如果前端实现时发现现有接口不足，可单独向后端提出字段补充，例如用户友好的 `display_title`、任务级 `next_step_label`、业务摘要短句或调试区可见性标记；在提出前不得由前端自行展示 AI 原始 payload 或解析后端内部字段来补标题。
+
 ## 3. 任务列表 / 工作台接口字段补齐
 
 建议路径：