From 6b5532a9dfe0afa13a7ae19337484bce50072452 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=AE=B6=E8=AE=AD?=
 <zhangjiaxun-xf@bestpay.com.cn>
Date: Wed, 5 Aug 2026 13:52:00 +0800
Subject: [PATCH] docs: design one-click AI test workflow

---
 ...08-05-ai-test-one-click-workflow-design.md | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-05-ai-test-one-click-workflow-design.md

diff --git a/docs/superpowers/specs/2026-08-05-ai-test-one-click-workflow-design.md b/docs/superpowers/specs/2026-08-05-ai-test-one-click-workflow-design.md
new file mode 100644
index 0000000..7a0e988
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-05-ai-test-one-click-workflow-design.md
@@ -0,0 +1,54 @@
+# AI 单测一键生成与覆盖率分析设计
+
+## 目标
+
+让用户在“项目与增量”Tab 内完成从增量分析到单测生成、Maven 验证和 JaCoCo 增量覆盖率计算的完整流程，避免任务停在 `ANALYZED` 状态而误以为覆盖率生成失败。
+
+## 交互设计
+
+- “项目与增量”Tab 提供主操作“生成单测并分析覆盖率”。
+- 主操作按顺序执行：增量分析、CodeFree 生成单测、Maven 测试编译、Maven/JaCoCo 测试、增量覆盖率计算。
+- 保留“仅分析增量”作为次要操作，用于检查增量范围。
+- 执行成功后自动展示“结果与合并”Tab，并优先展示覆盖率结果；生成文件仍可在结果区查看。
+- 任一阶段失败后自动展示“运行日志”，状态栏说明失败阶段，不将 `ANALYZED` 表示成完整任务成功。
+- 工具链 Tab 不在启动或主流程中自动展开、切换或弹出。只有工具链缺失或验证失败时，提示用户进入该 Tab 处理。
+
+## 默认工具链配置
+
+- 用户保存过配置时始终优先使用保存值。
+- 没有保存配置或对应路径为空时执行自动探测：
+  1. JDK 8 优先读取 `JAVA_HOME`，其次根据当前 `java.home` 识别 JDK 根目录；若运行时位于 `jre` 子目录则取父目录。
+  2. Maven 优先读取 `MAVEN_HOME` 或 `M2_HOME`，其次调用全局 `mvn -version` 并解析 `Maven home:`。
+  3. CodeFree 使用全局命令 `codefree`。
+- 当前 Windows 开发环境的兜底值为：
+  - JDK 8：`C:\Program Files\Java\jdk-1.8`
+  - Maven：`D:\bestpay-maven\apache-maven-3.8.6`
+- Windows 兜底仅在路径真实存在时使用；macOS/Linux 不写入 Windows 路径，保持跨平台探测。
+- 成功探测出的配置保存到现有 `settings.properties`，后续启动直接复用。
+
+## 执行与状态模型
+
+- 复用现有 `AiTestWorkflow.analyze` 与 `generateAndVerify`，由界面层的一键协调方法串联，不复制领域逻辑。
+- 第一步返回 `ANALYZED` 时立即进入生成验证；返回 `FAILED` 或 `CANCELLED` 时停止。
+- 一键任务从开始到最终状态只维护一次 busy/progress 生命周期，防止两段异步调用之间按钮闪烁或旧结果覆盖新结果。
+- 保留现有最新请求保护逻辑；项目切换或重复操作不得用旧异步结果覆盖当前选择。
+
+## 错误处理
+
+- 工具链路径无效时在执行前失败，提示缺失项并定位到工具链配置，而不是启动 CodeFree/Maven 后才失败。
+- CodeFree、测试编译、测试执行和覆盖率计算的失败分别保留原始日志，并显示可读阶段信息。
+- 覆盖率未生成时明确显示失败原因，不只显示“尚无覆盖率结果”。
+
+## 测试策略
+
+- 配置测试覆盖已保存值优先、环境变量探测、`java.home` 的 `jre` 归一化、`mvn -version` 解析及 Windows 兜底存在性。
+- JavaFX 结构测试覆盖第一 Tab 的主/次操作以及工具链 Tab 默认不被选择。
+- 协调流程测试覆盖：分析成功后继续生成、分析失败时停止、最终覆盖率被渲染、失败时切换运行日志。
+- 回归测试继续使用 `master...DEV_1156339215001460262`，验证 `ft-loancapital-core-start` 的显式目标引用分析不受影响。
+
+## 范围限制
+
+- 不实现 MixMax3。
+- 不修改 CodeFree CLI 的协议和现有质量规范格式。
+- 不自动合并生成代码；仍需用户审核后显式合并到目标本地分支。
+- 不优化“手机 UI 自动化”插件。