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

165 行
7.9 KiB
Markdown

# 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.