张家训
93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# 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.
|