workutils/docs/superpowers/plans/2026-07-31-api-doc-compatible-merge.md

API Doc Compatible Merge Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 合并插件重构分支，同时保留 API 文档页三个 Tab 的现有 UI。

Architecture: 以当前分支的 Tab 布局为展示外壳，把导出执行替换为 ApiDocExportRequest、RunApiDocExportUseCase 和 AsyncOperationController。历史 Tab 改用公共 ExportHistoryPane，主题样式合并而非二选一。

Tech Stack: Java 17、JavaFX、JUnit 5、Maven、Git

Global Constraints

• Git 评审不参与修改。
• 本地调试代理默认关闭。
• 不恢复 new Thread、setBtnLoading 或按钮文字驱动状态。
• 保留三个 Tab 和 .apidoc-tab-pane 样式。
• 不修改或暂存用户未跟踪文件。

---

Task 1: API 文档窗口架构保护测试

Files:

• Create: src/test/java/com/example/workutils/biz/apidoc/ApiDocWindowArchitectureTest.java
• Modify: src/main/java/com/example/workutils/biz/apidoc/ApiDocWindow.java

Interfaces:

• Consumes: AsyncOperationController<ApiDocExportResult>、ExportHistoryPane

• Produces: 不包含旧线程与 Loading 辅助逻辑、仍包含三个 Tab 的窗口源码

• Step 1: 写失败测试

读取 ApiDocWindow.java，断言包含三个 Tab 和 LoadingButtonBinder.bind， 不包含 new Thread(、setBtnLoading(。

• Step 2: 运行测试并确认失败

Run: .\mvnw.cmd -q -Dtest=ApiDocWindowArchitectureTest test

• Step 3: 合并窗口实现

保留 Tab 容器与模式卡片；导出按钮绑定 exportOperation；历史 Tab 嵌入 ExportHistoryPane；请求由 buildRequest() 构造并交给 use case。

• Step 4: 运行测试并确认通过

Run: .\mvnw.cmd -q -Dtest=ApiDocWindowArchitectureTest test

Task 2: 主题样式合并

Files:

• Modify: src/main/resources/css/light-theme.css

Interfaces:

• Consumes: .apidoc-tab-pane

• Produces: .operation-status、.empty-state 与 Tab 样式同时存在

• Step 1: 扩展源码测试

断言主题文件同时包含 .apidoc-tab-pane、.operation-status 和 .empty-state。

• Step 2: 运行测试并确认失败

Run: .\mvnw.cmd -q -Dtest=ApiDocWindowArchitectureTest test

• Step 3: 合并两侧 CSS

保留 Tab 样式，并追加异步状态与空状态样式。

• Step 4: 运行测试并确认通过

Run: .\mvnw.cmd -q -Dtest=ApiDocWindowArchitectureTest test

Task 3: 完成分支合并

Files:

• Merge: codex/plugin-ui-refactor into 20260730-API插件继续优化

Interfaces:

• Produces: 一个包含重构与兼容 UI 的合并提交

• Step 1: 提交兼容实现

提交测试、窗口和 CSS 的兼容修改。

• Step 2: 合并到当前分支

使用普通 merge，遇到已解决过的两个文件时采用兼容提交结果。

• Step 3: 完整验证

Run: .\mvnw.cmd -q test

Run: .\mvnw.cmd -q -DskipTests compile

Run: git diff --check

• Step 4: UI 只读验收

确认三个 Tab、代理默认关闭、导出空闲状态和历史 Tab，不触发导出。