feat(admin): 管理端 UI/UX 深度优化——错误/加载/空状态、表单快捷键、移动端适配与无障碍

docs/ux-optimization-summary.md

@@ -0,0 +1,80 @@
+# 管理端 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` 已有请求中防护，未做额外改动。