astrbot_plugin_imagestudio/docs/ui-redesign-audit-2026-07-21.md

83 行
7.2 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# ImageStudio 前端 UI 审计
日期:2026-07-21
范围:`frontend/standalone-web` 工作台、共享 API 类型、导航与 Gallery 页面
方法:Impeccable `audit` 技术检查、源码静态审计、基线 typecheck/build/contract tests
## 项目盘点
### 技术栈与入口
- Vue 3 Composition API + TypeScript + Vite 6。
- 独立 Web 入口:`frontend/standalone-web/src/main.ts` → `App.vue`。
- AstrBot 插件页入口:`frontend/plugin-page/src/main.ts`,通过 `astrbot-page-bridge` 注入后复用 `standalone-web/src/App.vue`。
- API 统一入口:`frontend/shared/api/client.ts`;路径常量集中在 `frontend/shared/api/endpoints.ts`,基础路径为 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio`。
- 当前无 Vue Router;页面切换由 `activeNav` + URL 查询参数 `view` / `module` / `materialView` / `profile` 维护,并使用 `history.replaceState`。
### 页面与主要组件
- 工作台页面:overview、generate、queue、performance、gallery、profiles、materials、settings、logs。
- 主要页面组件:`GalleryPage.vue`、`ProfilesPage.vue`、`AdvancedMaterialImportPage.vue`、`SettingsPage.vue`、`BackupPage.vue`、`LogsPage.vue`。
- 主要复用组件:`AppNavigationRail.vue`、`StateCard.vue`、`EmptyState.vue`、`MetricCardGrid.vue`、多个 Dialog/Drawer 组件。
- 复杂业务子域:workflow、profiles、materials;多数页面仍由 `App.vue` 组合和持有状态。
### 不能改变的契约
- 不改变导航 key、module 映射、URL 查询参数语义及插件页/独立 Web 双入口。
- 不改变 `frontend/shared/api/endpoints.ts` 中的 endpoint 名称、HTTP 方法、请求体字段和响应类型。
- 不改变 `frontend/shared/types/**` 的数据结构,尤其是 image、job、workflow、profile、material、settings、storage 相关类型。
- 不改变生成、队列、图库批量操作、工作流轮次/分支、角色卡、素材识别、设置备份与日志的现有交互语义。
- 不删除 AstrBot plugin page bridge、媒体签名/载荷流程、后端连接状态与错误恢复路径。
## Audit Health Score
| 维度 | 分数 | 关键发现 |
|---|---:|---|
| Accessibility | 2/4 | 已有语义按钮、`aria-current`、`aria-pressed`、状态 live region;但部分表单控件缺少显式 label,图片预览/弹层焦点管理与键盘闭环需要统一验证。 |
| Performance | 2/4 | 生产构建可用;`App.vue` 单文件约 22k 行、Web JS gzip 约 211.5 kB,且存在 `transition: width`、`transition: max-height` 等布局属性动画。 |
| Theming | 2/4 | 有 dark/light 变量和主色持久化;但 tokens 集中在 `App.vue`,大量页面级颜色/阴影/渐变仍混杂,主题边界难以复用。 |
| Responsive Design | 2/4 | Gallery 等页面有 1180/900/560 断点;工作台整体仍依赖 244px rail、宽 topbar 与多列面板,窄桌面窗口存在拥挤/溢出风险。 |
| Anti-Patterns | 2/4 | 本地 detector 命中布局属性动画、圆角元素厚边、侧边/顶部强调条、占位图片检测;背景网格、玻璃模糊和多层渐变也提高了视觉噪声。 |
| **Total** | **10/20** | **Acceptable:功能基础稳定,但需要有边界的结构化 UI 重构。** |
## Anti-Patterns Verdict
**部分通过,仍有明显 AI/模板化痕迹。** 具体包括:工作台背景的装饰性网格、多个 surface 的渐变与 blur、状态卡片的顶部强调条、导航 active 状态的侧边强调、圆角 + 宽阴影组合,以及大单体 App 文件导致的重复视觉词汇难以治理。它们不是功能阻塞,但会让工具界面显得“装饰先于任务”。
## 问题清单与优先级
### P0 Blocking
- 当前没有确认到会阻塞主要任务完成的 P0 UI 问题。基线功能检查全部通过。
### P1 Major
- **P1-01:工作台壳层与业务页面耦合过重**:`frontend/standalone-web/src/App.vue` 约 22k 行,同时承载导航、数据加载、弹层、生成器、队列、图库、素材与设置。影响:任何视觉调整都容易触碰业务状态,回归面大。
- **P1-02:桌面窄窗口的结构风险**:导航 rail、sticky topbar、双栏工作区和多个固定最小宽度并存,约 1024–1280px 宽度下容易造成操作区压缩、横向滚动或首屏信息层级失衡。
- **P1-03:主题 token 没有形成可复用层**:核心变量主要位于 `App.vue` 的全局 style,页面组件继续直接组合 `var(--panel)`、`var(--border)`、颜色混合和阴影。影响:dark/light 与未来页面统一成本高。
- **P1-04:交互状态覆盖不均**:部分按钮有 disabled/hover/focus,弹层、批量操作、加载、空态、错误态的状态表达不完全统一;需要以组件级状态矩阵补齐。
- **P1-05:可访问性需专项修复**:`GalleryPage.vue` 搜索框和批量 checkbox 等控件依赖邻近文本,部分复杂弹层/预览需要确认 focus return、Escape、焦点陷阱与可读名称;不能只依赖视觉状态。
- **P1-06:性能边界**:`App.vue` 产生单一大 JS/CSS 包,构建已给出超过 500 kB 的 chunk 警告;本轮不改业务加载策略,但应避免新增全局样式和重型运行时依赖。
### P2 Minor
- **P2-01:视觉节奏不一致**:8/10/12/14/16/18/22/24 等间距和 7/8/10/12 等圆角并存,需抽取有限的 spacing/radius scale。
- **P2-02:装饰噪声偏高**:背景网格、渐变、backdrop-filter 在多个层级重复,降低任务区域的对比度和层级清晰度。
- **P2-03:状态色与表面色混用**:good/warn/bad/idle 的 border、背景、顶部条规则分散在多个选择器,需集中到语义状态 tokens。
- **P2-04:图库卡片信息密度不稳定**:grid/list/inspector 三种模式的操作按钮、选中态和媒体占比不完全一致,批量操作区在窄桌面易成为第二工具栏。
- **P2-05:部分过渡动画直接改变布局属性**:检测命中 `transition: width` 与 `transition: max-height`;应优先改为 transform/opacity 或 grid 行过渡。
- **P2-06:图片替代文本规则不统一**:多数业务图片有 alt,但预览/通知缩略图存在空 alt 或依赖上下文的情况,需要区分装饰图与内容图。
## 正向发现
- 业务 API 与类型文件集中,页面重构可以保持数据契约不变。
- 导航、状态卡、空态、预览对话框已有复用组件,不需要推倒重来。
- Gallery 已具备搜索、筛选、grid/list、批量操作、预览、错误和 loading 路径,适合作为第一批页面。
- 基线 `npm.cmd run typecheck`、`npm.cmd run build:web`、`npm.cmd run test:contracts` 均通过。
## 来源与边界
- 本地源码:`frontend/standalone-web/src/App.vue`、`frontend/standalone-web/src/features/gallery/GalleryPage.vue`、`frontend/standalone-web/src/components/AppNavigationRail.vue`、`frontend/shared/api/client.ts`、`frontend/shared/api/endpoints.ts`、`frontend/shared/types/**`。
- 本地配置:`frontend/package.json`、`frontend/standalone-web/vite.config.ts`、`frontend/plugin-page/vite.config.ts`。
- Impeccable 本地 detector:命中 5 项静态提示,未替代人工审计。
- 未使用外部网络资料;本次目标是对现有仓库实现做代码级审计。