# API Doc Refactor Phase 3 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:** Give API document export one immutable request, one async operation owner, an explicit debug-proxy option, and the shared history UI.

**Architecture:** Capture all JavaFX form values into `ApiDocExportRequest` on the UI thread, then execute from `AsyncOperationController`. Inject the debug endpoint into `ApiDocGenerator`; only the export use case may decide whether to start the local proxy. Adapt existing history rows to `HistoryItem` without changing persistence.

**Tech Stack:** Java 17, JavaFX, JUnit 5, Maven.

## Global Constraints

- Work only on `codex/plugin-ui-refactor` in the existing isolated worktree.
- Preserve generated HTML structure and history-file format.
- Do not introduce `new Thread`.
- File and directory choosers must not enter loading state.
- Local debug proxy is a visible option and defaults to disabled.
- Write and observe a failing test before production behavior.

---

### Task 1: Immutable API export request

**Files:**
- Create: `src/main/java/com/example/workutils/biz/apidoc/application/ApiDocExportRequest.java`
- Test: `src/test/java/com/example/workutils/biz/apidoc/application/ApiDocExportRequestTest.java`

**Interfaces:**
- Produces: `Mode { PATH, FQN, BATCH }`.
- Produces validated factories `path`, `fqn`, and `batch`.
- Carries debug-proxy opt-in and batch filters.

- [ ] Test mode-specific validation and immutable project-path copying.
- [ ] Observe focused test failure.
- [ ] Implement the minimal request record.
- [ ] Confirm focused test passes.

### Task 2: Explicit debug endpoint injection

**Files:**
- Modify: `src/main/java/com/example/workutils/biz/apidoc/generator/ApiDocGenerator.java`
- Test: `src/test/java/com/example/workutils/biz/apidoc/generator/ApiDocGeneratorProxyTest.java`

**Interfaces:**
- Produces constructor `ApiDocGenerator(WorkUtilsProperties, Supplier<String>)`.
- Existing constructor supplies an empty endpoint and never starts a proxy.

- [ ] Test that generated HTML receives the supplied endpoint and the default constructor does not instantiate the proxy.
- [ ] Observe focused test failure.
- [ ] Inject endpoint supplier and remove `DubboDebugProxy.getInstance()` from HTML rendering.
- [ ] Confirm focused test passes.

### Task 3: Single async export operation

**Files:**
- Create: `src/main/java/com/example/workutils/biz/apidoc/application/RunApiDocExportUseCase.java`
- Modify: `src/main/java/com/example/workutils/biz/apidoc/ApiDocWindow.java`
- Test: `src/test/java/com/example/workutils/biz/apidoc/application/RunApiDocExportUseCaseTest.java`

**Interfaces:**
- Consumes `ApiDocExportRequest`.
- Produces `Result(Path output, int moduleCount, int classCount, int methodCount)`.
- Reports progress through `OperationContext`.

- [ ] Test proxy-disabled execution does not resolve a local endpoint and proxy-enabled execution resolves it once.
- [ ] Observe focused test failure.
- [ ] Move export orchestration behind the use case and connect it to `AsyncOperationController`.
- [ ] Bind the button through `LoadingButtonBinder` and status through `OperationStatusPane`.
- [ ] Confirm focused and existing tests pass.

### Task 4: Shared history UI

**Files:**
- Modify: `src/main/java/com/example/workutils/biz/apidoc/ApiDocWindow.java`
- Test: `src/test/java/com/example/workutils/biz/apidoc/ApiDocHistoryMappingTest.java`

**Interfaces:**
- Produces package-visible `toHistoryItem(HistoryRow)`.
- Consumes `ExportHistoryPane` and `HistoryFileCommands`.

- [ ] Test history mapping.
- [ ] Observe focused test failure.
- [ ] Replace duplicated table and action cell.
- [ ] Confirm focused test passes.

### Task 5: Verification

- [ ] Run all tests.
- [ ] Compile with JDK 17.
- [ ] Run `git diff --check`.
- [ ] Confirm `ApiDocWindow` contains no `new Thread`, `buildActionCell`, or direct export-button state mutations.
- [ ] Inspect PATH, FQN, and BATCH panels without invoking export or file choosers.