From b095b410ee7123556bda640fc8922c7b48849289 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: Fri, 31 Jul 2026 15:17:31 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A7=84=E5=88=92=20API=20=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E9=A1=B5=E5=85=BC=E5=AE=B9=E5=90=88=E5=B9=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-07-31-api-doc-compatible-merge.md    | 101 ++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-31-api-doc-compatible-merge.md

diff --git a/docs/superpowers/plans/2026-07-31-api-doc-compatible-merge.md b/docs/superpowers/plans/2026-07-31-api-doc-compatible-merge.md
new file mode 100644
index 0000000..06bb348
--- /dev/null
+++ b/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，不触发导出。