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