th-hotel-simple/docs/superpowers/specs/2026-07-22-v4-order-task-detail-visual-polish-design.md

M002 V4 订单事项办理页视觉与交互优化设计

1. 背景

当前 /reservation/order-tasks/{orderTaskId} 已能按 V4 订单任务、多卡模型和字段白名单完成 Basic Information、业务卡、复核态卡片、Payment 附件预览、Rooming List 事项确认、Trace 卡和来源邮件展示。

本次用户反馈是页面“太丑”。已在视觉伴随页对比三种方向后确认采用 A. 克制的业务办理台：保留现有纵向办理结构，但优化首屏摘要、状态层级、卡片视觉、间距和操作区，使页面更像普通酒店员工使用的业务办理页，而不是技术卡片堆叠页。

2. 目标

• 让首屏更快表达当前办理对象：订单线索、业务类型、来源邮件、任务状态、卡片处理进度。
• 让卡片层级更清楚：标题、状态、提示、字段、错误 / 成功消息、操作按钮有稳定视觉位置。
• 保持普通酒店员工视角，默认不展示 V4、ORDER_TASK、Task Card、JSON Pointer、payload、version、内部 ID 等技术信息。
• 保持当前确认和复核流程不变，继续在原业务卡内完成确认或复核解阻。
• 只做前端视觉和交互 polish，不改变后端接口、权限、安全边界、审计和提交契约。

3. 非目标

• 不新增后端接口或修改 /api/reservation/order-tasks/** 响应字段。
• 不改变卡片确认接口、复核解阻接口、字段白名单或目录校验规则。
• 不新增拖拽、批量确认、自动跳下一张或左侧卡片导航。
• 不把 SourceMessage 原文、附件 URL、AI 原始 payload 或调试字段提升到默认主信息层级。
• 不重做全站设计系统，不引入新 UI 框架或 Admin Template。

4. 方案选择

4.1 已选方案：克制的业务办理台

该方案保留当前页面的纵向结构：

1. 页面标题和刷新按钮。
2. 订单事项摘要区。
3. Basic Information 卡。
4. 业务卡列表。
5. SourceMessage 展示卡。

优化重点是视觉层级：

• 摘要区改为更紧凑的业务办理头部，突出订单参考号、业务类型、目标线索、来源邮件、来源时间、任务状态和卡片进度。
• 卡片区域统一为白底、轻边框、清楚标题、状态徽标和右下操作区。
• 卡片提示、错误、成功消息采用更明确但不过度抢眼的样式。
• “确认卡片”作为主操作稳定放在卡片底部右侧；“查看订单”保持次级入口。

4.2 放弃方案

• 一次只办一张卡：聚焦性更强，但会改变当前多卡浏览节奏，容易把本次 polish 扩大成流程重构。
• 左侧卡片导航 + 右侧办理：结构感强，但响应式复杂度更高，也更适合卡片数量显著增加后的后续版本。

5. 页面结构

5.1 顶部办理摘要

ReservationV4OrderTaskDetailView.vue 的摘要区继续使用当前 detail 数据，不新增 API 字段。展示内容按业务优先级重排：

• 主标题：订单参考号，优先 display_order_key，否则 target_locator_value。
• 辅助信息：来源邮件主题、发件人摘要、来源接收时间。
• 状态信息：订单事项状态、业务类型、目标线索状态。
• 进度信息：总卡片数、待确认数、复核数、已确认数。

摘要区不展示 order_task_id、card_id、version、target_resolution_status 原始代码等技术字段。若某项为空，继续按现有格式显示 - 或本地化空状态文案。

5.2 卡片视觉

ReservationV4TaskCardSection.vue 保持当前职责：根据卡类型分发到 Room Information、Rooming List、Payment、Trace 或通用字段渲染器。

视觉优化包括：

• 卡片标题区使用更清楚的左右布局：左侧标题，右侧状态徽标。
• 可读提示放在标题下方，采用温和提示条，不和错误消息混在一起。
• 字段区域和操作区留出稳定间距，避免页面像一组表单块直接堆叠。
• 复核态输入区继续显示在原卡内，视觉上与字段区相邻，明确这是当前卡的处理动作。
• 底部操作区固定为次级入口在左或左侧、主确认按钮在右侧，窄屏下仍保持按钮不挤压文本。

5.3 业务卡列表

业务卡列表保留当前纵向渲染，不新增步骤条或折叠导航。列表标题可弱化，只表达“业务事项”和卡片数量，不出现模型术语。

Basic Information 仍在业务卡之前，SourceMessage 展示卡仍在页面底部，避免来源邮件抢占办理主流程。

6. 组件边界

• ReservationV4OrderTaskDetailView.vue：负责页面级摘要结构、卡片顺序、加载 / 错误 / 空状态和接口调用。
• ReservationV4TaskCardSection.vue：负责单张卡片的标题、状态、提示、字段渲染入口、复核输入和确认操作区。
• ReservationV4RoomInformationCard.vue、ReservationV4TraceCard.vue、ReservationV4PaymentAttachmentPreview.vue、ReservationV4RoomingListCard.vue：保持现有业务渲染职责，不在本次改动中引入跨卡状态。
• i18n locale 文件：只新增或调整用户可见文案，稳定业务判断继续依赖后端代码和前端类型，不依赖显示文案。
• 样式文件：优先使用现有 th-* token 和项目 CSS 习惯，不引入新样式框架。

7. 数据流

数据流保持现状：

1. 页面根据 orderTaskId 和当前酒店调用 fetchReservationV4OrderTaskDetail。
2. 后端返回 order_task、card_counts、basic_information_card、business_cards、source_message_summary 和 source_message_card。
3. 页面用现有 computed 派生展示值和初始表单值。
4. 用户编辑卡片字段后，仍通过现有 buildReservationV4ConfirmedPayload 或 buildReservationV4ReviewOverrides 构造提交内容。
5. 确认或复核成功后仍重新加载详情，以后端最新状态为准。

本次不新增 Pinia 状态，不缓存服务端数据到客户端长期状态，也不绕过后端权限与状态机。

8. 错误与状态处理

• 页面加载中、详情加载失败、空业务卡等状态保留现有行为，视觉上与新版卡片风格对齐。
• 单卡确认失败继续展示在对应卡片内，不提升为全页错误，避免用户不知道哪张卡出错。
• 单卡确认成功继续展示在对应卡片内，并由刷新后的后端状态更新徽标和进度。
• 只读原因继续通过 availability.readonly_reason_message 或 readonly_reason_code 本地化文案展示，不显示内部校验路径。
• 无权限确认或复核时，主按钮保持 disabled，并通过现有只读原因或错误消息解释。

9. 响应式要求

• 桌面端摘要信息可使用多列网格，但不应过度拉宽字段。
• 窄屏下摘要区和卡片字段自然单列堆叠，按钮区保留主操作可见且文字不溢出。
• 卡片底部操作区在窄屏下允许换行，但“确认卡片”仍保持主按钮视觉优先级。
• 不使用随 viewport 宽度缩放的字体，不使用负 letter-spacing。

10. 测试计划

前端测试重点：

• reservationV4Views.spec.ts 覆盖摘要信息、卡片进度、业务卡顺序、确认按钮和来源邮件卡仍按预期渲染。
• 如卡片结构变动影响现有断言，更新断言以业务文案和稳定测试标识为准，不改为技术 ID 断言。
• 保留现有字段白名单、确认 payload、复核 payload 相关测试，不因视觉调整放宽业务约束。

验证命令：

CI=true pnpm --dir client lint
CI=true pnpm --dir client typecheck
CI=true pnpm --dir client test -- reservationV4Views.spec.ts

如实现触及共享样式或组件，再补跑：

CI=true pnpm --dir client test
CI=true pnpm --dir client build

11. 文档影响

本次设计文档作为交互优化规格记录。实现完成后需要检查：

• PROJECT_STATE.md 是否需要记录新的 checkpoint 状态。
• docs/project/frontend-backend/backend-to-frontend-notes.md 是否需要补充“前端仅消费现有展示字段”的说明。
• docs/project/security-access-control-boundary.md 不需要更新，除非实现中新增或修改接口、权限、审计、酒店隔离或敏感数据返回。

12. 验收标准

• /reservation/order-tasks/{orderTaskId} 首屏明显更像业务办理页，订单线索、来源摘要、状态和卡片进度一眼可见。
• Basic Information、业务卡、SourceMessage 的顺序不变，用户仍能按当前流程逐卡确认或复核。
• 每张卡的状态、提示、字段区、错误 / 成功消息和“确认卡片”按钮层级清楚。
• 默认页面不展示 V4 模型、Task Card、JSON Pointer、payload、version、内部 ID 或附件 URL 等技术信息。
• 前端测试通过，且没有后端接口、权限、安全边界或审计契约变化。