Initial commit

docs/staff-h5-gsap-ux-plan.md

@@ -0,0 +1,139 @@
+# 员工端 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. 效果指标
+
+关注重复点击率、一次叫号完成时间、失败后的重试成功率、重复手机号确认放弃率和项目误切换反馈。动效成功的标准是减少犹豫与误操作，而不是增加动画播放次数。