7.2 KiB
7.2 KiB
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 项静态提示,未替代人工审计。
- 未使用外部网络资料;本次目标是对现有仓库实现做代码级审计。