# 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.