docs(src): src/README를 「~한다」체로 맞추고 Compose 최소 버전은 정본을 가리킨다

src/README.md가 「~합니다」체다(끝맺음 215곳, 「~한다」는 번역 묶음이 고친
두 문장뿐). docs/README.md 「문서 수명과 언어」는 살아 있는 문서의 문체를
「~한다」로 정하고 한 문서 안에서 섞지 않게 한다. 번역 묶음(D2a)이 이
문서의 영어 제목·문장만 맡아 문체는 범위 밖으로 넘겼다.

- 끝맺음만 바꿨다. 낱말 111개를 하나씩 대응표로 바꾸고(합니다 → 한다,
  입니다 → 이다·다, 형용사는 하다·다: 견고하다, 필요하다, 다르다, 크다,
  쉽다, 같다, 「있지 않습니다」 → 「있지 않다」, 「~세요」 → 「~한다」),
  바뀐 195줄을 한 줄씩 읽었다. 줄 수(577)와 다른 글자는 그대로다.
- 「Docker Compose 최소 버전 `2.24.4`」가 정본
  (compose-profile-contracts.json의 minimumComposeVersion)을 옆에 적고도
  값을 복사했다. 값을 지우고 정본 키를 가리킨다.

버린 대안: 문체를 그대로 두고 규칙 쪽에 예외를 두기. 한 파일만 다른
문체를 허용할 근거가 없다.

이 문서를 글자 그대로 읽는 테스트는 없다(git grep 'src/README' — 링크
검사 범위 목록 테스트 하나만 경로를 적는다).

검증(노트북): check-docs.py OK, 「~니다」 끝맺음 남은 수 0(「아니다」 제외).
This commit is contained in:
DongHyeonka
2026-11-07 18:27:30 +09:00
parent 9c4ca9f391
commit 2af465e71c
+195 -195
View File
@@ -1,24 +1,24 @@
# src — 빌드 스크립트 / 환경 변수 참조
`src/` 는 Gradle 멀티모듈 루트입니다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT 입니다.
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다.
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
결정 근거**를 모아둔 참조용 기록입니다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명합니다.
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명한다.
---
## build.gradle — 빌드 / 검증 게이트
검증은 로컬 피드백과 저장소 전체 검증을 분리합니다. `:<leaf>:check`는 해당 모듈의 컴파일,
테스트, Spotless, Checkstyle, Error Prone만 담당합니다. 저장소 전체 정책은 이름이 드러나는
루트 task로 실행하며, CI가 이를 집계합니다.
검증은 로컬 피드백과 저장소 전체 검증을 분리한다. `:<leaf>:check`는 해당 모듈의 컴파일,
테스트, Spotless, Checkstyle, Error Prone만 담당한다. 저장소 전체 정책은 이름이 드러나는
루트 task로 실행하며, CI가 이를 집계한다.
이 셋의 역할은 겹치지 않습니다. Spotless(google-java-format)가 포맷과 import 순서를 소유하고,
Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 가지 논리/설계 규칙만 — 봅니다
이 셋의 역할은 겹치지 않는다. Spotless(google-java-format)가 포맷과 import 순서를 소유하고,
Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 가지 논리/설계 규칙만 — 본다
(`config/checkstyle/checkstyle.xml`). 줄 길이·들여쓰기·import 순서 모듈이 여기에 없는 것은 누락이
아니라 포매터와 싸우지 않기 위한 선택입니다. Error Prone은 컴파일 시점 버그 패턴을 담당합니다.
아니라 포매터와 싸우지 않기 위한 선택이다. Error Prone은 컴파일 시점 버그 패턴을 담당한다.
| 게이트 | 하는 일 |
| --- | --- |
@@ -34,8 +34,8 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를
먼저 사용합니다. 전체 기동 qualification은 일반 leaf `check`나 `:app-bootstrap:build`에
매달지 않고 `qualificationCheck`/`mainCheck`에서 실행합니다.
먼저 사용한다. 전체 기동 qualification은 일반 leaf `check`나 `:app-bootstrap:build`에
매달지 않고 `qualificationCheck`/`mainCheck`에서 실행한다.
**2026-09에 삭제한 게이트.** `verifyOneTypePerFile`(Checkstyle의 `OneTopLevelClass`가 같은 규칙을
파싱된 파일에 대해 검사한다), `verifyTrivyignore`·`verifyQuarantineSunset`(빈 레지스트리를 지키는
@@ -47,65 +47,65 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
### 로컬 첫 실행
`scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰
app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
끝나 public health endpoint가 준비되어야 다음 단계로 넘어갑니다. `src/.env.example`은 커밋된
env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 example/registry/shipped YAML을
함께 검사합니다.
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `src/.env.example`은 커밋된
env 계약이고 `src/.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
함께 검사한다.
### 추적 가능한 버전과 의존성 잠금
- leaf version은 release version뿐입니다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`).
revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙습니다. revision은 jar
- leaf version은 release version뿐이다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`).
revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙는다. revision은 jar
이름에 넣지 않고 각 jar manifest의 `Build-Revision`과 app-bootstrap의
`META-INF/build-info.properties`(`build.revision`)에 남깁니다. 예전에는 version이
`META-INF/build-info.properties`(`build.revision`)에 남긴다. 예전에는 version이
`<MAJOR>.<MINOR>.<PATCH>+<sha>`라 커밋마다 새 jar 이름이 생겼고 그 잔여물을 `ca.archive-hygiene`이
치웠는데, 둘 다 없앴습니다(리뷰 BUILD-O3-5).
치웠는데, 둘 다 없앴다(리뷰 BUILD-O3-5).
- `releaseCheck`가 실행하는 `verifyReleaseProvenance`(루트 `build.gradle`, revision 판정은
`ca.java-conventions`와 같은 함수)는 source revision이 없으면 실패하므로 추적 불가능한 산출물을
release로 취급할 수 없습니다. 예전 `ca.release-provenance` 플러그인은 없앴습니다(리뷰 BUILD-O3-5).
release로 취급할 수 없다. 예전 `ca.release-provenance` 플러그인은 없앴다(리뷰 BUILD-O3-5).
- 모든 subproject가 `lockAllConfigurations()` + `LockMode.STRICT`를 사용하고, lock state는 Gradle
기본 `<module>/gradle.lockfile`에 둡니다. 이 경로는 Renovate Gradle manager 기본 인식 경로와
같습니다.
- lock 갱신은 `./gradlew resolveAndLockAll --write-locks` 한 가지 명령으로 수행합니다. 이 task는
`--write-locks`가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 합니다.
기본 `<module>/gradle.lockfile`에 둔다. 이 경로는 Renovate Gradle manager 기본 인식 경로와
같다.
- lock 갱신은 `./gradlew resolveAndLockAll --write-locks` 한 가지 명령으로 수행한다. 이 task는
`--write-locks`가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 한다.
### 재현 가능한 아카이브 (D10)
모든 `AbstractArchiveTask`는 file timestamp 보존을 끄고, file order를 재현 가능하게 정렬하며,
directory/file mode를 각각 `0755`/`0644`로 고정합니다. Java toolchain은 21이고 로컬·CI patch
version은 root `.tool-versions`의 Temurin 값으로 맞춥니다.
directory/file mode를 각각 `0755`/`0644`로 고정한다. Java toolchain은 21이고 로컬·CI patch
version은 root `.tool-versions`의 Temurin 값으로 맞춘다.
archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제합니다. 현재 저장소에는
archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제한다. 현재 저장소에는
별도의 `verify-reproducible-build.sh`가 없으므로 byte-for-byte 이중-build 비교를 자동 게이트라고
주장하지 않습니다. 릴리스 검증의 정본 진입점은 `./gradlew releaseCheck`와
`.github/workflows/release.yml`입니다.
주장하지 않는다. 릴리스 검증의 정본 진입점은 `./gradlew releaseCheck`와
`.github/workflows/release.yml`이다.
### `-parameters` 컴파일러 플래그
- **결정.** 모든 subproject 의 Java 컴파일에 `-parameters` 플래그를 직접 설정합니다.
- **결정.** 모든 subproject 의 Java 컴파일에 `-parameters` 플래그를 직접 설정한다.
- **근거.** Spring MVC 는 `@PathVariable` / `@RequestParam` 의 이름을 reflection 의 parameter
metadata 에서 읽습니다. 이 플래그가 없으면 파라미터 이름이 `arg0`, `arg1` 로 컴파일되어 바인딩이
깨집니다. Spring Boot Gradle 플러그인은 이 플래그를 자동으로 켜 주지만, 이 프로젝트는 플러그인을
`apply false` 로 두기 때문에 자동 적용이 일어나지 않습니다. 그래서 각 subproject 의 `JavaCompile`
에 직접 설정합니다.
metadata 에서 읽는다. 이 플래그가 없으면 파라미터 이름이 `arg0`, `arg1` 로 컴파일되어 바인딩이
깨진다. Spring Boot Gradle 플러그인은 이 플래그를 자동으로 켜 주지만, 이 프로젝트는 플러그인을
`apply false` 로 두기 때문에 자동 적용이 일어나지 않는다. 그래서 각 subproject 의 `JavaCompile`
에 직접 설정한다.
### `verifyCleanArchitectureDependencies`
- **하는 일.** [config/architecture/modules.json](config/architecture/modules.json)의
`allowed_dependencies`를 읽고, 실제 Gradle 프로젝트 의존(`api` / `implementation` /
`compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킵니다.
- **JSON registry가 의존 방향의 SSOT 입니다.** 새 모듈이나 새 production 의존 edge를 추가하면
registry와 `:app-bootstrap:architectureTest`의 관련 ArchUnit 규칙을 함께 갱신해야 합니다. settings와 gate는
같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부합니다.
`compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킨다.
- **JSON registry가 의존 방향의 SSOT이다.** 새 모듈이나 새 production 의존 edge를 추가하면
registry와 `:app-bootstrap:architectureTest`의 관련 ArchUnit 규칙을 함께 갱신해야 한다. settings와 gate는
같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부한다.
조립 루트가 받는 모듈의 별도 membership 검사는 없습니다. `app-bootstrap`의 `allowed_dependencies`
조립 루트가 받는 모듈의 별도 membership 검사는 없다. `app-bootstrap`의 `allowed_dependencies`
밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 `app-bootstrap/build.gradle`의 의존성이
정합니다.
정한다.
세 opt-in inbound transport의 test-only composition, 실제 wire 경계, positive-count/zero-skip 증거는
다음 release-blocking aggregate로 실행합니다.
다음 release-blocking aggregate로 실행한다.
```bash
./gradlew conditionalTransportQualification
@@ -113,136 +113,136 @@ archive task 자체는 timestamp 비보존·재현 가능한 file order·고정
### 파일당 public 최상위 타입 1개 (code-conventions I6)
Checkstyle이 소유합니다 — `OneTopLevelClass`와 `OuterTypeFilename`(`config/checkstyle/checkstyle.xml`).
각 leaf의 `checkstyleMain`/`checkstyleTest`가 그 leaf의 `check`에서 돕니다.
Checkstyle이 소유한다 — `OneTopLevelClass`와 `OuterTypeFilename`(`config/checkstyle/checkstyle.xml`).
각 leaf의 `checkstyleMain`/`checkstyleTest`가 그 leaf의 `check`에서 돈다.
`verifyOneTypePerFile`이라는 루트 태스크가 있었고 삭제했습니다. `src/main/java`를 줄 단위 정규식으로
읽었고 세 가지가 틀렸습니다: package-private 최상위 타입이 보이지 않았고(126개 main 소스가 한 번도
`verifyOneTypePerFile`이라는 루트 태스크가 있었고 삭제했다. `src/main/java`를 줄 단위 정규식으로
읽었고 세 가지가 틀렸다: package-private 최상위 타입이 보이지 않았고(126개 main 소스가 한 번도
매칭되지 않아, 파일 하나에 package-private 타입 다섯 개가 있어도 통과했다), `src/main/java`만 읽었고,
`^public` 앵커 때문에 블록 주석이나 텍스트 블록의 `public`으로 시작하는 줄을 선언으로 셌습니다.
Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돕니다.
`^public` 앵커 때문에 블록 주석이나 텍스트 블록의 `public`으로 시작하는 줄을 선언으로 셌다.
Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다.
### `:app-bootstrap:verifyEnvKeys`
- **소유.** app-bootstrap. 이 질문("이 애플리케이션의 배포에 무엇을 줘야 하는가")은 composition
root의 것이고, `./gradlew :domain-core:check`가 알아야 할 사항이 아닙니다. 루트 집계 이름은
`configContractCheck`이고 구현은 `build-logic`의 `ca.config-contract` plugin입니다(소유자 결정 4:
root의 것이고, `./gradlew :domain-core:check`가 알아야 할 사항이 아니다. 루트 집계 이름은
`configContractCheck`이고 구현은 `build-logic`의 `ca.config-contract` plugin이다(소유자 결정 4:
태스크는 app-bootstrap에 유지, `build-tools` included build는 비워서 삭제).
- **하는 일.** `docs/registries/env-keys.yaml`, app-bootstrap의 `application*.yml` + `config/*.yml`,
capability 모듈이 싣는 `config/*.yml`·`config/module-defaults/*.yml`(기본 조립에 없어도 검사한다),
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지합니다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
실패시킵니다.
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지한다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
실패시킨다.
- **막으려는 것 3가지.** (1) 필수 env 가 조용히 누락되는 것, (2) 더 이상 쓰지 않는 stale env 키가
`.env.example` 에 남는 것, (3) 실제로 쓰는 `APP_` 키가 registry 에 등록되지 않고 빠져나가는 것.
- **검사 항목.**
- **A.** `application.yml` 의 placeholder 중 inline default(`${VAR:default}`)가 없는 **필수**
placeholder(`${VAR}`)는 반드시 `.env.example` 에 존재해야 합니다.
- **B.** `.env.example` 의 모든 키는 shipped configuration의 어떤 `${...}` placeholder 또는 등록된 consumer가 참조해야 합니다.
placeholder(`${VAR}`)는 반드시 `.env.example` 에 존재해야 한다.
- **B.** `.env.example` 의 모든 키는 shipped configuration의 어떤 `${...}` placeholder 또는 등록된 consumer가 참조해야 한다.
(아무도 안 쓰는 키는 orphan 으로 간주해 실패)
- **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 합니다.
- **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 한다.
- **`SPRING_*` 키는 왜 registry 추적 대상이 아닌가.** `SPRING_*` 는 Spring Boot 가 정의한 native 키라
프로젝트가 소유한 계약이 아닙니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔습니다.
- **비고.** `src/.env.example`이 커밋된 환경 계약이고 `src/.env`는 로컬 실행용 입력입니다.
프로젝트가 소유한 계약이 아니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔다.
- **비고.** `src/.env.example`이 커밋된 환경 계약이고 `src/.env`는 로컬 실행용 입력이다.
### `verifyPublicPathSnapshot`
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킵니다.
- **배경.** 이 앱은 deny-by-default 입니다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
경로를 **제외한** 모든 요청은 인증을 요구합니다
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킨다.
- **배경.** 이 앱은 deny-by-default이다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
경로를 **제외한** 모든 요청은 인증을 요구한다
(`app-bootstrap/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` →
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `src/.env` 였고 문서만 그대로 남아 있었습니다.
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml` 입니다
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `src/.env` 였고 문서만 그대로 남아 있었다.
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml`이다
(`build-logic/.../publicpath/PublicPathSnapshotPlugin.java`).
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점입니다.
그래서 그 표면을 snapshot 으로 떠 두고, 미승인 변경에 빌드를 실패시킵니다.
- **승인 방법.** `verifyPublicPathSnapshot` 은 항상 읽기 전용입니다. reviewer 가 변경을 승인한 뒤
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점이다.
그래서 그 표면을 snapshot 으로 떠 두고, 미승인 변경에 빌드를 실패시킨다.
- **승인 방법.** `verifyPublicPathSnapshot` 은 항상 읽기 전용이다. reviewer 가 변경을 승인한 뒤
`./gradlew updatePublicPathSnapshot -PapprovePublicPathChange` 로 snapshot 을 명시적으로 다시
생성합니다. 공개 경로 변경은 보안 리뷰 대상으로 보고 재생성된 snapshot 을 함께 커밋합니다.
생성한다. 공개 경로 변경은 보안 리뷰 대상으로 보고 재생성된 snapshot 을 함께 커밋한다.
- **결정 — 무엇을 snapshot 했나 (프로젝트 선택).** 초기안은 기동 시
`SecurityFilterChain.getFilters()` 를 introspection 하는 방식이었습니다. 하지만 그 reflection
은 Spring 버전마다 깨지기 쉽습니다(`permitAll` matcher 가
`SecurityFilterChain.getFilters()` 를 introspection 하는 방식이었다. 하지만 그 reflection
은 Spring 버전마다 깨지기 쉽다(`permitAll` matcher 가
`RequestMatcherDelegatingAuthorizationManager` 의 private 필드에 숨어 있음). 그래서 `permitAll()`
을 실제로 먹이는 결정적 SSOT 인 `SECURITY_PUBLIC_PATHS` 자체를 snapshot 합니다. 탐지 목표(공개 경로
변경은 무조건 게이트를 실패시킨다)는 같고, 메커니즘은 더 견고합니다.
을 실제로 먹이는 결정적 SSOT 인 `SECURITY_PUBLIC_PATHS` 자체를 snapshot 한다. 탐지 목표(공개 경로
변경은 무조건 게이트를 실패시킨다)는 같고, 메커니즘은 더 견고하다.
- **snapshot 위치.** `docs/security/public-paths-snapshot.txt`. 이 파일은 커밋된 필수 보안
baseline 입니다. CI 는 Gradle 실행 전에 파일이 비어 있지 않고 Git에 추적되는지 검사하므로 fresh
checkout 에서 누락되거나 untracked 상태면 즉시 실패합니다. 승인된 변경만 update task로 재생성한
뒤 보안 리뷰와 함께 커밋합니다.
baseline이다. CI 는 Gradle 실행 전에 파일이 비어 있지 않고 Git에 추적되는지 검사하므로 fresh
checkout 에서 누락되거나 untracked 상태면 즉시 실패한다. 승인된 변경만 update task로 재생성한
뒤 보안 리뷰와 함께 커밋한다.
### Trivy suppression과 플래키 격리 — 정책은 유지, 파서는 삭제
**Trivy suppression.** repo 루트 `.trivyignore.yaml`이 유일한 suppression 소스이고, 모든 Trivy 호출이
`--ignorefile .trivyignore.yaml`로 명시합니다. 항목은 `id`, 비어 있지 않은 `statement`, 90일 이내의
미래 `expired_at`을 갖춰야 합니다. 이 규칙은 그대로이고, 강제하는 주체가 `.github/CODEOWNERS` 리뷰어로
바뀌었습니다. `verifyTrivyignore`는 105줄짜리 손으로 쓴 YAML 파서였고 — 들여쓰기 추적, 인라인 스칼라
처리, 따옴표 제거 — 지키던 파일은 만들어진 이래 계속 비어 있었습니다. 실제 항목이 생기고 그것이
drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 진짜 YAML 라이브러리로.
`--ignorefile .trivyignore.yaml`로 명시한다. 항목은 `id`, 비어 있지 않은 `statement`, 90일 이내의
미래 `expired_at`을 갖춰야 한다. 이 규칙은 그대로이고, 강제하는 주체가 `.github/CODEOWNERS` 리뷰어로
바뀌었다. `verifyTrivyignore`는 105줄짜리 손으로 쓴 YAML 파서였고 — 들여쓰기 추적, 인라인 스칼라
처리, 따옴표 제거 — 지키던 파일은 만들어진 이래 계속 비어 있었다. 실제 항목이 생기고 그것이
drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진짜 YAML 라이브러리로.
**플래키 격리.** `quarantineTest` 버킷과 CI의 비차단 `quarantine` 잡은 삭제했습니다. 격리된
테스트가 한 번도 없었습니다. 간헐 실패 테스트는 고치거나 지웁니다.
**플래키 격리.** `quarantineTest` 버킷과 CI의 비차단 `quarantine` 잡은 삭제했다. 격리된
테스트가 한 번도 없었다. 간헐 실패 테스트는 고치거나 지운다.
`flaky-quarantine.yaml` 레지스트리와 `verifyQuarantineSunset`(14일 sunset + drift 검사)은
삭제했습니다. 250줄짜리 YAML 파서 + Java 렉서(주석과 문자열 리터럴 안의 `@Tag("quarantine")`를
걸러내려고 인덱스 보존 렉서를 직접 구현)로 항목이 0개인 레지스트리를 지키고 있었습니다. 순서가
반대입니다 — 실제로 격리된 테스트가 생기고, 그게 주차장이 되기 시작할 때 도입할 정책입니다.
삭제했다. 250줄짜리 YAML 파서 + Java 렉서(주석과 문자열 리터럴 안의 `@Tag("quarantine")`를
걸러내려고 인덱스 보존 렉서를 직접 구현)로 항목이 0개인 레지스트리를 지키고 있었다. 순서가
반대다 — 실제로 격리된 테스트가 생기고, 그게 주차장이 되기 시작할 때 도입할 정책이다.
### CI 게이트 배선
- **소유 범위.** 이 계약은 *게이트 배선*(어떤 게이트가 CI 에서 돌고 실패 시 어떻게 릴리스를 막는가)을
소유합니다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo
SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체입니다.
소유한다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo
SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체다.
> 이력: 게이트 표 `.github/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 그 검사기
> `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했습니다. 그 표는 이미 두 그래프에 있는 정보의
> 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했습니다. 결과적으로 체크 하나를
> 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했습니다.
> `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했다. 그 표는 이미 두 그래프에 있는 정보의
> 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했다. 결과적으로 체크 하나를
> 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했다.
- **워크플로.** `.github/workflows/ci-quality-gates.yml` 의 `release-gate` 잡이 모든 release-blocking
게이트의 fan-in(단일 required status check)입니다. included build 테스트는 경로 필터가 걸린
게이트의 fan-in(단일 required status check)이다. included build 테스트는 경로 필터가 걸린
`build-logic.yml`이, main 단계(`mainCheck`)·configuration-cache·JPA candidate evidence는
`integration-main.yml`이 돌립니다. 위임 게이트(Trivy SCA/이미지 스캔)는 `dependency-vulnerability.yml` 가 소유하며,
`integration-main.yml`이 돌린다. 위임 게이트(Trivy SCA/이미지 스캔)는 `dependency-vulnerability.yml` 가 소유하며,
GitHub Actions 는 워크플로 간 `needs` 를 못 쓰므로 branch protection 의 required check 합집합으로
묶습니다.
묶는다.
---
## .env — 환경 변수 레퍼런스
`spring-dotenv` 가 `src/.env` 를 읽어 외부화 설정을 주입합니다(`bootRun` 의 working dir 가 `src/` 라
이 파일이 잡힙니다). 아래는 섹션별 키 설명입니다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동
필요)로 간주하세요.
`spring-dotenv` 가 `src/.env` 를 읽어 외부화 설정을 주입한다(`bootRun` 의 working dir 가 `src/` 라
이 파일이 잡힌다). 아래는 섹션별 키 설명이다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동
필요)로 간주한다.
### 앱 이름과 profile
- **`APP_NAME`** — `spring.application.name` 과 JSON 로그의 `app` 필드. 자유 문자열.
- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. `local` | `dev` | `prod` 중 정확히 하나입니다. JSON
로그의 `profile` 필드도 이 값을 씁니다.
- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. `local` | `dev` | `prod` 중 정확히 하나다. JSON
로그의 `profile` 필드도 이 값을 쓴다.
### 런타임 안전 검사 (기동할 때 바로 실패시킨다, D8)
- **`APP_SERVER_ERROR_INCLUDE_STACKTRACE` / `APP_SERVER_ERROR_INCLUDE_MESSAGE`** — 로컬 디버깅용.
prod에서 `never`가 아니면 `ErrorDetailExposureSafetyValidator`가 기동을 막습니다(exit 71,
prod에서 `never`가 아니면 `ErrorDetailExposureSafetyValidator`가 기동을 막는다(exit 71,
`spring.web.error.include-binding-errors`·`include-exception`도 같음). request logging은 body를
읽지 않는 계약을 검증합니다.
읽지 않는 계약을 검증한다.
- **`APP_MULTI_INSTANCE_ENABLED`** — `true` 면 cross-instance `DistributedLockPort`
(`distributedLockProvider`)가 조립돼 있어야 하며, 없으면 기동이 실패합니다(exit 72,
(`distributedLockProvider`)가 조립돼 있어야 하며, 없으면 기동이 실패한다(exit 72,
`StartupSafetyValidator`).
- **`APP_RATE_LIMIT_ENABLED`** — 제공자에 묶이지 않은 앞단 요청 수 제한(rate limit) interceptor를 켠다
(429 + `Retry-After` + `X-RateLimit-*` 응답). 기본값은 `false`이며, `true`로 바꿀 때는
`APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 합니다.
비인증 요청의 키는 `getRemoteAddr()` 입니다. 프록시 뒤라면
`APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 한다.
비인증 요청의 키는 `getRemoteAddr()`이다. 프록시 뒤라면
`APP_SERVER_FORWARD_HEADERS_STRATEGY=native` 와 `server.tomcat.remoteip.internal-proxies` 로 신뢰할
프록시를 지정하세요(`framework` 면 rate limit 이 기동을 거부합니다).
프록시를 지정한다(`framework` 면 rate limit 이 기동을 거부한다).
- **`APP_IDEMPOTENCY_PROVIDER`** — 요청 멱등성 store. `disabled`(기본) | `redis` | `postgresql`.
`postgresql` 은 PostgreSQL data source 가 아니면 기동을 거부하므로 `bootRunH2` 에서는
`disabled` 나 `redis` 를 씁니다.
`disabled` 나 `redis` 를 쓴다.
- **`APP_IDEMPOTENCY_TTL`** — 완료 응답을 재생할 수 있는 기간(`replay-ttl`). duration(예: `24h`).
최대 72h 이고 넘으면 기동을 거부합니다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부합니다. 24h보다
올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올립니다.
최대 72h 이고 넘으면 기동을 거부한다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부한다. 24h보다
올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올린다.
### 비동기 executor
`@Async` `ThreadPoolTaskExecutor` 풀 크기 설정입니다.
`@Async` `ThreadPoolTaskExecutor` 풀 크기 설정이다.
- **`APP_ASYNC_EXECUTOR_CORE_SIZE`** — 항상 살아있는 워커 수. 1 이상 정수.
- **`APP_ASYNC_EXECUTOR_MAX_SIZE`** — 워커 수 상한. core-size 이상.
@@ -252,17 +252,17 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로,
### 기능 추가 = 한 줄 + env
기본 조립(`bootJar`)에는 web, 관측(actuator·metrics·tracing·로그), `domain-core`·`application-core`·
`shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있습니다. DB·Redis·
Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
있습니다.
`shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있다. DB·Redis·
Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
있다.
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `src/.env`에 넣습니다. 모듈이 classpath에 있으면 켜집니다.
- **끄기:** 줄을 지웁니다. 모듈의 bean·설정·의존성이 함께 빠집니다. 줄은 두고 잠시 끄려면 "끄는 키"를
`false`로 줍니다(모든 키의 기본값은 `true`).
- **줄을 바꾼 뒤:** strict lock을 갱신합니다.
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `src/.env`에 넣는다. 모듈이 classpath에 있으면 켜진다.
- **끄기:** 줄을 지운다. 모듈의 bean·설정·의존성이 함께 빠진다. 줄은 두고 잠시 끄려면 "끄는 키"를
`false`로 준다(모든 키의 기본값은 `true`).
- **줄을 바꾼 뒤:** strict lock을 갱신한다.
`./gradlew :app-bootstrap:resolveAndLockAll --write-locks`
- 모든 capability를 한 번에 싣는 jar가 필요하면(compose 레인·CI) `./gradlew :app-bootstrap:qualificationBootJar`를
씁니다. 배포용이 아닙니다.
쓴다. 배포용이 아니다.
| capability | `build.gradle` 한 줄 | 켜진 뒤 필요한 env | 끄는 키 |
|---|---|---|---|
@@ -279,28 +279,28 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키 8종과 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` |
전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`, 각 모듈이 제공하는 것은 그 모듈 README의
"제공하는 것 · 추가할 한 줄 · env 키" 절에 있습니다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay
→ JPA + Kafka)은 설정 검사가 아니라 build 줄로 맞춥니다. 표에 "JPA 줄도 필요"라고 적힌 기능은 두 줄을
함께 넣습니다.
"제공하는 것 · 추가할 한 줄 · env 키" 절에 있다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay
→ JPA + Kafka)은 설정 검사가 아니라 build 줄로 맞춘다. 표에 "JPA 줄도 필요"라고 적힌 기능은 두 줄을
함께 넣는다.
어떤 자동 설정이 켜졌는지는 Spring Boot의 `conditions` endpoint로 봅니다. 기본 노출 목록에는 없으므로
필요할 때 `management.endpoints.web.exposure.include`에 추가합니다.
어떤 자동 설정이 켜졌는지는 Spring Boot의 `conditions` endpoint로 본다. 기본 노출 목록에는 없으므로
필요할 때 `management.endpoints.web.exposure.include`에 추가한다.
종속 선택자 둘:
- `APP_GRAPHQL_DEPLOYMENT_MODE` — GraphQL이 켜지면 **필수**이고 기본값이 없습니다. 예전의 boolean과
enum 두 기본값이 서로 다른 말을 했기 때문에, 안전 태세는 배포가 명시적으로 고릅니다. 허용되는 값은
런타임 환경(`local`/`dev`/`prod`)마다 다릅니다.
- `APP_GRAPHQL_DEPLOYMENT_MODE` — GraphQL이 켜지면 **필수**이고 기본값이 없다. 예전의 boolean과
enum 두 기본값이 서로 다른 말을 했기 때문에, 안전 태세는 배포가 명시적으로 고른다. 허용되는 값은
런타임 환경(`local`/`dev`/`prod`)마다 다르다.
- `APP_NOTIFICATION_PLATFORM_MODE` — `SERVING`(기본) 또는 `INGEST_ONLY`. 선택 사항이고, 허용 값은
`NotificationModeSsotTest`가 enum에서 파생합니다.
`NotificationModeSsotTest`가 enum에서 파생한다.
### Compose와 런타임 스모크
- **Docker Compose 최소 버전 `2.24.4`.** SSOT는 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`
이고, 정본 스크립트가 검증합니다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있습니다.
- 진입점은 둘뿐이고, 그 둘만이 증거입니다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
초록으로 보고됩니다.
- **Docker Compose 최소 버전은 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의
`minimumComposeVersion`이다.** 정본 스크립트가 검증한다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있다.
- 진입점은 둘뿐이고, 그 둘만이 증거다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
초록으로 보고된다.
```bash
# 정적: profile별 정확한 service set, 병합된 모델 전체, mount target 유일성
@@ -311,36 +311,36 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
./scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
```
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아닙니다.
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아니다.
### 선택형 연동 adapter
Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니다. 모듈이 있으면 켜지고, 없으면 그
포트를 구현하는 bean이 아예 없습니다. 아래는 모듈을 고른 뒤 동작을 고르는 키입니다.
Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고른다. 모듈이 있으면 켜지고, 없으면 그
포트를 구현하는 bean이 아예 없다. 아래는 모듈을 고른 뒤 동작을 고르는 키다.
- **`APP_CACHE_REDIS_ENABLED`** — deprecated(2026-11-30 제거 예정). 읽는 곳이 없고,
기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`입니다.
기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`이다.
- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — 기본 캐시 영역(canonical default semantic region)의 제공자를 고른다.
`disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구합니다.
`disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구한다.
- **`APP_CACHE_REDIS_CLIENT_MODE`** — `managed`는 내장 Lettuce runtime, `external`은 프로젝트가
제공한 `RedisClient` bean을 사용합니다.
아래 세 키는 **활성화 스위치가 아니라 선택자**입니다. 어떤 capability가 켜지는지는 위의 build 한 줄과
끄는 키가 정하고, 이 값들은 켜진 capability가 *무엇으로* 동작할지만 고릅니다. 예전에는 "빈 값 = 비활성"으로
설명돼 있었고, 그 문장이 남아 있는 동안 두 개의 활성화 모델이 공존했습니다.
제공한 `RedisClient` bean을 사용한다.
아래 세 키는 **활성화 스위치가 아니라 선택자**이다. 어떤 capability가 켜지는지는 위의 build 한 줄과
끄는 키가 정하고, 이 값들은 켜진 capability가 *무엇으로* 동작할지만 고른다. 예전에는 "빈 값 = 비활성"으로
설명돼 있었고, 그 문장이 남아 있는 동안 두 개의 활성화 모델이 공존했다.
- **`APP_MESSAGING_BROKER`** — 활성 메시지 브로커 id. Kafka 모듈의 설정 기본값이 `kafka`(등록된 유일한
broker)라 보통 비워 두지 않습니다. 빈 값을 주면 기동이 거부되면서 이 키 이름을 지목합니다. 이 키를 비워도 메시징이 꺼지지는
않습니다 — 끄는 것은 `APP_MESSAGING_ENABLED=false`입니다.
broker)라 보통 비워 두지 않는다. 빈 값을 주면 기동이 거부되면서 이 키 이름을 지목한다. 이 키를 비워도 메시징이 꺼지지는
않는다 — 끄는 것은 `APP_MESSAGING_ENABLED=false`이다.
- **`APP_MESSAGING_KAFKA_BROKERS`** — `host:port` CSV. Kafka 모듈을 고르면 필수. messaging
platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 이 값을 씁니다.
`spring.kafka.bootstrap-servers`는 읽지 않습니다.
platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 이 값을 쓴다.
`spring.kafka.bootstrap-servers`는 읽지 않는다.
- **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 제공자를 켜는 값. notification 플랫폼이
켜졌을 때 어떤 provider를 쓸지 고르는 값입니다.
- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 제공자를 켜는 값. 위와 같습니다.
켜졌을 때 어떤 provider를 쓸지 고르는 값이다.
- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 제공자를 켜는 값. 위와 같다.
### 외부 HTTP 호출 (HTTP client)
현재 canonical activation은 다음 두 설정 트리만 사용합니다.
현재 canonical activation은 다음 두 설정 트리만 사용한다.
```yaml
app:
@@ -353,18 +353,18 @@ app:
```
- 기본 `DISABLED`는 binding/provider definition이 모두 비어 있어야 하며
`DISABLED_VERIFIED`만 게시하고 client, executor, pool, retry/CB registry를 만들지 않습니다.
- `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구합니다. 현재 유일한
`DISABLED_VERIFIED`만 게시하고 client, executor, pool, retry/CB registry를 만들지 않는다.
- `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구한다. 현재 유일한
buffered-classic readiness card가 `NOT_IMPLEMENTED`이므로 provider resource 생성 전에
fail-closed합니다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아닙니다.
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아닙니다. 루트 `src/.env`,
fail-closed한다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아니다.
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아니다. 루트 `src/.env`,
`app-bootstrap`의 application YAML, env-key registry에서 제거됐으며 canonical composition에
입력하면 상태와 무관하게 기동을 거부합니다.
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠습니다. 이제 저장소 어디에도 남아 있지 않습니다.
입력하면 상태와 무관하게 기동을 거부한다.
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠다. 이제 저장소 어디에도 남아 있지 않다.
- legacy JDK facade가 필요한 fork만 canonical composition 밖에서
`OutboundHttpSettings.bindLegacy(Binder)`와 legacy configuration을 명시적으로 import합니다.
`OutboundHttpSettings.bindLegacy(Binder)`와 legacy configuration을 명시적으로 import한다.
timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider
readiness를 증명하지 않습니다.
readiness를 증명하지 않는다.
### 로그
@@ -376,11 +376,11 @@ app:
**패키지별 레벨**(root 를 덮어씀) — 동일 허용값.
- **`APP_LOG_LEVEL_SPRING`** / **`APP_LOG_LEVEL_WEB`** — 각 패키지 레벨.
- **`APP_LOG_LEVEL_SQL`** — `DEBUG` 로 두면 JPA/jdbc 연결 후 SQL 문이 출력됩니다.
- **`APP_LOG_LEVEL_SQL`** — `DEBUG` 로 두면 JPA/jdbc 연결 후 SQL 문이 출력된다.
**파일 출력 + rolling**
- **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙입니다.
- **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙인다.
- **`APP_LOG_FILE_PATH`** — `bootRun` working dir(`src/`) 기준 상대 경로 또는 절대 경로.
- **`APP_LOG_FILE_MAX_SIZE`** — 파일 1개 최대 크기(단위 `KB` | `MB` | `GB`).
- **`APP_LOG_FILE_MAX_HISTORY`** — 보관할 rolled archive 개수. 1 이상 정수.
@@ -391,14 +391,14 @@ app:
- **`APP_LOG_ASYNC_ENABLED`** — `true` 면 appender 를 `AsyncAppender` 로 감싸 non-blocking I/O.
- **`APP_LOG_ASYNC_QUEUE_SIZE`** — back-pressure 전 in-memory 큐 깊이. 1 이상 정수.
- **`APP_LOG_ASYNC_DISCARDING_THRESHOLD`** — 남은 큐 용량이 이 값 미만이면 `TRACE`/`DEBUG`/`INFO`
이벤트를 버립니다(`WARN`/`ERROR` 는 항상 유지). `0` = 절대 버리지 않음. 0 이상 정수.
이벤트를 버린다(`WARN`/`ERROR` 는 항상 유지). `0` = 절대 버리지 않음. 0 이상 정수.
**JSON 인코더 세부**
- **`APP_LOG_JSON_TIMEZONE`** — IANA timezone(예: `UTC`, `Asia/Seoul`) 또는 `default`(JVM 기본).
- **`APP_LOG_JSON_TIMESTAMP_PATTERN`** — 타임스탬프 패턴. 보통 ISO 8601
(`yyyy-MM-dd'T'HH:mm:ss.SSSXXX`).
- **`APP_LOG_JSON_INCLUDE_CALLER_DATA`** — `true` 면 file/method/line 을 추가. **성능 비용이 큽니다.**
- **`APP_LOG_JSON_INCLUDE_CALLER_DATA`** — `true` 면 file/method/line 을 추가. **성능 비용이 크다.**
- **`APP_LOG_JSON_LOGGER_NAME_LENGTH`** — `0` = 로거 이름 전체, 양수 = 패키지 축약(예: `36` →
`dev.caskeleton.bootstrap.Foo` 가 `d.c.bootstrap.Foo` 로).
@@ -410,19 +410,19 @@ app:
### 분산 추적
- **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증합니다.
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증한다.
- **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는
`WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성합니다(D4 disabled-fallback 보장).
`WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성한다(D4 disabled-fallback 보장).
- **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float.
- profile별 기본값(D6): prod = `0.01`, dev/local = `1.0`.
- **결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix).** 빈 값이어야 per-profile resolver 의 기본값이
실제 tracer sampler 까지 도달합니다(`TracingSampleRateResolver` 가 SSOT). 값을 박으면 프로필별
기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채웁니다.
실제 tracer sampler 까지 도달한다(`TracingSampleRateResolver` 가 SSOT). 값을 박으면 프로필별
기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채운다.
### 개인정보: user_principal 가명화
- **`APP_PRIVACY_PSEUDONYMIZATION_SALT`** — secret 등급 HMAC-SHA-256 salt. `__LOCAL_DEV_` prefix 는 로컬 전용 sentinel 값이며,
**prod 에서는 secret-manager 가 주입하는 실제 값**을 써야 합니다.
**prod 에서는 secret-manager 가 주입하는 실제 값**을 써야 한다.
### Spring Boot 기동
@@ -433,34 +433,34 @@ app:
### Jackson — 역직렬화 정책
모든 request DTO 는 Jackson 경계를 지납니다. 아래 4개 스위치는 잘못된 입력을 **조용히 강제 변환하지
않고 즉시 실패**하게 만듭니다. 개별 DTO 에 클래스 레벨 `@JsonIgnoreProperties(ignoreUnknown = true)`
로 이 정책을 완화하는 것은 **금지**이며 ArchUnit 규칙으로 막혀 있습니다.
모든 request DTO 는 Jackson 경계를 지난다. 아래 4개 스위치는 잘못된 입력을 **조용히 강제 변환하지
않고 즉시 실패**하게 만든다. 개별 DTO 에 클래스 레벨 `@JsonIgnoreProperties(ignoreUnknown = true)`
로 이 정책을 완화하는 것은 **금지**이며 ArchUnit 규칙으로 막혀 있다.
- **`..._FAIL_ON_UNKNOWN_PROPERTIES`** — `true`: 타입에 선언되지 않은 JSON 키를 거부(Jackson 2.13+
기본).
- **`..._FAIL_ON_NULL_FOR_PRIMITIVES`** — `true`: primitive 필드에 JSON `null` 이 와도 `0`/`false`
로 강제 변환하지 않고 "필수 필드 누락" 에러로 노출. 또는 wrapper 타입(`Integer`/`Long`/`Boolean`)
과 `Optional<T>` 를 쓰세요.
과 `Optional<T>` 를 쓴다.
- **`..._FAIL_ON_IGNORED_PROPERTIES`** — `true`: JSON 에 `@JsonIgnore` 처리된 필드가 들어오면 throw
(조용히 버리는 대신 계약 drift 를 노출).
- **`..._READ_UNKNOWN_ENUM_VALUES_AS_NULL`** — `false`(Jackson 기본 유지): 모르는 enum 값이 조용히
`null` 이 되지 않고 throw 되어 `VALIDATION_FAILED` 로 드러나게 합니다.
`null` 이 되지 않고 throw 되어 `VALIDATION_FAILED` 로 드러나게 한다.
### Jackson — 직렬화 정책
응답 생성 쪽 정책입니다. 현재 Jackson/Spring Boot 기본값과 같지만 **명시적으로 못박아**, 미래에 Spring
Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니다(`spring.mvc.problemdetails.enabled=false`
응답 생성 쪽 정책이다. 현재 Jackson/Spring Boot 기본값과 같지만 **명시적으로 못박아**, 미래에 Spring
Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 한다(`spring.mvc.problemdetails.enabled=false`
와 같은 근거). `JacksonSerializationPolicyTest` 가 강제하며, `new BigDecimal(double)` 생성자는
`no_bigdecimal_double_constructor` ArchUnit 규칙으로 금지됩니다.
`no_bigdecimal_double_constructor` ArchUnit 규칙으로 금지된다.
- **`..._WRITE_DATES_AS_TIMESTAMPS`** — `false`(D2 / RFC 3339): `java.time` 값을 ISO-8601 문자열로
직렬화(`OffsetDateTime` → `"...Z"`, `LocalDate` → `"YYYY-MM-DD"`). `true` 면 epoch 숫자나
`[y,m,d,...]` 배열로 나가 datetime 계약이 깨집니다.
- **BigDecimal plain output** — Jackson 3에는 별도 `WRITE_BIGDECIMAL_AS_PLAIN` 설정 키가 없습니다.
`[y,m,d,...]` 배열로 나가 datetime 계약이 깨진다.
- **BigDecimal plain output** — Jackson 3에는 별도 `WRITE_BIGDECIMAL_AS_PLAIN` 설정 키가 없다.
`JacksonSerializationPolicyTest` 가 `"12300000000.00"` plain 출력을 직접 검증하고,
`no_bigdecimal_double_constructor` ArchUnit 규칙이 부정확한 `new BigDecimal(double)` 생성을
금지합니다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둡니다(공개/금융 API 는 string,
금지한다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둔다(공개/금융 API 는 string,
내부 API 는 number+plain).
### 서버 / Tomcat
@@ -493,9 +493,9 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
기동 실패. 예: `https://keycloak.example.com/realms/ca-skeleton`.
- **`APP_SECURITY_JWT_AUDIENCE`** — 기대하는 `aud` claim(쉼표 목록 가능, 하나라도 맞으면 통과).
JWT 모드에서 **필수** — 비어 있으면 기동 실패. 이 목록의 client 에 대한 `resource_access` role 만
권한으로 읽습니다. 예: `ca-skeleton-api`.
- **`SECURITY_PUBLIC_PATHS`** — 인증을 우회하는 경로 CSV. `api-base-path` 뒤의 full path 를 씁니다(예:
`/api/healthcheck`). 이 값의 변경은 `verifyPublicPathSnapshot` 게이트가 감시합니다(위 build.gradle
권한으로 읽는다. 예: `ca-skeleton-api`.
- **`SECURITY_PUBLIC_PATHS`** — 인증을 우회하는 경로 CSV. `api-base-path` 뒤의 full path 를 쓴다(예:
`/api/healthcheck`). 이 값의 변경은 `verifyPublicPathSnapshot` 게이트가 감시한다(위 build.gradle
설명 참조).
### CORS
@@ -512,7 +512,7 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
### 프로파일과 데이터베이스
프로파일마다 데이터스토어가 다르고, 그 차이는 `app-bootstrap/src/main/resources/application-*.yml`
가 소유합니다.
가 소유한다.
| 프로파일 | 데이터스토어 | 스키마 소유자 | 외부 인프라 |
| --- | --- | --- | --- |
@@ -521,45 +521,45 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
| `prod` | PostgreSQL | Flyway `db/migration/postgresql` | 필요 |
| `bootRunH2` (명시적 opt-out) | H2 in-memory | Hibernate `ddl-auto: create-drop` | 없음 |
`./gradlew :app-bootstrap:bootRun` 은 기본 `local` 프로파일에서도 PostgreSQL/Flyway를 사용합니다.
`./gradlew :app-bootstrap:bootRun` 은 기본 `local` 프로파일에서도 PostgreSQL/Flyway를 사용한다.
로컬과 운영의 schema owner를 다르게 두면 migration-only 결함을 개발 중에 놓치기 때문에 바뀐
계약입니다. 먼저 아래 Compose PostgreSQL을 띄운 뒤 `bootRun`을 실행하세요.
계약이다. 먼저 아래 Compose PostgreSQL을 띄운 뒤 `bootRun`을 실행한다.
Docker 없이 빠르게 wiring·요청/응답·애플리케이션 로직만 확인하려면
`./gradlew :app-bootstrap:bootRunH2`를 명시적으로 사용합니다. 이 태스크만
`./gradlew :app-bootstrap:bootRunH2`를 명시적으로 사용한다. 이 태스크만
`APP_PERSISTENCE_VENDOR=h2`, `APP_FLYWAY_ENABLED=false`,
`APP_DATASOURCE_DDL_AUTO=create-drop`을 주입합니다. H2에는 PostgreSQL migration tree가 없으므로
migration/vendor 계약의 증거로 사용하지 않습니다. 멱등성 provider(`APP_IDEMPOTENCY_PROVIDER`)는
`disabled`(기본)나 `redis`로 둡니다. `postgresql`은 H2 data source에서 기동을 거부합니다.
`APP_DATASOURCE_DDL_AUTO=create-drop`을 주입한다. H2에는 PostgreSQL migration tree가 없으므로
migration/vendor 계약의 증거로 사용하지 않는다. 멱등성 provider(`APP_IDEMPOTENCY_PROVIDER`)는
`disabled`(기본)나 `redis`로 둔다. `postgresql`은 H2 data source에서 기동을 거부한다.
`dev` 를 호스트에서 띄우려면(`SPRING_PROFILES_ACTIVE=dev`) PostgreSQL 이 필요합니다.
`dev` 를 호스트에서 띄우려면(`SPRING_PROFILES_ACTIVE=dev`) PostgreSQL 이 필요하다.
`compose.yaml` 의 `db` 서비스(`jpa` profile)가 루프백(`127.0.0.1:5433`)에만 게시하며, 이 주소가
아래 `APP_DATASOURCE_URL` 의 커밋된 기본값입니다. 저장소 루트에서 실행합니다.
아래 `APP_DATASOURCE_URL` 의 커밋된 기본값이다. 저장소 루트에서 실행한다.
```bash
docker compose up -d --wait db
```
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app
컨테이너의 `APP_DATASOURCE_URL` 을 내부 네트워크 주소 `jdbc:postgresql://db:5432/...` 로 덮어씁니다.
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않는다. compose 가 app
컨테이너의 `APP_DATASOURCE_URL` 을 내부 네트워크 주소 `jdbc:postgresql://db:5432/...` 로 덮어쓴다.
`app.persistence.vendor`(`postgresql` | `h2`)가 어느 vendor 구성을 조립할지 고르는 단일
스위치입니다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 `h2` 이거나 datasource URL 이
`jdbc:h2:` 이면 `PersistenceVendorProdSafetyValidator` 가 기동을 거부합니다(env 로 덮어써도 동일).
스위치다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 `h2` 이거나 datasource URL 이
`jdbc:h2:` 이면 `PersistenceVendorProdSafetyValidator` 가 기동을 거부한다(env 로 덮어써도 동일).
### 데이터베이스 (PostgreSQL)
- **`APP_DATASOURCE_URL`** — JDBC URL(예: `jdbc:postgresql://host:5432/dbname`). `dev`·`prod` 에서
쓰이며, 커밋된 기본값 `jdbc:postgresql://localhost:5433/ca_skeleton` 은 위 compose `db` 서비스의
호스트 주소입니다.
호스트 주소다.
- **`APP_DATASOURCE_USERNAME`** / **`APP_DATASOURCE_PASSWORD`** — DB 접속 계정.
- **`APP_DATASOURCE_DRIVER`** — Hibernate dialect 에 맞는 드라이버(예: `org.postgresql.Driver`).
- **`APP_DATASOURCE_DDL_AUTO`** — `none` | `validate` | `update` | `create` | `create-drop`. **prod
는 `validate` 또는 `none`**(`JpaDangerousConfigurationGuard` 가 기동 시 강제). `local` 은 이 값을 쓰지
않습니다 — `application-local.yml` 이 `create-drop` 으로 고정합니다.
않는다 — `application-local.yml` 이 `create-drop` 으로 고정한다.
- **`APP_DATASOURCE_SHOW_SQL`** — `true` 면 SQL 을 로그로 echo.
- **`APP_DATASOURCE_FORMAT_SQL`** — SQL pretty-print(`SHOW_SQL=true` 일 때만 의미 있음).
- **`APP_DATASOURCE_OPEN_IN_VIEW`** — Hibernate OSIV. **prod 에서는 피하세요.**
- **`APP_DATASOURCE_OPEN_IN_VIEW`** — Hibernate OSIV. **prod 에서는 피한다.**
**HikariCP 커넥션 풀**
@@ -568,10 +568,10 @@ docker compose up -d --wait db
- **`APP_DATASOURCE_CONNECTION_TIMEOUT`** — `acquire()` 가 실패하기 전 대기 시간(ms).
- **`APP_DATASOURCE_POOL_IDLE_TIMEOUT`** — idle 연결 회수 임계 시간(ms).
- **`APP_DATASOURCE_POOL_MAX_LIFETIME`** — 연결의 최대 수명(ms). broker timeout 전에 rotate 하도록
설정합니다.
설정한다.
### 관리 포트 / Actuator
- **결정 — management 포트 분리.** actuator 엔드포인트를 앱 API 와 **같은 소켓에 노출하지 않으려고**
별도 management 포트를 둡니다.
- **`MANAGEMENT_SERVER_PORT`** — 1~65535 정수. **`APP_SERVER_PORT`(8080)와 달라야 합니다.**
별도 management 포트를 둔다.
- **`MANAGEMENT_SERVER_PORT`** — 1~65535 정수. **`APP_SERVER_PORT`(8080)와 달라야 한다.**