# CLAUDE.md: Spring Boot 4 service

## Commands
`./mvnw verify` (or `./gradlew check`) · run: `./mvnw spring-boot:run` · single test: `./mvnw test -Dtest=OrderServiceTest`
- Check `pom.xml`/`build.gradle.kts` for the exact Boot version; if it's still 3.x, follow 3.x APIs.

## Code rules
- Java 25, constructor injection, `record` DTOs, package-by-feature.
- Null-safety: packages annotated with JSpecify `@NullMarked`; mark optional values `@Nullable`. Don't return `null` collections.
- Outbound HTTP via `RestClient` or declarative HTTP service interfaces (`@HttpExchange`, `@GetExchange`) registered as clients; set timeouts.
- JSON is Jackson 3 in Boot 4 (`tools.jackson.*` packages); don't mix in Jackson 2 imports in new code.
- Validation with `@Valid` + Jakarta constraints; errors as `ProblemDetail` from `@RestControllerAdvice`.
- `@Transactional` on service methods only; read-only where possible. Avoid N+1 with fetch joins/entity graphs.
- Flyway migrations for every schema change; never `ddl-auto=update`.
- Config via `@ConfigurationProperties` records with validation.
- Observability: Micrometer + `spring-boot-starter-actuator`; expose only `health`/`info`/`prometheus` publicly.

## Testing
- Slices: `@WebMvcTest` with `MockMvcTester`, `@DataJpaTest` + Testcontainers (`@ServiceConnection`). Use `@MockitoBean` (not the removed `@MockBean`).
- Integration: a few `@SpringBootTest` tests for critical paths.

## Don't
Don't add Lombok to a project that doesn't use it, or catch-and-ignore exceptions.