# 员工端 H5：GSAP UI/UX 交互提升规划

## 1. 目标

员工端动效的目标不是“更炫”，而是让现场员工快速确认：操作是否提交、结果是否生效、接下来做什么。

原则：业务状态先于动画；一次操作只突出一个结果；动画可中断、可清理、可降级；CSS 负责简单微反馈，GSAP 负责多元素状态编排；任何请求、刷新和导航都不能依赖动画回调。

## 2. 当前体验与机会

| 场景 | 当前基础 | 主要缺口 | 提升目标 |
|---|---|---|---|
| 叫号 | busy、结果 Banner、队列刷新 | 新号段、指标和列表同时变化，视觉关系弱 | 一眼确认叫了哪些号、队列已推进 |
| 取号 | 校验、重复手机号确认、上下个号码 | 成功后表单和指标瞬时变化 | 明确号码已生成，减少重复提交 |
| 我的 | 明确确认后切换项目 | 弹层和项目上下文变化不连续 | 降低误切项目风险 |
| 主导航 | 固定三入口 | 内容瞬时替换 | 建立轻量方向感 |
| 轮询/异常 | 5 秒刷新、离线与陈旧提示 | 后台变化可能与本地操作混淆 | 只强调与当前操作相关的新变化 |

## 3. Motion tokens

| Token | 时长 | 用途 |
|---|---:|---|
| press | 80–100ms | 按钮按压，CSS |
| fast | 140–180ms | 图标、提示条、小状态 |
| standard | 220–260ms | 页面内容、指标变化 |
| emphasis | 280–320ms | 叫号结果、项目切换 |
| exit | 140–180ms | 元素退出 |

推荐 `power2.out` / `power3.out`，位移控制在 6–16px，缩放控制在 `0.98–1.02`。

## 4. 六个重点方案

### A. 叫号提交与结果（P0）

1. 点击瞬间：按钮 CSS 下压，操作区立即锁定，文案切换为“正在叫号”。
2. 成功后：旧号段轻淡出，新号段作为整体从 `y: 10, opacity: 0` 进入，总时长不超过 300ms。
3. “下一个号、剩余未叫号”同步做一次背景高亮，不滚动数字。
4. 本次消费的队列行淡出并收起，后续可见行使用 GSAP Flip 平滑补位。
5. 失败 Banner 以 6px 位移淡入，不抖动；设备部分失败只扫过一次琥珀色边框。

以 API 返回的 batch/revision 标识动画事件；轮询看到相同 revision 不得重播。批量号码必须整体进入，禁止逐号 stagger、老虎机、弹跳或闪烁。

### B. 队列列表变化（P0）

- 使用 Flip 处理可见行删除和重排，220–260ms。
- 前台新增号码可使用 8px 淡入；纯轮询只做 600ms 静态背景高亮。
- 只动画首屏可见行，不为完整长队列创建时间线。
- 标签页从后台恢复时直接显示最新快照，不补播期间变化。

### C. 取号确认（P0）

- 提交时按钮保持尺寸稳定。
- 成功后“上个取号”在 240ms 内切换为新号码，“下个取号”同步低强度高亮。
- 号码确认出现后再清空表单，形成清晰的事务完成顺序。
- 重复手机号提示在字段附近展开，不造成大幅页面跳动。
- 增加 `aria-live="polite"` 成功播报；视觉提示可淡出，辅助技术反馈不依赖动画。

### D. 主导航与场景切换（P1）

- active 背景和按压继续用 CSS。
- 内容使用 180–220ms 的淡入和 8px 水平位移，方向跟随“叫号 → 取号 → 我的”。
- 路由先切换，进入动画随后播放，禁止等待退出动画。
- 首次加载骨架与内容交叉淡化，避免白屏。

### E. 项目切换弹层（P1）

- 遮罩 180ms 淡入；移动端 sheet 从 `y: 24` 进入 260ms；桌面对话框使用轻微缩放和 8px 位移。
- Escape、取消、确认走统一清理路径。
- 切换后旧项目淡出，新项目名称和首份队列数据一起进入，禁止出现“新标题 + 旧队列”。
- 同步实现焦点圈定、关闭后焦点返回和背景滚动锁定；这些不能由动画替代。

### F. 离线、陈旧与恢复（P1）

- 状态 Banner 从顶部 8px 淡入，不自动消失。
- 恢复后 Banner 淡出，数据区只做一次柔和绿色高亮。
- 必须先拉取服务端权威快照；动画只表达界面已同步，不代表硬件必然成功。

## 5. 配套 UI 调整

1. 叫号页固定“本次结果”为第一层，“快速叫号”为唯一主按钮，批量叫号为次级操作。
2. 指标按任务优先级排序：下一个号、剩余未叫号、最新叫到、最末号数、最末号预计时长。
3. 不恢复大型成功卡片，但提供短暂明确的取号号码确认。
4. disabled 按钮附近显示不可操作原因：离线、数据陈旧、项目停运或队列为空。
5. 动画不得改变至少 44×44px 的可点击区域。

## 6. 推荐代码结构

```text
web/src/
├── motion/
│   ├── tokens.ts
│   ├── useReducedMotion.ts
│   └── useRevisionMotion.ts
├── components/staff/
│   ├── CallResult.tsx
│   ├── QueueList.tsx
│   ├── TicketMetrics.tsx
│   ├── StaffScene.tsx
│   └── ProjectSwitcher.tsx
└── pages/StaffPage.tsx
```

`StaffPage.tsx` 保留业务数据和动作编排，视觉组件管理各自作用域内的时间线，避免轮询、表单、幂等与动画状态互相污染。

## 7. 实施路线

### Sprint 1：核心事务（P0，2–3 天）

- 建立 motion tokens、`useGSAP` scope、reduced motion。
- 实现叫号结果、revision 去重、可见队列 Flip。
- 实现取号号码确认与无障碍播报。

### Sprint 2：场景与恢复（P1，约 2 天）

- 实现场景进入和项目切换弹层。
- 补齐焦点管理、Escape、背景滚动锁定。
- 实现离线、陈旧与恢复反馈。

### Sprint 3：现场调优（1–2 天）

- 验证 320/375/390/414px 和低端 Android。
- 根据现场单手操作、网络延迟、强光环境调整时长和对比度。
- 小范围灰度并记录重复点击率、完成时长和错误恢复率。

## 8. 验收标准

- 动画开启、关闭或中途打断，业务结果完全一致。
- 相同 revision/batch 不重复播放。
- 后台恢复不补播旧叫号和队列变化。
- `prefers-reduced-motion: reduce` 下取消位移/缩放，0–100ms 内直接到终态。
- 焦点不被动画遮挡；弹层关闭后正确返回触发按钮。
- 成功、警告、失败通过 `aria-live` 或 `role=status|alert` 播报。
- 主要只动画 `transform`、`opacity`，清除列表收起产生的内联样式。
- 页面卸载后无存活 timeline、listener 或 matchMedia context。
- 测试覆盖 revision 去重、reduced motion、清理、焦点返回、连续点击、网络失败与后台恢复。

## 9. 效果指标

关注重复点击率、一次叫号完成时间、失败后的重试成功率、重复手机号确认放弃率和项目误切换反馈。动效成功的标准是减少犹豫与误操作，而不是增加动画播放次数。