astrbot_plugin_imagestudio/docs/ui-redesign-development-queue-2026-07-21.md

7.9 KiB

ImageStudio UI 重构后续开发队列

日期:2026-07-21 基线分支:codex/ui-redesign-gallery 范围:仅覆盖本轮 UI 重构尚未完成的事项;不包含后端功能新增。

当前结论

  • 已完成:共享视觉 token、工作台壳层、主要页面统一 surface/间距/圆角/状态/focus、Gallery 首批重构、桌面横向溢出修复、静态 detector 检查。
  • 尚未完成:真实 AstrBot 后端数据验收、逐页深度视觉精修、完整键盘/焦点审计、多个桌面尺寸验证、性能拆包、提交与发布收口。
  • 当前分支仍有未提交源码和文档改动;主支未修改。

P0:交付阻断项

Q0-01 真实 AstrBot 后端联调

目标:在真实 plugin-page bridge 和后端 API 下验证 UI,不再只依赖 preview mode。 涉及:frontend/plugin-page/src/main.ts、frontend/shared/api/client.ts、所有主要页面。 验收:

  • plugin-page 能加载真实 bootstrap、dashboard、profiles、images、jobs、settings、logs。
  • 后端未连接、401、超时、空数据、部分数据错误状态均有可读反馈。
  • 真实媒体签名、预览、刷新和批量操作不出现空白或死状态。

Q0-02 保护当前未提交改动并完成分支交付

目标:确认 GalleryPage.vue 原有改动与本轮改动的归属,完成 diff review、提交和 PR。 验收:

  • git diff --check 通过。
  • 无构建产物污染 web/ 或 pages/imagestudio/。
  • 用户确认后创建 commit/PR;未确认前不合并主支。

P1:发布前必须完成

Q1-01 逐页深度视觉精修

当前统一主要通过共享 CSS 层完成,以下页面还需要逐页检查内容层级、密度和操作优先级:

  • Overview:指标条、监控摘要、队列摘要、最近图片之间的层级和密度。
  • Generate:预览区、提示词输入、模型选择、生成操作和结果信息的空间分配。
  • Queue:过滤、任务状态、进度、详情和批量操作的优先级。
  • Performance:指标、趋势/明细、空态和失败态。
  • Profiles:master/detail/wardrobe 三栏在有数据、无数据和 sealed 状态下的层级。
  • Materials:导入、识别、确认、筛选、详情和空态。
  • Settings:section 导航、配置编辑、保存/校验/回滚状态。
  • Logs:筛选、日志列表、错误状态和长文本换行。
  • Workflow:节点流、轮次、分支、候选图、审查 dialog、素材 drawer。

验收:每页保留现有功能,并有明确的主操作、次操作、危险操作和恢复路径。

Q1-02 完整可访问性审计

涉及:所有 *.vue 页面和 Dialog/Drawer 组件。 任务:

  • 为搜索、筛选、checkbox、select、textarea、icon-only button 补齐稳定 label。
  • 验证 Tab 顺序、Enter/Space、Escape、焦点回收和 dialog focus trap。
  • 检查 heading 层级、landmark、aria-current、aria-expanded、aria-selected、aria-live。
  • 检查真实图片 alt、装饰图空 alt、加载/失败图片的替代内容。
  • 使用键盘完成 Gallery 批量操作、Profiles 选择、Workflow 节点操作和 Settings 保存。

验收:关键路径不依赖鼠标;焦点在 dark/light 两主题下可见。

Q1-03 多尺寸响应式验收

必须验证尺寸:

  • 1024×768:窄桌面,检查 rail、topbar、双栏/三栏区域。
  • 1280×800:常见桌面工作区。
  • 1440×900:宽桌面,检查内容是否过度拉伸。
  • 1600×900:超宽窗口,检查 max-width 和阅读线长。

验收:无横向溢出;sticky topbar/rail 不遮挡内容;批量工具栏和 dialog 不被裁切。

Q1-04 状态矩阵补齐

为每个主要页面记录并验证:default、hover、focus、active/selected、disabled、loading、empty、error、success、backend disconnected。 重点组件:按钮、tabs、filters、cards、dialogs、drawers、图片预览、表单保存栏。

P2:质量和维护性

Q2-01 视觉回归测试

  • 为 9 个主要 view 建立最小 Playwright/浏览器 smoke test。
  • 固定至少一组 dark/light 截图或 DOM 断言。
  • 断言 scrollWidth === clientWidth、页面标题、主要 landmark 和关键操作存在。
  • 将真实 backend 不可用场景纳入 preview-mode regression。

Q2-02 前端拆包与性能优化

现状:Web JS gzip 约 211.6 kB,Vite 报告单 chunk 超过 500 kB。 任务:

  • 评估按页面动态导入 Generate、Profiles、Materials、Settings、Workflow。
  • 保证 plugin-page bridge 首屏和 App.vue 的 URL 参数恢复不受影响。
  • 避免新增 UI 运行时依赖;对大图片列表保持懒加载和稳定的媒体 URL。
  • 对生成预览、Workflow 候选图和 Materials grid 做渲染数量边界检查。

验收:构建 chunk 警告下降或有明确的保留理由;交互没有新增延迟。

Q2-03 样式边界整理

  • 将 App.vue 中新增的全局 override 按壳层、页面、组件拆到可定位样式文件。
  • 避免继续增长 22k 行级别的单体 App.vue。
  • 保留 tokens.css 作为唯一视觉 token 来源,减少页面内直接写颜色/圆角/阴影。
  • 清理重复的局部样式和已被全局层覆盖的旧规则。

Q2-04 主题和对比度验证

  • 验证 dark/light 下正文、placeholder、disabled、warning、danger、success 的对比度。
  • 复核用户自定义 primary/accent 颜色的极端值,避免 focus 和文字失去对比度。
  • 记录至少一组自动化 contrast 检查结果。

P3:可选增强

Q3-01 设计文档和组件清单

  • 为 token、button、input、surface、status、dialog、empty state 建立简短使用约定。
  • 在 docs/ 维护页面状态矩阵和可复用组件清单。

Q3-02 真实数据密度优化

  • 用真实 profiles、materials、images、jobs、logs 数据压测长标题、长 prompt、长错误消息。
  • 检查分页/滚动/虚拟化需求,避免只在空数据预览态下看起来稳定。

Q3-03 发布前人工验收

  • 在 AstrBot plugin page 中完成一次完整生成、图库复用、角色选择、素材导入、设置保存、日志查看流程。
  • 记录阻塞项、截图和最终版本信息。

推荐执行顺序

  1. Q0-01 真实后端联调。
  2. Q1-01 逐页深度视觉精修。
  3. Q1-02 可访问性审计与修复。
  4. Q1-03 四种桌面尺寸验收。
  5. Q1-04 状态矩阵补齐。
  6. Q2-01 回归测试。
  7. Q2-02 拆包优化。
  8. Q2-03 样式边界整理。
  9. Q2-04 主题对比度验证。
  10. Q0-02 最终 diff review、commit 和 PR。
  11. Q3-03 真实插件页发布前验收。

暂不列入本队列

  • 后端 API 新功能。
  • 多租户权限链、持久 Worker、数据库迁移等后端架构事项。
  • 更换 Vue/Vite/TypeScript 或引入新的 UI 框架。

Execution update (2026-07-21)

  • Q0-01: source-level bridge/error/preview paths validated; live AstrBot host acceptance remains pending.
  • Q1-01: shared visual layer, page-level surface hierarchy, action states, and overview narrow-desktop override completed; all nine views smoke-tested.
  • Q1-02: stable search/workbench/status labels added; image preview dialog now traps focus and restores focus; existing confirmation dialog trap retained.
  • Q1-03: 1024x768, 1280x800, 1440x900, and 1600x900 passed across all nine views with no horizontal overflow.
  • Q1-04: state matrix recorded in docs/ui-redesign-state-matrix-2026-07-21.md.
  • Q2-01: added frontend/tests/ui-redesign-smoke.test.mjs and frontend/tests/ui-theme-contract.test.mjs; 7 UI contract tests pass.
  • Q2-02: page and workflow components use defineAsyncComponent; production chunks are split and the largest JS chunk is below the prior warning threshold.
  • Q2-03: new workbench overrides moved from App.vue into frontend/standalone-web/src/styles/workbench.css.
  • Q2-04: dark/light token contrast checks added; measured text pair ratios are 16.40, 7.52, 15.14, and 4.59.
  • Q0-02: diff review, build-artifact cleanup, full validation, commit, and PR are the remaining delivery actions.