FrameTour-BE/AGENTS.md

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.