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-ui/ (not part of the Maven build). Code is in jsowell-ui/src/, static assets in jsowell-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-ui/):

• npm run dev: start dev server (uses jsowell-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-ui/.editorconfig + jsowell-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-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-ui/.env.*.
• Do not commit real secrets/keys; use placeholders and local overrides.
• See CLAUDE.md for deeper architecture and operational notes.