workutils/docs/superpowers/specs/2026-08-05-ai-test-plugin-ui-optimization-design.md

AI 单测插件完整 UI 优化设计

目标

将 AI 单测插件从纵向堆叠的 Accordion 页面重构为清晰的四区 Tab 工作台，降低首屏密度，改进 JDK/Maven 路径选择、模块加载反馈和任务进度展示，同时保持已经验证的显式 Git 增量范围与异步防覆盖逻辑。

范围

本次仅调整 AI 单测插件的 JavaFX 界面组织和相关交互状态，不修改 CodeFree CLI 协议、Maven/JUnit5 执行规则、85% 增量覆盖率规则、质量规范格式、历史数据格式或本地分支合并安全检查。

页面结构

插件顶部保留标题与简短能力说明，主体改为一个不可关闭的主 TabPane：

1. 项目与增量
2. 工具链
3. 质量规范
4. 结果与合并

主 Tab 不嵌套 Accordion。各页使用统一的内容边距和纵向间距，表单标签与输入控件对齐，避免控件在宽屏下无限拉伸。

项目与增量

• 第一行选择项目和生成模块。
• 第二行填写基线分支/Commit和目标分支/Commit。
• 基线默认 master；目标默认 HEAD，用户可以填写 DEV_1156339215001460262 或任何有效分支/Commit。
• “包含未提交改动”作为独立选项放在增量范围下方。
• 项目变化后立即清空旧模块并显示局部加载状态。
• 模块加载成功后显示总模块数，例如“已检出 11 个 Maven 模块”。
• 若只有一个 artifactId 以 -start 结尾，自动选中；存在多个时不擅自选择，并提示用户手动选择。
• ft-loancapital-core 的真实场景应检出并可选择 ft-loancapital-core-start。
• 继续使用 LatestRequestGate：较早项目请求的成功或失败结果不得覆盖最新项目选择。

工具链

• JDK 8 Home 与 Maven Home 使用只读路径框和“选择目录”按钮。
• 目录选择器初始目录优先使用当前已保存且存在的路径；否则从用户目录开始。
• 选择目录后仅更新表单，不自动执行验证；用户点击“检查并保存工具链”后统一验证并持久化。
• CodeFree 命令保留可编辑，默认 codefree。
• 覆盖率目标与最大修复轮次保留当前 Spinner。
• 工具链状态使用文字和颜色表达“未检查、可用、检查失败”，失败详情写入运行日志。

质量规范

• 默认质量规范与当前项目规范左右分栏。
• 两个文本区都可编辑，具有独立标题和说明。
• 保存按钮位于页面底部；保存行为和文件位置保持不变。

结果与合并

• 页面上方放置“分析增量、生成并验证、取消”三个任务按钮。
• 中部保留二级结果 Tab：生成文件、覆盖率、运行日志、历史摘要。
• 下方放置审核与合并区：目标本地分支、提交信息、人工审核复选框和合并按钮。
• 分析成功后才允许生成；验证通过并完成审核后才允许合并；任务运行时禁用冲突操作。

进度与异步状态

• 应用打开和初始配置加载期间不显示全局旋转进度条。
• 空闲时进度条隐藏且不占据误导性的视觉注意力，状态文字仍可见。
• 仅分析、生成、Maven 验证和合并等用户主动任务进入 busy 状态时显示进度条。
• busy 结束后进度条隐藏并重置，下一次任务从干净状态开始。
• 项目模块加载使用项目页内的状态文字，不启用全局 busy，也不影响其他 Tab 浏览。
• 模块偏好保存为静默后台操作，不触发全局进度条；失败写入日志。

Git 增量兼容性

• GitIncrementAnalyzer 继续使用显式 baseline 和 targetRef，不得恢复为隐式比较当前 HEAD。
• 临时 worktree 继续从 targetRef 创建，保证 AI 读取的是目标分支源码。
• 示例 master...DEV_1156339215001460262 不是硬编码；用户可替换任意有效引用。
• 只有目标引用解析到当前 HEAD 时才允许叠加未提交改动。

错误处理与可访问性

• 目录选择器取消时不修改现有路径。
• 无效项目、POM 解析失败、模块为空和工具链失败都显示明确中文状态，并在日志保留详情。
• 所有图形或简写按钮必须提供 Tooltip 和 accessible text；目录选择按钮使用可读文字，不使用无标签图标。
• Tab、输入框、目录按钮和任务按钮均保持标准键盘焦点顺序。

代码边界

• AiTestPane 负责页面组合和事件绑定。
• 新增小型目录选择辅助组件，封装只读路径框、选择按钮和 DirectoryChooser 行为，避免 JDK/Maven 重复实现。
• 新增纯状态模型或辅助方法管理进度条可见性与模块加载文案，使关键交互可以脱离 JavaFX 场景做单元测试。
• 不改动其他插件页面或公共导航栏。

验证标准

• 架构测试确认主界面只有四个指定主 Tab，不再使用 Accordion。
• 目录选择组件测试确认路径框只读、取消不改值、选择后更新值。
• 状态测试确认初始/空闲隐藏进度，主动任务显示，完成后隐藏并重置。
• 模块测试确认唯一 -start 自动选中、多个 -start 要求手选，并显示模块数。
• 真实 ft-loancapital-core 回归继续检出 ft-loancapital-core-start。
• 异步竞态测试继续确认只有最新项目请求能更新结果。
• master...DEV_1156339215001460262 真实增量回归继续通过。
• 运行 AI 插件聚焦测试、Maven 全量测试、JAR 打包和 git diff --check。