# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Rule #0: the docs are the constraint, not a description

Architecture decisions live in **[`../conti-docs/backend/`](../conti-docs/backend/)** (01–13, the single
source of truth). This repo's `docs/` is a **copy** of it, so people don't have to switch repos.

- **Edit docs in `../conti-docs/backend/`, then sync into `docs/`** (sync commands — including two
  cross-repo link fixups — are in `docs/README.md`). Editing only one side causes drift.
- **When code and docs disagree, change the code, not the doc.** In particular, **never loosen a rule in
  `architecture-test` just to make code pass** — loosening the rules is exactly what makes this whole
  structure worthless.
- The few places where the scaffolding deliberately deviates from the docs are commented in the code
  itself.

## Commands

```bash
# Everyday check: compile + unit tests + ArchUnit. No Docker needed (~1 min).
./gradlew build -PexcludeIntegration

# Full check: includes Testcontainers / WireMock. Needs a working Docker daemon. Run before an MR.
./gradlew build

# Single test class / single test method
./gradlew :architecture-test:test --tests "*KotlinSyntaxScanTest*"
./gradlew :domains:identity-store:test --tests "*StoreJpaRepositoryTest*"

# Run locally (only MySQL is in Docker; the app runs via Gradle so breakpoints/hot-reload work)
docker compose up -d mysql
SPRING_PROFILES_ACTIVE=local ./gradlew :bootstrap:bootRun   # Swagger: http://localhost:8080/swagger-ui.html

# Reset the database
docker compose down -v && docker compose up -d mysql
```

Tests tagged `integration` (real MySQL / WireMock) are skipped by `-PexcludeIntegration`. When you touch a
repository layer or SQL, **`-PexcludeIntegration` does not exercise what you changed** — run the full build.

## Architecture

**Modular monolith**: 14 Gradle modules, one deployable jar. Boundaries are enforced *physically* by the
Gradle dependency graph, and *statically* by `architecture-test`.

```
bootstrap               the only module with @SpringBootApplication; the only one producing a jar;
                        the only one that applies the Boot plugin
platform/platform-*     cross-cutting infrastructure (web / security / persistence / observability / integration)
domains/*               business domains; identity-store is the only fully implemented vertical slice
integration/*           adapters to external systems (f6-adapter / mini-clients)
architecture-test       no production code; holds the architecture rules and source-scan tests
```

Dependency rules (enforced at compile time):

- **`domains/x` must never depend on `domains/y`** — only on `y-contract` (a read-only contract module
  containing no Spring Web / JPA).
- `domains/*` may depend on `integration/*` and `platform-*`.
- Among `platform-*`, a module **may only depend on `platform-web`**.
- Layering: `api → application → domain`, with `infrastructure` depended on by both. The `domain` layer
  **must not reference Spring or JPA at all** — its beans are wired explicitly via `@Bean` in
  `infrastructure/config/`. Entities live only in the `infrastructure` package; the `api` layer never sees them.

**Adding a domain requires wiring 4 places.** Miss one and the symptom is subtle (it compiles and boots, but
Flyway doesn't run or the boundary is silently unguarded):

1. `settings.gradle`: add the `include`, and write the module's `build.gradle`.
2. `bootstrap/build.gradle`: add `implementation project(...)`, or it never lands in the jar.
3. `DomainFlywayConfig.DOMAIN_SCHEMAS`: add the schema name, create
   `db/migration/<schema>/V1__init.sql` (a Flyway location must not be an empty dir), and add the
   `CREATE DATABASE` to `docker/mysql/init/01-create-databases.sql`.
4. `ArchitectureRulesTest.domains`: add the package name; `NativeQueryScanTest.ownerByModule`: add
   `"xxx" to "<schema>"`.

Package name is the directory name with hyphens stripped (`identity-store` → `identitystore`); the sole
exception is `bff-orchestration` → `bff`.

## architecture-test: three test classes, three mechanisms

Know what's in here before changing production code, or you'll hit a red build and not know why:

| Test class | Mechanism | What it catches |
| --- | --- | --- |
| `ArchitectureRulesTest` | ArchUnit over **bytecode** | layer directions, Entity placement, field injection, `java.util.Date`, util-class naming, etc. |
| `NativeQueryScanTest` | **reads source text** | a native SQL string naming another domain's schema — schema names are string literals, invisible in bytecode |
| `KotlinSyntaxScanTest` | **reads source text** | `!!` / `lateinit` / `suspend` / `kotlinx.coroutines` / RxJava / Reactor / `data class *Entity` |

**Two traps in the source-scan tests** (you only see them by reading the code):

- They locate sources with **relative paths** (`Path.of("../domains")`), relying on Gradle running them with
  the module dir as working directory. **If you add a new top-level source root, you must add it to
  `KotlinSyntaxScanTest.productionSources()`** — otherwise the new code is never checked.
- `productionSources()` contains `filter { Files.exists(it) }`: **if the path is wrong it silently scans
  zero files and reports green.** When writing a test like this, confirm it actually reads files by
  planting a deliberate violation and checking that it goes red — don't trust a green alone.

### Kotlin coding constraints (see `13-kotlin-style.md`)

`!!` / `lateinit` / coroutines / RxJava / Reactor / `data class` entities / any
`XxxUtils|Util|Helper|Common` class **are build gates** — violating them fails `test` and therefore
`build`. They are not suggestions.

Two things that are **deliberately not automated**:

- `companion object` restricted to legitimate uses — left to review (all 14 existing uses are legitimate;
  a hard rule would only cause false positives).
- **Entities must be proxyable by Hibernate — currently NOT enforced (known gap)**: the root `build.gradle`
  does **not** apply `kotlin("plugin.jpa")`, so entities are final, Hibernate cannot proxy them, and
  `fetch = LAZY` **silently degrades to eager**. This hasn't blown up only because there are currently zero
  lazy associations. Read the "已知缺口（2026-09）" (known gap) section of `13-kotlin-style.md` before
  adding anything like `@ManyToOne(fetch = LAZY)`.

## Hard version constraints

| Component | Version | Constraint |
| --- | --- | --- |
| Gradle | `9.5.0` (wrapper) | **Two-sided**: the Boot 4.1 plugin needs 8.14+ or 9.x, while KGP 2.4.10's fully-supported ceiling is 9.5.0. Bumping either Boot or Kotlin means recomputing the intersection. |
| Kotlin | `2.4.10` | |
| Java | `21` (pinned via toolchain) | |
| Spring Boot / Cloud | `4.1.0` / `2025.1.2` | |

- Version alignment always goes through Gradle's native **`platform()` BOM; `io.spring.dependency-management`
  is deliberately not used** (that plugin historically breaks on every Gradle major).
- **Gradle 9 no longer bundles the JUnit Platform launcher** — deleting
  `testRuntimeOnly 'org.junit.platform:junit-platform-launcher'` from the root `build.gradle` makes every
  `test` task fail outright.
- **Boot 4 moved packages**: `@DataJpaTest` → `org.springframework.boot.data.jpa.test.autoconfigure`,
  `@AutoConfigureTestDatabase` → `org.springframework.boot.jdbc.test.autoconfigure` (both need
  `spring-boot-starter-data-jpa-test`); `spring-boot-starter-aop` is now `spring-boot-starter-aspectj`.

## Database conventions

- One domain, one database (in MySQL, schema ≡ database), so `DomainFlywayConfig` starts one Flyway
  instance per entry in `DOMAIN_SCHEMAS`.
- **An already-executed Flyway script must never be edited** (checksum mismatch → startup fails with
  `Validate failed`; this applies to the dev environment too). To change something, add a higher-versioned
  script.
- **Every migration must be forward-compatible**: `maxUnavailable: 0` means old and new pods share one
  database during a rolling update, so dropping or altering a column requires expand-contract across two
  releases.
- **Store-scoped queries must use `StoreContextHolder.currentStoreId()`, never a `storeId` request
  parameter** — that parameter is the standard entry point for an authorization-bypass query.
- Seed data (`LocalSeedDataConfig`) **exists only under the `local` profile and must never be written into
  a Flyway script**.

## Deployment and misc

- `local` on your own machine (Gradle); `dev` on internal k3s (`./scripts/deploy-dev.sh <sha>`, connect
  VPN first); `uat`/`prod` on Azure AKS (protected tag → manual Promote in GitLab).
- **Images don't compile code**: the `Dockerfile` consumes the jar produced by the CI `validate` stage, so
  the bytes deployed are the bytes that were tested.
- **Real secrets are in no file in this repo**; `k8s/secret-uat.yaml` holds only
  `__injected_by_pipeline__` placeholders.
- The `lint` (ktlint/detekt) and coverage jobs are currently **left commented out** in `.gitlab-ci.yml` —
  the plugins aren't wired up, so enabling them would go red immediately. `.editorconfig` already reserves
  the `ij_kotlin_*` section.