规划 API 文档页兼容合并

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

@@ -0,0 +1,101 @@
+# 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，不触发导出。