jsowell-charger-web/AGENTS.md

# Repository Guidelines

This repository contains a Java 8, multi-module Spring Boot backend plus a separate Vue 2 (Vue CLI) admin UI.

## Project Structure & Module Organization

- Backend parent: `pom.xml` (aggregates the Maven modules).
- Backend modules live under `jsowell-*/`.
  - Entry point/service: `jsowell-admin/` (Spring Boot app).
  - Shared/core: `jsowell-common/`, `jsowell-framework/`, `jsowell-system/`.
  - Business/integrations: `jsowell-pile/`, `jsowell-netty/`, `jsowell-thirdparty/`, plus schedulers/generator/settlement modules.
- UI: `jsowell-charge-ui/` (not part of the Maven build). Code is in `jsowell-charge-ui/src/`, static assets in `jsowell-charge-ui/public/`.
- Reference material: `doc/`, `docs/`; database scripts: `sql/`; helper batch scripts: `bin/`.

## Build, Test, and Development Commands

Backend (from repo root):
- `mvn clean compile`: compile all modules.
- `mvn clean package -DskipTests` (or `bin\\package.bat`): build artifacts.
- `mvn test` (or `mvn -pl jsowell-admin test`): run backend tests.
- `mvn -pl jsowell-admin spring-boot:run -Dspring-boot.run.profiles=dev`: run the API locally.

UI (from `jsowell-charge-ui/`):
- `npm run dev`: start dev server (uses `jsowell-charge-ui/.env.*` modes).
- `npm run build:prd`: production build.
- `npm run lint`: ESLint on `src/`.

## Coding Style & Naming Conventions

- Java: follow existing conventions (4 spaces; `PascalCase` types; `camelCase` methods; `UPPER_SNAKE_CASE` constants). Keep changes scoped to one module when possible.
- UI: follow `jsowell-charge-ui/.editorconfig` + `jsowell-charge-ui/.eslintrc.js` (2 spaces, single quotes, no semicolons). Run `npm run lint` before PRs.

## Testing Guidelines

- Backend tests are primarily in `jsowell-admin/src/test/java` and use Spring Boot + JUnit.
- Prefer `*Test.java` naming and avoid tests that depend on external services unless clearly marked/configured.

## Commit & Pull Request Guidelines

- Commit subjects commonly use short prefixes: `add ...`, `update ...`, `bugfix ...`. Keep them under ~72 chars; add module context when helpful (example: `jsowell-charge-ui: update login flow`).
- PRs should target `dev` unless agreed otherwise, include a clear description, and link the relevant issue/ticket.
- Include screenshots for UI changes and migration notes for DB/API changes (`sql/`, request/response examples).

## Security & Configuration Notes

- Environment config lives in `jsowell-admin/src/main/resources/application-*.yml` and `jsowell-charge-ui/.env.*`.
- Do not commit real secrets/keys; use placeholders and local overrides.
- See `CLAUDE.md` for deeper architecture and operational notes.