docs: define AI test plugin UI optimization

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

@@ -0,0 +1,96 @@
+# 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`。
+