workutils/docs/superpowers/specs/2026-07-31-api-doc-merge-compatibility-design.md

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。