# Backend Code Quality Guidelines

## Spring Boot Standards

### Controllers

- Use proper HTTP methods
- Endpoints should handle entities as substantives
- Make sure Response Codes include: [200, 201, 204, 400, 401, 403, 404, 409, 422, 500, 503] (if non-compliant classify as BLOCKER)
- Validate input with `@Valid`
- Handle exceptions with `@ExceptionHandler`
- Keep controllers thin - business logic in services
- Use DTOs for API contracts

### Services

- Use `@Transactional` appropriately
- Handle exceptions properly
- Keep methods focused and small
- Avoid business logic in controllers or repositories

### Repositories

- Extend appropriate Spring Data interfaces
- Use method naming conventions for queries
- Optimize queries with `@Query` when needed
- Avoid N+1 problems with `@EntityGraph`

### Entities

- Use Lombok annotations appropriately
- Define proper relationships (`@OneToMany`, `@ManyToOne`, etc.)
- Use `@Version` for optimistic locking
- Never expose entities in API - use DTOs

### Mappers

- Use Mapstruct for all mapping (If non-compliant, classify as MINOR)
- Mappers should not have logic (If non-compliant, classify as MAJOR)

### Logging

- Recommend @Slf4j annotation in Lombok (If non-compliant, classify as MINOR)

## Security Requirements

### Authentication & Authorization

- Never hardcode credentials
- Use Spring Security properly
- Validate JWT tokens correctly
- Check permissions before operations

### Data Validation

- Validate all user input
- Use parameterized queries (JPA does this by default)
- Sanitize data before logging
- Never trust client-side validation alone

### SQL Injection Prevention

- Always use JPA/JPQL or prepared statements
- Never concatenate SQL strings
- Be careful with native queries
- Use `@Query` with proper parameter binding

## Performance

### Database

- Use pagination for large result sets
- Optimize queries with proper indexes
- Avoid loading unnecessary data
- Use projections when you don't need full entities

### Threading

- Be careful with `@Async` methods
- Use proper thread pool configuration
- Avoid blocking operations in async methods
- Handle exceptions in async methods

### Caching

- Use `@Cacheable` appropriately
- Clear caches when data changes
- Don't cache sensitive data without encryption

## Testing

### Unit Tests

- Unit tests should use exclusively JUnit 5, and specific annotations @SpringBootTest, @MockBean, @Test
- Use `@DataJpaTest` for repository tests
- Use `@WebMvcTest` for controller tests
- Mock external dependencies
- Aim for 80%+ coverage on new code

### Integration Tests

- Use `@SpringBootTest` with real application context
- Test complete request-response flows
- Verify database transactions and rollbacks
- Test API endpoint integration with all layers
- Use `@Transactional` with `@Rollback` for test data cleanup

### Security Tests

- Test authentication and authorization scenarios
- Verify access control for protected endpoints
- Test with invalid/expired tokens
- Validate input sanitization and XSS prevention
- Test SQL injection prevention with malicious input

## Common Issues to Avoid

❌ Returning entities from controllers
❌ Missing `@Transactional` on write operations
❌ Hardcoded secrets or credentials
❌ Catching and ignoring exceptions
❌ Missing input validation
❌ Exposing sensitive data in logs
❌ Using `SELECT *` in queries
❌ Not handling null values properly