From 1bcea41c5e1758286eb17a2a7df00d1a76c3a4c9 Mon Sep 17 00:00:00 2001
From: zgw <13623675548@163.com>
Date: Tue, 4 Aug 2026 09:57:13 +0800
Subject: [PATCH] docs: define javaTest method comment coverage

---
 ...-04-javaTest-method-commentation-design.md | 63 +++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-04-javaTest-method-commentation-design.md

diff --git a/docs/superpowers/specs/2026-08-04-javaTest-method-commentation-design.md b/docs/superpowers/specs/2026-08-04-javaTest-method-commentation-design.md
new file mode 100644
index 0000000..6bf32a1
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-04-javaTest-method-commentation-design.md
@@ -0,0 +1,63 @@
+# JavaTest Method Commentation Design
+
+## Goal
+
+Make every Java method under `javaTest/src/main/java` and `javaTest/src/test/java`
+readable to a developer who is learning the WCS simulation, without changing
+runtime behavior, public APIs, test data, or test outcomes.
+
+## Scope
+
+- Cover all Java source files under `javaTest/src/main/java` and
+  `javaTest/src/test/java`.
+- Cover every constructor, public method, private method, package-visible
+  method, getter, helper, and test method.
+- Add class-level context where a class represents a domain concept, algorithm,
+  adapter, simulator, result object, or test fixture.
+- Preserve generated resources, output evidence, Maven configuration, and all
+  non-Java files unchanged.
+
+## Comment Style
+
+- Use Chinese Javadoc immediately above each method.
+- State the method's responsibility first. Add inputs, return meaning,
+  state changes, ordering rules, failure behavior, or invariants only when they
+  help the reader understand behavior beyond the signature.
+- Use `@param`, `@return`, and `@throws` when a method has meaningful inputs,
+  results, or deliberate failure behavior.
+- Constructors describe the object state that is established.
+- Simple getters receive concise comments identifying the exposed state rather
+  than repeating implementation details.
+- Test methods describe the business scenario, fixture condition, and assertion
+  intent. Test helpers describe the deterministic data or topology they build.
+- Use short line or block comments only before non-obvious algorithmic sections,
+  including path construction, resource reservation/release, fault recovery,
+  watchdog progress, report metrics, and endpoint mapping. Do not annotate each
+  statement mechanically.
+
+## Content Rules
+
+- Comments describe current code, never intentions that the implementation does
+  not satisfy.
+- Keep domain terms consistent: task, vehicle, route, node, edge, resource,
+  HOLD, redispatch, PLC, WMS, archive, history path, and physical endpoint.
+- Distinguish historical comparison fields from fields that affect current
+  dispatch decisions.
+- Preserve English identifiers, enum values, exception messages, and protocol
+  names; explain their business meaning in Chinese when needed.
+- Avoid comments that claim field-test or production behavior. The existing
+  boundary remains an in-memory simulation unless a class actually controls a
+  real integration.
+
+## Verification
+
+- Use a source scan to confirm every Java method and constructor has a
+  immediately preceding Javadoc block.
+- Compile and run `mvn clean test` from `javaTest` after all comment-only edits.
+- Review `git diff --check` and confirm the diff contains comments only.
+
+## Non-Goals
+
+- No refactoring, renaming, logic changes, formatting-only rewrites, or new
+  features.
+- No modification to `ruoyi-*` production modules.