profile-java-database-accesslisted

# Profile — Java Database Access Opinionated conventions for Java projects using JPA for database access. Apply these rules only when `PROJECT_BRIEF.md` → `## Profiles` lists `profile-java-database-access`. ## Precedence `PROJECT_BRIEF.md` > this profile > model defaults. If the brief contradicts any rule below, follow the brief and surface the conflict to the user. If the brief is silent, this profile is authoritative. ## Rules ### 1. DTO projections, not entity queries Fetch the shape the caller needs, not the whole entity. - Use JPQL constructor expressions: `SELECT new com.example.FooDto(f.id, f.name) FROM FooEntity f`. - Or use Spring Data interface / class projections on repository methods. - Or use the Criteria API with explicit `.multiselect(...)` returning a DTO, not an entity. - Repository methods should declare DTO return types (or projection interfaces) whenever the caller does not need a managed, mutable entity. - **Entities MUST NOT leave the repository layer.** Convert at the repository boundary. - Entity-returning queries are permitted only when the caller genuinely needs a managed, mutable entity in the same transaction (update-and-save flows). Document why in a short comment on those methods. ### 2. Bulk retrieval over iterative round-trips One query returning many rows beats N queries each returning one. - Use `IN` clauses with `findAllById(Collection<ID>)`, or explicit JPQL `WHERE id IN :ids`. - For lazy collections or associations that will be i