48 lines
2.6 KiB
Markdown
48 lines
2.6 KiB
Markdown
|
# Repository Guidelines
|
||
|
|
|
||
|
|
## Project Structure & Module Organization
|
||
|
|
- Spring Boot 3 (Java 17) Maven app.
|
||
|
|
- Key paths:
|
||
|
|
- `src/main/java` — root package `com.mosquito.project` (modules: `controller`, `service`, `domain`, `dto`, `job`, `exception`).
|
||
|
|
- `src/main/resources` — app config (`application.properties`), Flyway migrations in `db/migration`.
|
||
|
|
- `src/test/java` — JUnit 5 tests mirroring `main` packages.
|
||
|
|
- `docs/`, `specs/` — documentation and specifications.
|
||
|
|
- `target/` — build outputs (generated).
|
||
|
|
|
||
|
|
## Build, Test, and Development Commands
|
||
|
|
- Build: `mvn clean package` — compile, test, and create JAR in `target/`.
|
||
|
|
- Run (dev): `mvn spring-boot:run` — start app with live reload of resources.
|
||
|
|
- Run (JAR): `java -jar target/mosquito-0.0.1-SNAPSHOT.jar`.
|
||
|
|
- Test all: `mvn test`.
|
||
|
|
- Test one: `mvn -Dtest=ActivityServiceTest test`.
|
||
|
|
- Verify: `mvn verify` — full lifecycle checks.
|
||
|
|
|
||
|
|
## Coding Style & Naming Conventions
|
||
|
|
- Java 17; 4-space indentation; one class per file; braces on same line.
|
||
|
|
- Packages: lowercase under `com.mosquito.project`.
|
||
|
|
- Classes: `PascalCase`; methods/fields: `camelCase`; constants: `UPPER_SNAKE_CASE`.
|
||
|
|
- DTOs end with `Request`/`Response`; exceptions end with `Exception`.
|
||
|
|
- Use Lombok where present (e.g., `@Getter`, `@Builder`); avoid wildcard imports.
|
||
|
|
- Validate inputs with Bean Validation annotations (e.g., `@NotNull`, `@Size`).
|
||
|
|
|
||
|
|
## Testing Guidelines
|
||
|
|
- Frameworks: JUnit 5, Spring Boot Test, WebMvcTest/MockMvc; H2 and Embedded Redis for tests; Testcontainers available when needed.
|
||
|
|
- Location: `src/test/java` with names `*Test.java`; mirror package of code under test.
|
||
|
|
- Conventions: method names like `shouldDoX_whenY()`; prefer fast slice tests for controllers, `@SpringBootTest` for integration.
|
||
|
|
- Run: `mvn test` or a focused run via `-Dtest=...`.
|
||
|
|
|
||
|
|
## Commit & Pull Request Guidelines
|
||
|
|
- Use Conventional Commits: `feat|fix|docs|test|refactor|chore(scope): message`.
|
||
|
|
- Example: `feat(activity): add graph endpoint with validation`.
|
||
|
|
- PRs: include purpose, linked issues, API examples or reproduction steps, updated tests/docs, and ensure `mvn -q verify` passes.
|
||
|
|
|
||
|
|
## Security & Configuration Tips
|
||
|
|
- App config in `src/main/resources/application.properties` (e.g., `spring.redis.host/port`); DB via `SPRING_DATASOURCE_*` env vars.
|
||
|
|
- Never commit secrets; prefer environment variables or an untracked `application-local.properties`.
|
||
|
|
- Database schema changes go through Flyway migrations in `src/main/resources/db/migration`.
|
||
|
|
|
||
|
|
## Agent-Specific Notes
|
||
|
|
- Keep changes minimal and localized; match the existing package layout.
|
||
|
|
- Avoid introducing new dependencies without discussion; update tests and docs with behavior changes.
|
||
|
|
|