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

员工端 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. 推荐代码结构

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. 效果指标

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