docs(javaTest): document every Java method

docs/superpowers/plans/2026-08-04-javaTest-method-commentation-plan.md

@@ -0,0 +1,129 @@
+# JavaTest Method Commentation 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:** Add Chinese documentation to every Java constructor and method under `javaTest`, with detailed explanations for the WCS dispatch simulation's core control flow.
+
+**Architecture:** Use a temporary Java compiler-API scanner to find every `MethodTree` reliably, including nested types and multi-line declarations. Use the same scanner after editing to prove that each method has an immediately preceding Javadoc block. Add concise comments to simple value objects and tests, then enrich scheduler, map, resource, simulation, report, and fault-handling methods manually where behavior cannot be inferred from a name alone.
+
+**Tech Stack:** Java 8 source, JDK compiler tree API, Maven, JUnit 5.
+
+## Global Constraints
+
+- Modify only Java comments under `javaTest/src/main/java` and `javaTest/src/test/java`; no executable Java behavior may change.
+- Cover every constructor and method, including getters, helpers, nested types, and JUnit test methods.
+- Use Chinese Javadoc. Add `@param`, `@return`, or `@throws` where the signature's contract needs explanation.
+- Keep line comments restricted to complex algorithmic blocks.
+- Do not modify `ruoyi-*` modules, test resources, Maven configuration, or generated evidence.
+- Final verification requires a complete method-Javadoc scan, `git diff --check`, and `cd javaTest && mvn clean test`.
+
+---
+
+### Task 1: Establish method coverage inventory
+
+**Files:**
+- Read: `javaTest/src/main/java/**/*.java`
+- Read: `javaTest/src/test/java/**/*.java`
+- Create temporarily outside the repository: compiler-API scanner source and compiled class.
+
+**Interfaces:**
+- Consumes: Java source roots.
+- Produces: a deterministic list of methods lacking a Javadoc block directly before the declaration.
+
+- [x] **Step 1: Run a baseline scan**
+
+Compile and run a temporary Java program that uses `JavacTask.parse()` and `TreePathScanner.visitMethod()` to print `<relative-file>:<line>:<method>` when the declaration's preceding non-whitespace source text does not end in `*/`.
+
+Expected: every current Java method is reported because the baseline contains no Javadocs.
+
+- [x] **Step 2: Preserve the scanner command for final verification**
+
+Use the same temporary scanner source and source roots without modifying any repository file. The final run must emit no missing methods.
+
+### Task 2: Cover non-simulation production support code
+
+**Files:**
+- Modify: `javaTest/src/main/java/com/ft546/wcs/demo/**/*.java`
+- Modify: `javaTest/src/main/java/com/ft546/wcs/shadow/{decision,map,replay,resource,snapshot}/**/*.java`
+
+**Interfaces:**
+- Consumes: method names, signatures, and class responsibilities.
+- Produces: a Javadoc block for every method in the listed packages.
+
+- [x] **Step 1: Add type and method Javadocs**
+
+Document domain values, queue admission, vehicle assignment, path and traffic helpers, decision models, replay adapters, resource ledgers, and snapshots. For setters and lifecycle methods, state which state changes. For predicates, state the condition evaluated. For value-object accessors, state the exposed field meaning.
+
+- [x] **Step 2: Add algorithm block comments**
+
+Explain only non-obvious loops and ordering rules, such as candidate scoring, resource capacity evaluation, canonical edge keys, and snapshot version checks.
+
+- [x] **Step 3: Run the coverage scan for the listed roots**
+
+Expected: no method from these packages appears in the scanner output.
+
+### Task 3: Cover history ingestion and complete dispatch simulation
+
+**Files:**
+- Modify: `javaTest/src/main/java/com/ft546/wcs/shadow/history/**/*.java`
+- Modify: `javaTest/src/main/java/com/ft546/wcs/shadow/history/simulation/**/*.java`
+
+**Interfaces:**
+- Consumes: historical queue/map records and the in-memory simulation workflow.
+- Produces: method-level explanations of data normalization, full-grid compilation, endpoint resolution, scheduling, path planning, arbitration, clearance, PLC acknowledgement, movement, release, archive, WMS callback, fault recovery, reporting, and metrics.
+
+- [x] **Step 1: Add comments to history loading and data objects**
+
+Explain manifest/hash validation, historical-field boundaries, normalized path quality issues, and immutable result/data object accessors.
+
+- [x] **Step 2: Add detailed comments to simulation orchestration**
+
+For `HistoricalDispatchSimulator` and related managers, describe the tick order, eligible vehicle selection, independent path planning, corridor ownership, HOLD/redispatch conditions, clearance move lifecycle, resource release timing, watchdog rules, terminalization, and invariants.
+
+- [x] **Step 3: Add detailed comments to report and adapter code**
+
+Explain duration scaling, historical-vs-simulated comparison fields, CSV escaping, deterministic manifest construction, and the distinction between WMS deliveries and idempotent business effects.
+
+- [x] **Step 4: Run the coverage scan for main sources**
+
+Expected: no production Java method appears in the scanner output.
+
+### Task 4: Cover test code and fixtures
+
+**Files:**
+- Modify: `javaTest/src/test/java/**/*.java`
+
+**Interfaces:**
+- Consumes: existing JUnit scenarios and fixture helpers.
+- Produces: a Javadoc block for every test, lifecycle helper, and fixture/data builder explaining scenario setup and assertion intent.
+
+- [x] **Step 1: Document unit and integration tests**
+
+Describe the expected business property for every test. Document parameter sources, fixture constructors, synthetic maps, deterministic fault plans, and test data builders so a reader can understand why the scenario exists.
+
+- [x] **Step 2: Run the coverage scan for test sources**
+
+Expected: no test method or fixture helper appears in the scanner output.
+
+### Task 5: Verify comment-only delivery
+
+**Files:**
+- Verify: all Java files under `javaTest/src/main/java` and `javaTest/src/test/java`.
+
+- [x] **Step 1: Run the full source coverage scan**
+
+Expected: zero missing Javadocs across all constructors and methods.
+
+- [x] **Step 2: Inspect the diff for accidental behavior changes**
+
+Run `git diff --check` and inspect changed Java lines. Expected: only comments and unavoidable line-ending metadata warnings; no executable statements, imports, signatures, or literals change.
+
+- [x] **Step 3: Run full verification**
+
+Run `cd javaTest && mvn clean test`.
+
+Expected: the existing complete suite passes without test failures, errors, or skips.
+
+- [x] **Step 4: Commit the documentation change**
+
+Run `git add javaTest/src/main/java javaTest/src/test/java docs/superpowers/plans/2026-08-04-javaTest-method-commentation-plan.md` followed by `git commit -m "docs(javaTest): document every Java method"`.