keyboard_backend/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Entrypoint src/main/java/com/yolo/keyborad/MyApplication.java; feature code organized by layer: controller (REST), service (business), mapper (MyBatis mappers), model/common/constant for DTOs, responses, and constants, plus config, aop, annotation, Interceptor, and utils for cross-cutting concerns.
• Resource configs live in src/main/resources: application.yml with application-dev.yml/application-prod.yml profiles, mapper XML files under mapper/, and platform keys/certs (Apple, mail, storage). Keep secrets out of commits.
• Tests belong in src/test/java/com/yolo/keyborad/... mirroring package names; add fixtures alongside tests when needed.

Build, Test, and Development Commands

• ./mvnw clean install — full build with tests; requires JDK 17.
• ./mvnw test — run test suite only.
• ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev — start the API with the dev profile (loads application-dev.yml).
• ./mvnw clean package -DskipTests — create an artifact when tests are already covered elsewhere.

Coding Style & Naming Conventions

• Java 17, Spring Boot 3.5, MyBatis/MyBatis-Plus; prefer Lombok for boilerplate (@Data, @Builder) and constructor injection for services.
• Use 4-space indentation, lowercase package names, UpperCamelCase for classes, lowerCamelCase for fields/params.
• Controllers end with *Controller, services with *Service, mapper interfaces with *Mapper, and request/response DTOs under model or common with clear suffixes like Request/Response.
• Keep configuration isolated in config; shared constants in constant; AOP/logging in aop; custom annotations in annotation.

Testing Guidelines

• Use Spring Boot Test + JUnit (via spring-boot-starter-test, JUnit 4/5 support) and MockMvc/WebTestClient for HTTP layers when practical.
• Name classes *Test and align packages with the code under test. Cover service logic, mappers, and controller contracts (status + payload shape).
• For data-access tests, use in-memory setups or dedicated test containers and clean up test data.

Commit & Pull Request Guidelines

• Follow the existing conventional style seen in history (e.g., feat(user): add email registration); keep scope lowercase and concise.
• PRs should describe the change, list validation steps/commands run, call out config/profile impacts, and link issues/tasks. Add screenshots or sample requests/responses for API-facing changes when helpful.
• Ensure secrets (p8 certificates, Mailgun keys, AWS creds) are never committed; rely on environment variables or local config overrides.

Security & Configuration Tips

• Activate the intended profile via SPRING_PROFILES_ACTIVE or -Dspring-boot.run.profiles. Keep application-dev.yml local-only; never hardcode production endpoints or credentials.
• Validate signing/encryption helpers (SignInterceptor, JWT, Apple receipt validation) with representative non-production keys before merging.
• Log only necessary context; avoid logging tokens, receipts, or PII.