# CannaManage — Coding Standards & Git Strategy

**Phase 4a | Document 7 of 7**  
**Date:** 2026-04-06  
**Stack:** Java 21 · Spring Boot 3.x · JPA/Hibernate · PrimeFaces JSF · PostgreSQL

---

## Table of Contents

1. [Project Structure](#1-project-structure)
2. [Java Coding Standards](#2-java-coding-standards)
3. [Compliance Code Rules](#3-compliance-code-rules)
4. [Git Strategy](#4-git-strategy)
5. [Testing Standards](#5-testing-standards)
6. [Code Review Checklist](#6-code-review-checklist)
7. [Security Standards](#7-security-standards)
8. [Environment Configuration](#8-environment-configuration)

---

## 1. Project Structure

### Maven Multi-Module Layout

```
cannamanage/
├── pom.xml                         # Parent POM — dependency management, versions
├── cannamanage-domain/             # JPA entities, enums, exceptions, value objects
│   └── src/main/java/de/cannamanage/domain/
│       ├── member/                 # Member, MemberStatus, MembershipType
│       ├── distribution/           # Distribution, DistributionRecord
│       ├── stock/                  # Strain, Batch, BatchStatus
│       ├── compliance/             # ComplianceConstants, QuotaExceededException
│       └── common/                 # AbstractTenantEntity, TenantId
│
├── cannamanage-service/            # Business logic, compliance engine, repositories
│   └── src/main/java/de/cannamanage/service/
│       ├── member/                 # MemberService, MemberRepository
│       ├── distribution/           # DistributionService, DistributionRepository
│       ├── stock/                  # StockService, BatchRepository
│       ├── compliance/             # ComplianceService, QuotaCalculator
│       └── report/                 # ReportDataService
│
├── cannamanage-web/                # PrimeFaces JSF backing beans + XHTML views
│   └── src/main/
│       ├── java/de/cannamanage/web/
│       │   ├── admin/              # AdminDashboardBean, DistributionFormBean
│       │   ├── member/             # MemberDashboardBean
│       │   └── common/             # AuthBean, NavigationBean
│       └── webapp/
│           ├── admin/              # dashboard.xhtml, distribution-form.xhtml, stock.xhtml
│           ├── member/             # dashboard.xhtml, stock.xhtml
│           └── WEB-INF/            # faces-config.xml, web.xml
│
├── cannamanage-api/                # REST controllers (Spring Boot MVC)
│   └── src/main/java/de/cannamanage/api/
│       ├── member/                 # MemberController, MemberDto
│       ├── distribution/           # DistributionController, DistributionDto
│       ├── stock/                  # StockController, BatchDto
│       ├── auth/                   # AuthController, JwtFilter
│       └── report/                 # ReportController
│
└── cannamanage-report/             # iText 7 PDF generation
    └── src/main/java/de/cannamanage/report/
        ├── monthly/                # MonthlyComplianceReport
        ├── recall/                 # BatchRecallReport
        └── export/                 # MemberCsvExporter
```

### Module Dependencies

```
cannamanage-domain    (no deps on other modules)
       ↑
cannamanage-service  (depends on domain)
       ↑
cannamanage-api      (depends on service, domain)
cannamanage-web      (depends on service, domain)
cannamanage-report   (depends on service, domain)
```

`cannamanage-api` and `cannamanage-web` are siblings — they do not depend on each other. The web module is the PrimeFaces JSF frontend (MVP); the API module provides the REST layer (future mobile / integration use).

---

## 2. Java Coding Standards

### Language Version

Java 21. All modern language features are permitted and preferred:

| Feature | Use Case | Example |
|---|---|---|
| Records | DTOs, value objects, query results | `record MemberSummary(UUID id, String name, BigDecimal quotaUsed)` |
| Sealed classes | Result types, compliance outcomes | `sealed interface QuotaResult permits QuotaOk, QuotaWarning, QuotaExceeded` |
| Text blocks | JPQL, SQL in tests, JSON fixtures | `String jpql = """ SELECT m FROM Member m WHERE... """` |
| Pattern matching `instanceof` | Type checks in services | `if (result instanceof QuotaExceeded e) { ... }` |
| Switch expressions | Status mapping, report routing | `yield` syntax preferred |

### Package Structure

Pattern: `de.cannamanage.[module].[layer]`

```
de.cannamanage.domain.member          # Member entity
de.cannamanage.domain.compliance      # ComplianceConstants, exceptions
de.cannamanage.service.distribution   # DistributionService
de.cannamanage.api.stock              # StockController, BatchDto
de.cannamanage.web.admin              # DistributionFormBean
de.cannamanage.report.monthly         # MonthlyComplianceReport
```

### Class Naming Conventions

| Type | Pattern | Example |
|---|---|---|
| JPA Entity | `{Domain}` | `Member`, `Distribution`, `Batch` |
| Spring Service | `{Domain}Service` | `MemberService`, `ComplianceService` |
| Repository | `{Domain}Repository` | `DistributionRepository` |
| REST Controller | `{Domain}Controller` | `StockController` |
| JSF Backing Bean | `{Screen}Bean` | `DistributionFormBean`, `AdminDashboardBean` |
| DTO (request) | `{Domain}Request` | `CreateDistributionRequest` |
| DTO (response) | `{Domain}Response` / `{Domain}Dto` | `MemberSummaryDto` |
| Exception | `{Condition}Exception` | `QuotaExceededException`, `BatchRecalledException` |
| Enum | `{Domain}Status` / `{Domain}Type` | `BatchStatus`, `MembershipType` |
| Constants class | `{Domain}Constants` | `ComplianceConstants` |

### Dependency Injection

**Constructor injection only.** Field injection (`@Autowired` on fields) is prohibited.

```java
// ✅ Correct
@Service
@RequiredArgsConstructor
public class DistributionService {

    private final DistributionRepository distributionRepository;
    private final ComplianceService complianceService;
    private final MemberRepository memberRepository;
}

// ❌ Prohibited
@Service
public class DistributionService {

    @Autowired
    private DistributionRepository distributionRepository;
}
```

Lombok `@RequiredArgsConstructor` is the preferred way to generate the constructor.

### Entity Base Class

All `@Entity` classes must extend `AbstractTenantEntity`. No raw entities without tenant isolation.

```java
// de.cannamanage.domain.common.AbstractTenantEntity
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class AbstractTenantEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;

    @Column(name = "tenant_id", nullable = false, updatable = false)
    private UUID tenantId;

    @CreatedDate
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    @LastModifiedDate
    @Column(name = "updated_at", nullable = false)
    private Instant updatedAt;
}

// ✅ All entities extend this
@Entity
@Table(name = "members")
@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Member extends AbstractTenantEntity {
    // domain fields only — no id/tenantId/audit fields here
}
```

### Transaction Boundaries

- `@Transactional` belongs on **service layer** methods only
- Controllers and repositories must not declare `@Transactional`
- Use `@Transactional(readOnly = true)` for query-only methods — improves performance with Hibernate's read-only session optimization

```java
// ✅ Service layer — correct
@Service
@RequiredArgsConstructor
public class MemberService {

    @Transactional(readOnly = true)
    public MemberSummaryDto getById(UUID memberId, UUID tenantId) { ... }

    @Transactional
    public void updateMemberStatus(UUID memberId, MemberStatus status, UUID tenantId) { ... }
}

// ❌ Controller — prohibited
@RestController
public class MemberController {

    @Transactional  // Never here
    @GetMapping("/members/{id}")
    public MemberSummaryDto getMember(@PathVariable UUID id) { ... }
}
```

### Lombok Usage

| Annotation | Allowed | Notes |
|---|---|---|
| `@Getter` | ✅ | On entities and DTOs |
| `@Setter` | ✅ | Use sparingly on entities; prefer builder pattern |
| `@Builder` | ✅ | On entities and DTOs |
| `@RequiredArgsConstructor` | ✅ | Services, beans (for DI) |
| `@NoArgsConstructor` | ✅ | JPA requires no-arg constructor |
| `@AllArgsConstructor` | ✅ | With `@Builder` |
| `@ToString` | ✅ | Exclude sensitive fields: `@ToString.Exclude` on `passwordHash` etc. |
| `@EqualsAndHashCode` | ✅ | Entities: only on `id` field |
| `@Data` | ❌ | **Prohibited on entities** — generates mutable setters for all fields, breaks JPA proxy patterns |
| `@SneakyThrows` | ❌ | Never hide checked exceptions |

### Code Style

- **Checkstyle config:** Google Java Style Guide (`checkstyle-google.xml` in parent POM)
- **Indentation:** 4 spaces (no tabs)
- **Line length:** 120 characters max
- **No magic numbers** — use named constants or enums:

```java
// ❌ Magic number
if (member.getAge() < 21) { limit = 30; }

// ✅ Named constant
if (member.getAge() < ComplianceConstants.AGE_LIMIT_UNDER21) {
    limit = ComplianceConstants.MONTHLY_LIMIT_UNDER21_GRAMS;
}
```

---

## 3. Compliance Code Rules

These rules apply exclusively to code that enforces CanG (Cannabisgesetz) distribution limits. Violations here carry legal risk.

### Compliance Constants

All legal limits live in a single, centrally tested constants class. **Never hardcode these values inline.**

```java
// de.cannamanage.domain.compliance.ComplianceConstants
public final class ComplianceConstants {

    private ComplianceConstants() {} // no instantiation

    /** Maximum grams per single distribution for any member. */
    public static final BigDecimal DAILY_LIMIT_GRAMS = new BigDecimal("25.0");

    /** Monthly gram limit for adult members (age ≥ 21). */
    public static final BigDecimal MONTHLY_LIMIT_ADULT_GRAMS = new BigDecimal("50.0");

    /** Monthly gram limit for members under 21 years of age (CanG §10 Abs.1). */
    public static final BigDecimal MONTHLY_LIMIT_UNDER21_GRAMS = new BigDecimal("30.0");

    /** Age threshold below which the reduced monthly limit applies. */
    public static final int AGE_LIMIT_UNDER21 = 21;

    /** Minimum age for club membership (CanG §15 Abs.1). */
    public static final int MINIMUM_MEMBER_AGE = 18;
}
```

### ComplianceService Rules

1. `ComplianceService` methods **must always execute within a `@Transactional` boundary** — either by being called from a service method already in a transaction, or by declaring `@Transactional` themselves. The compliance check and the distribution record creation must be atomic.

2. Every public method in `ComplianceService` must have a corresponding test in `ComplianceServiceTest` that exercises its boundary conditions.

3. `ComplianceService` is the **only** class permitted to read `ComplianceConstants` limits and make pass/fail decisions. No other class performs limit arithmetic.

```java
@Service
@RequiredArgsConstructor
public class ComplianceService {

    private final DistributionRepository distributionRepository;

    /**
     * Validates whether a distribution of the given weight is permitted for the member.
     *
     * <p>Checks the daily single-distribution limit and the member's monthly quota.
     * Must be called inside an existing @Transactional boundary — the calling
     * DistributionService is responsible for the transaction.
     *
     * @param memberId   the member receiving the distribution
     * @param tenantId   the club's tenant identifier
     * @param weightGrams the proposed distribution weight in grams
     * @return QuotaOk if permitted; QuotaWarning if >80% used; QuotaExceeded if over limit
     * @throws IllegalArgumentException if weightGrams exceeds DAILY_LIMIT_GRAMS
     */
    public QuotaResult checkDistributionAllowed(UUID memberId, UUID tenantId, BigDecimal weightGrams) {
        if (weightGrams.compareTo(ComplianceConstants.DAILY_LIMIT_GRAMS) > 0) {
            throw new IllegalArgumentException(
                "Single distribution exceeds daily limit of " + ComplianceConstants.DAILY_LIMIT_GRAMS + "g");
        }
        // ... monthly quota logic using ComplianceConstants
    }
}
```

### Distribution Record Immutability

Once written, a `Distribution` record may never be modified (legal audit trail requirement). Enforce this at the JPA level:

```java
@Entity
@Table(name = "distributions")
@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Distribution extends AbstractTenantEntity {

    @Column(name = "member_id", nullable = false, updatable = false)
    private UUID memberId;

    @Column(name = "batch_id", nullable = false, updatable = false)
    private UUID batchId;

    @Column(name = "weight_grams", nullable = false, updatable = false,
            precision = 8, scale = 2)
    private BigDecimal weightGrams;

    @Column(name = "distributed_at", nullable = false, updatable = false)
    private Instant distributedAt;

    @Column(name = "recorded_by_admin_id", nullable = false, updatable = false)
    private UUID recordedByAdminId;

    // No setters — @Getter only, no @Setter
    // updatable = false on ALL columns — Hibernate will reject any UPDATE attempt
}
```

### Compliance Test Coverage Requirement

`ComplianceServiceTest` must include at minimum:

| Test Method | What It Covers |
|---|---|
| `checkDistributionAllowed_givenWeightAt25g_shouldReturnQuotaOk` | Exactly at daily limit |
| `checkDistributionAllowed_givenWeightOver25g_shouldThrowIllegalArgument` | Daily limit exceeded |
| `checkDistributionAllowed_givenMemberAtMonthlyLimit_shouldReturnQuotaExceeded` | Adult at 50g |
| `checkDistributionAllowed_givenUnder21MemberAt30g_shouldReturnQuotaExceeded` | Under-21 at 30g |
| `checkDistributionAllowed_givenUnder21MemberAtAdultLimit_shouldReturnQuotaExceeded` | Under-21 must not reach 50g |
| `checkDistributionAllowed_givenMemberAt80Percent_shouldReturnQuotaWarning` | Warning threshold |
| `checkDistributionAllowed_givenMemberAt40g_shouldReturnQuotaOk` | Normal adult, within limit |

---

## 4. Git Strategy

### Branching Model — GitHub Flow (Solo Dev)

```
main ──────────────────────────────────────────────────────► (production-ready)
       │                  │                    │
       └─► feature/US-042─┘    └─► fix/member-age-edge ─┘
```

| Branch | Purpose | Merge Via |
|---|---|---|
| `main` | Production-ready code only; protected | PR only |
| `develop` | Integration branch for in-progress work | Merge to main when stable |
| `feature/US-XXX-short-description` | New feature tied to a user story | PR → develop → main |
| `fix/short-description` | Bug fix | PR → main (or develop if risk is low) |
| `chore/short-description` | Dependency updates, config, CI | PR → main |

**Branch naming examples:**
- `feature/US-042-compliance-quota-check`
- `feature/US-015-member-registration-form`
- `fix/member-under21-age-boundary`
- `chore/update-spring-boot-3.3.1`

### Commit Message Format — Conventional Commits

```
type(scope): short description (imperative, ≤72 chars)

[optional body — explain WHY, not WHAT; reference CanG sections if relevant]

[optional footer]
BREAKING CHANGE: description if applicable
Closes #issue-number
```

#### Types

| Type | When to Use |
|---|---|
| `feat` | New feature or user-visible behavior |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, whitespace — no logic change |
| `refactor` | Code restructuring — no behavior change |
| `test` | Adding or updating tests |
| `chore` | Build, deps, config, CI — no production code |

#### Scopes

| Scope | Module / Area |
|---|---|
| `member` | Member management |
| `distribution` | Distribution recording and history |
| `stock` | Strain and batch management |
| `compliance` | `ComplianceService`, `ComplianceConstants`, CanG limits |
| `auth` | JWT, Spring Security, login |
| `report` | PDF/CSV generation |
| `infra` | Docker, CI, Flyway migrations |
| `web` | PrimeFaces JSF views and backing beans |
| `api` | REST controllers and DTOs |

#### Commit Examples

```bash
feat(compliance): add daily 25g distribution limit check

Implements CanG §10 Abs.1 single-distribution cap. ComplianceService
now throws IllegalArgumentException before any quota calculation if
weightGrams > ComplianceConstants.DAILY_LIMIT_GRAMS.

fix(member): correct under-21 flag when age is exactly 21

Age comparison was using < instead of <=. Members who turn 21 on the
exact distribution date now correctly receive the adult (50g) limit.
Closes #17

test(distribution): add quota boundary tests for 30g under-21 limit

Adds 6 parameterized test cases covering 28g, 29g, 29.9g, 30g, 30.1g,
and 31g for under-21 members. All reference ComplianceConstants — no
hardcoded values in test assertions.

chore(deps): update Spring Boot to 3.3.1

CVE-2024-38821 fix included. No API changes required.

docs(compliance): document ComplianceConstants usage policy in README
```

### Tag Strategy

Semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`

```bash
git tag -a v1.0.0 -m "Initial release — core member + distribution management"
git tag -a v1.1.0 -m "Add member portal with quota view"
git tag -a v1.0.1 -m "Fix under-21 monthly limit boundary condition"
```

---

## 5. Testing Standards

### Framework Stack

| Layer | Framework | Annotation / Config |
|---|---|---|
| Unit tests | JUnit 5 + Mockito | `@ExtendWith(MockitoExtension.class)` |
| Integration tests | Spring Boot Test + Testcontainers | `@SpringBootTest`, `@Testcontainers` |
| Web layer tests | `MockMvc` | `@WebMvcTest(DistributionController.class)` |
| Repository tests | `DataJpaTest` + Testcontainers | Real PostgreSQL via Testcontainers |
| PDF generation tests | JUnit 5 + iText assertions | Verify PDF structure, not pixel comparison |

### Test Naming Convention

```
methodName_givenCondition_shouldExpectedBehavior
```

```java
// ✅ Correct
@Test
void checkDistributionAllowed_givenMemberAtMonthlyLimit_shouldThrowQuotaExceededException()

@Test
void createDistribution_givenValidRequest_shouldPersistAndReturnDto()

@Test
void getQuotaRemaining_givenUnder21Member_shouldCapAt30g()

@Test
void generateMonthlyReport_givenNoPriorDistributions_shouldReturnZeroTotals()
```

### Unit Test Structure

```java
@ExtendWith(MockitoExtension.class)
class ComplianceServiceTest {

    @Mock
    private DistributionRepository distributionRepository;

    @InjectMocks
    private ComplianceService complianceService;

    @Test
    void checkDistributionAllowed_givenMemberAtMonthlyLimit_shouldReturnQuotaExceeded() {
        // GIVEN
        UUID memberId = UUID.randomUUID();
        UUID tenantId = UUID.randomUUID();
        BigDecimal currentMonthTotal = ComplianceConstants.MONTHLY_LIMIT_ADULT_GRAMS;

        when(distributionRepository.sumWeightByMemberAndMonth(eq(memberId), eq(tenantId), any()))
            .thenReturn(currentMonthTotal);

        // WHEN
        QuotaResult result = complianceService.checkDistributionAllowed(
            memberId, tenantId, new BigDecimal("1.0"));

        // THEN
        assertThat(result).isInstanceOf(QuotaExceeded.class);
    }
}
```

### Integration Test Structure

```java
@SpringBootTest
@Testcontainers
@Transactional  // rolls back after each test
class DistributionServiceIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @DynamicPropertySource
    static void configureDataSource(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    // Tests run against real PostgreSQL — Flyway migrations apply automatically
}
```

### Coverage Target

| Module | Line Coverage Target |
|---|---|
| `cannamanage-service` | **≥ 80%** (enforced by JaCoCo in CI) |
| `cannamanage-domain` | ≥ 70% (entities + value objects) |
| `cannamanage-api` | ≥ 70% (controllers via MockMvc) |
| `cannamanage-report` | ≥ 60% (PDF generation harder to test) |
| `cannamanage-web` | Best effort (JSF backing beans — limited testability) |

### Test Rules

1. **No test may hardcode a compliance limit value.** All assertions must reference `ComplianceConstants`:

```java
// ❌ Prohibited
assertThat(limit).isEqualTo(new BigDecimal("50.0"));

// ✅ Required
assertThat(limit).isEqualTo(ComplianceConstants.MONTHLY_LIMIT_ADULT_GRAMS);
```

2. Parameterized tests (`@ParameterizedTest`) are strongly preferred for boundary condition coverage.

3. Test data builders (or fixtures) must live in `src/test/java/.../fixtures/` — no anonymous object creation scattered across test methods.

---

## 6. Code Review Checklist

Since CannaManage is a solo development project, a self-review checklist replaces a peer review process. All items must be checked before merging any PR to `main`.

### Self-Review Checklist

```markdown
## Compliance & Legal
- [ ] All distribution limits reference `ComplianceConstants` — zero hardcoded values
- [ ] `Distribution` entity fields are annotated `@Column(updatable = false)` where required
- [ ] `ComplianceService` calls are only made inside `@Transactional` boundaries
- [ ] New compliance rules have corresponding unit tests in `ComplianceServiceTest`

## Data & Multi-Tenancy
- [ ] New entity extends `AbstractTenantEntity`
- [ ] `tenant_id` is never accepted from user input (HTTP body, query param, path variable)
- [ ] All repository queries filter by `tenantId` — no cross-tenant data leakage possible

## Security & DSGVO
- [ ] No PII in log statements (no email, full name, member number in log lines)
- [ ] No passwords, tokens, or secrets hardcoded anywhere
- [ ] New REST endpoints annotated with `@PreAuthorize`
- [ ] DTOs validated with Bean Validation annotations (`@NotNull`, `@Size`, etc.)

## Database
- [ ] Flyway migration file added for any schema change (`V{n}__description.sql`)
- [ ] Migration file is backward-compatible or includes rollback notes
- [ ] No `@Column(nullable = false)` added without corresponding DB migration

## Code Quality
- [ ] Constructor injection used — no `@Autowired` field injection
- [ ] No `@Data` on JPA entities
- [ ] No magic numbers — named constants or enums used
- [ ] Checkstyle passes locally (`./mvnw checkstyle:check`)
- [ ] Javadoc on all public service methods

## Testing
- [ ] Unit test added for new service method
- [ ] Integration test updated if schema or contract changed
- [ ] Test coverage does not decrease in `cannamanage-service`
- [ ] Test method names follow `method_givenCondition_shouldExpect` pattern

## General
- [ ] Commit message follows Conventional Commits format
- [ ] Branch name follows `feature/US-XXX-` or `fix/` convention
- [ ] No `TODO` comments left in production code (use GitHub Issues instead)
```

---

## 7. Security Standards

### Authentication & Authorization

```java
// JWT secret from environment only — never in application.properties
@Value("${JWT_SECRET}")
private String jwtSecret;

// All endpoints behind @PreAuthorize — no security by obscurity
@RestController
@RequestMapping("/api/v1/distributions")
public class DistributionController {

    @GetMapping
    @PreAuthorize("hasRole('ADMIN')")
    public Page<DistributionDto> list(...) { ... }

    @PostMapping
    @PreAuthorize("hasRole('ADMIN')")
    public DistributionDto create(...) { ... }
}

// Member portal endpoints restricted to role + own data
@GetMapping("/api/v1/member/quota")
@PreAuthorize("hasRole('MEMBER') and #memberId == authentication.principal.memberId")
public QuotaDto getQuota(@RequestParam UUID memberId) { ... }
```

### CORS Configuration

```java
@Bean
CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    // No wildcard — club subdomain only
    config.setAllowedOriginPatterns(List.of("https://*.cannamanage.de"));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
    config.setAllowCredentials(true);
    // ...
}
```

### Input Validation

All DTOs must be annotated with Bean Validation constraints. The controller calls `@Valid` on request bodies.

```java
public record CreateDistributionRequest(

    @NotNull(message = "Member ID is required")
    UUID memberId,

    @NotNull(message = "Batch ID is required")
    UUID batchId,

    @NotNull(message = "Weight is required")
    @DecimalMin(value = "0.1", message = "Weight must be at least 0.1g")
    @DecimalMax(value = "25.0", message = "Weight cannot exceed daily limit")
    BigDecimal weightGrams
) {}
```

### SQL Injection Prevention

- **JPA named queries only** — no string concatenation in JPQL
- Spring Data JPA repository methods generate parameterized queries automatically
- Native SQL queries use `@Query` with named parameters (`:param` syntax), never `+`

```java
// ✅ Safe — parameterized
@Query("SELECT SUM(d.weightGrams) FROM Distribution d WHERE d.memberId = :memberId AND d.tenantId = :tenantId AND MONTH(d.distributedAt) = :month")
BigDecimal sumWeightByMemberAndMonth(@Param("memberId") UUID memberId,
                                     @Param("tenantId") UUID tenantId,
                                     @Param("month") int month);

// ❌ Prohibited — SQL injection risk
String jpql = "SELECT ... WHERE name = '" + memberName + "'";
```

### Password Hashing

```java
@Bean
PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder(12);  // strength 12 — ~250ms per hash on modern hardware
}
```

### Sensitive Data Logging

```java
// ❌ Never log PII
log.info("Processing distribution for member: {}", member.getEmail());
log.info("Member {} requested quota", member.getFullName());

// ✅ Log with opaque identifiers only
log.info("Processing distribution for memberId={} tenantId={}", member.getId(), tenantId);
log.info("Quota check passed for memberId={}", memberId);
```

---

## 8. Environment Configuration

### Environment Variables Reference

All secrets and environment-specific configuration are provided via environment variables. Never commit secrets to version control.

| Variable | Required | Default | Description |
|---|---|---|---|
| `DB_URL` | ✅ | — | JDBC URL, e.g. `jdbc:postgresql://localhost:5432/cannamanage` |
| `DB_USERNAME` | ✅ | — | PostgreSQL username |
| `DB_PASSWORD` | ✅ | — | PostgreSQL password |
| `JWT_SECRET` | ✅ | — | 256-bit (32-byte) random secret for JWT signing; generate with `openssl rand -base64 32` |
| `JWT_ACCESS_TTL_HOURS` | ❌ | `8` | Access token TTL in hours |
| `JWT_REFRESH_TTL_DAYS` | ❌ | `30` | Refresh token TTL in days |
| `STRIPE_SECRET_KEY` | ✅ (billing) | — | Stripe secret key (starts with `sk_live_` in production) |
| `STRIPE_WEBHOOK_SECRET` | ✅ (billing) | — | Stripe webhook signing secret for subscription events |
| `MAIL_HOST` | ✅ | — | SMTP host for transactional emails |
| `MAIL_USERNAME` | ✅ | — | SMTP username |
| `MAIL_PASSWORD` | ✅ | — | SMTP password |
| `MAIL_FROM` | ❌ | `noreply@cannamanage.de` | From address for system emails |
| `SENTRY_DSN` | ❌ | — | Sentry DSN for error tracking; omit to disable |
| `APP_BASE_URL` | ✅ | — | Application base URL, e.g. `https://meinclub.cannamanage.de` |
| `ADMIN_INITIAL_EMAIL` | ❌ | — | Seed admin email on first startup (Flyway data migration) |
| `ADMIN_INITIAL_PASSWORD` | ❌ | — | Seed admin password — change immediately after first login |

### `application.properties` Pattern

```properties
# application.properties — references env vars only; no values hardcoded

spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

spring.jpa.hibernate.ddl-auto=validate
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration

jwt.secret=${JWT_SECRET}
jwt.access.ttl-hours=${JWT_ACCESS_TTL_HOURS:8}
jwt.refresh.ttl-days=${JWT_REFRESH_TTL_DAYS:30}

stripe.secret-key=${STRIPE_SECRET_KEY}
stripe.webhook-secret=${STRIPE_WEBHOOK_SECRET}

spring.mail.host=${MAIL_HOST}
spring.mail.username=${MAIL_USERNAME}
spring.mail.password=${MAIL_PASSWORD}

sentry.dsn=${SENTRY_DSN:}
```

### Profile Strategy

> **`spring.profiles.active=prod` is NOT a security mechanism.** Never use profile-based condition checks to gate security-relevant behavior (e.g., `@ConditionalOnProperty(name="spring.profiles.active", havingValue="prod")`).

Profiles are used **only** for infrastructure wiring (in-memory H2 vs. real PostgreSQL for tests, Testcontainers vs. external DB).

| Profile | Usage |
|---|---|
| `(none)` | Production — all config from environment variables |
| `test` | JUnit integration tests — Testcontainers PostgreSQL |
| `dev` | Local development — Docker Compose PostgreSQL, verbose SQL logging |

### Local Development Setup

```bash
# Start local PostgreSQL via Docker Compose
docker compose up -d postgres

# Run with dev profile (verbose SQL, local DB)
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev \
  -Dspring-boot.run.arguments="--DB_URL=jdbc:postgresql://localhost:5432/cannamanage_dev \
    --DB_USERNAME=cannamanage --DB_PASSWORD=dev_password \
    --JWT_SECRET=$(openssl rand -base64 32)"
```

---

*End of CannaManage coding standards. See also [03-ARCHITECTURE.md](03-ARCHITECTURE.md) for data model and [05-API-SPEC.md](05-API-SPEC.md) for REST contract.*