gongxue-base/docs/ux-optimization-summary.md

管理端 UI/UX 深度优化变更总结（apps/admin）

目标：深度优化用户操作的 UI/UX（表单、列表、反馈、导航、加载态、错误态、空状态、移动端适配等）， 保持现有 Ant Design 体系与功能不变，最终通过类型检查、lint 与测试验证。 本文件按类别汇总已落地改动与验证记录，供 review 使用。

一、错误态（失败不再伪装成"空数据/0 值"，均带重试）

• 工作台 Dashboard：全部接口失败时显示 QueryErrorState + 重试（此前静默显示 0 值）。
• 考试详情页：失败显示错误态 + 重试（此前空白页）。
• 机构列表 / 操作日志：失败显示错误态 + 重试（此前弹 toast 后渲染空表）。
• 部分失败反馈：Dashboard 部分接口失败改为页面内可关闭 Alert（此前每次切换日期弹 toast）。

二、加载态

• 6 个页面骨架屏替代整页 Spin：工作台（统计卡片骨架）、教师工作台、班级详情、考试详情、宿舍可视化、AI 配置。
• 学生表展开行（多班型对比）加载中显示 Spin + 提示，不再空白。
• 班级花名册导出按钮 loading（try/finally）。

三、空状态

• 复用统一 QueryEmpty（描述 + 主操作按钮引导）：学生/宿舍/押金/账单/教室/教师/钱包/机构等列表页已覆盖。

四、表单

• 新增 useSubmitShortcut：Cmd/Ctrl+Enter 提交，覆盖 12+ 弹窗（学生、宿舍/床位/柜子、押金×4、费用×3、教室、租赁、班级添加学员/教师）。
• 15 个表单统一 scrollToFirstError：校验失败自动滚动到首个错误字段。
• 防重复提交：考勤时段配置、班级添加学员/教师补齐 confirmLoading（其余弹窗已具备）。

五、列表

• 表格横向滚动：10+ 个缺失 scroll.x 的表格补齐（学生资料 4 Tab、考勤明细、考勤机、钱包、宿舍抽屉、教师工作台、押金弹窗等）。
• 移动端操作列固定：学生/宿舍/押金/账单/教室/教师/钱包 7 个主列表操作列 fixed: 'right'。
• 手动刷新入口：新增 RefreshButton，接入 8 个列表页（学生/宿舍/押金/教室/账单/教师/机构；钱包原有）。
• 分页/跨页勾选/已选提示均已具备，未改动。

六、反馈

• 通知铃铛：全部已读失败给出错误提示；无未读时按钮置灰；铃铛改为可聚焦按钮 + aria-label。
• 统一消息桥（App context）已具备；导出/删除/保存反馈已具备。

七、导航

• 新增 ScrollToTop：路由切换后滚动复位到顶部。
• 新增全局 BackTop：长列表滚动超过 400px 后浮现"回到顶部"按钮（尊重 reduced-motion）。
• 登录页用户名自动聚焦。
• 路由标签（RouteDock）窄屏压缩尺寸，避免横向裁切。

八、移动端适配

• 表格横向滚动 + 操作列固定（见"列表"）。
• Descriptions 响应式列数：班级详情、账单详情×2、学生档案、集成配置（此前固定列数在窄屏过挤）。
• 内容区 padding 已按 breakpoint 响应式（MainLayout 原有）。

九、无障碍与质感（全局 CSS）

• :focus-visible 品牌蓝焦点环（键盘导航可见）。
• @media (prefers-reduced-motion: reduce) 关闭动画/平滑滚动。
• ::selection 品牌色；WebKit 细滚动条；html 平滑滚动。

新增文件

• components/RefreshButton.tsx、components/ScrollToTop.tsx、components/BackTop.tsx
• hooks/useSubmitShortcut.ts
• components/ux.integration.test.tsx（5 个浏览器用例：RefreshButton / useSubmitShortcut 激活与未激活 / ScrollToTop / BackTop）

验证记录

检查	结果
typecheck（admin + server）	✅
lint（oxlint + eslint）	✅ 0 warning / 0 error
admin vitest（浏览器）	✅ 31 文件 / 166 用例
server jest	✅ 191 用例
aislop scan --changes	✅ 100/100

未做/后续（可选）

• 运行时视觉走查：需要 MySQL + 后端 + 前端环境（当前本地未运行），用于最终逐页截图核对。
• AI 助手抽屉：已具备响应式/空态/取消/技能锁定，submit 已有请求中防护，未做额外改动。