153 lines
8.7 KiB
Markdown
153 lines
8.7 KiB
Markdown
# 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 相关测试，不因视觉调整放宽业务约束。
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
CI=true pnpm --dir client lint
|
||
CI=true pnpm --dir client typecheck
|
||
CI=true pnpm --dir client test -- reservationV4Views.spec.ts
|
||
```
|
||
|
||
如实现触及共享样式或组件，再补跑：
|
||
|
||
```bash
|
||
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 等技术信息。
|
||
- 前端测试通过，且没有后端接口、权限、安全边界或审计契约变化。
|