# API 文档页合并兼容设计

日期：2026-07-31

## 目标

将 `codex/plugin-ui-refactor` 的 API 文档导出架构合并到
`20260730-API插件继续优化`，同时保留当前分支已经完成的三个 Tab
布局，不因解决 Git 冲突而回退 UI 或恢复旧的线程、Loading 和历史逻辑。

## 保留的 UI

- 保留“导出配置、导出历史、基类配置”三个 Tab。
- 保留紧凑的模式卡片、导出进度区域和当次结果入口。
- 保留 `.apidoc-tab-pane` 主题样式。

## 接入的新架构

- 导出任务由 `AsyncOperationController` 和
  `RunApiDocExportUseCase` 执行。
- 导出按钮仅通过 `LoadingButtonBinder` 绑定状态，不再直接修改
  文案、图标和禁用状态。
- 导出请求统一构造为不可变 `ApiDocExportRequest`。
- 本地调试代理为显式选项，默认关闭。
- 历史 Tab 使用公共 `ExportHistoryPane` 和
  `HistoryFileCommands`，删除窗口内重复的表格单元格和文件操作代码。
- 主题文件同时保留 Tab 样式、异步状态样式和空状态样式。

## 数据流

1. UI 根据当前模式构造 `ApiDocExportRequest`。
2. `AsyncOperationController` 将请求交给
   `RunApiDocExportUseCase`。
3. UseCase 根据请求决定是否启动调试代理，再调用生成逻辑。
4. 成功结果更新当次结果入口和公共历史列表。
5. 错误由操作状态面板与日志展示，UI 恢复由状态绑定完成。

## 冲突解决边界

- 不直接选择 Git 的 ours 或 theirs 覆盖完整文件。
- 以当前分支布局为外壳，以重构分支的请求、用例和状态管理为内部实现。
- Git 评审相关文件不参与本次修改。
- 未跟踪的审计文档和 SQL 文件保持不动。

## 验证

- 现有请求、代理、历史和异步状态测试必须全部通过。
- 增加源码结构测试，防止 API 文档窗口重新出现 `new Thread`、
  `setBtnLoading` 或直接启动隐式代理。
- 编译并运行完整测试。
- 执行 `git diff --check`。
- 只读 UI 验收三个 Tab、代理默认关闭、空闲状态和历史 Tab。