AstrBot-Desktop/docs/reports/ui-audit-2026-07-21.md

63 行
5 KiB
Markdown

# AstrBot Desktop 前端 UI 审计
日期:2026-07-21
范围:`src/App.tsx`、`src/styles.css`、`src/features/**`、前端测试与构建配置
## 审计方式
- 读取 `docs/01_Architecture_Design.md`、`docs/02_Codex_Implementation_Tasks.md` 和现有前端实现。
- 按 Impeccable technical audit 的 Accessibility、Performance、Theming、Responsive、Anti-patterns 五个维度检查。
- 运行本地 detector:`node C:\Users\Administrator\.agents\skills\impeccable\scripts\detect.mjs --json src/App.tsx src/styles.css src/features`;未返回结构化命中项,因此以下结论以源码和基线检查为准。
- 基线:`pnpm run typecheck`、`pnpm run lint`、`pnpm run test`、`pnpm run build` 均通过;Node 版本有 `24.14.0` vs 要求 `>=24.17.0` 的警告。
## Health score
| 维度 | 分数 | 结论 |
| ------------- | --------: | --------------------------------------------------------------------------------------- |
| Accessibility | 2/4 | 已有主导航、部分 ARIA 和 live region,但焦点、键盘 tab 语义、表单标签及窗口控件仍不完整 |
| Performance | 2/4 | 聊天状态集中在大组件,生产 JS gzip 约 4.0 MB,存在按页面拆分和减少无关重渲染空间 |
| Theming | 2/4 | 有 dark/light 主题,但大量颜色、渐变和阴影直接写在 CSS,主题 token 未形成单一来源 |
| Responsive | 2/4 | 有 900/760/680px 断点,但聊天会话列表、工具栏、桌面窗口尺寸和 44px 触控目标仍需验证 |
| Anti-patterns | 2/4 | 不是营销页式 AI slop,但存在渐变背景、重复卡片、过度圆角/阴影和全局大标题层级偏重 |
| **总分** | **10/20** | **Acceptable:需要系统性重构,但不需要改写业务架构** |
## P0:阻塞项
当前没有确认会阻塞任务完成的 P0 功能问题。
## P1:发布前必须处理
1. **聊天页信息层级不稳定** — `src/features/chat/ChatPanel.tsx:577`;运行时状态、槽位切换、会话列表、消息流和输入区堆在同一面板,主任务入口不够突出。
2. **主题令牌不完整** — `src/styles.css:1`、`src/styles.css:1804`;深浅色主题依赖大量重复选择器和硬编码色值,新增页面容易产生视觉漂移。
3. **焦点和键盘状态不完整** — `src/styles.css:246` 只覆盖输入框/选择框;导航按钮、槽位 tab、消息操作和窗口控件缺少统一 `:focus-visible` 样式。
4. **表单标签与可读性不一致** — `src/App.tsx:945`、`src/App.tsx:950`、`src/App.tsx:973` 使用 `aria-label` 代替可见标签;`CredentialEnrollmentCard` 的 label 结构也需要统一间距和错误提示。
5. **聊天构建体积过大** — `pnpm run build` 输出 `index-D8Ql9rJN.js` 约 5.6 MB(gzip 约 4.0 MB);页面级懒加载和资源边界应纳入 P2,若继续增加桌宠/诊断功能则应提前拆分。
6. **状态反馈缺少统一视觉语义** — 连接、加载、错误、空会话和上传状态分散在多个 class,颜色和文案没有统一 token/状态等级。
7. **桌宠浮层遮挡主导航** — 浏览器预览中 pp-pet-overlay 覆盖左侧导航项,桌宠可见时会降低页面可操作性;应限制浮层层级/停靠区,或提供不遮挡导航的安全边界。
## P2:下一批处理
1. 统一桌面工作区的密度、间距、圆角和阴影,减少重复 `card` 包裹。
2. 修正 680px 以下布局:会话列表、聊天工具条、输入框按钮和长文本溢出。
3. 给所有异步按钮补充进行中、失败、恢复动作和 `aria-live` 反馈。
4. 给聊天消息操作、附件移除、窗口控制补充 tooltip/可见焦点,不依赖符号字符表达含义。
5. 引入 `text-wrap: balance/pretty`、`font-variant-numeric: tabular-nums` 和统一字体回退链。
6. 增加 `prefers-reduced-motion` 覆盖,保留桌宠状态动画但避免普通 UI 无限动画扩散。
## 不可改变的产品边界
- 技术栈继续使用 Tauri 2、React、TypeScript、Vite、Rust、SQLite、REST + SSE。
- 保留页面 key:`chat`、`connections`、`desktop`、`pet`、`diagnostics`。
- 不改变 Tauri IPC command/event 名称、Rust 权限边界、profile/slot/session/message 数据结构。
- 不改变 `companion` 与 `operations` 两个槽位的隔离规则,不把 `conversation_id` 单独作为本地唯一键。
- 不让 React 直接读取凭据、任意文件或执行 Shell;不修改后端协议和数据库迁移。
## 首批建议
先重构 `ChatPage` / `ChatPanel` 的视觉层:保留所有 state、invoke/listen、session、attachment、voice 和发送逻辑,只调整信息分组、CSS token、状态展示和响应式布局。
## 外部技能可用性
- 已使用本地 Impeccable audit 规范与 detector。
- 已读取本机 `redesign-existing-projects` 与 `design-taste-frontend` 技能说明,并将其约束应用于方案;它们没有独立可执行命令或额外 CLI。