张家训
53 lines
2.1 KiB
Markdown
53 lines
2.1 KiB
Markdown
# 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。
|