# Repository Guidelines ## Project Structure & Module Organization - Application code: `src/main/java/com/ycwl/basic/**` (controllers, services, mapper/repository, dto/model, config, util). - Resources: `src/main/resources/**` (Spring configs, `mapper/*.xml`, static assets, logging). - Tests: `src/test/java/**` mirrors main packages. - Build output: `target/` (never commit). ## Build, Test, and Development Commands - Build artifact: `mvn clean package` (tests are skipped by default via `pom.xml`). - Run locally (dev): `mvn spring-boot:run -Dspring-boot.run.profiles=dev`. - Run jar: `java -jar target/basic21-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev`. - Execute tests: `mvn -DskipTests=false test` (note: `pom.xml` excludes `**/*Test.java` from test-compile; temporarily remove/override that config if you need to compile and run tests). ## Coding Style & Naming Conventions - Java 21. Use 4-space indentation; UTF-8; no wildcard imports. - Packages: `com.ycwl.basic.*`; classes PascalCase; methods/fields camelCase; constants UPPER_SNAKE_CASE. - Controllers in `controller`, business logic in `service`, persistence in `mapper` + `resources/mapper/*.xml`. - Prefer Lombok for boilerplate and constructor injection where applicable. ## Testing Guidelines - Framework: Spring Boot testing + JUnit (see `spring-boot-starter-test`). - Test names end with `Test` or `Tests` and mirror package structure. - Aim to cover service/util layers and critical controllers. No enforced coverage target. - To enable tests locally, remove/override the `maven-compiler-plugin` `testExcludes` in `pom.xml` and run `mvn -DskipTests=false test`. ## Commit & Pull Request Guidelines - Follow Conventional Commits: `feat(scope): summary`, `fix(scope): summary`, `refactor: ...`. - Reference issues (e.g., `#123`) and include brief rationale and screenshots for UI-facing changes. - Keep PRs focused; include run/build instructions and any config changes. ## Security & Configuration Tips - Profiles: `application.yml` and `bootstrap.yml` with `-dev`/`-prod` variants. Select via `--spring.profiles.active`. - Do not commit secrets. Provide Nacos, Redis, MySQL, OSS/S3, and 3rd‑party keys via environment or secure config. - Review `logback-spring*.xml` before raising log levels in production. ## Agent-Specific Notes - Keep changes minimal and within existing package boundaries. - Do not reorganize MyBatis XML names or mapper interfaces without updating both sides. - If altering APIs, update affected tests and documentation in the same PR.