docs

AGENTS.md

@@ -0,0 +1,40 @@
+# 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.