# Repository Guidelines

## Project Structure & Module Organization
- Java backend lives in `src/main/java/com/zy`: `core` drives device orchestration, `asrs` holds domain logic/tasks/websockets, `system` manages auth/permissions/logging, and `common` hosts shared web/utils.
- Resources in `src/main/resources`: `application.yml`, MyBatis-Plus XML mappers in `mapper/`, and SQL helpers in `sql/`.
- UI assets sit in `src/main/webapp` with static JS/CSS/Layui/Vue and feature views grouped under `views/` (e.g., `views/locMast`, `views/user`).
- Build output lands in `target/` as `wcs.war`; runtime logs default to `stock/out/wcs/logs`.

## Build, Test, and Development Commands
- `mvn clean package -DskipTests` — compile and build the WAR in `target/`.
- `mvn spring-boot:run` — start the app using `src/main/resources/application.yml`.
- `mvn test` — execute the test suite (add tests under `src/test/java`).
- Adjust DB/Redis endpoints in `application.yml` or via env overrides before running locally.

## Coding Style & Naming Conventions
- Java 8 with 4-space indentation; Lombok annotations already used in entities/services.
- Controllers end with `Controller`, services with `Service`/`ServiceImpl`, and MyBatis mappers with `Mapper` plus XML in `mapper/`.
- Use `camelCase` for fields/methods, `UPPER_SNAKE_CASE` for constants, and package by feature (core/asrs/system/common).
- Keep REST endpoints descriptive and consistent with the `/@pom.build.finalName@` context path.

## Testing Guidelines
- Add JUnit/Spring Boot tests in `src/test/java` mirroring package structure; name classes `*Test`.
- For data access, prefer `@SpringBootTest` with test containers or stubbed beans; isolate mapper XML where possible.
- Target coverage on controller/service logic and device orchestration flows; document required external services.

## Commit & Pull Request Guidelines
- Use imperative, scoped commit messages (e.g., `core: stabilize rgv reconnect`) and keep commits focused.
- PRs should describe the change, related ticket/issue, how to reproduce/verify, and note config or schema impacts.
- Include screenshots for UI updates under `src/main/webapp` and list commands/tests executed (build, test, spring-boot:run).
- Avoid committing secrets; sanitize `application.yml` or provide sample overrides instead.

## Security & Configuration Tips
- Update database and Redis credentials in `application.yml` before running; never commit real credentials.
- Logging path defaults to `./stock/out/wcs/logs`; ensure the directory is writable in your environment.
- Swagger is disabled by default (`swagger.enable: false`); enable only in trusted environments.