From a4382b477fc7866b9c8c21cc6f6328f0fa626eff Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 01/12] =?UTF-8?q?docs(readme):=20=EB=A3=A8=ED=8A=B8=20READ?= =?UTF-8?q?ME=EB=A5=BC=20=EA=B5=AC=EC=A1=B0=C2=B7=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=A7=80=EB=8F=84=EA=B0=80=20=EB=B3=B4=EC=9D=B4=EB=8A=94=20?= =?UTF-8?q?=EC=A0=88=20=EC=88=9C=EC=84=9C=EB=A1=9C=20=EB=8B=A4=EC=8B=9C=20?= =?UTF-8?q?=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 처음 온 사람이 루트 README만 보고는 저장소 구조와 문서 위치를 알 수 없다. 절이 「아키텍처 한눈에, 퀵스타트, 새 프로젝트로 시작하기, 아키텍처 규칙과 검증, 수동 전용 Gradle 태스크, 더 알아보기」라 `src/platforms/`, 루트 `compose.yaml`, `compose/`, 문서 폴더가 어디에도 없다. 코드와 다른 주장도 있다. - 「수동 전용 Gradle 태스크」는 `grpcPerformanceTest`를 어떤 workflow도 돌리지 않고 `cd src && ./gradlew :grpc:grpc-testkit:grpcPerformanceTest`로 부른다고 한다. 실제로는 `integration-main.yml`이 `-p platforms/optional-build performanceCheck`로 돌리고, gRPC 플랫폼은 다른 빌드라 그 명령은 주 빌드에서 돌지 않는다. - 패키지 이름 바꾸기 명령이 `.java`·`.gradle`·`.yml`만 고친다. `dev.caskeleton`은 `AutoConfiguration.imports` 29개, `spring.factories` 9개, 생성 명령 템플릿, xml·json 파일에도 있다. 고른 방법: design-docs `conventions/docs-system.md` 6.1절 순서로 절을 다시 짠다 (프로젝트 구조 → 시작하기 → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로 시작하기 → 규칙과 기여). 구조 절은 최상위 폴더 표, `src/` 폴더 표(기본 조립에 들어가나), 의존 방향 도식을 두고 모듈 개수와 버전 숫자는 쓰지 않는다. 틀린 두 주장은 지우거나 `git grep -l 'dev\.caskeleton'`로 찾게 바꾼다. 프로파일 표와 `bootRunH2` 설명은 이미 `src/README.md`가 가지므로 거기를 가리킨다. 문체는 「~한다」로 바꾼다. 버린 대안: 옛 절을 그대로 두고 두 절만 더하기. 6.1절 순서와 다르고, 같은 내용이 `src/README.md`와 두 곳에 남는다. 위험·한계: README 문구를 단언하던 `DeveloperExperienceContractTest .readmeDocumentsOneFirstRunEntrypoint`의 기대 문자열을 「## 시작하기」·「첫 실행 진입점은 하나다.」로 맞췄다. 진입점 하나와 성공 확인을 지키는 계약은 그대로다. 검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py --links README.md` 깨진 링크 0. --- README.md | 204 ++++++++---------- .../DeveloperExperienceContractTest.java | 4 +- 2 files changed, 91 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index 7e375860..1994aa9b 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,135 @@ -# ca-skeleton — Clean Architecture Spring Boot 템플릿 +# ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿 -ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다. +ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `src/gradle/libs.versions.toml`이 정한다. -이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다. +## 프로젝트 구조 -## 아키텍처 한눈에 +저장소 루트에는 정해진 것만 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다. -의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다. +| 폴더 | 하는 일 | 먼저 읽을 곳 | +| --- | --- | --- | +| `src/` | Gradle 루트. 모든 코드, 빌드 규칙, registry | [src/README.md](src/README.md) | +| `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) | +| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh` | +| `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 | +| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) | +| `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) | + +`src/` 아래 폴더는 계층 leaf, 조립, 들여온 제품, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다. + +| 폴더 | 책임 | 기본 조립에 들어가나 | +| --- | --- | --- | +| `domain-core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 | +| `application-core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 | +| `application-fileserver/`, `application-notification/`, `application-objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 | +| `shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 | +| `adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 | +| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 | +| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 | +| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 | +| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼), `grpc`·`grpc-advanced`(gRPC 라이브러리, 다른 빌드 `optional-build`) | 들어가지 않는다. adapter를 거쳐서만 닿는다 | +| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 | + +의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다. ```text -app-bootstrap -> adapter:inbound:* -> application-core -> domain-core -app-bootstrap -> adapter:outbound:* -> application-core -> domain-core -모든 런타임 모듈 -> shared-contract +app-bootstrap ─▶ adapter:inbound:* ─▶ application-core ─▶ domain-core +app-bootstrap ─▶ adapter:outbound:* ─▶ application-core ─▶ domain-core +모든 런타임 모듈 ─▶ shared-contract ``` -family 수준의 책임은 다음과 같습니다. +불변식: 도메인 규칙은 `domain-core`와 `application-core`에만 있고, 기술 선택(웹, DB, 메시징)은 adapter에만 있다. -| 모듈 family | 책임 | -| --- | --- | -| `domain-core` | 순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지 | -| `application-core` | command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 | -| `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 | -| `adapter:outbound:persistence-*` | JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration | -| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 | -| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 | -| `app-bootstrap` | Spring Boot entrypoint와 composition root | +## 시작하기 -등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는 -[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused -test는 해당 Gradle path에서 `./gradlew :test --console=plain` 형태로 파생하며, root -문서나 기억에서 개별 leaf edge를 추론하지 않습니다. - -## 퀵스타트 - -전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다. +전제는 Temurin 21(`.tool-versions`에 고정)과 Docker Engine 또는 Docker Desktop이다. Gradle은 저장소의 wrapper를 쓴다. 첫 실행 진입점은 하나다. ```bash scripts/bootstrap-local.sh ``` -`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다. +이 스크립트는 네 단계를 차례로 돈다: 컴파일, PostgreSQL 기동, 앱 이미지 빌드와 기동, `GET /api/healthcheck` 확인. 단계마다 `bootstrap N/4` 줄을 찍고, 실패하면 그 단계에서 멈춘다. 쓰는 compose 파일은 루트의 `compose.yaml` 하나다. + +성공하면 이 명령이 HTTP 200을 돌려준다. ```bash curl -fsS http://localhost:8080/api/healthcheck ``` -로컬 스택을 내릴 때는 저장소 루트에서 실행합니다. +내릴 때는 저장소 루트에서 `--profile '*'`를 붙인다. 붙이지 않으면 profile로 띄운 `db` 같은 서비스가 남는다. ```bash docker compose --profile '*' down ``` -`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다. +환경 변수는 `src/.env`(로컬 실행 입력)와 `src/.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다. -Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다. +## 기능 켜고 끄기 -`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다. +기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `cd src && ./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다. -### 기본 조립과 부가 기능 +DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다. -기본 조립(`bootJar`)은 web, 관측, `domain-core`·`application-core`·`shared-contract`, support, -identifier뿐이라 DB·Redis·Kafka 없이 기동합니다. +- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다. +- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다. +- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표. +- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md). +- capability 모듈이 지켜야 하는 규칙: [AGENTS.md](AGENTS.md) 「부가 기능(capability) 모듈 규칙」. + +뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다. + +## 문서 지도 + +모든 문서 폴더의 지도는 [docs/README.md](docs/README.md)다. 무엇을 하려는지에 따라 여기서 시작한다. + +| 하려는 일 | 시작할 곳 | +| --- | --- | +| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) | +| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` | +| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` | +| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` | +| 왜 이렇게 정했는지 보기 | 결정 기록 `docs/adr/`, `docs/notification/adr/` | +| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 | +| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` | + +각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)). + +## 검증 + +명령은 `src/`에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다. ```bash cd src -./gradlew :app-bootstrap:bootRun +./gradlew :app-bootstrap:check --console=plain +./gradlew architectureCheck --console=plain ``` -DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 `app-bootstrap/build.gradle`에 주석 처리된 -`runtimeOnly` 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다. -줄마다 필요한 env와 끄는 키는 [src/README.md](src/README.md)의 "기능 추가 = 한 줄 + env" 표에 있습니다. +`./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [src/README.md](src/README.md) 「build.gradle — 빌드 / 검증 게이트」다. -| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 | -| --- | --- | --- | -| `local` | Compose PostgreSQL (`./gradlew :app-bootstrap:bootRunH2`는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) | Flyway (H2는 Hibernate `create-drop`) | -| `dev` | PostgreSQL | Flyway | -| `prod` | PostgreSQL | Flyway | +문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다. -H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 [src/app-bootstrap/src/main/resources/](src/app-bootstrap/src/main/resources/)의 `application-{local,dev,prod}.yml`이, 상세 설명은 [src/README.md](src/README.md)가 소유합니다. +## 새 서비스로 시작하기 -## 새 프로젝트로 시작하기 +이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 전체 체크리스트는 [AGENTS.md](AGENTS.md) 「템플릿 재사용 체크리스트」다. -이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 [AGENTS.md](AGENTS.md)의 "템플릿 재사용 체크리스트"에 있습니다. - -1. [src/settings.gradle](src/settings.gradle)의 `rootProject.name`을 새 서비스 이름으로 바꿉니다. -2. 패키지 루트 `dev.caskeleton`을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야 `mainClass`·`group`이 어긋나 `bootstrap`이 깨지지 않습니다. +1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다. +2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. ```bash - cd src - find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g' + git grep -l 'dev\.caskeleton' -- src scripts ``` - 애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다. +3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다. +4. 새 업무 기능은 `scripts/new-feature.sh `으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다. +5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다. -3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh `으로 만듭니다. -4. 모듈 이름과 경계는 그대로 유지합니다. +복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`). -검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서 -`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬 -피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가 -담당합니다. +이름을 바꾼 뒤에는 위 「검증」의 두 명령과 `./gradlew :app-bootstrap:test --console=plain`을 돌린다. -```bash -cd src -./gradlew :app-bootstrap:test -./gradlew architectureCheck -``` +## 규칙과 기여 -병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다. - -## 아키텍처 규칙과 검증 - -애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬 -정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다. -일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다. - -- `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다. -- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다. -- inbound DTO는 `application-core`나 `domain-core`로 들어가지 않습니다. -- 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다. -- 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다. - -이 규칙은 두 축으로 자동 강제합니다. `:app-bootstrap:architectureTest`의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을, -`verifyCleanArchitectureDependencies` 게이트가 JSON registry의 허용 Gradle project edge를 -검사합니다. - -```bash -cd src -./gradlew verifyCleanArchitectureDependencies -``` - -두 검증 축은 [ci-quality-gates.yml](.github/workflows/ci-quality-gates.yml)의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다. - -## 수동 전용 Gradle 태스크 - -아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다. - -여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의 -```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는 -Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의 -함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다. - -```bash -cd src -./gradlew :grpc:grpc-testkit:grpcPerformanceTest -``` - -- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI - runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의 - 태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다. - - -## 더 알아보기 - -- 빌드·검증 게이트·환경 변수 상세: [src/README.md](src/README.md) -- 모듈 레지스트리(등록 leaf SSOT): [src/config/architecture/modules.json](src/config/architecture/modules.json) -- 에이전트·기여자 작업 규칙: [AGENTS.md](AGENTS.md) · [CLAUDE.md](CLAUDE.md) -- release/publish 자동화는 `.github/workflows/release.yml`이 소유하며, release provenance·SBOM· - 이미지 build/push를 해당 workflow의 명시적 권한과 게이트 아래에서 수행합니다. -- 모듈별 설계 결정: [domain-core](src/domain-core/README.md) · [application-core](src/application-core/README.md) · [adapter:inbound:web](src/adapter/inbound/web/README.md) · [adapter:outbound:persistence-jpa](src/adapter/outbound/persistence-jpa/README.md) · [shared-contract](src/shared-contract/README.md) · [app-bootstrap](src/app-bootstrap/README.md) +- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다. +- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. +- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다. +- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다. diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java index af7bb788..1347650f 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java @@ -137,8 +137,8 @@ class DeveloperExperienceContractTest { assertThat(readme) .contains("scripts/bootstrap-local.sh") .contains("GET /api/healthcheck") - .contains("## 퀵스타트") - .contains("첫 실행 진입점은 하나입니다."); + .contains("## 시작하기") + .contains("첫 실행 진입점은 하나다."); } @Test From 145ae00f90e110a4e874854b40d10c9c7a40b141 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 02/12] =?UTF-8?q?docs(src):=20src/README=EC=9D=98=20?= =?UTF-8?q?=EC=98=81=EC=96=B4=20=EC=A0=9C=EB=AA=A9=EA=B3=BC=20=EC=BD=94?= =?UTF-8?q?=EB=93=9C=EC=99=80=20=EB=8B=A4=EB=A5=B8=20=EC=A3=BC=EC=9E=A5?= =?UTF-8?q?=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `src/README.md`에 영어 제목(「Local bootstrap」「App identity」 등)과 영어 문장이 남아 있다. 지운 게이트 표 `.github/ci-gate-matrix.yml`과 검사기 `.github/scripts/verify-gate-matrix.sh`를 지금 있는 것처럼 인라인 코드로 적어 참조 검사의 예외 줄 둘이 남아 있다. 코드와 다른 주장도 둘이다. - `SPRING_PROFILES_ACTIVE`를 「보통 local | dev | stage | prod」라 한다. registry `allowed_values`와 `RuntimeEnvironment`는 local·dev·prod뿐이다. - 추적 샘플 비율 기본값에 「staging = 0.10」이 있다. `TracingSampleRateResolver`는 PROD 0.01, LOCAL·DEV 1.0만 안다. 고른 방법: 영어 제목과 문장을 한국어로 옮기고, 지운 두 파일 이야기는 「> 이력」 인용 블록으로 옮긴다. 두 주장은 코드에 맞춘다. 다른 문서가 이름으로 가리키는 「기능 추가 = 한 줄 + env」 제목은 그대로 둔다. 위험·한계: 문서 전체가 「~합니다」체다. 문체를 「~한다」로 바꾸는 일은 하지 않았다. 검증: `python3 scripts/check-docs.py` rc=0(예외 줄 둘을 지움). --- scripts/check-docs-exceptions.txt | 2 -- src/README.md | 58 +++++++++++++++---------------- 2 files changed, 29 insertions(+), 31 deletions(-) diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 1bff4f87..d384cec2 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -185,8 +185,6 @@ reference docs/mongodb/consumer-leaf-guide.md :adapter:outbound:persistence-note reference docs/web/http-contract.md docs/architecture/backend-api-and-server-state-contract.md reference docs/work/operate.md :a:test reference docs/work/operate.md :b:test -reference src/README.md .github/ci-gate-matrix.yml -reference src/README.md .github/scripts/verify-gate-matrix.sh # 숫자: 정본(src/gradle/libs.versions.toml, registry)이 정하는 값을 복사한 곳. 정본을 가리키게 고치면 지운다. number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 diff --git a/src/README.md b/src/README.md index d51064ec..f9fcbcff 100644 --- a/src/README.md +++ b/src/README.md @@ -44,7 +44,7 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 `verifyConfigurationPropertiesProcessor`(`ca.spring-config` convention plugin이 대체). 근거는 `docs/design/2026-09-16-verification-surface-reduction-design.md`. -### Local bootstrap +### 로컬 첫 실행 `scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 → app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰 @@ -54,7 +54,7 @@ DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`( env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 example/registry/shipped YAML을 함께 검사합니다. -### Traceable version + dependency locking +### 추적 가능한 버전과 의존성 잠금 - leaf version은 release version뿐입니다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`). revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙습니다. revision은 jar @@ -71,7 +71,7 @@ env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 - lock 갱신은 `./gradlew resolveAndLockAll --write-locks` 한 가지 명령으로 수행합니다. 이 task는 `--write-locks`가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 합니다. -### Reproducible archives (D10) +### 재현 가능한 아카이브 (D10) 모든 `AbstractArchiveTask`는 file timestamp 보존을 끄고, file order를 재현 가능하게 정렬하며, directory/file mode를 각각 `0755`/`0644`로 고정합니다. Java toolchain은 21이고 로컬·CI patch @@ -192,10 +192,10 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 소유합니다. 개별 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/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 그 검사기 + > `.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 테스트는 경로 필터가 걸린 `build-logic.yml`이, main 단계(`mainCheck`)·configuration-cache·JPA candidate evidence는 @@ -211,13 +211,13 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 이 파일이 잡힙니다). 아래는 섹션별 키 설명입니다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동 필요)로 간주하세요. -### App identity +### 앱 이름과 profile - **`APP_NAME`** — `spring.application.name` 과 JSON 로그의 `app` 필드. 자유 문자열. -- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. 보통 `local` | `dev` | `stage` | `prod`. JSON +- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. `local` | `dev` | `prod` 중 정확히 하나입니다. JSON 로그의 `profile` 필드도 이 값을 씁니다. -### Runtime safety (기동 시 fail-fast 검사, D8) +### 런타임 안전 검사 (기동할 때 바로 실패시킨다, D8) - **`APP_SERVER_ERROR_INCLUDE_STACKTRACE` / `APP_SERVER_ERROR_INCLUDE_MESSAGE`** — 로컬 디버깅용. prod에서 `never`가 아니면 `ErrorDetailExposureSafetyValidator`가 기동을 막습니다(exit 71, @@ -226,7 +226,7 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, - **`APP_MULTI_INSTANCE_ENABLED`** — `true` 면 cross-instance `DistributedLockPort` (`distributedLockProvider`)가 조립돼 있어야 하며, 없으면 기동이 실패합니다(exit 72, `StartupSafetyValidator`). -- **`APP_RATE_LIMIT_ENABLED`** — provider-neutral edge rate-limit interceptor 활성화 +- **`APP_RATE_LIMIT_ENABLED`** — 제공자에 묶이지 않은 앞단 요청 수 제한(rate limit) interceptor를 켠다 (429 + `Retry-After` + `X-RateLimit-*` 응답). 기본값은 `false`이며, `true`로 바꿀 때는 `APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 합니다. 비인증 요청의 키는 `getRemoteAddr()` 입니다. 프록시 뒤라면 @@ -240,7 +240,7 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부합니다. 24h보다 올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올립니다. -### Async executor +### 비동기 executor `@Async` `ThreadPoolTaskExecutor` 풀 크기 설정입니다. @@ -313,14 +313,14 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle` `--lane `는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아닙니다. -### Optional integration adapters +### 선택형 연동 adapter Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니다. 모듈이 있으면 켜지고, 없으면 그 포트를 구현하는 bean이 아예 없습니다. 아래는 모듈을 고른 뒤 동작을 고르는 키입니다. - **`APP_CACHE_REDIS_ENABLED`** — deprecated(2026-11-30 제거 예정). 읽는 곳이 없고, 기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`입니다. -- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — canonical default semantic region 선택. +- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — 기본 캐시 영역(canonical default semantic region)의 제공자를 고른다. `disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구합니다. - **`APP_CACHE_REDIS_CLIENT_MODE`** — `managed`는 내장 Lettuce runtime, `external`은 프로젝트가 제공한 `RedisClient` bean을 사용합니다. @@ -334,11 +334,11 @@ Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니 - **`APP_MESSAGING_KAFKA_BROKERS`** — `host:port` CSV. Kafka 모듈을 고르면 필수. messaging platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 이 값을 씁니다. `spring.kafka.bootstrap-servers`는 읽지 않습니다. -- **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 provider enable flag. notification 플랫폼이 +- **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 제공자를 켜는 값. notification 플랫폼이 켜졌을 때 어떤 provider를 쓸지 고르는 값입니다. -- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 provider enable flag. 위와 같습니다. +- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 제공자를 켜는 값. 위와 같습니다. -### Outbound HTTP client +### 외부 HTTP 호출 (HTTP client) 현재 canonical activation은 다음 두 설정 트리만 사용합니다. @@ -366,7 +366,7 @@ app: timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider readiness를 증명하지 않습니다. -### Logging +### 로그 **Root / app 레벨** — 허용값은 모두 `TRACE` | `DEBUG` | `INFO` | `WARN` | `ERROR` | `OFF`. @@ -407,31 +407,31 @@ app: - **`APP_LOG_SAMPLING_RATE`** — `INFO` 이하 로그를 남길 확률. [0.0, 1.0] float. prod 는 `0.1`(10% 샘플링)이 권장, `WARN`/`ERROR` 는 항상 유지. `1.0` = 샘플링 없음(dev/local/staging 기본). -### Distributed tracing +### 분산 추적 - **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증합니다. - **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는 `WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성합니다(D4 disabled-fallback 보장). - **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float. - - per-profile 기본값(D6): prod = `0.01`, staging = `0.10`, dev/local = `1.0`. + - profile별 기본값(D6): prod = `0.01`, dev/local = `1.0`. - **결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix).** 빈 값이어야 per-profile resolver 의 기본값이 실제 tracer sampler 까지 도달합니다(`TracingSampleRateResolver` 가 SSOT). 값을 박으면 프로필별 기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채웁니다. -### Privacy: user_principal pseudonymization +### 개인정보: user_principal 가명화 - **`APP_PRIVACY_PSEUDONYMIZATION_SALT`** — secret 등급 HMAC-SHA-256 salt. `__LOCAL_DEV_` prefix 는 로컬 전용 sentinel 값이며, **prod 에서는 secret-manager 가 주입하는 실제 값**을 써야 합니다. -### Spring Boot bootstrap +### Spring Boot 기동 - **`SPRING_BANNER_MODE`** — `off` | `console` | `log`. - **`SPRING_MAIN_LAZY_INITIALIZATION`** — `true` 면 빈 생성을 첫 사용 시점까지 지연. - **`SPRING_MAIN_LOG_STARTUP_INFO`** — `true` 면 `Starting`/`Started` 로그 출력. - **`SPRING_THREADS_VIRTUAL_ENABLED`** — `true` 면 Tomcat 요청 처리에 Java 21 virtual threads 사용. -### Jackson — deserialization policy +### Jackson — 역직렬화 정책 모든 request DTO 는 Jackson 경계를 지납니다. 아래 4개 스위치는 잘못된 입력을 **조용히 강제 변환하지 않고 즉시 실패**하게 만듭니다. 개별 DTO 에 클래스 레벨 `@JsonIgnoreProperties(ignoreUnknown = true)` @@ -447,7 +447,7 @@ app: - **`..._READ_UNKNOWN_ENUM_VALUES_AS_NULL`** — `false`(Jackson 기본 유지): 모르는 enum 값이 조용히 `null` 이 되지 않고 throw 되어 `VALIDATION_FAILED` 로 드러나게 합니다. -### Jackson — serialization policy +### Jackson — 직렬화 정책 응답 생성 쪽 정책입니다. 현재 Jackson/Spring Boot 기본값과 같지만 **명시적으로 못박아**, 미래에 Spring Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니다(`spring.mvc.problemdetails.enabled=false` @@ -463,7 +463,7 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니 금지합니다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둡니다(공개/금융 API 는 string, 내부 API 는 number+plain). -### Server / Tomcat +### 서버 / Tomcat - **`APP_SERVER_PORT`** — 1~65535 정수. - **`APP_SERVER_SHUTDOWN`** — `graceful` | `immediate`. @@ -482,12 +482,12 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니 - **`APP_SERVER_ERROR_INCLUDE_STACKTRACE`** — `always` | `never` | `on_param`. - **`APP_SERVER_ERROR_INCLUDE_MESSAGE`** — `always` | `never` | `on_param`. -### Presentation +### 표현 계층 (presentation) - **`PRESENTATION_API_BASE_PATH`** — 모든 controller 앞에 붙는 leading-slash 경로(예: `/api` | `/v1` | `""`). -### Auth (OIDC resource server) +### 인증 (OIDC resource server) - **`APP_SECURITY_JWT_ISSUER`** — OIDC issuer URI(Keycloak realm, Auth0 tenant 등). **필수** — 없으면 기동 실패. 예: `https://keycloak.example.com/realms/ca-skeleton`. @@ -547,7 +547,7 @@ docker compose up -d --wait db 스위치입니다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 `h2` 이거나 datasource URL 이 `jdbc:h2:` 이면 `PersistenceVendorProdSafetyValidator` 가 기동을 거부합니다(env 로 덮어써도 동일). -### Database (Postgres) +### 데이터베이스 (PostgreSQL) - **`APP_DATASOURCE_URL`** — JDBC URL(예: `jdbc:postgresql://host:5432/dbname`). `dev`·`prod` 에서 쓰이며, 커밋된 기본값 `jdbc:postgresql://localhost:5433/ca_skeleton` 은 위 compose `db` 서비스의 @@ -570,7 +570,7 @@ docker compose up -d --wait db - **`APP_DATASOURCE_POOL_MAX_LIFETIME`** — 연결의 최대 수명(ms). broker timeout 전에 rotate 하도록 설정합니다. -### Management / Actuator +### 관리 포트 / Actuator - **결정 — management 포트 분리.** actuator 엔드포인트를 앱 API 와 **같은 소켓에 노출하지 않으려고** 별도 management 포트를 둡니다. From 81f17b49e01efc68b285813974feb71a1bb4485f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 03/12] =?UTF-8?q?docs(github):=20PR=20=EC=96=91=EC=8B=9D?= =?UTF-8?q?=EA=B3=BC=20=EC=9D=98=EC=A1=B4=EC=84=B1=20=EC=B7=A8=EC=95=BD?= =?UTF-8?q?=EC=A0=90=20=EC=A0=95=EC=B1=85=EC=9D=84=20=ED=95=9C=EA=B5=AD?= =?UTF-8?q?=EC=96=B4=EB=A1=9C=20=EC=98=AE=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `.github/pull_request_template.md`와 `.github/dependency-vulnerability-policy.md`가 영어라 언어 검사 예외에 있다. 옮기면서 보니 코드와 다른 주장이 넷이다. - PR 양식이 격리 테스트를 `flaky-quarantine.yaml`에 등록하라고 한다. 그 레지스트리는 지웠다(`src/README.md` 「Trivy suppression과 플래키 격리」). - 정책이 이미지 빌드·SBOM·서명·provenance를 「없는 job」이라 한다. 지금은 `release.yml`에 있다. - 정책이 patch·pin·digest 보안 갱신은 필수 검사 뒤 자동 병합할 수 있다고 한다. `renovate.json`은 모든 갱신이 `automerge: false`이고, lockfile은 사람이 다시 만든다. - 정책이 `gradle.lockfile`을 「19개」라 한다. 지금 68개다. 고른 방법: 뜻을 그대로 옮기고 위 넷은 코드에 맞춘다. lockfile 개수는 숫자를 쓰지 않는다. 명령·경로·변수 이름은 원문으로 둔다. 검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움). --- .github/dependency-vulnerability-policy.md | 134 ++++++++++----------- .github/pull_request_template.md | 25 ++-- scripts/check-docs-exceptions.txt | 2 - 3 files changed, 79 insertions(+), 82 deletions(-) diff --git a/.github/dependency-vulnerability-policy.md b/.github/dependency-vulnerability-policy.md index f046077e..cda1c924 100644 --- a/.github/dependency-vulnerability-policy.md +++ b/.github/dependency-vulnerability-policy.md @@ -1,92 +1,92 @@ -# Dependency Vulnerability Policy +# 의존성 취약점 정책 -This policy is enforced by +이 정책을 강제하는 것은 [`dependency-vulnerability.yml`](workflows/dependency-vulnerability.yml), [`dependency-review-config.yml`](dependency-review-config.yml), -[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS, and -[`../renovate.json`](../renovate.json). +[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS, +[`../renovate.json`](../renovate.json)이다. -## Execution and platform boundary +## 실행 위치와 플랫폼 경계 -Canonical workflow files live under `.github/workflows`. The current origin is Gitea and -server-side Actions is externally disabled; committing these controls does not enable or prove -remote execution. An administrator must enable Actions, provide compatible runners, configure -required checks, and require code-owner review separately. +정본 workflow 파일은 `.github/workflows` 아래에 있다. 지금 origin은 Gitea이고, 서버 쪽 Actions는 밖에서 +꺼져 있다. 이 통제를 커밋해도 원격 실행이 켜지거나 증명되지 않는다. 관리자가 따로 Actions를 켜고, 맞는 +runner를 주고, 필수 검사(required check)를 설정하고, code owner 리뷰를 필수로 해야 한다. -External actions execute only by verified full commit SHA; inline comments retain the immutable -release tag for review. GitHub dependency review publishes check output but never writes a PR -summary comment, preserving the workflow-wide `contents: read` permission. +외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를 +남긴다. GitHub dependency review는 검사 결과만 내고 PR 요약 댓글은 쓰지 않는다. 그래서 workflow 전체의 +`contents: read` 권한이 유지된다. -GitHub dependency review and dependency submission depend on GitHub.com APIs. They are guarded by -`github.server_url == 'https://github.com'` and intentionally skip on Gitea. `trivy-fs` is the -platform-neutral release-blocking snapshot and runs for pull requests, `main` pushes, daily -schedule, and manual dispatch. +GitHub dependency review와 dependency submission은 GitHub.com API에 기댄다. 둘은 +`github.server_url == 'https://github.com'` 조건으로 막혀 있고, Gitea에서는 일부러 건너뛴다. `trivy-fs`는 +플랫폼에 묶이지 않는, 릴리스를 막는 전체 스냅숏 검사다. pull request, `main` push, 매일 예약 실행, 손으로 +부른 실행에서 돈다. -The later supply-chain slice owns image builds/scans, SBOM, signing, provenance, tag release, and -retention. This policy does not claim those absent jobs. +이미지 빌드·스캔, SBOM, 서명, provenance, 태그 릴리스는 `workflows/release.yml`이 맡는다. 이 정책은 그 +job을 다루지 않는다. -## Severity and response +## 심각도와 대응 -| Severity | CI posture | Target remediation | +| 심각도 | CI 처리 | 고칠 기한 | | --- | --- | --- | -| KEV / Critical | block | 7 days or the CISA due date, whichever is sooner | -| High | block | 30 days | -| Medium | advisory | 90 days | -| Low | advisory | best effort | +| KEV / Critical | 막는다 | 7일 또는 CISA 기한 중 빠른 쪽 | +| High | 막는다 | 30일 | +| Medium | 알리기만 한다 | 90일 | +| Low | 알리기만 한다 | 가능한 대로 | -High/Critical is the template's release threshold. The exact threshold and remediation targets are -team policy rather than an external mandate and should be reviewed when the template is adopted. -GitHub dependency review applies the same High threshold to newly introduced runtime dependencies. +High/Critical이 이 템플릿의 릴리스 기준이다. 정확한 기준과 고칠 기한은 외부 규정이 아니라 팀 정책이다. +템플릿을 받아 쓸 때 다시 검토한다. GitHub dependency review도 새로 들어온 runtime 의존성에 같은 High +기준을 쓴다. -The Trivy JSON snapshot is also compared with the CISA Known Exploited Vulnerabilities catalog. -Any intersection blocks regardless of Trivy severity. Before intersection, CI requires nonblank -catalog metadata, a positive integral declared count, a non-empty vulnerability array whose length -matches that count, and unique CVE-pattern `cveID` values. A missing, empty, malformed, -count-inconsistent, duplicate, or unreachable KEV feed fails closed; configure the `KEV_FEED_URL` -repository variable to an approved internal mirror when direct CISA access is unavailable. +Trivy JSON 스냅숏은 CISA KEV(Known Exploited Vulnerabilities, 실제 악용이 확인된 취약점) 목록과도 +대조한다. 겹치는 항목이 있으면 Trivy 심각도와 상관없이 막는다. 대조하기 전에 CI는 KEV 목록을 확인한다. -Candidate extraction also validates Trivy's JSON first: the top level must be an object with a -non-empty `Results` array; each result is an object whose `Vulnerabilities` value is null or an -array; and every listed vulnerability has a nonblank string `VulnerabilityID`. Invalid scanner -output fails closed instead of becoming an empty candidate set. +- 목록 메타데이터가 비어 있지 않다. +- 선언한 개수가 양의 정수다. +- 취약점 배열이 비어 있지 않고 길이가 선언한 개수와 같다. +- `cveID` 값이 CVE 형식이고 서로 다르다. -## Scanner and network requirements +KEV 목록이 없거나, 비었거나, 형식이 깨졌거나, 개수가 맞지 않거나, 중복이 있거나, 받을 수 없으면 실패한다 +(fail closed). CISA에 직접 닿을 수 없으면 저장소 변수 `KEV_FEED_URL`을 승인된 내부 mirror로 설정한다. -Trivy scans the committed filesystem and Gradle lockfiles. High/Critical findings exit non-zero; -Medium/Low findings are reported with exit zero. Scanner database or tool-download failures remain -failures rather than silently producing an empty result. +후보를 뽑을 때도 Trivy JSON을 먼저 검사한다. 맨 위가 객체이고 `Results` 배열이 비어 있지 않아야 한다. +각 결과는 객체이고, `Vulnerabilities` 값은 null이거나 배열이다. 나열된 취약점마다 비어 있지 않은 문자열 +`VulnerabilityID`가 있어야 한다. 스캐너 출력이 잘못됐으면 빈 후보 목록으로 넘어가지 않고 실패한다. -Runners need HTTPS egress to: +## 스캐너와 네트워크 요구사항 -- the configured Trivy binary source (GitHub Releases by default); -- Trivy vulnerability databases (the scanner defaults, commonly OCI registries); -- jq releases, unless `JQ_DOWNLOAD_BASE_URL` points to an internal mirror; -- the CISA KEV feed, unless `KEV_FEED_URL` points to an internal mirror; -- GitHub action sources when the forge does not mirror actions. +Trivy는 커밋된 파일 시스템과 Gradle lockfile을 검사한다. High/Critical이 나오면 0이 아닌 코드로 끝나고, +Medium/Low는 보고만 하고 0으로 끝난다. 스캐너 DB나 도구를 받지 못하면 빈 결과가 아니라 실패다. -Closed networks must mirror the pinned Trivy/jq artifacts and checksums, set -`TRIVY_DOWNLOAD_BASE_URL` and `JQ_DOWNLOAD_BASE_URL`, configure Trivy's documented database mirror -environment, and set `KEV_FEED_URL`. Mirror availability and freshness are operational -dependencies; stale mirrors can delay detection. +runner는 다음 곳으로 HTTPS로 나갈 수 있어야 한다. -## Suppression governance +- 설정한 Trivy 실행 파일 출처(기본은 GitHub Releases) +- Trivy 취약점 DB(스캐너 기본값, 보통 OCI 레지스트리) +- jq 릴리스(`JQ_DOWNLOAD_BASE_URL`이 내부 mirror를 가리키면 그쪽) +- CISA KEV 목록(`KEV_FEED_URL`이 내부 mirror를 가리키면 그쪽) +- forge가 action을 mirror하지 않으면 GitHub action 출처 -The only suppression source is repository-root `.trivyignore.yaml`. Every Trivy scan passes it -explicitly with `--ignorefile .trivyignore.yaml`. Each future entry must contain an identifier, a -non-empty rationale, and a future expiry no more than 90 days away. A CODEOWNERS reviewer validates -the shape and expiry; CODEOWNERS plus branch protection controls who may approve the change. -Neither control substitutes for the other. +닫힌 네트워크에서는 고정한 Trivy·jq 산출물과 체크섬을 mirror하고, `TRIVY_DOWNLOAD_BASE_URL`과 +`JQ_DOWNLOAD_BASE_URL`을 설정하고, Trivy 문서에 있는 DB mirror 환경을 설정하고, `KEV_FEED_URL`을 설정한다. +mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mirror는 탐지를 늦출 수 있다. -Do not use an ad-hoc ignore file or an inline scanner bypass. An expired suppression is removed or -renewed with fresh owner review and current evidence. +## 예외(suppression) 관리 -## Dependency update policy +예외의 출처는 저장소 루트 `.trivyignore.yaml` 하나다. 모든 Trivy 검사가 `--ignorefile .trivyignore.yaml`로 +그 파일을 명시한다. 앞으로 더하는 항목마다 식별자, 비어 있지 않은 이유, 90일 안의 미래 만료일이 있어야 +한다. CODEOWNERS 리뷰어가 모양과 만료일을 확인하고, CODEOWNERS와 branch protection이 누가 그 변경을 승인할 +수 있는지 정한다. 둘 중 하나가 다른 하나를 대신하지 않는다. -Renovate is the checked-in security-update bot configuration. Patch/pin/digest security updates -may auto-merge only after every configured required check succeeds; minor and major updates require -human review. Dependency declarations and all 19 `gradle.lockfile` files must move together, and -`verifyDependencyLocks` remains release-blocking. +임시 ignore 파일이나 스캐너를 건너뛰는 인라인 옵션을 쓰지 않는다. 만료된 예외는 지우거나, 소유자가 새로 +검토하고 지금의 증거를 붙여 갱신한다. -Bot alerts are not a transitive-dependency backstop on every forge. Use a Gradle constraint or -resolution rule for a vulnerable transitive dependency, refresh locks deliberately, and retain the -full-snapshot Trivy scan. +## 의존성 갱신 정책 + +Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다 +(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가 +`cd src && ./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께 +커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를 +막는다. + +봇 알림은 모든 forge에서 전이 의존성(transitive dependency)까지 봐 주지 않는다. 취약한 전이 의존성은 +Gradle constraint나 resolution rule로 고정하고, 잠금을 의도적으로 다시 만들고, 전체 스냅숏 Trivy 검사를 +유지한다. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b0736f82..a9b235c0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,17 @@ -## What changed and why +## 무엇을 왜 바꿨나 - + -## Verification +## 검증 -- [ ] I ran focused `::check` tasks for the modules I changed. -- [ ] I ran `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks` when the change touched repository structure, dependencies, or public paths. -- [ ] I did not add an unregistered production module dependency. -- [ ] Dependency changes include refreshed `gradle.lockfile` files and a strict-lock verification. -- [ ] Trivy suppressions include an owner-reviewed reason and an expiry within 90 days. -- [ ] Any quarantined test is registered in `flaky-quarantine.yaml` with a reason, issue, and - `quarantined_since` date. -- [ ] I documented checks that could not run and their remaining risk. +- [ ] 바꾼 모듈마다 `::check`를 돌렸다. +- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다. +- [ ] registry에 없는 production 모듈 의존을 더하지 않았다. +- [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다. +- [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다. +- [ ] 간헐 실패 테스트는 격리하지 않고 고치거나 지웠다(격리 레지스트리는 없다). +- [ ] 돌리지 못한 검사와 그 때문에 남은 위험을 적었다. -## Compatibility and operations +## 호환성과 운영 - + diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index d384cec2..8a5aa7f4 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -5,8 +5,6 @@ # - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다. # 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다. -language .github/dependency-vulnerability-policy.md -language .github/pull_request_template.md language compose/keycloak/README.md language compose/redis/acl/README.md language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md From af177de0aa4d403316a51a49f4549f5e498630a9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 04/12] =?UTF-8?q?docs(compose):=20Keycloak=20realm?= =?UTF-8?q?=EA=B3=BC=20Redis=20ACL=20=EC=95=88=EB=82=B4=EB=A5=BC=20?= =?UTF-8?q?=ED=95=9C=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=98=AE=EA=B8=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `compose/keycloak/README.md`와 `compose/redis/acl/README.md`가 영어라 언어 검사 예외에 있다. ACL README의 파일 표에는 폴더에 있는 `sentinel-accounts.acl`이 없다. 고른 방법: 뜻을 그대로 옮긴다. 긴 문단은 목록으로 나눈다. 파일 표에 `sentinel-accounts.acl` 행을 더하고, 지금 이 파일을 `aclfile`로 읽는 compose 파일이 없다고 적는다(`git grep sentinel-accounts`가 이 README 밖에서 0건). 위험·한계: `sentinel-accounts.acl`을 지울지는 정하지 않았다. 검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움). --- compose/keycloak/README.md | 54 +++++++--------- compose/redis/acl/README.md | 104 ++++++++++++++++-------------- scripts/check-docs-exceptions.txt | 2 - 3 files changed, 80 insertions(+), 80 deletions(-) diff --git a/compose/keycloak/README.md b/compose/keycloak/README.md index 57266885..c44a9531 100644 --- a/compose/keycloak/README.md +++ b/compose/keycloak/README.md @@ -1,37 +1,33 @@ -# Keycloak realm artifact +# Keycloak realm 파일 -`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml` -and is the same realm every GraphQL qualification lane authenticates against. +루트 `compose.yaml`의 `keycloak` 서비스가 `realms/ca-skeleton-realm.json`을 가져온다(import). 모든 GraphQL +qualification lane이 인증하는 realm도 이 파일이다. -## The client secret is a reference, never a value +## client secret은 값이 아니라 참조다 -The confidential client `ca-skeleton-api` carries `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`. -`entrypoint.sh` reads the value from the Compose secret mounted at -`/run/secrets/keycloak-graphql-smoke-client-secret`, exports it, and execs `kc.sh start-dev ---import-realm`, so the value never reaches Git, a rendered Compose config, a command line, or an -evidence file. A realm file with a working credential in it is a credential in the repository, and -"it is only for smoke tests" is not something a scanner or a fork can tell. +confidential client `ca-skeleton-api`는 `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`를 가진다. +`entrypoint.sh`가 `/run/secrets/keycloak-graphql-smoke-client-secret`에 마운트된 Compose secret에서 값을 읽어 +export하고, `kc.sh start-dev --import-realm`을 exec한다. 그래서 값이 Git, 렌더링된 Compose 설정, 명령줄, +증거 파일 어디에도 닿지 않는다. 동작하는 자격 증명이 든 realm 파일은 저장소 안의 자격 증명이다. 「smoke +테스트에만 쓴다」는 사정은 스캐너도 fork도 알 수 없다. -## No comment keys in the realm JSON +## realm JSON에 주석 키를 두지 않는다 -Keycloak deserializes this file into `RealmRepresentation` with unknown fields **rejected**, not -ignored. A `"_comment"` key here fails the whole import with `Unrecognized field "_comment"`, the -container exits 1, and the lane fails on Keycloak rather than on anything it was testing. That is -why this rationale lives in Markdown next to the artifact instead of inside it. +Keycloak은 이 파일을 `RealmRepresentation`으로 역직렬화할 때 모르는 필드를 무시하지 않고 **거절한다**. +`"_comment"` 키 하나가 `Unrecognized field "_comment"`로 import 전체를 실패시키고, 컨테이너가 1로 끝나고, +lane은 시험하던 것이 아니라 Keycloak에서 실패한다. 그래서 이 근거를 파일 안이 아니라 옆의 Markdown에 둔다. -## What the realm grants +## realm이 주는 권한 -- realm role `user` — the baseline role the application authorizes ordinary calls on -- client role `ca-skeleton-api:graphql-query` — permission to execute a GraphQL query -- client roles `notification-submit`, `notification-template-publish`, `operation-submit` — the - platform permissions `security.yml` maps them to -- client roles `ROLE_FILE_READ` and `ROLE_FILE_WRITE` — the fileserver's read and write tiers, which - `security.yml` also maps to `file:read` and to `file:upload`, `file:delete`, `file:copy`, - `file:move`; `ROLE_FILE_ADMIN` (`file:admin`) is defined but not granted to the service account, - since the management plane is off by default -- a service account for the client-credentials grant the qualification lane uses -- audience and realm/client role mappers, so the issued token carries what the resource server - validates +- realm role `user`: 애플리케이션이 보통 호출을 허가하는 기본 role +- client role `ca-skeleton-api:graphql-query`: GraphQL query를 실행할 권한 +- client role `notification-submit`, `notification-template-publish`, `operation-submit`: `security.yml`이 + 플랫폼 권한으로 바꾸는 role +- client role `ROLE_FILE_READ`, `ROLE_FILE_WRITE`: 파일 서버의 읽기·쓰기 등급. `security.yml`이 각각 + `file:read`와 `file:upload`·`file:delete`·`file:copy`·`file:move`로 바꾼다. `ROLE_FILE_ADMIN` + (`file:admin`)은 정의만 하고 service account에 주지 않는다. 관리 기능은 기본으로 꺼져 있다 +- qualification lane이 쓰는 client credentials grant용 service account +- audience mapper와 realm·client role mapper. 발급한 토큰에 resource server가 검증하는 값이 실린다 -Standard flow and direct access grants are disabled: the lane authenticates as a service, and an -enabled password grant is a second way in that nothing tests. +standard flow와 direct access grant는 꺼 두었다. lane은 서비스로 인증하고, 켜 둔 password grant는 아무도 +시험하지 않는 두 번째 입구가 된다. diff --git a/compose/redis/acl/README.md b/compose/redis/acl/README.md index adfc2118..01a388bc 100644 --- a/compose/redis/acl/README.md +++ b/compose/redis/acl/README.md @@ -1,58 +1,64 @@ -# ACL accounts — test fixtures, not a deployment file +# ACL 계정 — 배포 파일이 아니라 시험용 fixture -**Nothing in this directory is loaded by a deployment.** Every file here is a fixture for the local -and test lanes: its passwords are public (`fixture-*`, written in this repository), and -`lane-fixture-accounts.acl` also provisions three accounts that only a lane topology needs — among -them `ca-skeleton-cluster-bootstrap`, which has `~* &* +@all`, every command on every key. Loaded into -a real Redis, that line alone gives anyone who can reach the server and read this repository full -control of it (`CONFIG`, `MODULE`, every key). A deployment writes its own ACL file of the same -shape: the application accounts it actually uses, passwords from its secret store, and none of the -lane-only accounts (review 2026-11-03 RR-07-04). The application enforces its half of that: under -the `prod` runtime profile it refuses to start while a secret holds a value beginning with -`fixture-` (`SecretSourceValidator`): a key the secrets registry classifies `secret`, a variable a -module's `RequiredProductionSecrets` bean names, or the variable a `secret://…/` credential -reference in the environment names. A reference held in code — the typed SDK's admin account, -contributed as a `RedisAccountContribution` bean — is none of those: the composer names its variable -in a `RequiredProductionSecrets` bean too (`src/adapter/outbound/redis-sdk/README.md`), or the -`fixture-admin` password passes. A deployment that copied a lane's -`APP_REDIS_AUTHENTICATION_*_REFERENCE` and `REDIS_LANE_*` values stops before it connects. Values -that are not secrets — a pod's `HOSTNAME`, an application name — are not read, because `fixture-` -is an ordinary word as well. +**이 폴더의 어떤 파일도 배포에서 읽지 않는다.** 모든 파일이 로컬·테스트 lane용 fixture다. -One file per `CommandAccess` level. Each account is deliberately narrower than the SDK's own rules: -the account is the last enforcement boundary and a permit issued inside the process never widens it, -so a mistake in the SDK is still refused by the server. +- 비밀번호가 공개돼 있다(`fixture-*`, 이 저장소에 적혀 있다). +- `lane-fixture-accounts.acl`은 lane 구성에만 필요한 계정 셋도 만든다. 그중 + `ca-skeleton-cluster-bootstrap`은 `~* &* +@all`, 곧 모든 key에 모든 명령을 가진다. +- 이 줄 하나를 실제 Redis에 올리면, 서버에 닿을 수 있고 이 저장소를 읽을 수 있는 누구나 서버 전체 + (`CONFIG`, `MODULE`, 모든 key)를 다룰 수 있다. -A Redis ACL file accepts nothing but complete `user` lines — no comments and no line continuations — -which is why the rationale lives here instead of inline. +배포는 같은 모양의 자기 ACL 파일을 쓴다. 실제로 쓰는 애플리케이션 계정만 두고, 비밀번호는 자기 secret +store에서 가져오고, lane 전용 계정은 두지 않는다(review 2026-11-03 RR-07-04). -Every account here carries a **fixture** password (`fixture-*`). They are written down rather than -left as `nopass` because an account that accepts any password makes every assertion about -authentication pass for the same reason a typo would have — and because these files are what a fork -copies. The four per-role files carried `nopass` long after the combined lane file had been fixed; -a fork that copied one of them got an open account and a green lane. +애플리케이션도 자기 몫을 강제한다. `prod` 런타임 profile에서 비밀값이 `fixture-`로 시작하면 기동을 +거부한다(`SecretSourceValidator`). 보는 비밀값은 셋이다. -| File | Account | Grants | +- 비밀 레지스트리가 `secret`으로 분류한 키 +- 모듈의 `RequiredProductionSecrets` bean이 이름을 댄 변수 +- 환경 안의 `secret://…/` 자격 증명 참조가 가리키는 변수 + +코드에 있는 참조(typed SDK의 admin 계정을 `RedisAccountContribution` bean으로 기여하는 경우)는 이 셋 중 +어디에도 들지 않는다. 조립하는 쪽이 그 변수도 `RequiredProductionSecrets` bean에 적어야 한다 +(`src/adapter/outbound/redis-sdk/README.md`). 그러지 않으면 `fixture-admin` 비밀번호가 통과한다. +lane의 `APP_REDIS_AUTHENTICATION_*_REFERENCE`와 `REDIS_LANE_*` 값을 복사한 배포는 연결하기 전에 멈춘다. +비밀이 아닌 값(pod의 `HOSTNAME`, 애플리케이션 이름)은 읽지 않는다. `fixture-`는 보통 낱말이기도 하다. + +`CommandAccess` 등급마다 파일이 하나다. 각 계정은 SDK 자체 규칙보다 일부러 더 좁다. 계정이 마지막 +강제 경계이고 프로세스 안에서 내준 허가는 그 경계를 넓히지 못한다. 그래서 SDK에 실수가 있어도 서버가 +거절한다. + +Redis ACL 파일은 완전한 `user` 줄만 받는다. 주석도, 줄 이어 쓰기도 안 된다. 그래서 근거를 파일 안이 +아니라 여기에 둔다. + +여기의 모든 계정은 **fixture** 비밀번호(`fixture-*`)를 가진다. `nopass`로 두지 않고 적어 둔 이유는 둘이다. + +- 아무 비밀번호나 받는 계정에서는 인증에 대한 모든 단언이 오타가 있어도 통과한다. +- fork가 복사하는 것이 이 파일들이다. 역할별 파일 넷은 합친 lane 파일을 고친 뒤에도 오래 `nopass`였고, + 그중 하나를 복사한 fork는 열린 계정과 녹색 lane을 함께 얻었다. + +| 파일 | 계정 | 주는 권한 | | --- | --- | --- | -| `application.acl` | `CommandAccess.APPLICATION` | the typed data-structure commands over `prod:*`, with the dangerous and deprecated names denied | -| `application-advanced.acl` | `APPLICATION_ADVANCED` | the above plus pub/sub, transactions, and the registered-script path. `EVAL` is absent: only `EVALSHA` of an already loaded digest is reachable. `+time` is granted because the rate-limit and idempotency scripts read the server clock with `redis.call('TIME')`, and `TIME` is in no data category (`@read`/`@write`): without it every such script fails with an ACL error. The startup SCRIPT probe runs `TIME` so a template missing it fails at boot | -| `raw-gateway.acl` | `RAW_GATEWAY` | exactly the commands the catalog classifies `RAW_ONLY`, and nothing else | -| `lane-fixture-accounts.acl` | – | what the lanes load (Redis takes one `aclfile`): `user default off`, the four per-role accounts of this table, and three lane-only accounts — `ca-skeleton-replication` (replica sync) and `ca-skeleton-sentinel` for the replicated and sentinel topologies, `ca-skeleton-cluster-bootstrap` (`+@all`) to create the cluster lane's slots. Never a deployment file | -| `admin-readonly.acl` | `ADMIN_READONLY` | read-only diagnostics. Every destructive counterpart is denied here and blocked in the command policy catalog — two independent controls for the same rule | +| `application.acl` | `CommandAccess.APPLICATION` | `prod:*` 위의 typed 자료구조 명령. 위험한 명령과 폐기된 명령 이름은 막는다 | +| `application-advanced.acl` | `APPLICATION_ADVANCED` | 위 권한에 pub/sub, 트랜잭션, 등록된 script 경로를 더한다. `EVAL`은 없다: 이미 올린 digest의 `EVALSHA`만 닿는다. `+time`을 주는 이유: rate-limit·idempotency script가 `redis.call('TIME')`으로 서버 시계를 읽는데, `TIME`은 어떤 데이터 범주(`@read`/`@write`)에도 없다. 없으면 그런 script가 모두 ACL 오류로 실패한다. 기동 때의 SCRIPT 확인이 `TIME`을 돌려서, 이 권한이 빠진 템플릿은 기동에서 실패한다 | +| `raw-gateway.acl` | `RAW_GATEWAY` | catalog가 `RAW_ONLY`로 분류한 명령만, 그 밖에는 없다 | +| `lane-fixture-accounts.acl` | – | lane이 읽는 파일(Redis는 `aclfile` 하나만 받는다): `user default off`, 이 표의 역할별 계정 넷, lane 전용 계정 셋 — `ca-skeleton-replication`(replica 동기화)과 `ca-skeleton-sentinel`(replicated·sentinel 구성용), `ca-skeleton-cluster-bootstrap`(`+@all`, cluster lane의 slot을 만든다). 배포 파일이 아니다 | +| `admin-readonly.acl` | `ADMIN_READONLY` | 읽기 전용 진단. 파괴적인 짝 명령은 모두 여기서 막고 명령 정책 catalog에서도 막는다 — 같은 규칙에 서로 독립인 통제 둘 | +| `sentinel-accounts.acl` | – | sentinel 프로세스용 계정(`ca-skeleton-sentinel-client`, `ca-skeleton-sentinel-peer`, `ca-skeleton-sentinel-operator`). 지금 이 파일을 `aclfile`로 읽는 compose 파일은 없다 | -## Who loads `lane-fixture-accounts.acl` +## 누가 `lane-fixture-accounts.acl`을 읽나 -The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the -application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in -`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's -`redis` service (root `compose.yaml`). They all mount this directory read-only; neither -keeps a copy, because a second copy of these lines is a second place for a password or a key -pattern to drift. +- Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}` +- Redis를 켜는 애플리케이션 Compose lane: `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의 + `local-redis`, `all-adapters` +- 개발 환경의 `redis` 서비스(루트 `compose.yaml`) -The Compose lanes connect the application as `ca-skeleton-application` and -`ca-skeleton-application-advanced`, through `secret://@environment/` references -whose variables carry the fixture passwords above. They run with the Redis namespace environment -`prod`, because every account here is fenced to `~prod:*`. `scripts/verify-compose-profile-contracts.sh` -compares each Redis lane's references, passwords and namespace with the account lines in this file, -so changing a password or a key pattern here without the lanes fails that check rather than the -lane's first command. +모두 이 폴더를 읽기 전용으로 마운트한다. 복사본을 두지 않는다. 이 줄들의 두 번째 사본은 비밀번호나 key +패턴이 따로 어긋날 두 번째 자리다. + +Compose lane은 애플리케이션을 `ca-skeleton-application`과 `ca-skeleton-application-advanced`로 연결한다. +연결은 `secret://@environment/` 참조를 거치고, 그 변수가 위 fixture 비밀번호를 가진다. +여기의 모든 계정이 `~prod:*`로 묶여 있어서, lane은 Redis namespace 환경을 `prod`로 두고 돈다. +`scripts/verify-compose-profile-contracts.sh`가 Redis lane마다 참조·비밀번호·namespace를 이 파일의 계정 줄과 +비교한다. 그래서 lane을 고치지 않고 여기의 비밀번호나 key 패턴만 바꾸면, lane의 첫 명령이 아니라 그 검사가 +실패한다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 8a5aa7f4..a2395d6d 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -5,8 +5,6 @@ # - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다. # 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다. -language compose/keycloak/README.md -language compose/redis/acl/README.md language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md language docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md language docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md From 5a8414a371bdd35eec93ff3c6bfbfdc122c1e985 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 05/12] =?UTF-8?q?docs(agents):=20=EC=A7=80=EC=9A=B4=20buil?= =?UTF-8?q?d-tools=20=EA=B2=BD=EB=A1=9C=20=EB=8C=80=EC=8B=A0=20=EC=A0=9C?= =?UTF-8?q?=EA=B1=B0=20=ED=91=9C=EB=A5=BC=20=EA=B0=80=EB=A6=AC=ED=82=A8?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `AGENTS.md`가 지운 `src/build-tools/`를 인라인 코드 경로로 적어 참조 검사 예외에 남아 있다. 고른 방법: 경로 대신 이름 `build-tools`와 그 삭제를 적은 `docs/capability-status.md` 「제거된 코드」를 가리킨다. 그 표에 이미 build-tools included build 삭제 행이 있다. 검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0. --- AGENTS.md | 2 +- scripts/check-docs-exceptions.txt | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce0f3085..3ae9a897 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,7 +81,7 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. - `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 - `ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다. + `ca.config-contract`다. 옛 included build `build-tools`는 지웠다(`docs/capability-status.md` 「제거된 코드」). - `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index a2395d6d..8a2449b2 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -176,7 +176,6 @@ language src/platforms/optional-build/README.md language src/shared-contract/CLAUDE.md # 참조: 지금 트리·registry에 없는 경로. 고치거나 「> 이력」 인용 블록으로 옮기면 지운다. -reference AGENTS.md src/build-tools/ reference docs/mongodb/consumer-leaf-guide.md :adapter:outbound:persistence-note:check reference docs/web/http-contract.md docs/architecture/backend-api-and-server-state-contract.md reference docs/work/operate.md :a:test From b3121a8626d5a2d92e3dfd3a8e399b598a7ca68a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 06/12] =?UTF-8?q?docs(work):=20--rerun=20=EC=98=88?= =?UTF-8?q?=EC=8B=9C=EB=A5=BC=20=EC=8B=A4=EC=A0=9C=20Gradle=20=EA=B2=BD?= =?UTF-8?q?=EB=A1=9C=EB=A1=9C=20=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/work/operate.md`의 `--rerun` 예시가 `:a:test`·`:b:test`라 registry에 없는 Gradle 경로로 참조 검사 예외에 있다. 고른 방법: 실제 leaf `:domain-core:test`·`:application-core:test`로 바꾼다. 뜻은 같다. 검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0. --- docs/work/operate.md | 2 +- scripts/check-docs-exceptions.txt | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/work/operate.md b/docs/work/operate.md index 9487fe83..0fa9b782 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -137,5 +137,5 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다. - 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다. -- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:a:test --rerun :b:test --rerun`). `ci` 같은 집계 태스크는 새 worktree에서 `--no-build-cache`로 돌린다([reference/gates.md](reference/gates.md) 3절). +- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:domain-core:test --rerun :application-core:test --rerun`). `ci` 같은 집계 태스크는 새 worktree에서 `--no-build-cache`로 돌린다([reference/gates.md](reference/gates.md) 3절). - 커밋하고 push한 뒤 desktop에서 돌려, 결과를 커밋 본문에 못 넣는다. push 전에 패치로 검증한다(4.1절). diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 8a2449b2..255664ef 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -178,8 +178,6 @@ language src/shared-contract/CLAUDE.md # 참조: 지금 트리·registry에 없는 경로. 고치거나 「> 이력」 인용 블록으로 옮기면 지운다. reference docs/mongodb/consumer-leaf-guide.md :adapter:outbound:persistence-note:check reference docs/web/http-contract.md docs/architecture/backend-api-and-server-state-contract.md -reference docs/work/operate.md :a:test -reference docs/work/operate.md :b:test # 숫자: 정본(src/gradle/libs.versions.toml, registry)이 정하는 값을 복사한 곳. 정본을 가리키게 고치면 지운다. number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 From 12d3f398936edfaa80cf706ae7680eab9998fddb Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 07/12] =?UTF-8?q?docs(manual):=20=EC=83=9D=EC=84=B1=20?= =?UTF-8?q?=EB=AA=85=EB=A0=B9=20=EC=99=95=EB=B3=B5=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EC=9D=98=20leaf=20=EA=B0=9C=EC=88=98=20=EB=8C=80=EC=8B=A0=20?= =?UTF-8?q?=EC=9D=B4=EB=A6=84=EC=9D=84=20=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/manual/01-generator.md`가 「./gradlew 5 leaf check」로 leaf 개수를 복사해 숫자 검사 예외에 있다. 고른 방법: `scripts/verify-feature-scaffold.sh`가 실제로 돌리는 leaf 이름(domain-core, application-core, identifier, web, app-bootstrap)을 쓴다. 검증: `python3 scripts/check-docs.py` rc=0. --- docs/manual/01-generator.md | 2 +- scripts/check-docs-exceptions.txt | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/manual/01-generator.md b/docs/manual/01-generator.md index fe9a0c8e..51adb4c1 100644 --- a/docs/manual/01-generator.md +++ b/docs/manual/01-generator.md @@ -64,7 +64,7 @@ verify-feature-scaffold.sh -> new-feature.sh Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀) -> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어) -> 생성 파일이 있는지 확인 - -> ./gradlew 5 leaf check + architectureCheck + -> 생성물이 닿는 leaf(domain-core, application-core, identifier, web, app-bootstrap) check + architectureCheck -> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인 -> 임시 디렉터리 삭제 ``` diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 255664ef..d3976e00 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -185,7 +185,6 @@ number docs/httpclient/repository-adaptation.md 19 leaf number docs/httpclient/repository-adaptation.md Spring Boot 4.0.8 number docs/jpa/repository-adaptation.md 19 leaf number docs/jpa/repository-adaptation.md Spring Boot 4.0.8 -number docs/manual/01-generator.md 5 leaf number docs/mongodb/repository-adaptation.md 19 leaf number docs/mongodb/repository-adaptation.md Spring Boot 4.0.8 number src/adapter/inbound/graphql/CLAUDE.md Spring Boot 4.0.0 From 6fa4f825f2ada0b64ee3945ad86349bc01111cf5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH 08/12] =?UTF-8?q?ci(links):=20=EA=B8=B0=EB=A1=9D=20?= =?UTF-8?q?=EC=95=88=EC=9D=98=20=EC=A3=BD=EC=9D=80=20=EC=99=B8=EB=B6=80=20?= =?UTF-8?q?=EB=A7=81=ED=81=AC=20=EB=84=B7=EC=9D=84=20lychee=20=EC=A0=9C?= =?UTF-8?q?=EC=99=B8=20=EB=AA=A9=EB=A1=9D=EC=97=90=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: lychee가 기록 문서 안의 외부 링크 404 넷으로 실패한다(mongodb write-concern, aws credentials-chain `.html/`, aws SES SendEmail `.html/`, spring-graphql 1.3 request-execution). 넷 모두 `docs/design`·`docs/reviews` 안에 있고, 기록 본문은 고치지 않는다. 고른 방법: 저장소 루트에 `.lycheeignore`를 두고 그 네 URL만 `^…$`로 묶은 정규식으로 뺀다. lychee는 실행 위치의 `.lycheeignore`를 읽으므로 workflow를 고치지 않아도 된다. `scripts/check-repo-layout.py` 허용 목록에 이 파일을 더한다. 버린 대안: - `lychee.toml`의 `exclude_path`로 기록 폴더를 통째로 빼기. 기록 안 상대 링크까지 검사에서 빠진다. - workflow에 `--exclude` 인자 더하기. workflow는 CI 재편 작업이 고친다. 위험·한계: 같은 URL을 살아 있는 문서가 쓰면 거기서도 검사하지 않는다. 끝의 `/`가 없는 aws 두 URL은 살아 있어 빼지 않았다. 검증: `python3 scripts/check-repo-layout.py` rc=0. 정규식이 네 URL에만 맞고 `/` 없는 aws 두 URL에는 맞지 않는 것을 Python `re`로 확인했다. --- .lycheeignore | 13 +++++++++++++ scripts/check-repo-layout.py | 1 + 2 files changed, 14 insertions(+) create mode 100644 .lycheeignore diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 00000000..82f08cd2 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,13 @@ +# lychee 링크 검사가 건너뛸 URL. 한 줄에 정규식 하나다. lychee가 저장소 루트에서 이 파일을 읽는다. +# 기록 문서 docs/design, docs/history, docs/reviews 안의 죽은 외부 링크만 여기에 더한다. +# 기록 본문은 고치지 않으니 링크 대신 이 목록을 고친다. 살아 있는 문서의 죽은 링크는 문서를 고친다. +# 규칙은 docs/README.md 문서 검사 절이다. + +# docs/design/2026-07-26-production-capability-platform-design.md +^https://www\.mongodb\.com/docs/manual/reference/write-concern/index\.html$ +# docs/design/2026-07-28-notification-production-capability-design.md +^https://docs\.aws\.amazon\.com/ses/latest/APIReference-V2/API_SendEmail\.html/$ +# docs/design/2026-07-28-notification-production-capability-design.md +^https://docs\.aws\.amazon\.com/sdk-for-java/latest/developer-guide/credentials-chain\.html/$ +# docs/reviews/2026-08-14-graphql-module-code-review.md +^https://docs\.spring\.io/spring-graphql/reference/1\.3/request-execution\.html$ diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py index 805adb87..d05fb1b3 100755 --- a/scripts/check-repo-layout.py +++ b/scripts/check-repo-layout.py @@ -47,6 +47,7 @@ ROOT_ALLOWED = { # 파일 ".gitattributes": "Git 설정", ".gitignore": "Git 설정", + ".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다", ".tool-versions": "JDK 버전 고정", ".trivyignore.yaml": "취약점 검사 예외", "AGENTS.md": "규칙 정본", From d8afffce9e960b1706637aa0d8e8d5ef4d2bc3c2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:19 +0900 Subject: [PATCH 09/12] =?UTF-8?q?docs(docs):=20docs/README=EB=A5=BC=20?= =?UTF-8?q?=EB=AA=A8=EB=93=A0=20=EB=AC=B8=EC=84=9C=20=ED=8F=B4=EB=8D=94?= =?UTF-8?q?=EB=A5=BC=20=EB=8D=AE=EB=8A=94=20=EC=A7=80=EB=8F=84=EB=A1=9C=20?= =?UTF-8?q?=EB=8B=A4=EC=8B=9C=20=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/README.md`의 폴더 표에 `ci-cd/`, `compatibility/`, `mongo/`, `objectstorage/`, `observability/`, `roadmap/`, `testing/`, `upgrade/`, `web/`, `websocket/`가 없다. 폴더 밖 문서 둘(`capability-status.md`, `storage-capability-boundary.md`)도 없다. 처음 온 사람이 문서를 찾을 수 없다. 고른 방법: 「문서 지도」 절 하나에 목적별 표(매뉴얼, 계약과 스냅숏, 영역 운영 문서, 운영과 전달, 결정 기록, 설계와 기록, 폴더 밖 문서)를 두고, 표의 첫 칸에 `폴더/`를 적는다. 다음 커밋의 `map` 검사가 이 첫 칸을 읽는다. 「문서 검사」 절에 `map`·`readme` 검사, resources 폴더 제외, `.lycheeignore` 규칙을 적는다. 위험·한계: 알림 ADR은 지금 위치 `notification/adr/`로 적었다. 옮기는 변경이 지도도 고친다. 검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py --links docs/README.md` 깨진 링크 0. --- docs/README.md | 123 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 88 insertions(+), 35 deletions(-) diff --git a/docs/README.md b/docs/README.md index 54351e62..e43e5876 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,60 +1,108 @@ # docs -저장소의 모든 문서는 이 디렉터리 아래에 있다. 규칙은 둘이다: 어떤 문서를 어디에 두는지(아래 표), -문서의 수명에 따라 무엇을 어떤 언어로 고치는지(「문서 수명과 언어」). 파일 목록은 디렉터리를 직접 읽는다. -개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다. +저장소의 모든 문서는 이 폴더 아래에 있다. 이 README는 두 가지를 정한다. -## 어댑터별 운영 문서 +- 어떤 문서가 어느 폴더에 있나: 아래 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다. +- 문서의 수명에 따라 무엇을 어떤 언어로 고치나: 「문서 수명과 언어」. -각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고, -`docs/httpclient/` 는 `scripts/verify-httpclient-docs.py` 가 코드에서 뽑은 이름과 대조한다. +파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다. -| 디렉터리 | 대상 | +## 문서 지도 + +- 표의 첫 칸이 폴더다(`docs/` 기준 경로). +- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다. +- `python3 scripts/check-docs.py`의 `map` 검사가 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(「문서 검사」). + +### 매뉴얼 + +일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다. + +| 폴더 | 무엇 | | --- | --- | -| `fileserver/` | 파일 서버 어댑터 | -| `httpclient/` | HTTP 클라이언트 플랫폼 | -| `jpa/` | JPA·PostgreSQL 영속성 | -| `messaging/` | 메시징 어댑터 | -| `mongodb/` | MongoDB 문서 영속성 (`advanced/`, `runbooks/` 포함) | -| `notification/` | 알림 전달 플랫폼 (`adr/` 포함) | -| `redis/` | Redis 캐시·세션 | - -## 횡단 문서 - -| 디렉터리 | 대상 | -| --- | --- | -| `adr/` | 아키텍처 결정 기록 | -| `architecture/` | 공개 API 표면 스냅숏 | -| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 | +| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 | | `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` | -| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT | -| `reviews/` | 모듈 코드 리뷰 결과 | -| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) | -| `security/` | 공개 경로 스냅숏 | +| `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 | -## 설계와 기록 +### 계약과 스냅숏 + +코드와 테스트가 대조하는 정본이다. 바꾸면 공개 계약이 바뀔 수 있다(`work/README.md` 2절). + +| 폴더 | 무엇 | +| --- | --- | +| `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 | +| `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 | +| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 | +| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 | +| `observability/` | 구조화 로그 필드 사전 | +| `compatibility/` | gRPC 플랫폼 지원 매트릭스(무엇에 대해 인증했고 무엇은 지켜보기만 하나) | + +### 영역 운영 문서 + +capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마이그레이션이다. 코드와 같은 변경에서 고친다. +`httpclient/`는 `scripts/verify-httpclient-docs.py`가 코드에서 뽑은 이름과 대조한다. + +| 폴더 | 무엇 | +| --- | --- | +| `fileserver/` | 파일 서버 | +| `httpclient/` | 외부 HTTP 호출(HTTP client 플랫폼) | +| `jpa/` | JPA·PostgreSQL 영속성 | +| `messaging/` | 메시징 adapter | +| `mongodb/` | MongoDB 문서 영속성 | +| `mongodb/advanced/` | MongoDB 고급 기능(암호화, 멀티 테넌시, 샤딩). 설정 키가 아니라 라이브러리 API로 켠다 | +| `mongodb/runbooks/` | MongoDB 장애 대응 | +| `mongo/` | MongoDB 영속성 설정 예시 파일(Spring이 읽지 않는 예시) | +| `notification/` | 알림 전달 플랫폼 | +| `objectstorage/` | 객체 저장소의 설정 필드와 env 이름 표(`env-fields.yaml`) | +| `redis/` | Redis 캐시·세션 | +| `websocket/` | WebSocket handler 장애 대응 | + +### 운영과 전달 + +| 폴더 | 무엇 | +| --- | --- | +| `runbooks/` | 오류 코드별 장애 대응 런북(`runbooks/template.md` 형식) | +| `ci-cd/` | CI/CD 경계: 검증·빌드(CI)와 배포(CD)의 경계, 템플릿과 파생 서비스가 각각 돌릴 검증 | +| `upgrade/` | 파생 서비스용 변경 안내: 템플릿 변경을 받을 때 서비스가 할 일 | +| `roadmap/` | 아직 구현하지 않은 다음 단계와 그 조건 | + +### 결정 기록 + +| 폴더 | 무엇 | +| --- | --- | +| `adr/` | 아키텍처 결정 기록(ADR) | +| `notification/adr/` | 알림 플랫폼의 결정 기록 | + +### 설계와 기록 설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다. -| 디렉터리 | 대상 | +| 폴더 | 무엇 | | --- | --- | | `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` | | `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` | | `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 | | `history/evidence/` | 작업 단계별 증거·체크포인트 | | `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 | +| `reviews/` | 코드 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나 | -`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을 -남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서 +`history/packages/<어댑터>/`는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을 +남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/`과 `history/plans/`에 있으므로 이 폴더에서 문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다. -`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은 +`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256`은 납품 당시 바이트의 해시다. 계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로 조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는 -`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라 +`module-mapping.md`가 기록한다. 계획서를 나중에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다. +### 폴더 밖 문서 + +| 문서 | 무엇 | +| --- | --- | +| [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) | +| [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 | + ## 문서 수명과 언어 규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고, @@ -118,11 +166,12 @@ - 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는 registry(`src/config/architecture/modules.json`)를 가리킨다. - 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이 - 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다. + 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, + `readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다. ## 문서 검사 -`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가 +`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여섯을 본다. PR마다 workflow `docs-check`가 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 문서를 낡게 만든다. @@ -132,13 +181,17 @@ | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | | `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 | +| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | +| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | - 하나만 돌리기: `python3 scripts/check-docs.py --only head`. +- 소스 세트의 resources 폴더 아래 `.md`(`src/**/src/<세트>/resources/`)는 테스트가 읽는 입력이라 문서로 보지 않는다. - 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서 더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다. - 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`. -- 마크다운 상대 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. +- 마크다운 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. + 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다. ## 여기에 없는 것 From f56a100528849ee2f7b98b07b2205a3759920cda Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:19 +0900 Subject: [PATCH 10/12] =?UTF-8?q?ci(docs):=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=A7=80=EB=8F=84=EC=99=80=20=EB=A3=A8=ED=8A=B8=20README=20?= =?UTF-8?q?=EC=A0=88=EC=9D=84=20=EB=AC=B8=EC=84=9C=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EA=B0=80=20=EB=B3=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 「모든 문서 폴더가 `docs/README.md` 지도에 있다」와 「루트 README가 정해진 절을 가진다」(design-docs `conventions/docs-system.md` 7절 K5·K6)를 아무것도 지키지 않는다. 테스트 자원 `broken-readme.md`(일부러 깨뜨린 입력)를 살아 있는 문서로 보고 언어 검사 예외에 둔다. 고른 방법: `scripts/check-docs.py`에 검사 둘을 더한다. docs-check workflow가 인자 없이 돌리므로 PR에서 바로 실패로 돈다. - `map`: `docs/` 바로 아래 폴더가 모두 지도 표의 첫 칸에 있어야 한다. 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. `.md`가 없는 폴더(스냅숏, yaml)도 본다. 지도에 있지만 없는 폴더도 실패다. - `readme`: 첫 줄 `# 제목`, 그 아래 한 문단, `README_SECTIONS`의 `##` 절이 그 순서로 있어야 한다. 사이에 다른 절은 있어도 된다. - 소스 세트 resources 폴더 아래 `.md`(`/src/<세트>/resources/`)는 문서로 보지 않는다. 그래서 `broken-readme.md` 예외 줄을 지운다. 버린 대안: 지도 폴더를 모든 깊이까지 요구하기. 리뷰 라운드 폴더, 납품 패키지 폴더마다 행이 생겨 지도가 목록이 된다. 절을 정확히 일곱 개만 허용하기. 서비스가 절을 더할 수 없게 된다. 위험·한계: `FROZEN` 지문은 건드리지 않았다. leaf·family README 절 검사(K6 뒷부분)와 파일 이름 규칙·실행 산출물 검사(K5 뒷부분)는 넣지 않았다. 검증: - `python3 -m unittest discover -s scripts/tests` 65건 rc=0(새 시험 22건). - 판정 조건 18개를 하나씩 끈 사본마다 자기 시험이 실패했다(rc=1). - `python3 scripts/check-docs.py` rc=0. --- scripts/check-docs-exceptions.txt | 1 - scripts/check-docs.py | 146 ++++++++++++++++++++++++++++-- scripts/tests/test_check_docs.py | 121 +++++++++++++++++++++++++ 3 files changed, 261 insertions(+), 7 deletions(-) diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index d3976e00..1d81c4a0 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -166,7 +166,6 @@ language src/adapter/outbound/redis-sdk/README.md language src/adapter/outbound/redis-sdk/compose/README.md language src/adapter/outbound/support/CLAUDE.md language src/app-bootstrap/CLAUDE.md -language src/app-bootstrap/src/test/resources/developer-experience/broken-readme.md language src/application-core/CLAUDE.md language src/build-logic/README.md language src/composition/outbox-relay/CLAUDE.md diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 3e482356..c5736f85 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""문서 검사 넷: 언어, 기록의 머리 블록, 참조, 복사한 숫자. 하나라도 걸리면 rc=1이다. +"""문서 검사 여섯: 언어, 기록의 머리 블록, 참조, 복사한 숫자, 문서 지도, 루트 README 절. 하나라도 걸리면 rc=1이다. 규칙의 정본은 design-docs `conventions/docs-system.md`이고, 이 repo의 적용은 `docs/README.md` 「문서 수명과 언어」다. 이 스크립트는 그 규칙 중 기계로 볼 수 있는 것만 본다. @@ -15,6 +15,14 @@ registry에 있다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수. + map docs/README.md의 문서 지도가 지금 있는 문서 폴더를 모두 덮는다. 지도는 표의 첫 칸에 적은 + `폴더/`다. docs/ 바로 아래 폴더가 대상이고, 파일 없이 폴더만 가진 묶음 폴더(history/)는 + 그 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다. + readme 루트 README.md가 정해진 절을 정해진 순서로 가진다: 첫 줄의 제목, 그 아래 한 문단, 그리고 + README_SECTIONS의 ## 제목. 그 사이에 다른 절이 있어도 된다. + +소스 세트의 resources 폴더 아래 .md(src/**/src/<세트>/resources/)는 시험 입력이나 실행 자원이라 문서로 +보지 않는다. 예외 목록(scripts/check-docs-exceptions.txt)은 줄기만 한다. - 목록의 줄은 아래 FROZEN(2026-11-07 기준선의 지문)에 있어야 한다. 목록에 새 줄을 더하면 실패한다. @@ -44,7 +52,7 @@ from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt" REGISTRY_FILE = "src/config/architecture/modules.json" -CHECKS = ("language", "head", "reference", "number") +CHECKS = ("language", "head", "reference", "number", "map", "readme") # 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다. RECORD_KINDS = [ @@ -80,6 +88,16 @@ HEAD_FIELDS = ("상태", "작성일", "요약", "현재 정본") HEAD_OPTIONAL = ("대체", "대체됨") HEAD_SEARCH_LINES = 20 +# 문서가 아닌 .md: 소스 세트의 resources 폴더 아래 파일은 테스트가 읽는 입력이나 실행 자원이다. +NOT_DOCUMENT = re.compile(r"/src/[A-Za-z]+/resources/") + +# 문서 지도(K5)와 루트 README(K6). 절 목록의 정본은 design-docs `conventions/docs-system.md` 6.1절이다. +MAP_FILE = "docs/README.md" +DOCS_ROOT = "docs/" +README_FILE = "README.md" +README_SECTIONS = ("프로젝트 구조", "시작하기", "기능 켜고 끄기", "문서 지도", "검증", "새 서비스로 시작하기", + "규칙과 기여") + # 2026-11-07 기준선. 예외 목록의 줄마다 sha256 앞 16자. 늘리지 않는다(맨 위 설명). FROZEN: frozenset[str] = frozenset({ "0176963415821bbe", "01984fd96d72b997", "02810bf817c5098f", "02f77e3cc483fa7b", "05fff3c3ff8a5c9a", @@ -179,15 +197,19 @@ def fingerprint(line: str) -> str: return hashlib.sha256(line.encode("utf-8")).hexdigest()[:16] -def tracked_markdown(root: Path) -> list[str]: - """Markdown files git knows or would add: tracked plus untracked files that are not ignored.""" +def tracked_files(root: Path, pathspec: str) -> list[str]: + """Files git knows or would add: tracked plus untracked files that are not ignored.""" result = subprocess.run( - ["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*.md"], + ["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", pathspec], capture_output=True, check=True) names = {name for name in result.stdout.decode("utf-8").split("\0") if name} return sorted(name for name in names if (root / name).is_file()) +def tracked_markdown(root: Path) -> list[str]: + return [name for name in tracked_files(root, "*.md") if not NOT_DOCUMENT.search(name)] + + def record_kind(path: str) -> str | None: for prefix, kind in RECORD_KINDS: if path.startswith(prefix): @@ -485,7 +507,119 @@ def check_number(root: Path, files: list[str]) -> list[Problem]: return problems -RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number} +def required_folders(paths: list[str]) -> set[str]: + """지도에 있어야 하는 폴더(`docs/` 기준): docs/ 바로 아래 폴더. 파일 없이 폴더만 가진 묶음 폴더는 + 그 바로 아래 폴더가 대신한다(history/ → history/plans/ 등). 더 깊이는 내려가지 않는다.""" + def children(paths: list[str]) -> dict[str, list[str]]: + found: dict[str, list[str]] = {} + for path in paths: + name, slash, rest = path.partition("/") + if slash: + found.setdefault(name, []).append(rest) + return found + + folders: set[str] = set() + for name, inside in children(paths).items(): + if any("/" not in path for path in inside): + folders.add(f"{name}/") + else: + folders |= {f"{name}/{child}/" for child in children(inside)} + return folders + + +def outside_code(lines: list[str]) -> list[tuple[int, str]]: + """(줄 번호, 줄) — 코드 블록 밖의 줄만.""" + kept, fence = [], None + for number, line in enumerate(lines, start=1): + match = FENCE.match(line) + if fence: + if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence): + fence = None + continue + if match: + fence = match.group(1) + continue + kept.append((number, line)) + return kept + + +def map_entries(lines: list[str]) -> list[tuple[int, str]]: + """(줄 번호, `docs/` 기준 폴더) — 코드 블록 밖 표 행의 첫 칸에 인라인 코드로 적은 `폴더/`.""" + entries = [] + for number, line in outside_code(lines): + cells = line.strip().split("|") + if not line.strip().startswith("|") or len(cells) < 3: + continue + for found in INLINE.finditer(cells[1]): + token = found.group(0).strip("`").strip() + if token.startswith(DOCS_ROOT): + token = token[len(DOCS_ROOT):] + if token.endswith("/") and not PLACEHOLDER.search(token): + entries.append((number, token)) + return entries + + +def check_map(root: Path, files: list[str]) -> list[Problem]: + del files # 지도는 .md만이 아니라 docs/ 아래 모든 파일의 폴더를 본다(스냅숏·yaml만 있는 폴더도 있다). + if not (root / MAP_FILE).is_file(): + return [Problem("map", MAP_FILE, "", "문서 지도가 없다")] + documents = [path[len(DOCS_ROOT):] for path in tracked_files(root, DOCS_ROOT)] + entries = map_entries((root / MAP_FILE).read_text(encoding="utf-8").split("\n")) + mapped = {folder for _, folder in entries} + problems = [Problem("map", MAP_FILE, folder, f"지도에 없는 문서 폴더다: {DOCS_ROOT}{folder}. 지도에 행을 더한다") + for folder in sorted(required_folders(documents) - mapped)] + for number, folder in entries: + if not any(path.startswith(folder) for path in documents): + problems.append(Problem("map", MAP_FILE, folder, f"지도의 폴더가 없다: {DOCS_ROOT}{folder}", number)) + return problems + + +def headings(lines: list[str]) -> list[tuple[int, int, str]]: + """(줄 번호, 수준, 제목) — 코드 블록 밖의 # 제목.""" + found = [] + for number, line in outside_code(lines): + heading = re.match(r"^(#{1,6})\s+(.+?)\s*#*\s*$", line) + if heading: + found.append((number, len(heading.group(1)), heading.group(2))) + return found + + +def check_readme(root: Path, files: list[str]) -> list[Problem]: + del files + + def fail(key: str, message: str, line: int = 0) -> None: + problems.append(Problem("readme", README_FILE, key, message, line)) + + problems: list[Problem] = [] + if not (root / README_FILE).is_file(): + fail("", "루트 README가 없다") + return problems + lines = (root / README_FILE).read_text(encoding="utf-8").split("\n") + found = headings(lines) + first = next((number for number, line in enumerate(lines, start=1) if line.strip()), 0) + if not found or found[0][:2] != (first, 1): + fail("제목", "첫 줄은 `# 제목`이다", first) + else: + sections = [number for number, level, _ in found if level == 2] + intro = lines[first:sections[0] - 1] if sections else lines[first:] + if not any(line.strip() and not line.lstrip().startswith(("#", "|", "```", "~~~")) for line in intro): + fail("소개", "제목 아래, 첫 ## 절 앞에 무엇인지·누가 쓰나 한 문단을 둔다", first) + positions = {} + for number, level, title in found: + if level == 2 and title in README_SECTIONS and title not in positions: + positions[title] = number + for title in README_SECTIONS: + if title not in positions: + fail(title, f"「## {title}」 절이 없다. 절 목록은 {' → '.join(README_SECTIONS)}다") + present = [title for title in README_SECTIONS if title in positions] + for before, after in zip(present, present[1:]): + if positions[before] > positions[after]: + fail(after, f"「## {after}」 절은 「## {before}」 절 뒤에 온다", positions[after]) + return problems + + +RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number, + "map": check_map, "readme": check_readme} def read_exceptions(text: str) -> list[str]: diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index 64ebe46e..6638bfda 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -246,6 +246,127 @@ class NumberTest(RepositoryTestCase): self.assertEqual(self.errors_for("leaf 하나를 고른다.\n"), []) +class ScopeTest(RepositoryTestCase): + def test_markdown_under_a_source_set_resources_folder_is_not_a_document(self) -> None: + self.repo.write("src/app/src/test/resources/fixtures/broken-readme.md", "# Broken\n\n" + ENGLISH * 3) + self.assertEqual(self.repo.run(("language",)), []) + + def test_markdown_beside_a_source_set_is_still_a_document(self) -> None: + self.repo.write("src/app/src/test/README.md", "# Tests\n\n" + ENGLISH * 3) + self.assertFailsWith(self.repo.run(("language",)), "src/app/src/test/README.md: 영어 문서다") + + +def table(*rows: str) -> str: + return "| 폴더 | 무엇 |\n| --- | --- |\n" + "".join(f"| {row} | 설명 |\n" for row in rows) + + +class MapTest(RepositoryTestCase): + def errors_for(self, text: str) -> list[str]: + self.repo.write(check_docs.MAP_FILE, "# docs\n\n" + KOREAN + text) + return self.repo.run(("map",)) + + def test_a_map_that_names_every_folder_passes(self) -> None: + self.repo.write("docs/jpa/guide.md", KOREAN) + self.repo.write("docs/history/plans/2026-08-11-x-plan.md", KOREAN) + checks = "| 검사 | 보는 것 |\n| --- | --- |\n| `language` | 언어 |\n" + self.assertEqual(self.errors_for(table("`jpa/`", "`history/plans/`") + "\n" + checks), []) + + def test_a_folder_missing_from_the_map_fails(self) -> None: + self.repo.write("docs/redis/operations.md", KOREAN) + self.assertFailsWith(self.errors_for(table()), "지도에 없는 문서 폴더다: docs/redis/") + + def test_a_folder_without_markdown_must_be_mapped_too(self) -> None: + self.repo.write("docs/security/public-paths-snapshot.txt", "/api/healthcheck\n") + self.assertFailsWith(self.errors_for(table()), "지도에 없는 문서 폴더다: docs/security/") + + def test_a_folder_that_only_holds_folders_is_covered_by_its_subfolders(self) -> None: + self.repo.write("docs/history/plans/2026-08-11-x-plan.md", KOREAN) + self.repo.write("docs/history/study/x.md", KOREAN) + errors = self.errors_for(table("`history/`", "`history/plans/`")) + self.assertFailsWith(errors, "지도에 없는 문서 폴더다: docs/history/study/") + self.assertFalse(any("docs/history/plans/" in error for error in errors), errors) + + def test_folders_below_the_mapped_level_need_no_row(self) -> None: + self.repo.write("docs/history/packages/jpa/README.md", KOREAN) + self.repo.write("docs/mongodb/advanced/sharding.md", KOREAN) + self.repo.write("docs/mongodb/guide.md", KOREAN) + self.assertEqual(self.errors_for(table("`history/packages/`", "`mongodb/`")), []) + + def test_a_mapped_folder_that_does_not_exist_fails(self) -> None: + self.assertFailsWith(self.errors_for(table("`gone/`")), "지도의 폴더가 없다: docs/gone/") + + def test_a_folder_named_outside_the_first_cell_does_not_count(self) -> None: + self.repo.write("docs/redis/operations.md", KOREAN) + self.assertFailsWith(self.errors_for(table("운영") + "| 캐시 | `redis/` |\n"), + "지도에 없는 문서 폴더다: docs/redis/") + + def test_a_folder_inside_a_code_block_does_not_count(self) -> None: + self.repo.write("docs/redis/operations.md", KOREAN) + self.assertFailsWith(self.errors_for("```text\n" + table("`redis/`") + "```\n"), + "지도에 없는 문서 폴더다: docs/redis/") + + def test_a_folder_may_be_written_from_the_repository_root(self) -> None: + self.repo.write("docs/redis/operations.md", KOREAN) + self.assertEqual(self.errors_for(table("`docs/redis/`")), []) + + def test_a_placeholder_folder_is_not_an_entry(self) -> None: + self.assertEqual(self.errors_for(table("`history/packages/<어댑터>/`")), []) + + def test_a_repository_without_the_map_fails(self) -> None: + self.assertFailsWith(self.repo.run(("map",)), "문서 지도가 없다") + + +def readme(sections: tuple[str, ...] = check_docs.README_SECTIONS, title: str = "# 템플릿", + intro: str = "이 저장소가 무엇이고 누가 쓰는지 쓴 한 문단이다.") -> str: + parts = [title, "", intro, ""] if intro else [title, ""] + for section in sections: + parts += [section if section.startswith("#") else f"## {section}", "", KOREAN] + return "\n".join(parts) + + +class ReadmeTest(RepositoryTestCase): + def errors_for(self, text: str) -> list[str]: + self.repo.write(check_docs.README_FILE, text) + return self.repo.run(("readme",)) + + def test_every_section_in_order_passes(self) -> None: + self.assertEqual(self.errors_for(readme()), []) + + def test_other_sections_between_the_required_ones_pass(self) -> None: + sections = check_docs.README_SECTIONS[:2] + ("부록",) + check_docs.README_SECTIONS[2:] + self.assertEqual(self.errors_for(readme(sections)), []) + + def test_each_missing_section_fails(self) -> None: + for missing in check_docs.README_SECTIONS: + with self.subTest(missing=missing): + sections = tuple(section for section in check_docs.README_SECTIONS if section != missing) + self.assertFailsWith(self.errors_for(readme(sections)), f"「## {missing}」 절이 없다") + + def test_sections_out_of_order_fail(self) -> None: + sections = ("시작하기", "프로젝트 구조") + check_docs.README_SECTIONS[2:] + self.assertFailsWith(self.errors_for(readme(sections)), "「## 시작하기」 절은 「## 프로젝트 구조」 절 뒤에 온다") + + def test_a_readme_that_does_not_start_with_a_title_fails(self) -> None: + self.assertFailsWith(self.errors_for(readme(title="템플릿 소개")), "첫 줄은 `# 제목`이다") + self.assertFailsWith(self.errors_for("소개 한 줄\n\n" + readme()), "첫 줄은 `# 제목`이다") + + def test_a_readme_without_an_introduction_fails(self) -> None: + self.assertFailsWith(self.errors_for(readme(intro="")), "한 문단을 둔다") + + def test_a_section_heading_at_another_level_does_not_count(self) -> None: + sections = tuple("### 문서 지도" if section == "문서 지도" else section + for section in check_docs.README_SECTIONS) + self.assertFailsWith(self.errors_for(readme(sections)), "「## 문서 지도」 절이 없다") + + def test_a_section_heading_inside_a_code_block_does_not_count(self) -> None: + sections = tuple(section for section in check_docs.README_SECTIONS if section != "검증") + text = readme(sections) + "\n```markdown\n## 검증\n```\n" + self.assertFailsWith(self.errors_for(text), "「## 검증」 절이 없다") + + def test_a_repository_without_a_readme_fails(self) -> None: + self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다") + + class CommandLineTest(unittest.TestCase): def test_an_unknown_check_is_a_usage_error(self) -> None: self.assertEqual(check_docs.main(["--only", "spelling"]), 2) From 05e2145d22a3db8c3c9b2fa8808f9f0863a8f748 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:24:54 +0900 Subject: [PATCH 11/12] =?UTF-8?q?docs(registries):=20=EB=A0=88=EC=A7=80?= =?UTF-8?q?=EC=8A=A4=ED=8A=B8=EB=A6=AC=20yaml=EC=9D=98=20=EC=84=A4?= =?UTF-8?q?=EB=AA=85=20=EC=B9=B8=EA=B3=BC=20=EC=A3=BC=EC=84=9D=EC=9D=84=20?= =?UTF-8?q?=ED=95=9C=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=98=AE=EA=B8=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 소유자 결정(2026-11-07, design-docs `repo-structure/README.md` 3.2절)은 레지스트리 yaml의 설명 칸을 번역하라고 한다. 지금 값 칸 중 영어 산문은 env-keys `required_when` 7개, metrics `alert_severity_thresholds` 51개, object-storage-readiness `limitations` 15개이고, 주석은 약 940줄이 영어다. 주석 하나는 없는 파일 `docs/notification/configuration.md`를 가리킨다(있는 것은 `configuration-reference.md`). 고른 방법: - 값 칸: 뜻을 그대로 옮기고 속성 이름·지표 이름·연산자·기간(5m, 1h)·식별자는 원문으로 둔다. `required_when`의 `<속성>=<값>` 꼴(공백 없음)은 `RequiredWhenIsEnforcedTest`가 기계로 읽으므로 그대로 두고, 공백이 든 설명 꼴만 옮긴다. 옮긴 값도 공백을 가져 그 테스트가 계속 건너뛴다. - 주석: 파일 머리의 설명 블록과 행마다의 설명·출처 주석을 옮긴다. `# source:`는 `# 출처:`로 바꾸고, 설계 문서에서 따온 인용("...")은 원문으로 둔다. - 그대로 둔 것: `RegistryGovernanceCatalog`가 글자 그대로 비교하는 머리 줄 (`# Schema owner: ...`, object-storage-readiness 머리 넷)과 `# Registry:` 등 메타 줄. - 없는 문서 경로는 `docs/notification/configuration-reference.md`로 고친다. 이 칸을 읽는 테스트(먼저 찾음): - `RegistryGovernanceCatalog`(ContractRegistrySchemaGovernanceTest): 머리 주석 줄을 글자 그대로 본다 — 해당 줄은 바꾸지 않았다. - `RequiredWhenIsEnforcedTest`(redis-runtime): 공백 없는 `required_when`만 조건으로 쓴다. - `SecretsClassificationRegistryTest`: `required_when`이 null인지만 본다. - `MetricsAlertingContractTest`: 경보 키가 `AlertSeverity`로 풀리는지와 값이 비어 있지 않은지만 본다. - `ObjectStorageReadinessRegistryTest`: `limitations`가 비어 있지 않은지만 본다. - `NotificationModeSsotTest`: `name: APP_NOTIFICATION_PLATFORM_MODE` 뒤 첫 `default: `를 찾는다 — 옮긴 주석에 `default: ` 글자를 넣지 않았다. 위험·한계: 행마다의 주석은 설계 문서 ID와 날짜를 그대로 둔다. 남은 영어는 인용과 식별자뿐이다. 검증: 바꾸기 전후 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 값 칸 말고는 같다(주석만 바꾼 파일은 완전히 같다). `python3 scripts/check-docs.py` rc=0. --- docs/registries/capabilities.yaml | 52 +- docs/registries/env-keys.yaml | 1320 ++++++++--------- docs/registries/error-codes.yaml | 162 +- docs/registries/headers.yaml | 40 +- docs/registries/mdc-keys.yaml | 54 +- docs/registries/metrics.yaml | 266 ++-- docs/registries/object-storage-readiness.yaml | 28 +- docs/registries/secrets-classification.yaml | 144 +- 8 files changed, 1002 insertions(+), 1064 deletions(-) diff --git a/docs/registries/capabilities.yaml b/docs/registries/capabilities.yaml index 2fc161d4..157c27b8 100644 --- a/docs/registries/capabilities.yaml +++ b/docs/registries/capabilities.yaml @@ -3,24 +3,24 @@ # Owner branch: feature-repository-access-permission-contract # Last updated: 2026-06-05 # -# Notes -# - capability는 사용자 권한이 아니라 application use case가 infrastructure capability를 -# 사용할 수 있는지에 대한 계약 (feature-repository-access-permission-contract). -# - enforcement default = ArchUnit annotation-based rule. compile-time annotation processor는 -# alternative. runtime AOP는 forbidden. -# - capability 제거는 항상 breaking change. 추가는 additive (registry row 동반 시). -# - annotation 표기 (as-built, F1/F2 reconciled 2026-06-05): 코드 SSOT는 단일 -# `@UseCaseCapability` (TYPE target, typed attribute). 노트 D2/D11의 flat -# `@UseCaseRepositoryAccess(Capability[])` 모델은 superseded. 7 capability ↔ as-built 매핑: +# 읽는 법 +# - capability는 사용자 권한이 아니라, application use case가 인프라 기능을 쓸 수 있는지에 대한 +# 계약이다 (feature-repository-access-permission-contract). +# - 강제(enforcement) 기본값 = annotation을 보는 ArchUnit 규칙. compile-time annotation processor는 +# 대안이다. runtime AOP는 쓰지 않는다. +# - capability를 지우면 언제나 breaking change다. 더하는 것은 additive다(registry 행을 같이 더할 때). +# - annotation 표기 (구현된 모양, F1/F2를 2026-06-05에 맞춤): 코드의 정본은 `@UseCaseCapability` 하나다 +# (TYPE target, 타입이 있는 속성). 노트 D2/D11의 평평한 `@UseCaseRepositoryAccess(Capability[])` +# 모델은 대체됐다. capability와 구현된 속성의 대응: # READ_REPOSITORY/WRITE_REPOSITORY → repositoryAccess, TRANSACTION_REQUIRED → transactionMode, # EXTERNAL_OUTBOUND_ALLOWED → externalOutboundAllowed, SENSITIVE_READ → sensitiveRead, # BULK_WRITE → bulkWrite, CROSS_TENANT_ADMIN → crossTenantAdmin. -# 각 row의 annotation: 필드는 아래에서 as-built 표기로 정합됨. +# 각 행의 annotation: 칸은 아래에서 구현된 표기로 맞췄다. capabilities: - # source: feature-repository-access-permission-contract — 판정 기준 "Required capability: READ_REPOSITORY" - # source: feature-application-port-usecase-contract — "read-only query use case는 readOnly 와 READ_REPOSITORY capability만 선언 가능" + # 출처: feature-repository-access-permission-contract — 판정 기준 "Required capability: READ_REPOSITORY" + # 출처: feature-application-port-usecase-contract — "read-only query use case는 readOnly 와 READ_REPOSITORY capability만 선언 가능" - name: READ_REPOSITORY scope: use_case_method enforcement: archunit @@ -32,8 +32,8 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:read-repository-capability - # source: feature-repository-access-permission-contract — 판정 기준 "Required capability: WRITE_REPOSITORY" - # source: feature-application-port-usecase-contract — "write use case는 transactionMode, idempotency, repositoryAccess를 명시해야 함" + # 출처: feature-repository-access-permission-contract — 판정 기준 "Required capability: WRITE_REPOSITORY" + # 출처: feature-application-port-usecase-contract — "write use case는 transactionMode, idempotency, repositoryAccess를 명시해야 함" - name: WRITE_REPOSITORY scope: use_case_method enforcement: archunit @@ -45,8 +45,8 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:write-repository-capability - # source: feature-repository-access-permission-contract — decisions 2026-05-22 - # "SENSITIVE_READ marker = registry-managed metadata table (entity FQN + field name 단위)" + # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # "SENSITIVE_READ marker = registry-managed metadata table (entity FQN + field name 단위)" - name: SENSITIVE_READ scope: use_case_method enforcement: archunit @@ -58,8 +58,8 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:sensitive-read-capability - # source: feature-repository-access-permission-contract — decisions 2026-05-22 - # "BULK_WRITE threshold = N > 100 또는 batch size > 100. 미만은 일반 WRITE_REPOSITORY로 충분" + # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # "BULK_WRITE threshold = N > 100 또는 batch size > 100. 미만은 일반 WRITE_REPOSITORY로 충분" - name: BULK_WRITE scope: use_case_method enforcement: archunit @@ -71,9 +71,9 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:bulk-write-capability - # source: feature-repository-access-permission-contract — decisions 2026-05-22 - # "TRANSACTION_REQUIRED는 application-port branch의 TransactionPort contract와 연결되어야 하며 Spring @Transactional 직접 import로 충족하지 않음" - # source: feature-application-port-usecase-contract — TransactionPort Contract + # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # "TRANSACTION_REQUIRED는 application-port branch의 TransactionPort contract와 연결되어야 하며 Spring @Transactional 직접 import로 충족하지 않음" + # 출처: feature-application-port-usecase-contract — TransactionPort Contract - name: TRANSACTION_REQUIRED scope: use_case_method enforcement: archunit @@ -85,9 +85,9 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:transaction-required-capability - # source: feature-repository-access-permission-contract — decisions 2026-05-22 - # "EXTERNAL_OUTBOUND_ALLOWED 분류 = outbox row INSERT는 in-process(불요), polling publisher의 broker publish는 outbound(필요)" - # source: feature-application-port-usecase-contract — "outbound adapter 호출 use case에 EXTERNAL_OUTBOUND_ALLOWED가 없으면 실패" + # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # "EXTERNAL_OUTBOUND_ALLOWED 분류 = outbox row INSERT는 in-process(불요), polling publisher의 broker publish는 outbound(필요)" + # 출처: feature-application-port-usecase-contract — "outbound adapter 호출 use case에 EXTERNAL_OUTBOUND_ALLOWED가 없으면 실패" - name: EXTERNAL_OUTBOUND_ALLOWED scope: use_case_method enforcement: archunit @@ -99,8 +99,8 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:external-outbound-capability - # source: feature-repository-access-permission-contract — decisions 2026-05-22 - # "CROSS_TENANT_ADMIN capability를 capability vocabulary에 추가 (tenant branch feature-tenant-context-policy와 cross-link)" + # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # "CROSS_TENANT_ADMIN capability를 capability vocabulary에 추가 (tenant branch feature-tenant-context-policy와 cross-link)" - name: CROSS_TENANT_ADMIN scope: use_case_method enforcement: archunit diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index 6536d1ae..9fc9fb82 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -3,30 +3,30 @@ # Owner branch: feature-env-driven-runtime-configuration # Last updated: 2026-09-25 # -# Conventions: -# - Application-owned env uses `APP_` prefix, fully unified (D2, 2026-06-05): -# datasource/server/etc. keys that map onto Spring properties are renamed APP_* -# as well (e.g. SERVER_PORT -> APP_SERVER_PORT). -# - Only env the Spring runtime reads natively stays native: SPRING_* and -# SPRING_PROFILES_ACTIVE (D6 — profile selector is Spring-native, not APP_). -# - `classification: secret` rows only reference secrets-classification.yaml; full row owned there. -# - reload_policy default = `restart-only` (env-driven branch "config reload: no runtime reload"). -# - boolean encoding = true/false only (env-driven branch 2026-05-22). -# - Duration encoding = Spring shorthand (`30s`); ISO-8601 (`PT30S`) forbidden (env-driven branch 2026-05-22). -# - DataSize encoding = `10MB` (env-driven branch 2026-05-22). +# 표기 규칙 +# - 애플리케이션이 가진 env는 모두 `APP_` 접두어를 쓴다(D2, 2026-06-05). Spring 속성으로 이어지는 +# datasource·server 등의 키도 APP_*로 바꿨다(예: SERVER_PORT -> APP_SERVER_PORT). +# - Spring 런타임이 직접 읽는 env만 원래 이름으로 둔다: SPRING_*와 SPRING_PROFILES_ACTIVE +# (D6 — profile 선택자는 APP_가 아니라 Spring 자체 이름이다). +# - `classification: secret` 행은 secrets-classification.yaml을 가리키기만 한다. 행 전체는 그 파일이 가진다. +# - reload_policy 기본값 = `restart-only` (env-driven branch "config reload: no runtime reload" — 실행 중 +# 다시 읽지 않는다). +# - boolean 값은 true/false만 쓴다 (env-driven branch 2026-05-22). +# - Duration 값은 Spring 줄임 표기(`30s`)다. ISO-8601(`PT30S`)은 쓰지 않는다 (env-driven branch 2026-05-22). +# - DataSize 값은 `10MB` 꼴이다 (env-driven branch 2026-05-22). +# - required_when은 둘 중 하나다. `<속성>=<값>` 꼴(공백 없음)은 테스트가 그 조건에서 기동 실패를 확인하고, +# 공백이 든 설명 꼴은 사람이 읽는 조건이다(RequiredWhenIsEnforcedTest). env_keys: - # === Profile / Identity (feature-env-driven-runtime-configuration) === + # === Profile / 정체성 (feature-env-driven-runtime-configuration) === - name: SPRING_PROFILES_ACTIVE - # source: feature-env-driven-runtime-configuration D6 (2026-06-06), amended by - # five-adapter-runtime-remediation §7.1. Profile selector is Spring-native and sole - # (APP_PROFILE was dropped). Exactly one value, not a CSV list: two environments cannot both - # have their safety rules apply, and whichever lost did so silently. + # 출처: feature-env-driven-runtime-configuration D6 (2026-06-06), five-adapter-runtime-remediation §7.1에서 + # 고침. profile 선택자는 Spring 자체 키 하나뿐이다(APP_PROFILE은 지웠다). CSV 목록이 아니라 값 정확히 + # 하나다: 두 환경의 안전 규칙이 함께 적용될 수 없고, 진 쪽은 소리 없이 빠졌다. type: enum - # No default. A profile that is guessed is a deployment nobody chose: a jar started - # with none used to become local, which before persistence was gated also meant an - # in-memory database that loses every write on restart. + # 기본값이 없다. 짐작한 profile은 아무도 고르지 않은 배포다: 예전에는 profile 없이 띄운 jar가 local이 + # 됐고, 영속성을 조건으로 묶기 전에는 재기동 때 쓴 것을 모두 잃는 in-memory DB이기도 했다. allowed_values: [local, dev, prod] classification: public-config required: true @@ -36,12 +36,12 @@ env_keys: compatibility_impact: behavior-change required_test: env-contract:profile-active - # APP_PROFILE intentionally removed (D6, 2026-06-06): profile = SPRING_PROFILES_ACTIVE - # alone. A duplicate APP_PROFILE would only add information doubling + mismatch-fail - # cost. See design record feature-env-driven-runtime-configuration Claims (wont-fix). + # APP_PROFILE은 일부러 지웠다 (D6, 2026-06-06): profile = SPRING_PROFILES_ACTIVE 하나. APP_PROFILE을 + # 따로 두면 같은 정보를 두 번 두고, 어긋날 때 실패하는 비용만 늘어난다. 설계 기록 + # feature-env-driven-runtime-configuration Claims (wont-fix) 참고. - name: APP_NAME - # source: feature-env-driven-runtime-configuration 2026-05-22 + # 출처: feature-env-driven-runtime-configuration 2026-05-22 # "Required config: APP_NAME, APP_PROFILE..." type: string default: null @@ -54,12 +54,13 @@ env_keys: compatibility_impact: behavior-change required_test: env-contract:app-name-present - # === HTTP server (APP_ unified per D2) === + # === HTTP 서버 (D2에 따라 APP_로 통일) === - name: APP_SERVER_PORT - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — full APP_ - # unification; server.port maps from APP_SERVER_PORT. - # + feature-management-actuator-security-contract 2026-05-22 "management port default = 9001 (separate from app 8080)" + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_로 전부 통일. server.port는 + # APP_SERVER_PORT에서 온다. + # + feature-management-actuator-security-contract 2026-05-22 "management port default = 9001 (separate from app 8080)" + # (관리 포트 기본값 9001, 앱 8080과 분리) type: int default: 8080 allowed_values: null @@ -72,7 +73,7 @@ env_keys: required_test: env-contract:server-port-bound - name: MANAGEMENT_SERVER_PORT - # source: feature-management-actuator-security-contract 2026-05-22 + # 출처: feature-management-actuator-security-contract 2026-05-22 # "management port default = 9001 (separate from app 8080). single-port는 platform ingress 보호 + 문서화 시만 허용." type: int default: 9001 @@ -86,8 +87,8 @@ env_keys: required_test: actuator-contract:management-port-separated - name: APP_SERVER_SHUTDOWN - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (server.shutdown mode; graceful drains in-flight requests) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (server.shutdown 방식. graceful은 처리 중인 요청을 끝내고 내린다) type: enum default: graceful allowed_values: [graceful, immediate] @@ -100,9 +101,9 @@ env_keys: required_test: env-contract:server-shutdown-mode - name: APP_SERVER_SHUTDOWN_TIMEOUT - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification. - # Supersedes the old APP_SHUTDOWN_TIMEOUT row. Must stay <= k8s - # terminationGracePeriod (cross-ref feature-container-runtime-contract). + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일. + # 옛 APP_SHUTDOWN_TIMEOUT 행을 대신한다. k8s terminationGracePeriod 이하여야 한다 + # (feature-container-runtime-contract 참고). type: duration default: 30s allowed_values: null @@ -115,11 +116,11 @@ env_keys: required_test: env-contract:server-shutdown-timeout-aligned - name: APP_SERVER_FORWARD_HEADERS_STRATEGY - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification. - # Fail closed: forwarded headers are trusted only when a deployment opts in behind a - # sanitizing/trusted proxy. native = Tomcat RemoteIpValve, which honours them only from - # peers matching server.tomcat.remoteip.internal-proxies. framework is not allowed: its - # ForwardedHeaderFilter believes every peer, and the rate limiter refuses to start on it. + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일. + # 기본은 닫힘(fail closed): forwarded 헤더는 배포가 정리·신뢰 proxy 뒤에서 직접 켤 때만 믿는다. + # native = Tomcat RemoteIpValve. server.tomcat.remoteip.internal-proxies에 맞는 상대에게서 온 헤더만 + # 따른다. framework는 허용하지 않는다: 그 ForwardedHeaderFilter는 모든 상대를 믿고, rate limiter가 + # 그 값으로는 기동을 거부한다. type: enum default: none allowed_values: [none, native] @@ -132,8 +133,8 @@ env_keys: required_test: env-contract:server-forward-headers-strategy - name: APP_SERVER_TOMCAT_MAX_THREADS - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (ceiling on concurrent request workers) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (동시 요청 worker 상한) type: int default: 200 allowed_values: null @@ -146,8 +147,8 @@ env_keys: required_test: env-contract:tomcat-max-threads-bounded - name: APP_SERVER_TOMCAT_MIN_SPARE_THREADS - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (idle worker pool floor) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (쉬는 worker pool의 하한) type: int default: 10 allowed_values: null @@ -160,8 +161,8 @@ env_keys: required_test: env-contract:tomcat-min-spare-threads-valid - name: APP_SERVER_TOMCAT_ACCEPT_COUNT - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (OS-level backlog queue depth for incoming TCP connections) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (들어오는 TCP 연결의 OS backlog queue 깊이) type: int default: 100 allowed_values: null @@ -174,8 +175,8 @@ env_keys: required_test: env-contract:tomcat-accept-count-valid - name: APP_SERVER_TOMCAT_MAX_CONNECTIONS - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (hard cap on simultaneously open connections) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (동시에 열린 연결 수의 상한) type: int default: 8192 allowed_values: null @@ -188,8 +189,8 @@ env_keys: required_test: env-contract:tomcat-max-connections-bounded - name: APP_SERVER_TOMCAT_CONNECTION_TIMEOUT - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (connection timeout for the Tomcat connector) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (Tomcat connector 연결 timeout) type: duration default: 20s allowed_values: null @@ -202,8 +203,8 @@ env_keys: required_test: env-contract:tomcat-connection-timeout-set - name: APP_SERVER_COMPRESSION_ENABLED - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (server.compression toggle) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (server.compression 켜고 끄기) type: boolean default: true allowed_values: [true, false] @@ -216,8 +217,8 @@ env_keys: required_test: env-contract:server-compression-toggle - name: APP_SERVER_COMPRESSION_MIN_RESPONSE_SIZE - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (payloads below this threshold are not compressed) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (이 크기보다 작은 응답은 압축하지 않는다) type: data_size default: 1KB allowed_values: null @@ -230,8 +231,8 @@ env_keys: required_test: env-contract:server-compression-min-size - name: APP_SERVER_ERROR_INCLUDE_STACKTRACE - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (spring.web.error.include-stacktrace policy) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (spring.web.error.include-stacktrace 정책) type: enum default: never allowed_values: [always, never, on_param] @@ -244,8 +245,8 @@ env_keys: required_test: env-contract:server-error-stacktrace-policy - name: APP_SERVER_ERROR_INCLUDE_MESSAGE - # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ unification - # (spring.web.error.include-message policy) + # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # (spring.web.error.include-message 정책) type: enum default: never allowed_values: [always, never, on_param] @@ -258,13 +259,13 @@ env_keys: required_test: env-contract:server-error-message-policy - name: APP_MULTI_INSTANCE_ENABLED - # source: feature-env-driven-runtime-configuration D8 (2026-06-06) - # When true, StartupSafetyValidator (a StartupRule, run before any other singleton) - # requires a cross-instance DistributedLockPort bean named distributedLockProvider, - # else startup fails (exit 72). Consumed - # by feature-runtime-health-lifecycle-contract, feature-background-job-async-contract, - # feature-cache-consistency-contract, feature-domain-event-outbox-contract, - # feature-rate-limit-idempotency-contract, feature-migration-startup-contract. + # 출처: feature-env-driven-runtime-configuration D8 (2026-06-06) + # true면 StartupSafetyValidator(다른 singleton보다 먼저 도는 StartupRule)가 이름이 + # distributedLockProvider인 인스턴스 간 DistributedLockPort bean을 요구한다. 없으면 기동이 실패한다 + # (exit 72). 이 값을 쓰는 곳: feature-runtime-health-lifecycle-contract, + # feature-background-job-async-contract, feature-cache-consistency-contract, + # feature-domain-event-outbox-contract, feature-rate-limit-idempotency-contract, + # feature-migration-startup-contract. type: boolean default: false allowed_values: [true, false] @@ -277,9 +278,9 @@ env_keys: required_test: env-contract:multi-instance-beans-present - name: APP_MIGRATION_ON_STARTUP - # source: feature-migration-startup-contract - # When true, Flyway migrations are executed automatically during application startup. - # When false, migrations are bypassed (delegated to out-of-app container/pipeline jobs). + # 출처: feature-migration-startup-contract + # true면 애플리케이션이 기동하면서 Flyway migration을 자동으로 돌린다. + # false면 migration을 건너뛴다(앱 밖의 container·pipeline job에 맡긴다). type: boolean default: true allowed_values: [true, false] @@ -294,8 +295,9 @@ env_keys: # === Datasource / pool (env-driven branch "Required config: datasource") === - name: APP_DATASOURCE_URL - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # + feature-persistence-failure-baseline "datasource/pool/timeout/connection exhaustion log field" + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # + feature-persistence-failure-baseline "datasource/pool/timeout/connection exhaustion log field" + # (datasource·pool·timeout·연결 고갈 로그 필드) type: url default: null allowed_values: null @@ -308,7 +310,7 @@ env_keys: required_test: env-contract:datasource-url-resolvable - name: APP_DATASOURCE_USERNAME - # source: feature-env-driven-runtime-configuration "Required config: datasource" + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" type: string default: null allowed_values: null @@ -321,8 +323,8 @@ env_keys: required_test: env-contract:datasource-credential-present - name: APP_DATASOURCE_PASSWORD - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # + feature-secrets-config-source-contract — secret 분류로 secrets-classification.yaml에서 owns + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # + feature-secrets-config-source-contract — secret 분류라 secrets-classification.yaml이 행을 가진다 type: string default: null allowed_values: null @@ -335,8 +337,8 @@ env_keys: required_test: secrets-contract:db-password-not-leaked - name: APP_PERSISTENCE_VENDOR - # source: persistence vendor selector used by application-local.yml and bootRunH2. - # PostgreSQL is the shipped default; H2 is an explicit developer-only selection. + # 출처: application-local.yml과 bootRunH2가 쓰는 영속성 vendor 선택자. + # PostgreSQL이 기본으로 들어 있고, H2는 개발자가 명시적으로 고를 때만 쓴다. property: app.persistence.vendor type: enum default: postgresql @@ -379,10 +381,10 @@ env_keys: required_test: jpa-contract:realtime-replay-env - name: APP_FLYWAY_ENABLED - # source: local PostgreSQL parity / explicit H2 developer lane. - # Every profile runs migrations by default — the persistence-jpa module default reads this key - # (07-08; dev/prod no longer pin a literal over it); bootRunH2 disables them because the - # migration tree is PostgreSQL-specific. + # 출처: 로컬 PostgreSQL을 운영과 맞춤 / 명시적 H2 개발 lane. + # 모든 profile이 기본으로 migration을 돌린다 — persistence-jpa 모듈 기본값이 이 키를 읽는다 + # (07-08; dev/prod가 그 위에 값을 박지 않는다). bootRunH2는 migration tree가 PostgreSQL 전용이라 + # 끈다. property: spring.flyway.enabled type: boolean default: true @@ -396,8 +398,8 @@ env_keys: required_test: jpa-contract:local-flyway-parity - name: APP_DATASOURCE_POOL_MAX_SIZE - # source: feature-env-driven-runtime-configuration "datasource/pool env" - # + feature-persistence-failure-baseline "Hikari metric 노출 기준" + # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # + feature-persistence-failure-baseline "Hikari metric 노출 기준" type: int default: 10 allowed_values: null @@ -410,7 +412,7 @@ env_keys: required_test: env-contract:pool-bounded - name: APP_DATASOURCE_POOL_MIN_IDLE - # source: feature-env-driven-runtime-configuration "datasource/pool env" + # 출처: feature-env-driven-runtime-configuration "datasource/pool env" type: int default: 2 allowed_values: null @@ -423,13 +425,13 @@ env_keys: required_test: env-contract:pool-min-idle-valid - name: APP_DATASOURCE_CONNECTION_TIMEOUT - # source: feature-env-driven-runtime-configuration "datasource/pool env" - # + feature-persistence-failure-baseline "Hikari Alert Threshold: pool wait p99 > 100ms" - # unit: milliseconds. It feeds spring.datasource.hikari.connection-timeout, which binds onto - # HikariConfig#setConnectionTimeout(long) — a duration shorthand such as "5s" does not bind and - # fails the boot. This row said `duration` / `5s`, application.yml copied that default, and - # every prod and dev deployment refused to start; five-adapter-runtime-remediation Wave 2 found - # it in the prod-smoke lane. Corrected to what the property actually accepts. + # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # + feature-persistence-failure-baseline "Hikari Alert Threshold: pool wait p99 > 100ms" + # 단위: 밀리초. 이 값은 spring.datasource.hikari.connection-timeout으로 가고, 그 키는 + # HikariConfig#setConnectionTimeout(long)에 바인딩된다 — "5s" 같은 duration 줄임 표기는 바인딩되지 않아 + # 기동이 실패한다. 이 행이 `duration` / `5s`라 했고, application.yml이 그 기본값을 복사했고, 모든 prod·dev + # 배포가 기동을 거부했다. five-adapter-runtime-remediation Wave 2가 prod-smoke lane에서 찾았다. 실제로 + # 받는 값으로 고쳤다. type: integer default: 5000 allowed_values: null @@ -442,8 +444,8 @@ env_keys: required_test: env-contract:connection-timeout-set - name: APP_DATASOURCE_DRIVER - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # (JDBC driver class for the configured datasource URL) + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # (설정한 datasource URL의 JDBC driver class) type: string default: org.postgresql.Driver allowed_values: null @@ -456,8 +458,8 @@ env_keys: required_test: env-contract:datasource-driver-set - name: APP_DATASOURCE_DDL_AUTO - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # (Hibernate ddl-auto; prod must be validate|none, local update convenient) + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # (Hibernate ddl-auto. prod는 validate|none이어야 하고, local은 update가 편하다) type: enum default: validate allowed_values: [none, validate, update, create, create-drop] @@ -470,8 +472,8 @@ env_keys: required_test: env-contract:datasource-ddl-auto-safe - name: APP_DATASOURCE_SHOW_SQL - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # (echo SQL to logs) + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # (SQL을 로그에 찍는다) type: boolean default: false allowed_values: [true, false] @@ -484,8 +486,8 @@ env_keys: required_test: env-contract:datasource-show-sql-toggle - name: APP_DATASOURCE_FORMAT_SQL - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # (pretty-print SQL — only useful when SHOW_SQL=true) + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # (SQL을 보기 좋게 찍는다 — SHOW_SQL=true일 때만 쓸모 있다) type: boolean default: false allowed_values: [true, false] @@ -498,8 +500,8 @@ env_keys: required_test: env-contract:datasource-format-sql-toggle - name: APP_DATASOURCE_OPEN_IN_VIEW - # source: feature-env-driven-runtime-configuration "Required config: datasource" - # (Hibernate OSIV — don't enable in prod) + # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # (Hibernate OSIV — prod에서 켜지 않는다) type: boolean default: false allowed_values: [true, false] @@ -512,8 +514,8 @@ env_keys: required_test: env-contract:datasource-open-in-view-toggle - name: APP_DATASOURCE_POOL_IDLE_TIMEOUT - # source: feature-env-driven-runtime-configuration "datasource/pool env" - # (Hikari milliseconds; idle connection eviction threshold) + # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # (Hikari 밀리초. 쉬는 연결을 내보내는 기준) type: int default: 600000 allowed_values: null @@ -526,8 +528,8 @@ env_keys: required_test: env-contract:pool-idle-timeout-valid - name: APP_DATASOURCE_POOL_MAX_LIFETIME - # source: feature-env-driven-runtime-configuration "datasource/pool env" - # (Hikari milliseconds; max lifetime — rotate before broker timeout) + # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # (Hikari 밀리초. 연결 최대 수명 — broker timeout 전에 교체한다) type: int default: 1800000 allowed_values: null @@ -539,14 +541,14 @@ env_keys: compatibility_impact: behavior-change required_test: env-contract:pool-max-lifetime-valid - # === Tracing / Observability (feature-distributed-tracing-contract) === + # === 추적 / 관측 (feature-distributed-tracing-contract) === - name: OTEL_EXPORTER_OTLP_ENDPOINT - # source: feature-distributed-tracing-contract 2026-05-22 + # 출처: feature-distributed-tracing-contract 2026-05-22 # "Micrometer Tracing + OpenTelemetry exporter를 기본 기준으로 둠" - # OTLP base address (OpenTelemetry spec). TracingEnvironmentPostProcessor bridges it to - # management.opentelemetry.tracing.export.otlp.endpoint as /v1/traces (OTLP/HTTP); - # blank = no span exporter bean (review 07-01, 2026-11-01). + # OTLP 기본 주소(OpenTelemetry 규격). TracingEnvironmentPostProcessor가 이 값을 + # management.opentelemetry.tracing.export.otlp.endpoint의 /v1/traces(OTLP/HTTP)로 잇는다. + # 빈 값 = span exporter bean 없음 (review 07-01, 2026-11-01). type: url default: null allowed_values: null @@ -559,7 +561,7 @@ env_keys: required_test: tracing-contract:exporter-endpoint-resolvable - name: APP_TRACING_ENABLED - # source: feature-distributed-tracing-contract 2026-05-22 + # 출처: feature-distributed-tracing-contract 2026-05-22 # "tracing disabled profile에서도 envelope meta.traceId와 log traceId는 유지" type: boolean default: true @@ -573,12 +575,11 @@ env_keys: required_test: tracing-contract:meta-traceid-when-disabled - name: APP_TRACING_SAMPLE_RATE - # source: feature-distributed-tracing-contract 2026-05-22 + # 출처: feature-distributed-tracing-contract 2026-05-22 # "trace sampling rate default = prod 1%, dev/local 100%" - # D-1 ISSUE-1 fix (2026-06-16): blank = per-profile resolver 기본값 사용. - # RuntimeEnvironment is the profile SSOT; resolver policy is prod=0.01, dev/local=1.0. - # TracingEnvironmentPostProcessor bridges resolved rate to - # management.tracing.sampling.probability. + # D-1 ISSUE-1 fix (2026-06-16): 빈 값 = profile별 resolver 기본값을 쓴다. + # RuntimeEnvironment가 profile의 정본이다. resolver 정책은 prod=0.01, dev/local=1.0. + # TracingEnvironmentPostProcessor가 정한 비율을 management.tracing.sampling.probability로 잇는다. type: string default: "" allowed_values: null @@ -590,13 +591,13 @@ env_keys: compatibility_impact: behavior-change required_test: tracing-contract:sample-rate-per-profile - # === Log management (feature-log-management-contract) === + # === 로그 관리 (feature-log-management-contract) === - # APP_LOG_LEVEL (single key) replaced by the 5 granular APP_LOG_LEVEL_* rows below - # (root / app / spring / web / sql) — as built by feature-log-management-contract. + # APP_LOG_LEVEL 키 하나를 아래 APP_LOG_LEVEL_* 행 다섯(root / app / spring / web / sql)으로 나눴다 + # — feature-log-management-contract가 만든 대로. - name: APP_LOG_LEVEL_ROOT - # source: feature-log-management-contract — root logger level + # 출처: feature-log-management-contract — root logger 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -609,7 +610,7 @@ env_keys: required_test: log-contract:root-level - name: APP_LOG_LEVEL_APP - # source: feature-log-management-contract — application package level + # 출처: feature-log-management-contract — 애플리케이션 패키지 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -622,7 +623,7 @@ env_keys: required_test: log-contract:app-level - name: APP_LOG_LEVEL_SPRING - # source: feature-log-management-contract — Spring framework package level + # 출처: feature-log-management-contract — Spring framework 패키지 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -635,7 +636,7 @@ env_keys: required_test: log-contract:spring-level - name: APP_LOG_LEVEL_WEB - # source: feature-log-management-contract — web/MVC package level + # 출처: feature-log-management-contract — web/MVC 패키지 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -648,7 +649,7 @@ env_keys: required_test: log-contract:web-level - name: APP_LOG_LEVEL_SQL - # source: feature-log-management-contract — JPA/JDBC SQL package level (DEBUG prints SQL) + # 출처: feature-log-management-contract — JPA/JDBC SQL 패키지 레벨 (DEBUG면 SQL을 찍는다) type: enum default: WARN allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -661,7 +662,7 @@ env_keys: required_test: log-contract:sql-level - name: APP_LOG_FILE_ENABLED - # source: feature-log-management-contract — rolling JSON file appender toggle + # 출처: feature-log-management-contract — 순환(rolling) JSON 파일 appender 켜고 끄기 type: boolean default: false allowed_values: [true, false] @@ -674,7 +675,7 @@ env_keys: required_test: log-contract:file-appender-toggle - name: APP_LOG_FILE_PATH - # source: feature-log-management-contract — file path (relative to bootRun cwd or absolute) + # 출처: feature-log-management-contract — 파일 경로 (bootRun 실행 위치 기준 상대 경로 또는 절대 경로) type: string default: logs/ca-skeleton.json allowed_values: null @@ -687,7 +688,7 @@ env_keys: required_test: log-contract:file-path-set - name: APP_LOG_FILE_MAX_SIZE - # source: feature-log-management-contract — per-file rolling size cap + # 출처: feature-log-management-contract — 파일 하나의 순환 크기 상한 type: data_size default: 100MB allowed_values: null @@ -700,7 +701,7 @@ env_keys: required_test: log-contract:file-max-size - name: APP_LOG_FILE_MAX_HISTORY - # source: feature-log-management-contract — number of rolled archives to retain + # 출처: feature-log-management-contract — 남길 순환 보관 파일 수 type: int default: 14 allowed_values: null @@ -713,7 +714,7 @@ env_keys: required_test: log-contract:file-max-history - name: APP_LOG_FILE_TOTAL_SIZE_CAP - # source: feature-log-management-contract — total size cap across rolled files + # 출처: feature-log-management-contract — 순환 파일 전체의 크기 상한 type: data_size default: 3GB allowed_values: null @@ -726,7 +727,7 @@ env_keys: required_test: log-contract:file-total-size-cap - name: APP_LOG_ASYNC_ENABLED - # source: feature-log-management-contract — AsyncAppender wrap for non-blocking I/O + # 출처: feature-log-management-contract — 막히지 않는 I/O를 위한 AsyncAppender 감싸기 type: boolean default: true allowed_values: [true, false] @@ -739,7 +740,7 @@ env_keys: required_test: log-contract:async-appender-toggle - name: APP_LOG_ASYNC_QUEUE_SIZE - # source: feature-log-management-contract — in-memory queue depth before back-pressure + # 출처: feature-log-management-contract — 역압(back-pressure) 전 메모리 queue 깊이 type: int default: 512 allowed_values: null @@ -752,8 +753,8 @@ env_keys: required_test: log-contract:async-queue-size - name: APP_LOG_ASYNC_DISCARDING_THRESHOLD - # source: feature-log-management-contract — remaining-capacity floor below which - # TRACE/DEBUG/INFO events drop (WARN/ERROR always kept). 0 = never drop. + # 출처: feature-log-management-contract — 남은 용량이 이 값 아래로 내려가면 + # TRACE/DEBUG/INFO 이벤트를 버린다(WARN/ERROR는 늘 남긴다). 0 = 버리지 않는다. type: int default: 20 allowed_values: null @@ -766,7 +767,7 @@ env_keys: required_test: log-contract:async-discarding-threshold - name: APP_LOG_JSON_TIMEZONE - # source: feature-log-management-contract — IANA timezone for JSON encoder timestamps + # 출처: feature-log-management-contract — JSON encoder 시각에 쓰는 IANA timezone type: string default: UTC allowed_values: null @@ -779,7 +780,7 @@ env_keys: required_test: log-contract:json-timezone - name: APP_LOG_JSON_TIMESTAMP_PATTERN - # source: feature-log-management-contract — JSON encoder timestamp pattern (ISO 8601 default) + # 출처: feature-log-management-contract — JSON encoder 시각 형식 (기본 ISO 8601) type: string default: "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" allowed_values: null @@ -792,7 +793,7 @@ env_keys: required_test: log-contract:json-timestamp-pattern - name: APP_LOG_JSON_INCLUDE_CALLER_DATA - # source: feature-log-management-contract — include file/method/line (significant perf cost) + # 출처: feature-log-management-contract — 파일·메서드·줄 번호를 넣는다 (성능 비용이 크다) type: boolean default: false allowed_values: [true, false] @@ -805,7 +806,7 @@ env_keys: required_test: log-contract:json-include-caller-data - name: APP_LOG_JSON_LOGGER_NAME_LENGTH - # source: feature-log-management-contract — logger name abbreviation (0 = full name) + # 출처: feature-log-management-contract — logger 이름 줄이기 (0 = 전체 이름) type: int default: 0 allowed_values: null @@ -818,7 +819,7 @@ env_keys: required_test: log-contract:json-logger-name-length - name: APP_LOG_SAMPLING_RATE - # source: feature-log-management-contract 2026-05-22 + # 출처: feature-log-management-contract 2026-05-22 # "log sampling(prod 10%) > trace sampling(prod 1%)" + Sampling Policy 표 (prod 10%, dev/local 100%) type: string default: "1.0" @@ -831,12 +832,13 @@ env_keys: compatibility_impact: behavior-change required_test: log-contract:sample-rate-per-profile - # === Privacy: user_principal pseudonymization (feature-data-retention-privacy-contract) === + # === 개인정보: user_principal 가명화 (feature-data-retention-privacy-contract) === - name: APP_PRIVACY_PSEUDONYMIZATION_SALT - # source: feature-data-retention-privacy-contract — "pseudonymization key = HMAC-SHA-256 - # with rotating salt (90d)". Consumed by feature-log-management-contract (DRIFT-6) - # to record user_principal in pseudonymized form. secret 분류로 secrets-classification.yaml에서 owns. + # 출처: feature-data-retention-privacy-contract — "pseudonymization key = HMAC-SHA-256 + # with rotating salt (90d)" (가명화 키는 90일마다 바뀌는 salt의 HMAC-SHA-256). feature-log-management-contract + # (DRIFT-6)가 user_principal을 가명 형태로 남기는 데 쓴다. secret 분류라 secrets-classification.yaml이 행을 + # 가진다. type: string default: null allowed_values: null @@ -851,7 +853,7 @@ env_keys: # === Security / CORS / JWT (feature-security-operational-baseline) === - name: APP_SECURITY_CORS_ORIGINS - # source: feature-security-operational-baseline 2026-05-22 + # 출처: feature-security-operational-baseline 2026-05-22 # "allowlist origin은 env-driven runtime configuration의 APP_SECURITY_CORS_ORIGINS로 주입" type: csv_list default: null @@ -865,7 +867,7 @@ env_keys: required_test: security-contract:cors-allowlist - name: APP_SECURITY_CORS_ENABLED - # source: feature-security-operational-baseline — CORS filter master toggle + # 출처: feature-security-operational-baseline — CORS filter 전체 켜고 끄기 type: boolean default: false allowed_values: [true, false] @@ -878,8 +880,8 @@ env_keys: required_test: security-contract:cors-enabled-toggle - name: APP_SECURITY_CORS_ALLOWED_METHODS - # source: feature-security-operational-baseline — allowed methods - # (empty -> sensible method defaults in CorsSettings) + # 출처: feature-security-operational-baseline — 허용 method + # (빈 값 -> CorsSettings의 무난한 method 기본값) type: csv_list default: null allowed_values: null @@ -892,7 +894,7 @@ env_keys: required_test: security-contract:cors-allowed-methods - name: APP_SECURITY_CORS_ALLOWED_HEADERS - # source: feature-security-operational-baseline — allowed request headers ("*" = any) + # 출처: feature-security-operational-baseline — 허용 요청 헤더 ("*" = 모두) type: csv_list default: "*" allowed_values: null @@ -905,7 +907,7 @@ env_keys: required_test: security-contract:cors-allowed-headers - name: APP_SECURITY_CORS_ALLOW_CREDENTIALS - # source: feature-security-operational-baseline 2026-05-22 + # 출처: feature-security-operational-baseline 2026-05-22 # "CORS는 allowlist default, credentials false default" / "wildcard with credentials forbidden" type: boolean default: false @@ -919,7 +921,7 @@ env_keys: required_test: security-contract:cors-credentials-policy - name: APP_SECURITY_CORS_MAX_AGE - # source: feature-security-operational-baseline 2026-05-22 + # 출처: feature-security-operational-baseline 2026-05-22 # "preflight max-age 600s default" type: duration default: 600s @@ -1029,9 +1031,8 @@ env_keys: required_test: redis-session-contract:csrf-enabled - name: APP_SESSION_REDIS_NAMESPACE_ENVIRONMENT - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1046,9 +1047,8 @@ env_keys: required_test: redis-session-contract:key-namespace - name: APP_SESSION_IDLE_TIMEOUT - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -1063,9 +1063,8 @@ env_keys: required_test: redis-session-contract:idle-expiry - name: APP_SESSION_ABSOLUTE_LIFETIME - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -1080,9 +1079,8 @@ env_keys: required_test: redis-session-contract:absolute-expiry - name: APP_SESSION_TOUCH_INTERVAL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -1097,9 +1095,8 @@ env_keys: required_test: redis-session-contract:bounded-touch - name: APP_SESSION_TOMBSTONE_TTL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -1114,9 +1111,8 @@ env_keys: required_test: redis-session-contract:logout-tombstone - name: APP_SESSION_MAXIMUM_ENVELOPE_BYTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1131,9 +1127,8 @@ env_keys: required_test: redis-session-contract:serializer-bounded - name: APP_SESSION_MAXIMUM_ATTRIBUTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1148,9 +1143,8 @@ env_keys: required_test: redis-session-contract:serializer-bounded - name: APP_SESSION_MAXIMUM_SCALAR_BYTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1165,7 +1159,7 @@ env_keys: required_test: redis-session-contract:serializer-bounded - name: APP_SECURITY_JWT_ISSUER - # source: feature-security-operational-baseline 2026-05-22 + # 출처: feature-security-operational-baseline 2026-05-22 # "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH" type: url default: null @@ -1179,7 +1173,7 @@ env_keys: required_test: security-contract:jwt-issuer-set - name: APP_SECURITY_JWT_AUDIENCE - # source: feature-security-operational-baseline 2026-05-22 + # 출처: feature-security-operational-baseline 2026-05-22 # "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH" type: csv_list default: null @@ -1193,7 +1187,7 @@ env_keys: required_test: security-contract:jwt-audience-set - name: APP_RATE_LIMIT_ENABLED - # Inbound enforcement stays disabled until an exact provider is selected. + # 정확한 provider를 고르기 전까지 inbound 강제는 꺼져 있다. type: boolean default: false allowed_values: [true, false] @@ -1205,14 +1199,14 @@ env_keys: compatibility_impact: additive required_test: redis-rate-limit-contract:transport-provider-default-pair - # APP_RATE_LIMIT_CLIENT_IP_MODE removed (2026-09-25, review follow-up I-5a): its - # forwarded-headers-trusted value keyed unauthenticated callers by the leftmost X-Forwarded-For - # entry, which the caller writes. The client IP is getRemoteAddr(); behind a proxy set - # APP_SERVER_FORWARD_HEADERS_STRATEGY=native and server.tomcat.remoteip.internal-proxies. + # APP_RATE_LIMIT_CLIENT_IP_MODE는 지웠다 (2026-09-25, review follow-up I-5a): 그 값 + # forwarded-headers-trusted는 인증하지 않은 호출자를 X-Forwarded-For의 맨 왼쪽 값으로 구분했는데, 그 값은 + # 호출자가 쓴다. client IP는 getRemoteAddr()다. proxy 뒤라면 + # APP_SERVER_FORWARD_HEADERS_STRATEGY=native와 server.tomcat.remoteip.internal-proxies를 설정한다. - name: APP_RATE_LIMIT_REDIS_ENABLED - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.enabled (APP_REDIS_ENABLED). + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.enabled (APP_REDIS_ENABLED). deprecated_orphaned: true removal_deadline: 2026-11-30 type: boolean @@ -1299,8 +1293,8 @@ env_keys: required_test: rate-limit-contract:key-version-bounded - name: APP_RATE_LIMIT_REDIS_HOST - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.nodes (APP_REDIS_NODES). + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.nodes (APP_REDIS_NODES). deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1315,8 +1309,8 @@ env_keys: required_test: rate-limit-contract:redis-host-required - name: APP_RATE_LIMIT_REDIS_PORT - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.nodes (APP_REDIS_NODES). + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.nodes (APP_REDIS_NODES). deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1343,8 +1337,8 @@ env_keys: required_test: rate-limit-contract:redis-password-no-leak - name: APP_RATE_LIMIT_REDIS_TRUST_PEM - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.tls.trust-material-resource. + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.tls.trust-material-resource. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1383,8 +1377,8 @@ env_keys: required_test: redis-contract:session-password-no-leak - name: APP_SESSION_REDIS_TRUST_PEM - # DEPRECATED 2026-08-10: the session generation that bound this was removed, and the replacement does not own a Redis client of its own either. - # Replaced by: app.redis.tls.trust-material-resource. + # 폐기 2026-08-10: 이 값을 바인딩하던 session 세대를 지웠고, 대신한 것도 자기 Redis client를 갖지 않는다. + # 대체: app.redis.tls.trust-material-resource. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1399,9 +1393,8 @@ env_keys: required_test: redis-contract:session-trust-material-no-leak - name: APP_SESSION_REDIS_KEY_HMAC_SECRET - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1428,8 +1421,8 @@ env_keys: required_test: rate-limit-contract:redis-timeout-bounded - name: APP_RATE_LIMIT_REDIS_MAXIMUM_COMMAND_BYTES - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.limits.max-batch-request-bytes. + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.limits.max-batch-request-bytes. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1444,8 +1437,8 @@ env_keys: required_test: rate-limit-contract:redis-command-bytes-bounded - name: APP_RATE_LIMIT_REDIS_MAXIMUM_QUEUED_COMMANDS - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.capacity.maximum-in-flight-commands. + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.capacity.maximum-in-flight-commands. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1460,8 +1453,8 @@ env_keys: required_test: rate-limit-contract:redis-queue-bounded - name: APP_RATE_LIMIT_REDIS_MAXIMUM_IN_FLIGHT_BYTES - # DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it. - # Replaced by: app.redis.capacity.maximum-in-flight-bytes. + # 폐기 2026-08-10: rate limiter는 이제 자기 Redis client를 갖지 않는다. RedisRuntimeAutoConfiguration이 만든 client 하나가 모든 capability를 맡으므로, 두 번째 endpoint와 두 번째 상한은 그 client와 어긋날 수밖에 없었다. + # 대체: app.redis.capacity.maximum-in-flight-bytes. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -1476,8 +1469,8 @@ env_keys: required_test: rate-limit-contract:redis-byte-admission-bounded - name: APP_RATE_LIMIT_REDIS_NAMESPACE_ENVIRONMENT - # DEPRECATED 2026-08-10: the rate limiter no longer renders its own key prefix. Four capabilities each joining two free-form tokens produced four prefixes, and the ACL pattern matched none of them. - # Replaced by: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT), shared by every capability. + # 폐기 2026-08-10: rate limiter는 이제 key prefix를 스스로 만들지 않는다. capability 넷이 각자 자유 형식 토큰 둘을 이어 prefix 넷이 생겼고, ACL 패턴은 그중 어느 것과도 맞지 않았다. + # 대체: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT). 모든 capability가 함께 쓴다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1600,12 +1593,11 @@ env_keys: required_test: rate-limit-contract:cleanup-grace-bounded - name: APP_IDEMPOTENCY_TTL - # app.capabilities.idempotency.replay-ttl: how long a completed response stays - # replayable. One value for every provider; IdempotencySettings refuses more than 72h, less than - # APP_IDEMPOTENCY_PROCESSING_LEASE (re-review 2026-11-04 RR-03-11), and more than - # APP_IDEMPOTENCY_FAILURE_RETENTION (RR3-03-02, owner decision 2026-11-04), at startup: raising - # this key alone past the failure retention (default 24h) fails startup, so raise both - # (RR5-03-01). Each record lives for the processing lease plus this value in both stores. + # app.capabilities.idempotency.replay-ttl: 끝난 응답을 다시 돌려줄 수 있는 기간. 모든 provider가 + # 같은 값을 쓴다. IdempotencySettings는 기동할 때 72h보다 길거나, APP_IDEMPOTENCY_PROCESSING_LEASE보다 + # 짧거나(re-review 2026-11-04 RR-03-11), APP_IDEMPOTENCY_FAILURE_RETENTION보다 긴 값(RR3-03-02, 소유자 + # 결정 2026-11-04)을 거부한다. 이 키만 실패 보관 기간(기본 24h)보다 길게 올리면 기동이 실패하니 둘을 같이 + # 올린다(RR5-03-01). 두 저장소 모두에서 기록 하나는 처리 lease에 이 값을 더한 만큼 남는다. type: duration default: 24h allowed_values: null @@ -1618,12 +1610,12 @@ env_keys: required_test: idempotency-contract:ttl-applied - name: APP_IDEMPOTENCY_PROVIDER - # app.capabilities.idempotency.provider. redis and postgresql each contribute only the - # store; app-bootstrap builds the one IdempotencyExecutor and refuses startup unless exactly one - # store exists. postgresql uses the primary data source, applies its Flyway streams at startup - # and refuses a non-PostgreSQL data source, so bootRunH2 runs with disabled or redis. Selection - # is explicit and disabled by default; no implementation wins merely by being on the classpath. - # 2026-09-25: jdbc (the V1 store) was removed; a deployment still setting it fails to bind. + # app.capabilities.idempotency.provider. redis와 postgresql은 각각 저장소만 기여한다. app-bootstrap이 + # IdempotencyExecutor 하나를 만들고, 저장소가 정확히 하나가 아니면 기동을 거부한다. postgresql은 주 + # data source를 쓰고, 기동할 때 자기 Flyway stream을 적용하고, PostgreSQL이 아닌 data source를 거부한다. + # 그래서 bootRunH2는 disabled나 redis로 돈다. 선택은 명시적이고 기본은 disabled다. classpath에 있다는 + # 것만으로 고르는 구현은 없다. + # 2026-09-25: jdbc(V1 저장소)를 지웠다. 아직 이 값을 쓰는 배포는 바인딩에서 실패한다. type: enum default: disabled allowed_values: [disabled, redis, postgresql] @@ -1636,7 +1628,7 @@ env_keys: required_test: redis-idempotency-contract:provider-exclusive - name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET - # DEPRECATED 2026-09-22: the Redis idempotency adapter consumes caller-supplied scope digests and never read this secret. + # 폐기 2026-09-22: Redis idempotency adapter는 호출자가 준 scope digest를 쓰고 이 비밀을 읽은 적이 없다. deprecated_orphaned: true removal_deadline: 2026-12-31 type: string @@ -1651,8 +1643,8 @@ env_keys: required_test: redis-idempotency-contract:key-hmac-no-leak - name: APP_IDEMPOTENCY_REDIS_NAMESPACE_ENVIRONMENT - # DEPRECATED 2026-08-10: the idempotency store no longer renders its own key prefix. Four capabilities each joining two free-form tokens produced four prefixes, and the ACL pattern matched none of them. - # Replaced by: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT), shared by every capability. + # 폐기 2026-08-10: idempotency store는 이제 key prefix를 스스로 만들지 않는다. capability 넷이 각자 자유 형식 토큰 둘을 이어 prefix 넷이 생겼고, ACL 패턴은 그중 어느 것과도 맞지 않았다. + # 대체: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT). 모든 capability가 함께 쓴다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1667,10 +1659,9 @@ env_keys: required_test: redis-idempotency-contract:key-namespace - name: APP_IDEMPOTENCY_PROCESSING_LEASE - # app.capabilities.idempotency.processing-lease: how long one attempt holds its claim. Longer - # than the in-flight Retry-After (2s), at most 1h, and not longer than APP_IDEMPOTENCY_TTL. A - # claim whose lease runs out is taken over only if it never started; an execution whose lease - # ran out is answered IDEMPOTENCY_RECOVERY_REQUIRED and never run again. + # app.capabilities.idempotency.processing-lease: 시도 하나가 claim을 쥐는 기간. in-flight + # Retry-After(2s)보다 길고, 최대 1h이며, APP_IDEMPOTENCY_TTL보다 길지 않다. lease가 끝난 claim은 시작하지 + # 않았을 때만 넘겨받는다. lease가 끝난 실행은 IDEMPOTENCY_RECOVERY_REQUIRED로 답하고 다시 돌리지 않는다. type: duration default: 30s allowed_values: null @@ -1683,11 +1674,11 @@ env_keys: required_test: redis-idempotency-contract:processing-lease-bounded - name: APP_IDEMPOTENCY_FAILURE_RETENTION - # app.capabilities.idempotency.failure-retention: how long a record the executor marked failed - # (abandoned with an unknown effect, or retryable without one) stays, from the marking. At most - # 30d, and IdempotencySettings refuses less than APP_IDEMPOTENCY_TTL at startup: a shorter one - # lets an abandoned record go first, and a same-key resend runs the work again (re-review - # 2026-11-04 RR3-03-02, owner decision 2026-11-04). + # app.capabilities.idempotency.failure-retention: executor가 실패로 표시한 기록(결과를 모른 채 + # 버렸거나, 결과 없이 다시 시도할 수 있는 것)이 표시한 때부터 남는 기간. 최대 30d이고, + # IdempotencySettings는 기동할 때 APP_IDEMPOTENCY_TTL보다 짧은 값을 거부한다: 더 짧으면 버린 기록이 먼저 + # 사라지고, 같은 key로 다시 보낸 요청이 일을 한 번 더 한다(re-review 2026-11-04 RR3-03-02, 소유자 결정 + # 2026-11-04). type: duration default: 24h allowed_values: null @@ -1712,7 +1703,7 @@ env_keys: required_test: redis-lease-contract:provider-exclusive - name: APP_LEASE_REDIS_KEY_HMAC_SECRET - # DEPRECATED 2026-09-22: the Redis lease adapter consumes caller-supplied resource digests and never read this secret. + # 폐기 2026-09-22: Redis lease adapter는 호출자가 준 resource digest를 쓰고 이 비밀을 읽은 적이 없다. deprecated_orphaned: true removal_deadline: 2026-12-31 type: string @@ -1727,8 +1718,8 @@ env_keys: required_test: redis-lease-contract:key-hmac-no-leak - name: APP_LEASE_REDIS_NAMESPACE_ENVIRONMENT - # DEPRECATED 2026-08-10: the lease no longer renders its own key prefix. Four capabilities each joining two free-form tokens produced four prefixes, and the ACL pattern matched none of them. - # Replaced by: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT), shared by every capability. + # 폐기 2026-08-10: lease는 이제 key prefix를 스스로 만들지 않는다. capability 넷이 각자 자유 형식 토큰 둘을 이어 prefix 넷이 생겼고, ACL 패턴은 그중 어느 것과도 맞지 않았다. + # 대체: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT). 모든 capability가 함께 쓴다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -1754,10 +1745,10 @@ env_keys: compatibility_impact: additive required_test: redis-lease-contract:drift-budget-bounded - # === Cache / Redis (feature-cache-consistency-contract + integration-adapter-templates) === + # === 캐시 / Redis (feature-cache-consistency-contract + integration-adapter-templates) === - name: APP_CACHE_CANONICAL_DEFAULT_PROVIDER - # Canonical default semantic region provider selection; legacy enable is a separate migration path. + # 기본 캐시 영역(canonical default semantic region)의 provider 선택. 옛 켜기 키는 따로 옮겨 가는 경로다. type: enum default: disabled allowed_values: [disabled, redis] @@ -1770,12 +1761,12 @@ env_keys: required_test: redis-cache:canonical-cache-role-composition - name: APP_REDIS_ENABLED - # 2026-09-25 capability packaging: the cache-redis module is on when present (its - # config/module-defaults/cache-redis.yml maps this key with default true); false is the explicit - # off. Absent from the build is the ordinary off state. - # False loads no Redis settings, requires no Redis secret, and creates no client, connection, - # thread or health contributor. Role selectors choose which capabilities compose once Redis is - # on; none of them is a second on/off key. + # 2026-09-25 capability 포장: cache-redis 모듈은 있으면 켜진다(모듈의 + # config/module-defaults/cache-redis.yml이 이 키를 기본 true로 잇는다). false가 명시적으로 끄는 값이다. + # 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # false면 Redis 설정을 읽지 않고, Redis 비밀을 요구하지 않고, client·연결·thread·health contributor를 + # 만들지 않는다. Redis가 켜진 뒤 어떤 capability를 조립할지는 role 선택자가 고른다. 그중 어느 것도 두 + # 번째 켜고 끄기 키가 아니다. property: app.redis.enabled owner_module: adapter-outbound-cache-redis type: boolean @@ -1792,8 +1783,8 @@ env_keys: - name: APP_CACHE_REDIS_POSITIVE_HARD_TTL - # How long a cache entry stays usable. The physical Redis TTL equals this and nothing else, so - # an entry can never outlive the deployment's own notion of usability or be discarded early. + # 캐시 항목을 쓸 수 있는 기간. Redis의 실제 TTL은 이 값과 같고 다른 것이 아니다. 그래서 항목이 배포가 + # 정한 사용 기간보다 오래 남거나 일찍 버려지지 않는다. type: duration default: 5m allowed_values: null @@ -1806,8 +1797,8 @@ env_keys: required_test: redis-capability:cache-region-composition - name: APP_CACHE_REDIS_NEGATIVE_TTL - # How long an authoritative absence is cached. Separate from the positive TTL because "the - # source says this does not exist" is a fact with a different shelf life from a value. + # 권위 있는 「없음」을 캐시하는 기간. 「원천에 이것이 없다」는 사실은 값과 유통 기한이 달라서 값의 + # TTL과 따로 둔다. type: duration default: 10s allowed_values: null @@ -1820,9 +1811,9 @@ env_keys: required_test: redis-capability:cache-region-composition - name: APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS - # The cache's own script-lane connections. Separate from APP_REDIS_CAPACITY_MAXIMUM_SCRIPT_CONNECTIONS, - # which idempotency, rate limiting and leases share, so cache fills cannot starve them (review - # 2026-11-03 README section 4, RR-04-02). + # 캐시 자신의 script lane 연결 수. idempotency·rate limit·lease가 함께 쓰는 + # APP_REDIS_CAPACITY_MAXIMUM_SCRIPT_CONNECTIONS와 따로 두어, 캐시 채우기가 그 셋을 굶기지 않게 한다 + # (review 2026-11-03 README 4절, RR-04-02). property: app.capabilities.cache.maximum-script-connections owner_module: adapter-outbound-cache-redis type: integer @@ -1838,7 +1829,7 @@ env_keys: required_test: redis-capability:cache-script-lane-separate-from-correctness - name: APP_IDEMPOTENCY_REDIS_COMMAND_TIMEOUT - # The ceiling on one owner-safe transition. + # owner-safe 전이 하나의 상한. type: duration default: 200ms allowed_values: null @@ -1851,7 +1842,7 @@ env_keys: required_test: redis-capability:idempotency-store-composition - name: APP_LEASE_REDIS_COMMAND_TIMEOUT - # The ceiling on one lease operation. + # lease 연산 하나의 상한. type: duration default: 200ms allowed_values: null @@ -1864,8 +1855,8 @@ env_keys: required_test: redis-capability:lease-composition - name: APP_LEASE_REDIS_CONTENTION_RETRY_AFTER - # What a contended acquire tells the caller to wait. Distinct from the drift budget: one is - # advice to a caller that lost, the other is how much of its own lease a winner does not trust. + # 경합으로 acquire에 실패한 호출자에게 기다리라고 알려 줄 시간. drift 예산과 다르다: 하나는 진 + # 호출자에게 주는 조언이고, 다른 하나는 이긴 쪽이 자기 lease 중 믿지 않는 부분이다. type: duration default: 50ms allowed_values: null @@ -1877,14 +1868,14 @@ env_keys: compatibility_impact: additive required_test: redis-capability:lease-composition - # --- Redis runtime settings (app.redis.*) ---------------------------------- - # Bound only by RedisRuntimeAutoConfiguration in adapter-outbound-redis-runtime while - # APP_REDIS_ENABLED is true. application.yml does not force these values into Redis-free - # deployments; src/.env.example merely documents explicit operator inputs. verifyEnvKeys checks - # the registry against the runtime module's configuration metadata. + # --- Redis 런타임 설정 (app.redis.*) ---------------------------------- + # APP_REDIS_ENABLED가 true일 때만 adapter-outbound-redis-runtime의 RedisRuntimeAutoConfiguration이 + # 바인딩한다. application.yml은 Redis 없는 배포에 이 값을 넣지 않는다. src/.env.example은 운영자가 + # 명시적으로 넣을 값을 적어 둘 뿐이다. verifyEnvKeys가 이 레지스트리를 런타임 모듈의 설정 메타데이터와 + # 대조한다. - name: APP_REDIS_DATABASE - # Cluster supports database 0 only; a non-zero value fails startup there. + # Cluster는 database 0만 지원한다. 0이 아니면 거기서 기동이 실패한다. property: app.redis.database owner_module: adapter-outbound-redis-runtime type: integer @@ -1961,7 +1952,7 @@ env_keys: required_test: redis-sdk:typed-settings-bound-and-validated - name: APP_REDIS_NODES - # CSV of host:port. Cluster and Sentinel take every seed node. + # host:port CSV. Cluster와 Sentinel은 모든 seed node를 받는다. property: app.redis.nodes owner_module: adapter-outbound-redis-runtime type: csv @@ -1992,7 +1983,7 @@ env_keys: required_test: redis-sdk:typed-settings-bound-and-validated - name: APP_REDIS_TIMEOUT_FAST - # Single-key command profile; above 5s produces a startup warning. + # 단일 key 명령 profile. 5s를 넘으면 기동 때 경고를 남긴다. property: app.redis.timeout.fast owner_module: adapter-outbound-redis-runtime type: duration @@ -2022,16 +2013,15 @@ env_keys: compatibility_impact: additive required_test: redis-sdk:typed-settings-bound-and-validated - # --- Redis runtime composition settings (app.redis.*) ---------------------- - # Authentication, Sentinel discovery, TLS, lifecycle, Cluster routing and capacity. Same rule as the rest of app.redis.*: bound only while - # APP_REDIS_ENABLED is true, and deliberately absent from application.yml and .env. + # --- Redis 런타임 조립 설정 (app.redis.*) ---------------------- + # 인증, Sentinel 탐색, TLS, 수명 주기, Cluster 라우팅, 용량. 다른 app.redis.*와 규칙이 같다: + # APP_REDIS_ENABLED가 true일 때만 바인딩하고, application.yml과 .env에는 일부러 두지 않는다. - name: APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE - # Pointer to the account registered scripts run as, in the same - # secret://@/ form as the application reference. Unset, scripts run - # as the application account and startup logs a warning saying so. The Compose Redis lanes use - # secret://ca-skeleton-application-advanced@environment/REDIS_LANE_ADVANCED_PASSWORD, a fixture - # account of compose/redis/acl/lane-fixture-accounts.acl. + # 등록된 script가 실행될 계정을 가리키는 참조. 애플리케이션 참조와 같은 + # secret://@/ 형식이다. 비우면 script가 애플리케이션 계정으로 돌고 기동 때 그렇다고 + # 경고를 남긴다. Compose Redis lane은 compose/redis/acl/lane-fixture-accounts.acl의 fixture 계정인 + # secret://ca-skeleton-application-advanced@environment/REDIS_LANE_ADVANCED_PASSWORD를 쓴다. property: app.redis.authentication.advanced-credential-reference owner_module: adapter-outbound-cache-redis type: string @@ -2049,19 +2039,18 @@ env_keys: - name: APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED property: app.redis.authentication.anonymous-access-accepted owner_module: adapter-outbound-cache-redis - # Explicit acknowledgement that Redis runs with no credential. Startup fails without it when - # no credential reference is set, because booting anyway builds an unauthenticated client that - # cannot run a single command on any deployment which disabled the `default` ACL user — the - # failure moves from startup to the first request, where it reads as an outage rather than a - # missing setting. Setting this to true keeps the deployment running and logs the trade. - # No Compose lane sets it: the Redis lanes authenticate with the fixture accounts instead, because - # the warning this logs is the one their "startup is silent" check exists to catch. + # Redis가 자격 증명 없이 돈다는 것을 명시적으로 인정하는 값. 자격 증명 참조가 없을 때 이 값이 없으면 + # 기동이 실패한다. 그대로 기동하면 인증 없는 client가 만들어지고, `default` ACL 사용자를 끈 배포에서는 + # 명령 하나도 돌리지 못한다 — 실패가 기동에서 첫 요청으로 옮겨 가고, 빠진 설정이 아니라 장애처럼 보인다. + # true로 두면 배포는 돌고 그 trade-off를 로그에 남긴다. + # 이 값을 쓰는 Compose lane은 없다: Redis lane은 대신 fixture 계정으로 인증한다. 이 값이 남기는 경고가 바로 + # lane의 「기동은 조용하다」 검사가 잡으려는 것이기 때문이다. type: boolean default: false allowed_values: [true, false] classification: public-config required: false - required_when: app.redis.enabled=true and no credential reference is configured + required_when: app.redis.enabled=true이고 자격 증명 참조를 설정하지 않았을 때 reload_policy: restart-only owner_branch: redis-optionality-and-composition validation: boolean_strict @@ -2069,12 +2058,11 @@ env_keys: required_test: redis-sdk:authentication-required-unless-anonymous-accepted - name: APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE - # Pointer to the application ACL account credential. The value lives in the secret manager. - # Form: secret://@/; the environment source reads the variable - # . Without the account part the client authenticates as `default`, which a hardened - # Redis turns off. The Compose Redis lanes use - # secret://ca-skeleton-application@environment/REDIS_LANE_APPLICATION_PASSWORD, a fixture - # account of compose/redis/acl/lane-fixture-accounts.acl. + # 애플리케이션 ACL 계정 자격 증명을 가리키는 참조. 값은 secret manager에 있다. + # 형식: secret://@/. environment source는 변수 을 읽는다. 계정 부분이 + # 없으면 client가 `default`로 인증하는데, 단단히 설정한 Redis는 그 사용자를 끈다. Compose Redis lane은 + # compose/redis/acl/lane-fixture-accounts.acl의 fixture 계정인 + # secret://ca-skeleton-application@environment/REDIS_LANE_APPLICATION_PASSWORD를 쓴다. property: app.redis.authentication.credential-reference owner_module: adapter-outbound-cache-redis type: string @@ -2105,7 +2093,7 @@ env_keys: required_test: redis-sdk:runtime-composition-binds-and-validates - name: APP_REDIS_CAPACITY_MAXIMUM_SCRIPT_CONNECTIONS - # Physical SCRIPT lane connections are bounded separately from the per-connection command queue. + # 실제 SCRIPT lane 연결 수는 연결마다의 명령 queue와 따로 제한한다. property: app.redis.capacity.maximum-script-connections owner_module: adapter-outbound-redis-runtime type: integer @@ -2121,7 +2109,7 @@ env_keys: required_test: redis-runtime:script-lane-physical-connections-bounded - name: APP_REDIS_CAPACITY_REJECT_WHEN_DISCONNECTED - # True refuses commands while disconnected. False restores the driver offline queue, which replays a burst of writes on reconnect in arbitrary order relative to the outage. + # true면 연결이 끊긴 동안 명령을 거부한다. false면 driver의 offline queue를 되살리는데, 다시 연결될 때 쌓인 쓰기를 끊긴 동안의 순서와 상관없이 몰아서 다시 보낸다. property: app.redis.capacity.reject-when-disconnected owner_module: adapter-outbound-cache-redis type: boolean @@ -2167,7 +2155,7 @@ env_keys: required_test: redis-sdk:runtime-composition-binds-and-validates - name: APP_REDIS_LIFECYCLE_ACQUIRE_TIMEOUT - # How long a lane borrow waits for a returned connection before it is refused as not sent. + # lane이 연결을 빌릴 때, 돌려받은 연결을 기다리는 시간. 넘으면 보내지 않은 것으로 거부한다. property: app.redis.lifecycle.acquire-timeout owner_module: adapter-outbound-cache-redis type: duration @@ -2213,7 +2201,7 @@ env_keys: required_test: redis-sdk:runtime-composition-binds-and-validates - name: APP_REDIS_LIFECYCLE_DRAIN_TIMEOUT - # How long shutdown waits for in-flight commands before closing connections. + # 종료할 때 연결을 닫기 전에 처리 중인 명령을 기다리는 시간. property: app.redis.lifecycle.drain-timeout owner_module: adapter-outbound-cache-redis type: duration @@ -2266,11 +2254,10 @@ env_keys: allowed_values: null classification: sensitive-config required: false - # Applied only when present: RedisTopologyClientFactory sets the sentinel credentials provider - # through ifPresent, so a Sentinel deployment whose sentinels accept unauthenticated discovery - # starts without it. The unconditional "app.redis.mode=sentinel" this used to declare was a - # requirement the runtime never enforced. - required_when: app.redis.mode=sentinel and the sentinels require authentication + # 있을 때만 적용한다: RedisTopologyClientFactory가 sentinel 자격 증명 provider를 ifPresent로 설정한다. + # 그래서 sentinel이 인증 없는 탐색을 받는 Sentinel 배포는 이 값 없이 뜬다. 예전에 적었던 무조건 + # "app.redis.mode=sentinel"은 런타임이 강제한 적 없는 요구였다. + required_when: app.redis.mode=sentinel이고 sentinel이 인증을 요구할 때 reload_policy: restart-only owner_branch: redis-optionality-and-composition validation: nonblank_when_required @@ -2300,9 +2287,9 @@ env_keys: allowed_values: null classification: public-config required: false - # Falls back to app.redis.nodes by design, so a deployment that points nodes at its sentinels - # and says nothing else is the common case rather than a misconfiguration. - required_when: app.redis.mode=sentinel and app.redis.nodes does not list the sentinels + # 설계상 app.redis.nodes로 돌아간다. 그래서 nodes에 sentinel을 적고 다른 것은 말하지 않은 배포가 잘못된 + # 설정이 아니라 흔한 경우다. + required_when: app.redis.mode=sentinel이고 app.redis.nodes에 sentinel이 없을 때 reload_policy: restart-only owner_branch: redis-optionality-and-composition validation: csv_nonempty @@ -2317,9 +2304,9 @@ env_keys: allowed_values: null classification: public-config required: false - # A key manager is configured only when this is present. Ordinary one-way TLS needs no client - # certificate, so requiring one whenever TLS is on was a claim the runtime never made. - required_when: app.redis.tls.enabled=true and the server requires mutual TLS + # key manager는 이 값이 있을 때만 설정한다. 보통의 단방향 TLS에는 client 인증서가 필요 없으니, TLS가 + # 켜질 때마다 요구하는 것은 런타임이 한 적 없는 주장이었다. + required_when: app.redis.tls.enabled=true이고 서버가 mutual TLS를 요구할 때 reload_policy: restart-only owner_branch: redis-optionality-and-composition validation: nonblank_when_required @@ -2334,10 +2321,10 @@ env_keys: allowed_values: null classification: sensitive-config required: false - # A relationship between two settings rather than a switch: a client certificate without its - # key cannot build a key manager. Enforced in RedisRuntimeSettings.validate and covered by - # RedisRuntimeSettingsTest, which is where the registry's prose conditions are proven. - required_when: app.redis.tls.client-certificate-resource is configured + # 켜고 끄는 값이 아니라 두 설정 사이의 관계다: key 없는 client 인증서로는 key manager를 만들 수 없다. + # RedisRuntimeSettings.validate가 강제하고 RedisRuntimeSettingsTest가 다룬다. 레지스트리의 글로 쓴 조건은 + # 거기서 증명한다. + required_when: app.redis.tls.client-certificate-resource를 설정했을 때 reload_policy: restart-only owner_branch: redis-optionality-and-composition validation: nonblank_when_required @@ -2360,7 +2347,7 @@ env_keys: required_test: redis-sdk:runtime-composition-binds-and-validates - name: APP_REDIS_TLS_HOSTNAME_VERIFICATION - # Disabling this accepts any certificate the trust material signs, for any host. + # 이 값을 끄면 trust material이 서명한 모든 인증서를 어떤 host에 대해서도 받는다. property: app.redis.tls.hostname-verification owner_module: adapter-outbound-cache-redis type: boolean @@ -2383,22 +2370,21 @@ env_keys: allowed_values: null classification: public-config required: false - # A trust manager is installed only when this is present; otherwise the JDK default trust - # anchors apply, which is enough for a server certificate from a public CA. - required_when: app.redis.tls.enabled=true and the server certificate is not publicly trusted + # trust manager는 이 값이 있을 때만 설치한다. 없으면 JDK 기본 신뢰 앵커를 쓰고, 공개 CA가 발급한 서버 + # 인증서에는 그것으로 충분하다. + required_when: app.redis.tls.enabled=true이고 서버 인증서가 공개 신뢰 체인에 없을 때 reload_policy: restart-only owner_branch: redis-optionality-and-composition validation: nonblank_when_required compatibility_impact: additive required_test: redis-sdk:runtime-composition-binds-and-validates - name: APP_CACHE_REDIS_ENABLED - # source: feature-integration-adapter-templates 2026-05-22 + # 출처: feature-integration-adapter-templates 2026-05-22 # "Redis | disabled optional module | cache consistency" + Adapter Template Defaults 표 - # DEPRECATED 2026-08-10: this was a second Redis master switch, and the settings class that - # bound it was removed with the previous Redis generation, so the key reached nothing. - # APP_REDIS_ENABLED is the sole global activation authority; the cache role is selected by - # app.capabilities.cache.bindings.default. The row is kept rather than deleted so a - # deployment still setting this key can be told what replaced it. + # 폐기 2026-08-10: 두 번째 Redis 전체 스위치였고, 이를 바인딩하던 settings class를 옛 Redis 세대와 함께 + # 지워서 이 키는 어디에도 닿지 않는다. 전역 켜기는 APP_REDIS_ENABLED 하나가 정한다. 캐시 role은 + # app.capabilities.cache.bindings.default가 고른다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 + # 행을 지우지 않고 둔다. deprecated_orphaned: true deprecated_alias_for: APP_REDIS_ENABLED removal_deadline: 2026-11-30 @@ -2414,9 +2400,8 @@ env_keys: required_test: adapter-contract:redis-disabled-default - name: APP_CACHE_REDIS_CLIENT_MODE - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: enum @@ -2431,12 +2416,11 @@ env_keys: required_test: adapter-contract:redis-client-mode-explicit - name: APP_CACHE_REDIS_HOST - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # source: feature-cache-consistency-contract — Redis adapter (활성화 시 endpoint 필요) + # 출처: feature-cache-consistency-contract — Redis adapter (켜면 endpoint가 필요하다) type: string default: null allowed_values: null @@ -2449,12 +2433,11 @@ env_keys: required_test: cache-contract:redis-host-when-enabled - name: APP_CACHE_REDIS_PORT - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # source: feature-cache-consistency-contract — Redis adapter endpoint + # 출처: feature-cache-consistency-contract — Redis adapter endpoint type: int default: 6379 allowed_values: null @@ -2467,9 +2450,8 @@ env_keys: required_test: cache-contract:redis-port-bound - name: APP_CACHE_REDIS_PASSWORD - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -2484,8 +2466,8 @@ env_keys: required_test: secrets-contract:redis-password-no-leak - name: APP_CACHE_REDIS_TRUST_PEM - # DEPRECATED 2026-08-10: the cache no longer owns a Redis client of its own, so no code reads this. - # Replaced by: app.redis.tls.trust-material-resource (APP_REDIS_TLS_TRUST_MATERIAL_RESOURCE), which the one Redis client uses for every capability. + # 폐기 2026-08-10: 캐시는 이제 자기 Redis client를 갖지 않아서 이 값을 읽는 코드가 없다. + # 대체: app.redis.tls.trust-material-resource (APP_REDIS_TLS_TRUST_MATERIAL_RESOURCE). Redis client 하나가 모든 capability에 이 값을 쓴다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -2500,9 +2482,8 @@ env_keys: required_test: redis-contract:cache-trust-material-no-leak - name: APP_REDIS_SEMANTIC_PROBE_MINIMUM_INTERVAL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -2517,9 +2498,8 @@ env_keys: required_test: redis-contract:semantic-probe-cadence-bounded - name: APP_REDIS_SENTINEL_DISCOVERY_REFRESH_PERIOD - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -2534,9 +2514,8 @@ env_keys: required_test: redis-contract:sentinel-discovery-refresh-period-bounded - name: APP_REDIS_SEMANTIC_PROBE_MAXIMUM_STALENESS - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -2551,9 +2530,8 @@ env_keys: required_test: redis-contract:semantic-probe-staleness-bounded - name: APP_CACHE_REDIS_KEY_HMAC_SECRET - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -2568,9 +2546,8 @@ env_keys: required_test: cache-contract:redis-hmac-secret-bounded - name: APP_CACHE_REDIS_COMMAND_TIMEOUT - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -2585,9 +2562,8 @@ env_keys: required_test: cache-contract:redis-command-timeout-bounded - name: APP_CACHE_REDIS_MAXIMUM_QUEUED_COMMANDS - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2602,9 +2578,8 @@ env_keys: required_test: cache-contract:redis-command-queue-bounded - name: APP_CACHE_REDIS_MAXIMUM_IN_FLIGHT_BYTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2631,9 +2606,9 @@ env_keys: required_test: cache-contract:redis-soft-hard-ttl-order - name: APP_CACHE_REDIS_TTL_JITTER - # DEPRECATED 2026-11-02: no settings class binds it. Its only reader was a block in the - # sample module's application.yml that nothing bound either (07-10), removed with it. - # Kept so a deployment still setting it is told it does nothing. + # 폐기 2026-11-02: 바인딩하는 settings class가 없다. 읽던 곳은 샘플 모듈 application.yml의 블록 하나뿐이었고 + # 그것도 바인딩되지 않았다(07-10). 샘플과 함께 지웠다. 아직 이 키를 쓰는 배포에 아무 일도 하지 않는다고 + # 알려 주려고 둔다. deprecated_orphaned: true removal_deadline: 2027-02-28 type: float @@ -2660,12 +2635,10 @@ env_keys: required_test: cache-contract:redis-hard-ttl-minimum - name: APP_CACHE_REDIS_NAMESPACE_ENVIRONMENT - # DEPRECATED 2026-08-10: the cache no longer renders its own key prefix. Four capabilities - # each joining two free-form tokens produced four prefixes, and the ACL pattern that was meant - # to fence the deployment in matched none of them. The row is kept (not deleted) so a - # deployment still setting it can be told what replaced it. - # Replaced by: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT), shared by - # every capability. + # 폐기 2026-08-10: 캐시는 이제 key prefix를 스스로 만들지 않는다. capability 넷이 각자 자유 형식 토큰 둘을 + # 이어 prefix 넷이 생겼고, 배포를 가두려던 ACL 패턴은 그중 어느 것과도 맞지 않았다. 아직 이 키를 쓰는 + # 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. + # 대체: app.redis.namespace.environment (APP_REDIS_NAMESPACE_ENVIRONMENT). 모든 capability가 함께 쓴다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -2680,9 +2653,8 @@ env_keys: required_test: cache-contract:redis-namespace-environment-bound - name: APP_CACHE_REDIS_SEMANTIC_REGION - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: string @@ -2697,9 +2669,8 @@ env_keys: required_test: cache-contract:redis-semantic-region-bound - name: APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2714,9 +2685,8 @@ env_keys: required_test: cache-contract:redis-value-size-bounded - name: APP_CACHE_REDIS_L1_ENABLED - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: boolean @@ -2731,9 +2701,8 @@ env_keys: required_test: cache-contract:redis-l1-disabled-default - name: APP_CACHE_REDIS_L1_MAXIMUM_ENTRIES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2748,9 +2717,8 @@ env_keys: required_test: cache-contract:redis-l1-cardinality-bounded - name: APP_CACHE_REDIS_L1_MAXIMUM_WEIGHT_BYTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2765,9 +2733,8 @@ env_keys: required_test: cache-contract:redis-l1-weight-bounded - name: APP_CACHE_REDIS_L1_MAXIMUM_ENTRY_WEIGHT_BYTES - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2782,9 +2749,8 @@ env_keys: required_test: cache-contract:redis-l1-entry-weight-bounded - name: APP_CACHE_REDIS_L1_TTL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -2799,9 +2765,8 @@ env_keys: required_test: cache-contract:redis-l1-ttl-bounded - name: APP_CACHE_REDIS_L1_GENERATION_RECHECK_INTERVAL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: duration @@ -2816,9 +2781,8 @@ env_keys: required_test: cache-contract:redis-l1-generation-recheck-bounded - name: APP_CACHE_REDIS_L1_INVALIDATION_QUEUE_CAPACITY - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 type: int @@ -2833,12 +2797,11 @@ env_keys: required_test: cache-contract:redis-l1-invalidation-queue-bounded - name: APP_CACHE_DEFAULT_TTL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # source: feature-cache-consistency-contract 2026-05-22 + # 출처: feature-cache-consistency-contract 2026-05-22 # "TTL | explicit per key family | no-cache for sensitive data | immortal cache forbidden" type: duration default: 300s @@ -2852,12 +2815,11 @@ env_keys: required_test: cache-contract:default-ttl-bounded - name: APP_CACHE_NEGATIVE_TTL - # DEPRECATED 2026-08-10: the settings class that bound this property was removed - # with the previous Redis generation, so the key reached nothing. The row is kept - # (not deleted) so a deployment still setting it can be told what replaced it. + # 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도 + # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # source: feature-cache-consistency-contract 2026-05-22 + # 출처: feature-cache-consistency-contract 2026-05-22 # "negative cache 정책 = 존재하지 않는 row는 짧은 TTL(60s) 캐싱 허용" type: duration default: 60s @@ -2870,15 +2832,15 @@ env_keys: compatibility_impact: additive required_test: cache-contract:negative-ttl-bounded - # === Messaging / Kafka (feature-domain-event-outbox-contract + integration-adapter-templates) === + # === 메시징 / Kafka (feature-domain-event-outbox-contract + integration-adapter-templates) === - name: APP_MESSAGING_BROKER - # source: messaging multi-broker redesign 2026-06-16 — single active broker selection - # (app.messaging.broker=), read by the vendored messaging platform. Replaces the - # former Kafka-binary APP_MESSAGING_KAFKA_ENABLED. The application bridge no longer reads it: - # the legacy KafkaSender seam that did was removed with the canonical outbox (2026-09-28). + # 출처: messaging multi-broker redesign 2026-06-16 — 활성 broker 하나를 고른다 + # (app.messaging.broker=). 들여온 메시징 플랫폼이 읽는다. 옛 Kafka 전용 APP_MESSAGING_KAFKA_ENABLED를 + # 대신한다. 애플리케이션 bridge는 이제 읽지 않는다: 읽던 옛 KafkaSender seam은 canonical outbox와 함께 + # 지웠다(2026-09-28). type: string - # The Kafka module's config/module-defaults/messaging.yml defaults it to kafka, the only registered broker. + # Kafka 모듈의 config/module-defaults/messaging.yml이 기본값을 등록된 유일한 broker인 kafka로 둔다. default: kafka allowed_values: null classification: public-config @@ -2890,11 +2852,11 @@ env_keys: required_test: adapter-contract:messaging-broker-selection - name: APP_MESSAGING_PRODUCER_ID - # source: canonical messaging platform bridge 2026-09-18 - # Explicit logical producing-service identity for IntegrationEventPublishPort. - # Blank/absent = canonical platform bridge is not exposed; identity is never inferred. - # Every publication, the outbox relay's included, goes through that bridge, so with the - # messaging module present and on a blank value refuses startup (2026-09-28 canonical outbox). + # 출처: canonical messaging platform bridge 2026-09-18 + # IntegrationEventPublishPort가 쓰는, 메시지를 내는 서비스의 논리 이름(명시값). + # 비었거나 없음 = canonical 플랫폼 bridge를 내놓지 않는다. 이름을 짐작하지 않는다. + # outbox relay를 포함해 모든 발행이 그 bridge를 거치므로, 메시징 모듈이 있고 켜진 상태에서 값이 비면 기동을 + # 거부한다(2026-09-28 canonical outbox). type: string default: null allowed_values: null @@ -2908,11 +2870,10 @@ env_keys: required_test: adapter-contract:messaging-platform-producer-id - name: APP_MESSAGING_KAFKA_BROKERS - # source: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter" - # (broker 활성화 시 endpoint 필요) - # Feeds app.messaging.brokers.kafka.bootstrap-servers (the messaging platform's Kafka - # transport) through the Kafka module's config/module-defaults/messaging.yml. - # spring.kafka.bootstrap-servers is not read. + # 출처: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter" + # (broker를 켜면 endpoint가 필요하다) + # Kafka 모듈의 config/module-defaults/messaging.yml을 거쳐 app.messaging.brokers.kafka.bootstrap-servers + # (메시징 플랫폼의 Kafka transport)로 간다. spring.kafka.bootstrap-servers는 읽지 않는다. type: csv_list default: null allowed_values: null @@ -2924,10 +2885,10 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:kafka-brokers-when-enabled - # === Notification adapters (feature-integration-adapter-templates) === + # === 알림 adapter (feature-integration-adapter-templates) === - name: APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED - # source: R0 Slack webhook provider gate; maps to app.notification.slack-webhook.enabled + # 출처: R0 Slack webhook provider 스위치. app.notification.slack-webhook.enabled로 이어진다 type: boolean default: false allowed_values: [true, false] @@ -2940,7 +2901,7 @@ env_keys: required_test: adapter-contract:notification-slack-provider-selection - name: APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED - # source: R0 Google email provider gate; maps to app.notification.google-email.enabled + # 출처: R0 Google email provider 스위치. app.notification.google-email.enabled로 이어진다 type: boolean default: false allowed_values: [true, false] @@ -2952,22 +2913,20 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:notification-email-provider-selection - # === HTTP Client platform (app.httpclient.*) === + # === HTTP Client 플랫폼 (app.httpclient.*) === # - # Only the enabled key is registered here. The per-client surface is an indexed list whose - # element cannot be templated in application.yml without materialising a nameless client in every - # deployment, so it has no deployment-independent value for this registry to hold and is - # registered in docs/httpclient/env-fields.yaml instead. That manifest is derived from - # HttpClientPlatformSettings and enforced in both directions: a field with no entry fails - # HttpClientPlatformEnvManifestTest, and an APP_HTTPCLIENT_ variable with no field fails startup. + # 여기에는 enabled 키만 등록한다. client별 설정은 index가 붙은 목록이라, application.yml에 틀로 적으면 모든 + # 배포에 이름 없는 client가 생긴다. 그래서 배포와 상관없는 값이 없어 이 레지스트리에 둘 것이 없고, + # docs/httpclient/env-fields.yaml에 등록한다. 그 manifest는 HttpClientPlatformSettings에서 나오고 양쪽으로 + # 강제된다: 항목이 없는 필드는 HttpClientPlatformEnvManifestTest가 실패하고, 필드가 없는 APP_HTTPCLIENT_ + # 변수는 기동이 실패한다. - name: APP_HTTPCLIENT_ENABLED - # 2026-09-25 capability packaging: the module is on when present (its own config yml maps - # this key with default true); false is the explicit off. Absent from the build is the - # ordinary off state. - # While false the platform block is not bound at all: the auto-configuration that - # binds it is not processed, so no bean, connection pool, TLS context, credential, thread or - # gateway exists, and a malformed HTTP client setting cannot fail this deployment's startup. + # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). + # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # false인 동안 플랫폼 블록을 전혀 바인딩하지 않는다: 바인딩하는 자동 설정을 처리하지 않으므로 bean, + # connection pool, TLS context, 자격 증명, thread, gateway가 생기지 않고, 잘못된 HTTP client 설정이 이 배포의 + # 기동을 실패시킬 수 없다. type: boolean default: true allowed_values: [true, false] @@ -2980,10 +2939,9 @@ env_keys: required_test: httpclient-platform:off-state-zero-side-effects-and-env-manifest-parity - name: APP_HTTPCLIENT_ROTATION_DRAIN_TIMEOUT - # How long a retired runtime generation may keep draining after a certificate rotation before - # its connection pool is closed underneath whatever is still in flight. Rotation replaces a - # generation rather than mutating material in place, because a pool holds sockets established - # under the previous identity; this value is how long the old identity is allowed to finish. + # 인증서를 교체한 뒤, 물러난 런타임 세대가 처리 중인 것을 마저 끝낼 수 있는 기간. 이 시간이 지나면 + # 그 connection pool을 닫는다. 교체는 자료를 제자리에서 바꾸지 않고 세대를 바꾼다. pool이 옛 신원으로 맺은 + # 소켓을 들고 있기 때문이다. 이 값이 옛 신원이 일을 끝낼 수 있는 시간이다. type: duration default: 30s classification: public-config @@ -2996,11 +2954,10 @@ env_keys: # === Fileserver HTTP platform (app.fileserver-platform.*) === - name: APP_FILESERVER_PLATFORM_ENABLED - # 2026-09-25 capability packaging: the module is on when present (its own config yml maps - # this key with default true); false is the explicit off. Absent from the build is the - # ordinary off state. - # While false the platform block is not bound at all: the auto-configuration that - # binds it is not processed, so no bean, route, thread, schema check or filesystem call exists. + # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). + # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # false인 동안 플랫폼 블록을 전혀 바인딩하지 않는다: 바인딩하는 자동 설정을 처리하지 않으므로 bean, route, + # thread, schema 검사, 파일 시스템 호출이 생기지 않는다. type: boolean default: true allowed_values: [true, false] @@ -3013,8 +2970,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_INSTANCE_ID - # Writer-lease owner; must be unique per instance. The startup gate treats the default as - # single-instance and refuses a shared-metadata claim it cannot support. + # writer lease의 소유자. 인스턴스마다 달라야 한다. 기동 관문은 기본값을 단일 인스턴스로 보고, 지원할 수 + # 없는 공유 메타데이터 claim을 거부한다. type: string default: local-node allowed_values: null @@ -3027,7 +2984,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DEFAULT_NAMESPACE - # Namespace applied to a request that does not name one. + # namespace를 적지 않은 요청에 쓰는 namespace. type: string default: default allowed_values: null @@ -3040,8 +2997,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_TARGET_NAMESPACES - # Namespaces copy and move may write into besides the default namespace, which is always - # allowed. Empty means the default namespace only; any other target is ACCESS_DENIED. + # copy와 move가 기본 namespace(늘 허용) 밖에 쓸 수 있는 namespace. 비면 기본 namespace만이고, 다른 + # 대상은 ACCESS_DENIED다. type: csv_list default: null allowed_values: null @@ -3054,8 +3011,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_STORAGE_ROOT - # Absolute path on its own volume. A relative root resolves against the process working - # directory, which differs between a container and a test, so it is refused. + # 자기 volume 위의 절대 경로. 상대 경로는 프로세스 실행 위치를 기준으로 풀리는데, 그 위치가 container와 + # 테스트에서 달라서 거부한다. type: string default: /var/lib/backend/files allowed_values: null @@ -3068,7 +3025,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_STORAGE_PUBLISH_MODE - # atomic-move-required fails startup when the probe cannot prove an atomic rename. + # atomic-move-required는 확인 과정이 원자적 이름 바꾸기를 증명하지 못하면 기동을 실패시킨다. type: string default: atomic-move-preferred allowed_values: [atomic-move-required, atomic-move-preferred, metadata-pointer] @@ -3081,7 +3038,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_STORAGE_BUFFER_SIZE - # Bounds every transfer allocation, so resident bytes never scale with file size. + # 모든 전송의 할당을 제한한다. 그래서 메모리에 머무는 바이트가 파일 크기에 따라 늘지 않는다. type: data_size default: 128KB allowed_values: null @@ -3094,8 +3051,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_STORAGE_FORBIDDEN_ROOT_ANCESTORS - # A storage root under a web root turns every upload into a published file; under a config - # root, into a configuration change. Both are refused at binding time. + # web root 아래의 저장소 root는 모든 업로드를 공개 파일로 만들고, config root 아래면 설정 변경으로 + # 만든다. 둘 다 바인딩할 때 거부한다. type: csv_list default: /app,/etc,/usr/share/nginx/html allowed_values: null @@ -3108,8 +3065,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_MAX_FILE_SIZE - # Also drives spring.servlet.multipart.max-file-size. One placeholder for both: a smaller - # servlet ceiling rejects the upload before any Fileserver code, including its error mapping. + # spring.servlet.multipart.max-file-size도 이 값이 정한다. 둘에 자리표시자 하나다: servlet 상한이 더 + # 작으면 Fileserver 코드(오류 매핑 포함)에 닿기 전에 업로드를 거부한다. type: data_size default: 100MB allowed_values: null @@ -3135,7 +3092,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_INITIAL_RESERVATION - # Quota reserved for an upload that does not declare its length. + # 길이를 밝히지 않은 업로드에 잡아 두는 할당량. type: data_size default: 8MB allowed_values: null @@ -3148,7 +3105,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_MAX_PARTS - # Ceiling on parts in one multipart/batch request. + # multipart/batch 요청 하나의 part 수 상한. type: integer default: 16 allowed_values: null @@ -3161,7 +3118,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_TTL - # Lifetime of an upload resource before it is reclaimable. + # 업로드 자원을 회수할 수 있게 되기까지의 수명. type: duration default: 1h allowed_values: null @@ -3174,7 +3131,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_RESERVATION_TTL - # Lifetime of a quota reservation whose upload never completed. + # 업로드가 끝나지 않은 할당량 예약의 수명. type: duration default: 24h allowed_values: null @@ -3187,8 +3144,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_LEASE_DURATION - # Writer lease. Renewed at one third of this while a transfer runs; a transfer that cannot - # renew is fenced out before its next physical write. + # writer lease. 전송하는 동안 이 값의 1/3마다 갱신한다. 갱신하지 못한 전송은 다음 실제 쓰기 전에 + # 막힌다(fenced). type: duration default: 30s allowed_values: null @@ -3201,7 +3158,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_UPLOAD_REQUIRE_CONTENT_LENGTH - # When true a raw upload without Content-Length is refused with 411. + # true면 Content-Length 없는 raw 업로드를 411로 거부한다. type: boolean default: false allowed_values: [true, false] @@ -3214,7 +3171,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DOWNLOAD_CACHE_CONTROL - # Cache-Control emitted on every download response. + # 모든 다운로드 응답에 붙이는 Cache-Control. type: string default: private, no-store allowed_values: null @@ -3227,7 +3184,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DOWNLOAD_INLINE_ALLOWED - # Inline rendering is off by default; scriptable content is forced to attachment regardless. + # inline 표시는 기본으로 꺼져 있다. script가 돌 수 있는 내용은 설정과 상관없이 attachment로 보낸다. type: boolean default: false allowed_values: [true, false] @@ -3240,7 +3197,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGES - # Multi-range is opt-in; above one the response is multipart/byteranges. + # 여러 범위 요청은 켜야 쓴다. 둘 이상이면 응답이 multipart/byteranges다. type: integer default: 1 allowed_values: null @@ -3253,8 +3210,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGE_BYTES - # Applies to the single-range profile too, so the ceiling is not inert in the default - # configuration that almost every deployment runs. + # 범위 하나 profile에도 적용한다. 그래서 거의 모든 배포가 쓰는 기본 설정에서도 상한이 실제로 + # 작동한다. type: data_size default: 100MB allowed_values: null @@ -3267,7 +3224,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_ENABLED - # Changes only where bytes are copied, never a header or a status. + # 바이트를 복사하는 곳만 바꾼다. 헤더나 상태 코드는 바꾸지 않는다. type: boolean default: true allowed_values: [true, false] @@ -3280,7 +3237,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_MINIMUM_BYTES - # Below this the syscall setup costs more than it saves. + # 이보다 작으면 syscall 준비 비용이 아끼는 것보다 크다. type: data_size default: 16MB allowed_values: null @@ -3293,7 +3250,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_TRANSFER_CORE_SIZE - # Bounded transfer pool; rejection becomes a retryable 429, never caller-runs. + # 크기가 정해진 전송 pool. 거절은 다시 시도할 수 있는 429가 되고, 호출자 스레드에서 돌리지 않는다. type: integer default: 8 allowed_values: null @@ -3306,7 +3263,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_TRANSFER_MAX_SIZE - # Upper bound of the transfer pool. + # 전송 pool의 상한. type: integer default: 32 allowed_values: null @@ -3319,7 +3276,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_TRANSFER_QUEUE_CAPACITY - # Bounded queue; an unbounded one trades a fast 429 for eventual heap exhaustion. + # 크기가 정해진 queue. 무한 queue는 빠른 429를 결국 heap 고갈로 바꾼다. type: integer default: 64 allowed_values: null @@ -3332,7 +3289,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_TRANSFER_AWAIT_SECONDS - # Shutdown drain and per-transfer caller wait. + # 종료 때 남은 일 정리 시간과 전송마다 호출자가 기다리는 시간. type: integer default: 300 allowed_values: null @@ -3345,8 +3302,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY - # No permissive default. `required` fails startup unless the deployment supplies a - # FileAccessPolicyPort bean; `unenforced` is refused under a production profile. + # 허용하는 기본값이 없다. `required`는 배포가 FileAccessPolicyPort bean을 주지 않으면 기동을 + # 실패시킨다. `unenforced`는 production profile에서 거부한다. type: string default: required allowed_values: [required, role-based, unenforced] @@ -3359,7 +3316,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_SECURITY_READ_ROLES - # Roles accepted for read operations under the role-based policy. + # role 기반 정책에서 읽기 연산에 받는 role. type: csv_list default: ROLE_FILE_READ allowed_values: null @@ -3372,7 +3329,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_SECURITY_WRITE_ROLES - # Roles accepted for write operations under the role-based policy. + # role 기반 정책에서 쓰기 연산에 받는 role. type: csv_list default: ROLE_FILE_WRITE allowed_values: null @@ -3385,8 +3342,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_SECURITY_ADMIN_ROLES - # Roles accepted for the management plane. Admin routes additionally require this role at the - # servlet chain, not only in application policy. + # 관리 기능(management plane)에 받는 role. admin route는 application 정책만이 아니라 servlet chain에서도 + # 이 role을 요구한다. type: csv_list default: ROLE_FILE_ADMIN allowed_values: null @@ -3399,7 +3356,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_VERIFICATION_TIMEOUT - # Whole-chain verification budget for one upload. + # 업로드 하나의 검증 사슬 전체 예산. type: duration default: 5s allowed_values: null @@ -3412,7 +3369,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_VERIFICATION_REQUIRE_MEDIA_TYPE_VERDICT - # When true a file whose type could not be determined is refused rather than published. + # true면 형식을 알아내지 못한 파일을 공개하지 않고 거부한다. type: boolean default: false allowed_values: [true, false] @@ -3425,8 +3382,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_VERIFICATION_INLINE_SAFE_PROFILE - # When true scriptable content is accepted instead of quarantined; only safe when downloads - # are never served inline from a trusted origin. + # true면 script가 돌 수 있는 내용을 격리하지 않고 받는다. 다운로드를 신뢰하는 origin에서 inline으로 + # 절대 내주지 않을 때만 안전하다. type: boolean default: false allowed_values: [true, false] @@ -3439,7 +3396,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_INSTANCE_UPLOAD_PERMITS - # Concurrent uploads admitted per instance. + # 인스턴스마다 받는 동시 업로드 수. type: integer default: 16 allowed_values: null @@ -3452,7 +3409,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_SCOPE_UPLOAD_PERMITS - # Concurrent uploads admitted per caller (principal). + # 호출자(principal)마다 받는 동시 업로드 수. type: integer default: 4 allowed_values: null @@ -3465,7 +3422,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_DIRECT_DOWNLOAD_PERMITS - # Concurrent direct downloads admitted per instance. + # 인스턴스마다 받는 동시 직접 다운로드 수. type: integer default: 64 allowed_values: null @@ -3478,7 +3435,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_SOFT_HIGH_WATER - # Storage fraction at which new uploads start being shed. + # 새 업로드를 덜어내기 시작하는 저장소 사용 비율. type: string default: 0.70 allowed_values: null @@ -3491,7 +3448,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_HARD_HIGH_WATER - # Storage fraction at which every upload is refused. + # 모든 업로드를 거부하는 저장소 사용 비율. type: string default: 0.85 allowed_values: null @@ -3504,8 +3461,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT - # Most bytes one namespace may hold, live reservations plus committed usage. Empty means - # unlimited; a reservation past a set limit is refused with QUOTA_EXCEEDED (413). + # namespace 하나가 가질 수 있는 최대 바이트(살아 있는 예약과 확정된 사용량의 합). 비면 무제한이다. 정한 + # 상한을 넘는 예약은 QUOTA_EXCEEDED(413)로 거부한다. type: data_size default: null allowed_values: null @@ -3518,8 +3475,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_ADMIN_ENABLED - # Management plane, a separate decision from the data plane. Requires APP_FILESERVER_PLATFORM_ENABLED too: - # enabling it alone now does nothing instead of half-building a bean graph. + # 관리 기능(management plane). 데이터 기능과 따로 정한다. APP_FILESERVER_PLATFORM_ENABLED도 켜야 한다: + # 이 값만 켜면 이제 bean 그래프를 반쯤 만들지 않고 아무 일도 하지 않는다. type: boolean default: false allowed_values: [true, false] @@ -3532,8 +3489,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_ADMIN_ORPHAN_MINIMUM_AGE - # How long an unreferenced object must exist before a scan may name it; anything younger is - # assumed mid-commit rather than abandoned. + # 참조가 없는 객체가 scan에 이름이 오르기까지 있어야 하는 기간. 그보다 어린 것은 버려진 것이 아니라 + # 확정하는 중이라고 본다. type: duration default: 1h allowed_values: null @@ -3546,9 +3503,9 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_CLEANUP_ENABLED - # Background reclamation. On by default: without it cancelled/expired staging and rejected or - # deleted content stay on the volume until the hard high-water mark stops uploads. Turning it - # off logs a startup warning (another node or the admin plane must reclaim instead). + # 뒤에서 도는 회수. 기본으로 켜져 있다: 없으면 취소·만료된 staging과 거부·삭제된 내용이 volume에 남아, + # 결국 높은 수위(high-water mark)가 업로드를 막는다. 끄면 기동 때 경고를 남긴다(다른 노드나 관리 기능이 + # 대신 회수해야 한다). type: boolean default: true allowed_values: [true, false] @@ -3561,8 +3518,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_CLEANUP_INTERVAL - # Fixed delay between batches; sole owner of the schedule, with no @Scheduled placeholder - # carrying a second default. + # batch 사이의 고정 지연. 일정의 유일한 주인이다. 두 번째 기본값을 가진 @Scheduled 자리표시자를 두지 + # 않는다. type: duration default: 60s allowed_values: null @@ -3575,7 +3532,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_CLEANUP_MAX_ITEMS - # Item ceiling for one batch, so a backlog cannot monopolise the scheduler. + # batch 하나의 항목 수 상한. 밀린 일이 scheduler를 독차지하지 못하게 한다. type: integer default: 100 allowed_values: null @@ -3588,7 +3545,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_CLEANUP_MAX_BYTES - # Byte ceiling for one batch. + # batch 하나의 바이트 상한. type: data_size default: 1GB allowed_values: null @@ -3601,7 +3558,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_CLEANUP_RETRY_BACKOFF - # Delay before a failed cleanup item is retried. + # 실패한 정리 항목을 다시 시도하기 전 지연. type: duration default: 5m allowed_values: null @@ -3614,7 +3571,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_TUS_ENABLED - # tus 1.0. Requires APP_FILESERVER_PLATFORM_ENABLED too. + # tus 1.0. APP_FILESERVER_PLATFORM_ENABLED도 켜야 한다. type: boolean default: false allowed_values: [true, false] @@ -3627,7 +3584,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_HTTPBIS_DRAFT12_ENABLED - # Unratified draft whose contract can change without notice. Requires APP_FILESERVER_PLATFORM_ENABLED too. + # 승인되지 않은 초안이라 계약이 예고 없이 바뀔 수 있다. APP_FILESERVER_PLATFORM_ENABLED도 켜야 한다. type: boolean default: false allowed_values: [true, false] @@ -3640,8 +3597,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_NGINX_ENABLED - # Front-proxy delegation. Startup attests the internal mapping by exercising it; a mapping the - # proxy cannot resolve answers 200 with an empty body, so it fails closed instead. + # 앞단 proxy에 맡기기. 기동할 때 내부 매핑을 실제로 써 보고 확인한다. proxy가 풀지 못하는 매핑은 빈 + # 본문으로 200을 답하므로, 그대로 두지 않고 실패시킨다(fail closed). type: boolean default: false allowed_values: [true, false] @@ -3654,7 +3611,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_NGINX_INTERNAL_PREFIX - # Internal location the proxy resolves to the storage root. + # proxy가 저장소 root로 풀어 주는 내부 위치. type: string default: /__files/ allowed_values: null @@ -3667,7 +3624,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_NGINX_OBJECT_SUFFIX - # Suffix appended to the sharded object key in the internal URI. + # 내부 URI에서 shard로 나눈 객체 key 뒤에 붙이는 접미사. type: string default: .bin allowed_values: null @@ -3680,7 +3637,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_NGINX_MINIMUM_SIZE - # Below this the request is served by the application rather than delegated. + # 이보다 작은 요청은 맡기지 않고 애플리케이션이 직접 내준다. type: data_size default: 16MB allowed_values: null @@ -3693,7 +3650,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_OBSERVABILITY_METRICS_ENABLED - # When false neither the metrics port nor the fingerprint is created, and no key is required. + # false면 metrics port도 fingerprint도 만들지 않고 key도 요구하지 않는다. type: boolean default: true allowed_values: [true, false] @@ -3706,8 +3663,8 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY - # Keyed HMAC over file identifiers. An unkeyed digest of an enumerable identifier is - # reversible, so startup fails while metrics are on and this is blank. + # 파일 식별자에 거는 key 있는 HMAC. 셀 수 있는 식별자의 key 없는 digest는 되돌릴 수 있으므로, metrics가 + # 켜졌는데 이 값이 비면 기동이 실패한다. type: string default: null allowed_values: null @@ -3719,10 +3676,10 @@ env_keys: compatibility_impact: additive required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - # === File / Upload (feature-file-resource-handling-contract) === + # === 파일 / 업로드 (feature-file-resource-handling-contract) === - name: APP_ASYNC_EXECUTOR_CORE_SIZE - # source: feature-background-job-async-contract 2026-05-22 + # 출처: feature-background-job-async-contract 2026-05-22 # "executor pool sizing default = core=10, max=50, queue=200" type: int default: 10 @@ -3736,7 +3693,7 @@ env_keys: required_test: async-contract:executor-core-size - name: APP_ASYNC_EXECUTOR_MAX_SIZE - # source: feature-background-job-async-contract 2026-05-22 + # 출처: feature-background-job-async-contract 2026-05-22 # "core=10, max=50, queue=200" type: int default: 50 @@ -3750,7 +3707,7 @@ env_keys: required_test: async-contract:executor-max-size - name: APP_ASYNC_EXECUTOR_QUEUE_CAPACITY - # source: feature-background-job-async-contract 2026-05-22 + # 출처: feature-background-job-async-contract 2026-05-22 # "queue=200" + "unbounded queue forbidden" type: int default: 200 @@ -3763,18 +3720,15 @@ env_keys: compatibility_impact: behavior-change required_test: async-contract:executor-queue-bounded - # === Notification delivery platform (NTF-025 — configuration surface) === - # The tree exists in application.yml as app.notification.platform, disabled by - # default. Every key carries an inline default so a deployment that leaves the platform off - # supplies nothing. Reference: docs/notification/configuration.md. + # === 알림 전달 플랫폼 (NTF-025 — 설정 표면) === + # application.yml에 app.notification.platform 트리가 있고 기본으로 꺼져 있다. 모든 키가 같은 줄에 기본값을 + # 가지므로, 플랫폼을 끈 배포는 아무것도 주지 않아도 된다. 참고: docs/notification/configuration-reference.md. - name: APP_PERSISTENCE_JPA_ENABLED - # source: five-adapter-runtime-remediation §5.1 — switch for relational persistence, shipped by - # the persistence-jpa module itself (config/module-defaults/persistence-jpa.yml). The module is - # selected by one build line and is on while present; false switches off this module's beans - # (entity scan, repositories, stores, startup guards). Removing the build line removes the - # capability and this key's only reader. The old app.jpa-platform.enabled gated three add-on - # beans while reading like this one. + # 출처: five-adapter-runtime-remediation §5.1 — 관계형 영속성 스위치. persistence-jpa 모듈이 직접 + # 가진다(config/module-defaults/persistence-jpa.yml). 모듈은 빌드 한 줄로 고르고, 있는 동안 켜진다. false면 + # 이 모듈의 bean(entity scan, repository, store, 기동 관문)을 끈다. 빌드 줄을 지우면 기능과 이 키를 읽는 유일한 + # 곳이 함께 사라진다. 옛 app.jpa-platform.enabled는 이 키처럼 읽혔지만 부가 bean 셋만 막았다. type: boolean default: true allowed_values: [true, false] @@ -3861,10 +3815,9 @@ env_keys: required_test: jpa-contract:hibernate-runtime-settings - name: APP_PERSISTENCE_MONGO_ENABLED - # 2026-09-25 capability packaging: the module is on when present (its own config yml maps - # this key with default true); false is the explicit off. Absent from the build is the - # ordinary off state. - # source: five-adapter-runtime-remediation §5.1 — on/off key for MongoDB persistence. + # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). + # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # 출처: five-adapter-runtime-remediation §5.1 — MongoDB 영속성 켜고 끄기. type: boolean default: true allowed_values: [true, false] @@ -3876,9 +3829,8 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:persistence-mongo-disabled-safe - name: APP_PERSISTENCE_MONGO_ACTIVE_PROFILE - # source: five-adapter-runtime-remediation §5.1 — selects exactly one Mongo profile. The runtime - # builds one sync client and one pool; a profile present in the map but not selected has neither - # its secret resolved nor a client created. + # 출처: five-adapter-runtime-remediation §5.1 — Mongo profile을 정확히 하나 고른다. 런타임은 sync client + # 하나와 pool 하나를 만든다. map에 있지만 고르지 않은 profile은 비밀을 풀지도, client를 만들지도 않는다. type: string default: "" classification: public-config @@ -3890,15 +3842,15 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:persistence-mongo-active-profile - name: SPRING_MONGODB_URI - # source: persistence-mongo techlead review C1. Spring Boot 4 consumes this native key as - # spring.mongodb.uri. It is one of two valid connection sources; the alternate is the selected - # typed profile's uri-secret resolved through MongoCredentialResolver. + # 출처: persistence-mongo techlead review C1. Spring Boot 4는 이 자체 키를 spring.mongodb.uri로 쓴다. + # 유효한 연결 출처 둘 중 하나다. 다른 하나는 고른 typed profile의 uri-secret을 MongoCredentialResolver로 푼 + # 값이다. type: string default: null allowed_values: null classification: sensitive-config required: false - required_when: app.persistence-mongo.enabled=true AND no active-profile uri-secret + required_when: app.persistence-mongo.enabled=true이고 활성 profile의 uri-secret이 없을 때 reload_policy: restart-only owner_branch: persistence-mongo-runtime-remediation validation: mongodb_uri_when_selected_as_connection_source @@ -3906,11 +3858,10 @@ env_keys: required_test: adapter-contract:persistence-mongo-connection-source - name: APP_MESSAGING_ENABLED - # 2026-09-25 capability packaging: the module is on when present (its own config yml maps - # this key with default true); false is the explicit off. Absent from the build is the - # ordinary off state. - # source: five-adapter-runtime-remediation §5.1 — on/off key for broker publication. - # APP_MESSAGING_BROKER selects which transport and is no longer the de-facto switch. + # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). + # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # 출처: five-adapter-runtime-remediation §5.1 — broker 발행 켜고 끄기. + # APP_MESSAGING_BROKER는 어느 transport인지만 고르고, 이제 사실상의 스위치가 아니다. type: boolean default: true allowed_values: [true, false] @@ -3921,15 +3872,14 @@ env_keys: validation: boolean compatibility_impact: behavior-change required_test: adapter-contract:messaging-disabled-safe - # === Optional WebSocket build-composition contract === - # These keys map directly to app.websocket.* when the websocket leaf is present in a chosen - # composition. The default bootJar does not contain that leaf; presence remains a build-time - # decision and these rows do not imply runtime membership. + # === 선택형 WebSocket 빌드 조립 계약 === + # 고른 조립에 websocket leaf가 있으면 이 키들이 app.websocket.*로 바로 이어진다. 기본 bootJar에는 그 leaf가 + # 없다. 있을지는 빌드할 때 정하고, 이 행들이 런타임에 들어 있다는 뜻은 아니다. - name: APP_WEBSOCKET_ENABLED - # 2026-09-25 capability packaging: the module is on when present (its own config yml maps - # this key with default true); false is the explicit off. Absent from the build is the - # ordinary off state. + # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 + # 기본 true로 잇는다). false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 + # 보통의 꺼진 상태다. property: app.websocket.enabled owner_module: adapter-inbound-websocket type: boolean @@ -4000,7 +3950,7 @@ env_keys: required_test: websocket-contract:canonical-property-namespace - name: APP_WEBSOCKET_MESSAGE_SIZE_LIMIT - # Spring's own default, now explicit (review 03-06); at most 2147483647 bytes. + # Spring 자체 기본값을 명시했다(review 03-06). 최대 2147483647 bytes. property: app.websocket.message-size-limit owner_module: adapter-inbound-websocket type: data_size @@ -4015,7 +3965,7 @@ env_keys: required_test: websocket-contract:canonical-property-namespace - name: APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT - # Spring's own default, now explicit (review 03-06); at most 2147483647 bytes. + # Spring 자체 기본값을 명시했다(review 03-06). 최대 2147483647 bytes. property: app.websocket.send-buffer-size-limit owner_module: adapter-inbound-websocket type: data_size @@ -4030,7 +3980,7 @@ env_keys: required_test: websocket-contract:canonical-property-namespace - name: APP_WEBSOCKET_SEND_TIME_LIMIT - # Spring's own default, now explicit (review 03-06); at most 2147483647 ms. + # Spring 자체 기본값을 명시했다(review 03-06). 최대 2147483647 ms. property: app.websocket.send-time-limit owner_module: adapter-inbound-websocket type: duration @@ -4045,7 +3995,7 @@ env_keys: required_test: websocket-contract:canonical-property-namespace - name: APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE - # Spring's own default, now explicit (review 03-06); at most 2147483647 ms. + # Spring 자체 기본값을 명시했다(review 03-06). 최대 2147483647 ms. property: app.websocket.time-to-first-message owner_module: adapter-inbound-websocket type: duration @@ -4060,7 +4010,8 @@ env_keys: required_test: websocket-contract:canonical-property-namespace - name: APP_WEBSOCKET_MAX_CONNECTIONS - # New per-node STOMP session ceiling (review 03-06); the next session is closed with 1013. 1000 x 512KB send buffer bounds worst-case outbound buffering near 512 MiB. + # 노드마다의 새 STOMP session 상한(review 03-06). 그 다음 session은 1013으로 닫는다. 1000 x 512KB 송신 + # 버퍼라 최악의 송신 버퍼링이 512 MiB 근처로 묶인다. property: app.websocket.max-connections owner_module: adapter-inbound-websocket type: integer @@ -4075,10 +4026,9 @@ env_keys: required_test: websocket-contract:canonical-property-namespace - name: APP_OBJECTSTORAGE_ENABLED - # 2026-11-03 RR-06-07: the explicit off the Compose smoke wrapper sets for every lane that is - # not about object storage. It bound by relaxed binding and was in no registry, so the env - # contract could not tell it from an unread name. The module is on when present; absent from - # the build is the ordinary off state. + # 2026-11-03 RR-06-07: Compose smoke wrapper가 객체 저장소와 상관없는 모든 lane에 거는 명시적 끄기 값. + # relaxed binding으로 바인딩되면서 어느 레지스트리에도 없어, env 계약이 읽히지 않는 이름과 구별하지 못했다. + # 모듈은 있으면 켜진다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. property: app.object-storage.enabled owner_module: adapter-outbound-objectstorage type: boolean @@ -4092,9 +4042,9 @@ env_keys: compatibility_impact: none required_test: off-state-zero-side-effects-and-env-round-trip - name: APP_GRPC_SERVER_ENABLED - # 2026-11-03 RR-06-07: the explicit off for the gRPC server the Compose lanes set (it replaced - # CASKELETON_GRPC_ENABLED, which nothing read). The module is on when present; absent from the - # build is the ordinary off state. + # 2026-11-03 RR-06-07: Compose lane이 거는 gRPC 서버의 명시적 끄기 값(아무도 읽지 않던 + # CASKELETON_GRPC_ENABLED를 대신했다). 모듈은 있으면 켜진다. 빌드에 모듈이 없는 것이 보통의 꺼진 + # 상태다. property: app.grpc.server.enabled owner_module: adapter-inbound-grpc type: boolean @@ -4108,11 +4058,10 @@ env_keys: compatibility_impact: none required_test: off-state-zero-side-effects-and-env-round-trip - name: APP_GRAPHQL_ENABLED - # 2026-09-25 capability packaging: the module is on when present (its own config yml maps - # this key with default true); false is the explicit off. Absent from the build is the - # ordinary off state. - # source: five-adapter-runtime-remediation §5.1 — on/off key for the GraphQL transport. - # false publishes no /graphql route, including the one Spring GraphQL would publish by itself. + # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). + # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # 출처: five-adapter-runtime-remediation §5.1 — GraphQL transport 켜고 끄기. + # false면 /graphql route를 내지 않는다. Spring GraphQL이 스스로 내는 route도 포함이다. type: boolean default: true allowed_values: [true, false] @@ -4124,10 +4073,9 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:graphql-disabled-safe - name: APP_GRAPHQL_DEPLOYMENT_MODE - # source: five-adapter-runtime-remediation §5.1 / GQL-INT-002 — replaces app.graphql.production - # and app.graphql.environment, which defaulted to production=false with - # environment=PRODUCTION_PUBLIC and let anonymous-principal and allow-by-default authorization - # read one axis while the other claimed production. + # 출처: five-adapter-runtime-remediation §5.1 / GQL-INT-002 — app.graphql.production과 + # app.graphql.environment를 대신한다. 둘의 기본값이 production=false와 environment=PRODUCTION_PUBLIC이라, + # 익명 principal과 기본 허용 권한 검사는 한 축을 읽고 다른 축은 production이라 주장했다. type: enum default: "" allowed_values: [LOCAL, DEV, PRODUCTION_INTERNAL, PRODUCTION_PUBLIC] @@ -4290,9 +4238,9 @@ env_keys: required_test: graphql-contract:wired-operator-settings - name: APP_OUTBOX_ENABLED - # source: five-adapter-runtime-remediation §6.1 JPA-INT-004 — the outbox capability switch. - # relay-enabled below only starts the scheduler; conflating the two meant a relay-off deployment - # still assembled outbox metrics over a store port a database-less runtime does not have. + # 출처: five-adapter-runtime-remediation §6.1 JPA-INT-004 — outbox 기능 스위치. + # 아래 relay-enabled는 scheduler만 시작한다. 둘을 섞으면 relay를 끈 배포도 DB 없는 런타임에는 없는 store + # port 위에 outbox metrics를 조립했다. type: boolean default: false allowed_values: [true, false] @@ -4304,10 +4252,9 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:outbox-capability-disabled-safe - name: APP_OUTBOX_RELAY_ENABLED - # source: five-adapter-runtime-remediation §6.3 MSG-INT-001 — starts the relay scheduler. - # Requires APP_OUTBOX_ENABLED, APP_PERSISTENCE_JPA_ENABLED and APP_MESSAGING_ENABLED with - # APP_MESSAGING_PRODUCER_ID; the shipped default was true beside a blank broker, which refused - # every startup. + # 출처: five-adapter-runtime-remediation §6.3 MSG-INT-001 — relay scheduler를 시작한다. + # APP_OUTBOX_ENABLED, APP_PERSISTENCE_JPA_ENABLED, APP_MESSAGING_ENABLED와 APP_MESSAGING_PRODUCER_ID가 + # 필요하다. 예전 기본값은 broker가 빈 채로 true라 모든 기동을 거부했다. type: boolean default: false allowed_values: [true, false] @@ -4319,10 +4266,10 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:outbox-relay-dependency - name: APP_NOTIFICATION_PLATFORM_ENABLED - # 2026-09-25 capability packaging: the notification-platform module is on when present (its - # config/module-defaults/notification.yml maps this key with default true); false is the - # explicit off and binds nothing at all. Absent from the build is the ordinary off state. - # source: NTF-025. + # 2026-09-25 capability 포장: notification-platform 모듈은 있으면 켜진다(모듈의 + # config/module-defaults/notification.yml이 이 키를 기본 true로 잇는다). false가 명시적으로 끄는 값이고 + # 아무것도 바인딩하지 않는다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. + # 출처: NTF-025. type: boolean default: true allowed_values: [true, false] @@ -4335,9 +4282,8 @@ env_keys: required_test: adapter-contract:notification-platform-disabled-safe - name: APP_NOTIFICATION_PLATFORM_DEFAULT_LOCALE - # I-6b: the locale a submission that names none is rendered in. The accept use case applies - # it; the HTTP controller used to pick the host JVM's Locale.getDefault(), so the same request - # rendered differently per node. + # I-6b: locale을 적지 않은 제출을 그릴 locale. 접수 use case가 적용한다. 예전에는 HTTP controller가 host + # JVM의 Locale.getDefault()를 골라, 같은 요청이 노드마다 다르게 그려졌다. type: string default: ko-KR allowed_values: null @@ -4350,10 +4296,10 @@ env_keys: required_test: application-contract:notification-default-locale - name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY - # source: NTF-INT-007 — Encrypts recipient contact points at rest — addresses and phone numbers. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.contact-encryption-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — 저장된 수신자 연락처(주소와 전화번호)를 암호화한다. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.contact-encryption-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4366,10 +4312,10 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY - # source: NTF-INT-007 — Blind index over contact points, so a lookup never needs the plaintext. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.contact-lookup-hmac-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — 연락처의 blind index. 조회에 평문이 필요 없게 한다. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.contact-lookup-hmac-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4382,10 +4328,10 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY - # source: NTF-INT-007 — Signs the callback URLs a provider posts delivery outcomes back to. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.callback-signing-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — provider가 전달 결과를 보내는 callback URL에 서명한다. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.callback-signing-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4398,10 +4344,10 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY - # source: NTF-INT-007 — Encrypts stored provider credentials, which are themselves secrets. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.provider-credential-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — 저장된 provider 자격 증명(그 자체가 비밀)을 암호화한다. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.provider-credential-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4414,10 +4360,10 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY - # source: NTF-INT-007 — Encrypts notification variables and retained callback bodies at rest. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.payload-encryption-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — 저장된 알림 변수와 보관한 callback 본문을 암호화한다. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.payload-encryption-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4430,10 +4376,10 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY - # source: NTF-INT-007 — Keyed hash of provider request ids, which are provider-side identifiers. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.provider-request-lookup-hmac-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — provider 쪽 식별자인 provider request id의 key 있는 hash. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.provider-request-lookup-hmac-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4446,10 +4392,10 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY - # source: NTF-INT-007 — Keyed fingerprint of callback bodies, used to detect replays. - # Full row owned by secrets-classification.yaml. Bound by - # app.notification.platform.secrets.callback-fingerprint-hmac-key; the platform decodes it at startup and - # refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key. + # 출처: NTF-INT-007 — callback 본문의 key 있는 fingerprint. replay를 찾는 데 쓴다. + # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: + # app.notification.platform.secrets.callback-fingerprint-hmac-key. 플랫폼이 기동할 때 값을 풀고, + # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. type: string default: null allowed_values: null @@ -4462,9 +4408,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the CONTACT_ENCRYPTION key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY row above. Bound into + # 출처: NTF-INT-007 — CONTACT_ENCRYPTION key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CONTACT_ENCRYPTION. type: string default: null @@ -4478,9 +4424,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the CONTACT_LOOKUP_HMAC key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY row above. Bound into + # 출처: NTF-INT-007 — CONTACT_LOOKUP_HMAC key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CONTACT_LOOKUP_HMAC. type: string default: null @@ -4494,9 +4440,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the CALLBACK_SIGNING key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY row above. Bound into + # 출처: NTF-INT-007 — CALLBACK_SIGNING key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CALLBACK_SIGNING. type: string default: null @@ -4510,9 +4456,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the PROVIDER_CREDENTIAL key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY row above. Bound into + # 출처: NTF-INT-007 — PROVIDER_CREDENTIAL key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.PROVIDER_CREDENTIAL. type: string default: null @@ -4526,9 +4472,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the PAYLOAD_ENCRYPTION key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY row above. Bound into + # 출처: NTF-INT-007 — PAYLOAD_ENCRYPTION key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.PAYLOAD_ENCRYPTION. type: string default: null @@ -4542,9 +4488,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the PROVIDER_REQUEST_LOOKUP_HMAC key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY row above. Bound into + # 출처: NTF-INT-007 — PROVIDER_REQUEST_LOOKUP_HMAC key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.PROVIDER_REQUEST_LOOKUP_HMAC. type: string default: null @@ -4558,9 +4504,9 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID - # source: NTF-INT-007 — the id written into every envelope the CALLBACK_FINGERPRINT_HMAC key produces. - # An identifier, not key material, so it is public-config; the material itself is the - # APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY row above. Bound into + # 출처: NTF-INT-007 — CALLBACK_FINGERPRINT_HMAC key가 만드는 모든 envelope에 적는 id. + # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 + # APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CALLBACK_FINGERPRINT_HMAC. type: string default: null @@ -4574,7 +4520,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_SES_ENABLED - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: boolean default: false allowed_values: [true, false] @@ -4587,7 +4533,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_PRIMARY - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: boolean default: false allowed_values: [true, false] @@ -4600,7 +4546,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ENVIRONMENT - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: PRODUCTION allowed_values: null @@ -4613,7 +4559,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4626,7 +4572,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_TIMEOUT - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: duration default: 10s allowed_values: null @@ -4639,7 +4585,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_MAX_CONCURRENCY - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: int default: 8 allowed_values: null @@ -4652,7 +4598,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_RATE_PER_SECOND - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: int default: 20 allowed_values: null @@ -4665,7 +4611,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ENDPOINT - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: https://email.us-east-1.amazonaws.com allowed_values: null @@ -4678,7 +4624,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_REGION - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: us-east-1 allowed_values: null @@ -4691,7 +4637,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_SENDER_IDENTITY - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4704,7 +4650,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ACCESS_KEY_ID - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4717,7 +4663,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_CONFIGURATION_SET - # source: notification/fileserver H4-B — shipped SES dispatch assembler. + # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4730,9 +4676,9 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS - # source: 2026-09-24 module review Critical #10 — SNS topics whose SES event callbacks the - # shipped SES profile accepts. A valid SNS signature only proves AWS sent the message and - # anyone can own a topic, so binding fails when callbacks are enabled and this is empty. + # 출처: 2026-09-24 module review Critical #10 — 기본 SES profile이 받는 SES 이벤트 callback의 SNS topic. + # SNS 서명이 맞다는 것은 AWS가 보냈다는 것만 증명하고, topic은 누구나 가질 수 있다. 그래서 callback을 켰는데 + # 이 값이 비면 바인딩이 실패한다. type: csv default: "" allowed_values: null @@ -4745,7 +4691,7 @@ env_keys: required_test: adapter-contract:notification-ses-callback-topic-allowlist - name: APP_NOTIFICATION_PLATFORM_SMTP_ENABLED - # source: NTF-INT-001 — on/off key of the shipped SMTP provider profile; false means assembly skips it entirely. + # 출처: NTF-INT-001 — 기본 SMTP provider profile 켜고 끄기. false면 조립에서 통째로 뺀다. type: boolean default: false allowed_values: [true, false] @@ -4758,7 +4704,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY - # source: NTF-INT-001 — whether this profile is the primary route for EMAIL; exactly one primary per channel. + # 출처: NTF-INT-001 — 이 profile이 EMAIL의 주 경로인지. 채널마다 주 경로는 정확히 하나다. type: boolean default: true allowed_values: [true, false] @@ -4771,7 +4717,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT - # source: NTF-INT-001 — the profile's declared environment, carried on every dispatch record. + # 출처: NTF-INT-001 — profile이 밝힌 환경. 모든 발송 기록에 실린다. type: string default: local allowed_values: null @@ -4784,7 +4730,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE - # source: NTF-INT-001 — the credential profile the relay's credentials are resolved through. + # 출처: NTF-INT-001 — relay 자격 증명을 푸는 credential profile. type: string default: default allowed_values: null @@ -4797,7 +4743,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT - # source: NTF-INT-001 — per-attempt provider timeout for this profile. + # 출처: NTF-INT-001 — 이 profile의 시도마다 provider timeout. type: duration default: 10s allowed_values: null @@ -4810,7 +4756,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY - # source: NTF-INT-001 — how many attempts this profile may have in flight. + # 출처: NTF-INT-001 — 이 profile이 동시에 처리할 수 있는 시도 수. type: int default: 4 allowed_values: null @@ -4823,7 +4769,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND - # source: NTF-INT-001 — the profile's attempt rate limit. + # 출처: NTF-INT-001 — profile의 시도 속도 제한. type: int default: 10 allowed_values: null @@ -4836,7 +4782,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY - # source: NTF-INT-001 — the envelope sender every message is sent as. + # 출처: NTF-INT-001 — 모든 메시지를 보내는 envelope 발신자. type: string default: no-reply@example.invalid allowed_values: null @@ -4849,7 +4795,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY - # source: NTF-INT-001 — size of the bounded executor SMTP sends run on. + # 출처: NTF-INT-001 — SMTP 발송이 도는, 크기가 정해진 executor의 크기. type: int default: 4 allowed_values: null @@ -4862,8 +4808,8 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: SPRING_MAIL_HOST - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.host owner_module: adapter-outbound-notification type: string @@ -4879,8 +4825,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PORT - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.port owner_module: adapter-outbound-notification type: integer @@ -4896,8 +4842,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_USERNAME - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.username owner_module: adapter-outbound-notification type: string @@ -4913,8 +4859,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PASSWORD - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.password owner_module: adapter-outbound-notification type: string @@ -4930,8 +4876,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.starttls.enable owner_module: adapter-outbound-notification type: boolean @@ -4947,8 +4893,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_REQUIRED - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.starttls.required owner_module: adapter-outbound-notification type: boolean @@ -4964,8 +4910,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_CONNECTIONTIMEOUT - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.connectiontimeout owner_module: adapter-outbound-notification type: integer @@ -4981,8 +4927,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_TIMEOUT - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.timeout owner_module: adapter-outbound-notification type: integer @@ -4998,8 +4944,8 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_WRITETIMEOUT - # source: notification/fileserver techlead review H2 — native Spring Mail transport - # consumed by the JavaMailSender that the shipped SMTP assembler validates and uses. + # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.writetimeout owner_module: adapter-outbound-notification type: integer @@ -5015,9 +4961,9 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: APP_OPENAPI_DOCS_ENABLED - # source: five-adapter-runtime-remediation §9 — whether /v3/api-docs is served; application-prod.yml pins it false. Stated rather than defaulted because - # SpringDoc warns on every startup until a deployment decides, and a warning on every start is - # one nobody reads. + # 출처: five-adapter-runtime-remediation §9 — /v3/api-docs를 내줄지. application-prod.yml이 false로 + # 고정한다. 기본값에 맡기지 않고 적는 이유: 배포가 정할 때까지 SpringDoc이 기동마다 경고하고, 기동마다 나는 + # 경고는 아무도 읽지 않는다. type: boolean default: true allowed_values: [true, false] @@ -5030,9 +4976,9 @@ env_keys: required_test: env-contract:openapi-exposure-decided - name: APP_OPENAPI_UI_ENABLED - # source: five-adapter-runtime-remediation §9 — whether the Swagger UI is served; application-prod.yml pins it false. Stated rather than defaulted because - # SpringDoc warns on every startup until a deployment decides, and a warning on every start is - # one nobody reads. + # 출처: five-adapter-runtime-remediation §9 — Swagger UI를 내줄지. application-prod.yml이 false로 고정한다. + # 기본값에 맡기지 않고 적는 이유: 배포가 정할 때까지 SpringDoc이 기동마다 경고하고, 기동마다 나는 경고는 + # 아무도 읽지 않는다. type: boolean default: true allowed_values: [true, false] @@ -5045,10 +4991,10 @@ env_keys: required_test: env-contract:openapi-exposure-decided - name: APP_NOTIFICATION_PLATFORM_MODE - # source: NTF-025 — SERVING refuses to start without a working provider; INGEST_ONLY stores and does not dispatch. - # The constant is INGEST_ONLY. This row said ACCEPT_ONLY, a name NotificationPlatformMode has - # never had, so an operator following the registry got a binding failure naming a value the - # documentation does not mention. NotificationModeSsotTest derives the list below from the enum. + # 출처: NTF-025 — SERVING은 동작하는 provider 없이 기동을 거부한다. INGEST_ONLY는 저장만 하고 보내지 않는다. + # 상수는 INGEST_ONLY다. 이 행은 ACCEPT_ONLY라 했는데, NotificationPlatformMode에 그런 이름은 없었다. 그래서 + # 레지스트리를 따른 운영자는 문서에 없는 값을 지목하는 바인딩 실패를 받았다. NotificationModeSsotTest가 아래 + # 목록을 enum에서 만든다. type: enum default: SERVING allowed_values: [SERVING, INGEST_ONLY] @@ -5061,7 +5007,7 @@ env_keys: required_test: adapter-contract:notification-platform-mode - name: APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE - # source: NTF-025 — how many recipient deliveries one scheduler pass claims; 1..1000, refused outside that at binding + # 출처: NTF-025 — scheduler 한 번이 claim하는 수신자 전달 수. 1..1000이고 밖이면 바인딩에서 거부한다 type: integer default: 50 allowed_values: null @@ -5074,7 +5020,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_LEASE_DURATION - # source: NTF-025 — must outlast a provider call plus its timeout, or a live worker's delivery is claimed by a second one + # 출처: NTF-025 — provider 호출과 그 timeout보다 길어야 한다. 아니면 살아 있는 worker의 전달을 다른 worker가 claim한다 type: duration default: 2m allowed_values: null @@ -5087,7 +5033,7 @@ env_keys: required_test: adapter-contract:notification-lease-fencing - name: APP_NOTIFICATION_PLATFORM_POLL_INTERVAL - # source: NTF-025 — how often the scheduler asks for work when the last pass claimed nothing + # 출처: NTF-025 — 지난 차례에 claim한 것이 없을 때 scheduler가 일을 다시 묻는 간격 type: duration default: 1s allowed_values: null @@ -5100,7 +5046,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY - # source: NTF-025 — ceiling on in-flight provider calls across the whole process + # 출처: NTF-025 — 프로세스 전체에서 처리 중인 provider 호출 수 상한 type: integer default: 64 allowed_values: null @@ -5113,7 +5059,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS - # source: NTF-025 — retries after the first attempt; 0 means one attempt and no retry + # 출처: NTF-025 — 첫 시도 뒤의 재시도 수. 0이면 한 번 시도하고 재시도하지 않는다 type: integer default: 4 allowed_values: null @@ -5126,7 +5072,7 @@ env_keys: required_test: adapter-contract:notification-retry-policy - name: APP_NOTIFICATION_PLATFORM_ESTIMATED_DISPATCH_DURATION - # source: NTF-025 — dispatch latency estimate used by lease/retry planning + # 출처: NTF-025 — lease·재시도 계획에 쓰는 발송 지연 추정값 type: duration default: 2s allowed_values: null @@ -5139,7 +5085,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE - # source: NTF-025 — after this, a queued delivery expires rather than being sent late + # 출처: NTF-025 — 이 시간이 지나면 queue의 전달은 늦게 보내지 않고 만료된다 type: duration default: 24h allowed_values: null @@ -5152,7 +5098,7 @@ env_keys: required_test: adapter-contract:notification-expiry - name: APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK - # source: NTF-025 — an ambiguous attempt reached the provider with an unread outcome; falling back risks a duplicate send + # 출처: NTF-025 — 결과를 읽지 못한 애매한 시도가 provider에 닿았다. 다른 경로로 넘기면 두 번 보낼 위험이 있다 type: boolean default: false allowed_values: [true, false] @@ -5167,7 +5113,7 @@ env_keys: - name: APP_NOTIFICATION_PLATFORM_SHUTDOWN_GRACE - # source: NTF-025 — upper bound for worker drain during process termination + # 출처: NTF-025 — 프로세스 종료 때 worker 정리 시간의 상한 type: duration default: 20s allowed_values: null @@ -5180,7 +5126,7 @@ env_keys: required_test: adapter-contract:notification-shutdown-grace - name: APP_NOTIFICATION_PLATFORM_MAX_BACKLOG_DEPTH - # source: NTF-OBS-001 — readiness threshold for due and unclaimed deliveries + # 출처: NTF-OBS-001 — 기한이 됐는데 claim되지 않은 전달의 readiness 기준 type: integer default: 100000 allowed_values: null @@ -5193,7 +5139,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_OLDEST_DUE_AGE - # source: NTF-OBS-001 — readiness threshold for the oldest due delivery + # 출처: NTF-OBS-001 — 기한이 된 가장 오래된 전달의 readiness 기준 type: duration default: 10m allowed_values: null @@ -5206,7 +5152,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_STUCK_LEASES - # source: NTF-OBS-001 — readiness threshold for expired/stuck delivery leases + # 출처: NTF-OBS-001 — 만료되거나 멈춘 전달 lease의 readiness 기준 type: integer default: 50 allowed_values: null @@ -5219,7 +5165,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_PENDING_PROJECTIONS - # source: NTF-OBS-001 — readiness threshold for unapplied provider-event projections + # 출처: NTF-OBS-001 — 적용되지 않은 provider 이벤트 projection의 readiness 기준 type: integer default: 50000 allowed_values: null @@ -5232,7 +5178,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_FAILED_PROJECTIONS - # source: NTF-OBS-001 — readiness threshold for failed provider-event projections + # 출처: NTF-OBS-001 — 실패한 provider 이벤트 projection의 readiness 기준 type: integer default: 1000 allowed_values: null @@ -5245,7 +5191,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_OLDEST_PENDING_PROJECTION_AGE - # source: NTF-OBS-001 — readiness threshold for the oldest pending projection + # 출처: NTF-OBS-001 — 가장 오래 기다린 projection의 readiness 기준 type: duration default: 15m allowed_values: null @@ -5258,7 +5204,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_OLDEST_RECONCILIATION_AGE - # source: NTF-OBS-001 — readiness threshold for the oldest unresolved reconciliation + # 출처: NTF-OBS-001 — 가장 오래 풀리지 않은 대조(reconciliation)의 readiness 기준 type: duration default: 30m allowed_values: null @@ -5271,7 +5217,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED - # source: NTF-025 — whether the platform exposes provider callback endpoints + # 출처: NTF-025 — 플랫폼이 provider callback endpoint를 내놓을지 type: boolean default: false allowed_values: [true, false] @@ -5284,7 +5230,7 @@ env_keys: required_test: adapter-contract:notification-callback-ingestion - name: APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES - # source: NTF-025 — ceiling is 65251 = ciphertext column minus the largest envelope (version, key-id length, 255-byte key id, AES-GCM nonce and tag); larger is refused at binding + # 출처: NTF-025 — 상한 65251 = 암호문 칸 크기에서 가장 큰 envelope(version, key-id 길이, 255바이트 key id, AES-GCM nonce와 tag)를 뺀 값. 더 크면 바인딩에서 거부한다 type: integer default: 65251 allowed_values: null @@ -5297,8 +5243,8 @@ env_keys: required_test: adapter-contract:notification-callback-body-bound - name: APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW - # source: NTF-025 — how far a callback timestamp may differ from local time before it is treated as a replay - # review 05-20 — 1h covers SNS's whole HTTP/S retry period (capped at 3,600 s); a replay inside it is a ledger duplicate + # 출처: NTF-025 — callback 시각이 로컬 시각과 이만큼 넘게 다르면 replay로 본다 + # review 05-20 — 1h는 SNS의 HTTP/S 재시도 기간 전체(최대 3,600 s)를 덮는다. 그 안의 replay는 ledger 중복이다 type: duration default: 1h allowed_values: null diff --git a/docs/registries/error-codes.yaml b/docs/registries/error-codes.yaml index 821c32c1..929d5a8b 100644 --- a/docs/registries/error-codes.yaml +++ b/docs/registries/error-codes.yaml @@ -2,24 +2,24 @@ # Schema owner: feature-contract-registry-governance # Category enum owner: feature-operational-error-observability-foundation # Last updated: 2026-11-06 -# Scope: skeleton-wide OperationalError SSOT. Product/fork ApiErrorCode enums own local registries/contracts. +# 범위: 저장소 전체 OperationalError의 정본. 제품·fork의 ApiErrorCode enum은 자기 레지스트리·계약을 가진다. # -# Schema (per row): +# 행마다의 칸: # code: UPPER_SNAKE_CASE # category: VALIDATION | AUTH | AUTHZ | NOT_FOUND | CONFLICT | # RATE_LIMIT | TRANSIENT_DEPENDENCY | PERMANENT_DEPENDENCY | # DATA_INTEGRITY | INTERNAL -# http_status: int (async-only failures use 500 placeholder) +# http_status: int (비동기에서만 나는 실패는 자리표시로 500) # retryable: bool # retry_after_seconds: int | null (RATE_LIMIT/TRANSIENT 권고 backoff) # owner_layer: presentation | application | domain | infrastructure | crosscut # client_safe_message: = shared-contract ClientErrorMessages.of(category) — category별 한국어 문구 표 -# 하나(소유자 결정 11). no token / no principal raw / no internal path / no stack trace -# runbook_link: runbook://area/scenario OR null (client-error만 null 허용) +# 하나(소유자 결정 11). 토큰·principal 원문·내부 경로·stack trace를 담지 않는다 +# runbook_link: runbook://area/scenario 또는 null (client-error만 null 허용) # compatibility_impact: none | additive | behavior-change | breaking -# required_test: owning contract test identifier +# required_test: 이 행을 지키는 계약 테스트 식별자 # -# Runbook policy (operational-runbook-contract L80): +# runbook 규칙 (operational-runbook-contract L80): # retryable=false + category ∈ {AUTH, AUTHZ, RATE_LIMIT, INTERNAL, # TRANSIENT_DEPENDENCY, PERMANENT_DEPENDENCY} ⇒ runbook_link 필수. # VALIDATION/NOT_FOUND/CONFLICT/DATA_INTEGRITY는 client-error로 runbook 면제 가능. @@ -38,7 +38,7 @@ errors: # AUTH (feature-security-operational-baseline / Decision Matrix) # ============================================================ - # source: feature-security-operational-baseline L82 — "token 누락 | 401 | AUTH_TOKEN_MISSING | AUTH" + # 출처: feature-security-operational-baseline L82 — "token 누락 | 401 | AUTH_TOKEN_MISSING | AUTH" - code: AUTH_TOKEN_MISSING category: AUTH http_status: 401 @@ -51,7 +51,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L83 — "token malformed (parse fail) | 401 | AUTH_TOKEN_MALFORMED | AUTH" + # 출처: feature-security-operational-baseline L83 — "token malformed (parse fail) | 401 | AUTH_TOKEN_MALFORMED | AUTH" - code: AUTH_TOKEN_MALFORMED category: AUTH http_status: 401 @@ -64,7 +64,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L84 — "token expired (clock skew tolerance 60s 초과) | 401 | AUTH_TOKEN_EXPIRED | AUTH" + # 출처: feature-security-operational-baseline L84 — "token expired (clock skew tolerance 60s 초과) | 401 | AUTH_TOKEN_EXPIRED | AUTH" - code: AUTH_TOKEN_EXPIRED category: AUTH http_status: 401 @@ -77,7 +77,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L85 — "invalid signature | 401 | AUTH_TOKEN_INVALID_SIGNATURE | AUTH" + # 출처: feature-security-operational-baseline L85 — "invalid signature | 401 | AUTH_TOKEN_INVALID_SIGNATURE | AUTH" - code: AUTH_TOKEN_INVALID_SIGNATURE category: AUTH http_status: 401 @@ -90,7 +90,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L86 — "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH | AUTH" + # 출처: feature-security-operational-baseline L86 — "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH | AUTH" - code: AUTH_ISSUER_MISMATCH category: AUTH http_status: 401 @@ -103,7 +103,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L87 — "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH | AUTH" + # 출처: feature-security-operational-baseline L87 — "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH | AUTH" - code: AUTH_AUDIENCE_MISMATCH category: AUTH http_status: 401 @@ -116,7 +116,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L88 — "unknown kid (JWKS 미캐시) | 401 + Retry-After 5s | AUTH_KID_UNKNOWN | AUTH" + # 출처: feature-security-operational-baseline L88 — "unknown kid (JWKS 미캐시) | 401 + Retry-After 5s | AUTH_KID_UNKNOWN | AUTH" - code: AUTH_KID_UNKNOWN category: AUTH http_status: 401 @@ -130,7 +130,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L89 — "JWKS endpoint outage ... | AUTH_JWKS_UNAVAILABLE | TRANSIENT_DEPENDENCY" + # 출처: feature-security-operational-baseline L89 — "JWKS endpoint outage ... | AUTH_JWKS_UNAVAILABLE | TRANSIENT_DEPENDENCY" - code: AUTH_JWKS_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 @@ -143,7 +143,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-security-operational-baseline L90 — "claim mapping failure ... | 401 | AUTH_CLAIM_MAPPING_FAILED | AUTH" + # 출처: feature-security-operational-baseline L90 — "claim mapping failure ... | 401 | AUTH_CLAIM_MAPPING_FAILED | AUTH" - code: AUTH_CLAIM_MAPPING_FAILED category: AUTH http_status: 401 @@ -160,7 +160,7 @@ errors: # AUTHZ (feature-security-operational-baseline) # ============================================================ - # source: feature-security-operational-baseline L91 — "valid token + 권한 부족 | 403 | AUTHZ_INSUFFICIENT_PERMISSION | AUTHZ" + # 출처: feature-security-operational-baseline L91 — "valid token + 권한 부족 | 403 | AUTHZ_INSUFFICIENT_PERMISSION | AUTHZ" - code: AUTHZ_INSUFFICIENT_PERMISSION category: AUTHZ http_status: 403 @@ -173,7 +173,7 @@ errors: compatibility_impact: none required_test: contract-verification:authz-category - # source: feature-security-operational-baseline L92 — "valid token + tenant cross-access | 403 | AUTHZ_TENANT_MISMATCH | AUTHZ" + # 출처: feature-security-operational-baseline L92 — "valid token + tenant cross-access | 403 | AUTHZ_TENANT_MISMATCH | AUTHZ" - code: AUTHZ_TENANT_MISMATCH category: AUTHZ http_status: 403 @@ -190,7 +190,7 @@ errors: # INTERNAL (feature-security-operational-baseline + container-runtime) # ============================================================ - # source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL" + # 출처: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL" - code: INTERNAL_AUTH_MISCONFIGURATION category: INTERNAL http_status: 500 @@ -203,7 +203,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # source: feature-container-runtime-contract L113 — "JVM OutOfMemoryError → ExitOnOutOfMemoryError로 137 exit, log에 error.code=JVM_OOM 명시" + # 출처: feature-container-runtime-contract L113 — "JVM OutOfMemoryError → ExitOnOutOfMemoryError로 137 exit, log에 error.code=JVM_OOM 명시" - code: JVM_OOM category: INTERNAL http_status: 500 @@ -217,10 +217,10 @@ errors: required_test: contract-verification:container-runtime-oom # ============================================================ - # DB / Persistence (feature-persistence-failure-baseline / SQLState Matrix) + # DB / 영속성 (feature-persistence-failure-baseline / SQLState Matrix) # ============================================================ - # source: feature-persistence-failure-baseline L85 — "08* | all | TRANSIENT_DEPENDENCY | DB_UNAVAILABLE | true" + # 출처: feature-persistence-failure-baseline L85 — "08* | all | TRANSIENT_DEPENDENCY | DB_UNAVAILABLE | true" - code: DB_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 @@ -233,7 +233,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L86 — "40001 | Postgres/MySQL | CONFLICT | DB_SERIALIZATION_FAILURE | true" + # 출처: feature-persistence-failure-baseline L86 — "40001 | Postgres/MySQL | CONFLICT | DB_SERIALIZATION_FAILURE | true" - code: DB_SERIALIZATION_FAILURE category: CONFLICT http_status: 409 @@ -246,7 +246,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L87 — "40P01 | Postgres | CONFLICT | DB_DEADLOCK | true (backoff)" + # 출처: feature-persistence-failure-baseline L87 — "40P01 | Postgres | CONFLICT | DB_DEADLOCK | true (backoff)" - code: DB_DEADLOCK category: CONFLICT http_status: 409 @@ -259,7 +259,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L88 — "23502 | Postgres | DATA_INTEGRITY | DB_NULL_VIOLATION | false" + # 출처: feature-persistence-failure-baseline L88 — "23502 | Postgres | DATA_INTEGRITY | DB_NULL_VIOLATION | false" - code: DB_NULL_VIOLATION category: DATA_INTEGRITY http_status: 409 @@ -272,7 +272,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L89 — "23503 | Postgres | DATA_INTEGRITY | DB_FK_VIOLATION | false" + # 출처: feature-persistence-failure-baseline L89 — "23503 | Postgres | DATA_INTEGRITY | DB_FK_VIOLATION | false" - code: DB_FK_VIOLATION category: DATA_INTEGRITY http_status: 409 @@ -285,7 +285,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L90 — "23505 | Postgres | CONFLICT | DB_UNIQUE_VIOLATION | false (business mapping)" + # 출처: feature-persistence-failure-baseline L90 — "23505 | Postgres | CONFLICT | DB_UNIQUE_VIOLATION | false (business mapping)" - code: DB_UNIQUE_VIOLATION category: CONFLICT http_status: 409 @@ -298,7 +298,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L91 — "23514 | Postgres | DATA_INTEGRITY | DB_CHECK_VIOLATION | false" + # 출처: feature-persistence-failure-baseline L91 — "23514 | Postgres | DATA_INTEGRITY | DB_CHECK_VIOLATION | false" - code: DB_CHECK_VIOLATION category: DATA_INTEGRITY http_status: 409 @@ -311,7 +311,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L92 — "25P03 | Postgres | TRANSIENT_DEPENDENCY | DB_IDLE_IN_TX_TIMEOUT | true" + # 출처: feature-persistence-failure-baseline L92 — "25P03 | Postgres | TRANSIENT_DEPENDENCY | DB_IDLE_IN_TX_TIMEOUT | true" - code: DB_IDLE_IN_TX_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 503 @@ -324,7 +324,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: feature-persistence-failure-baseline L93 — "57014 | Postgres | TRANSIENT_DEPENDENCY | DB_QUERY_CANCELED | false" + # 출처: feature-persistence-failure-baseline L93 — "57014 | Postgres | TRANSIENT_DEPENDENCY | DB_QUERY_CANCELED | false" - code: DB_QUERY_CANCELED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -337,7 +337,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # source: review-followup P15 (S2-lead-4) — JPA OPTIMISTIC_CONFLICT (@Version check failed at flush/commit) + # 출처: review-followup P15 (S2-lead-4) — JPA OPTIMISTIC_CONFLICT (flush·commit 때 @Version 검사 실패) - code: DB_OPTIMISTIC_CONFLICT category: CONFLICT http_status: 409 @@ -350,7 +350,7 @@ errors: compatibility_impact: additive required_test: persistence-jpa:JpaPersistenceExceptionCodeTest - # source: review-followup P15 (S2-lead-4) — JPA COMPLETION_UNKNOWN (40003 / commit-phase connection loss) + # 출처: review-followup P15 (S2-lead-4) — JPA COMPLETION_UNKNOWN (40003 / commit 단계 연결 끊김) - code: DB_COMPLETION_UNKNOWN category: DATA_INTEGRITY http_status: 500 @@ -367,7 +367,7 @@ errors: # Rate limit / Idempotency (feature-rate-limit-idempotency-contract) # ============================================================ - # source: feature-rate-limit-idempotency-contract — rate limit response/log 기준 / Retry-After header 기준 (scope L29, L33) + # 출처: feature-rate-limit-idempotency-contract — rate limit 응답·로그 기준 / Retry-After 헤더 기준 (scope L29, L33) - code: RATE_LIMIT_EXCEEDED category: RATE_LIMIT http_status: 429 @@ -380,7 +380,7 @@ errors: compatibility_impact: none required_test: contract-verification:rate-limit - # source: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지. + # 출처: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지. # 2초 = 기본 processing lease(30s)보다 짧은 고정값. 이전 "client는 polling"(retryable=false)은 조회 엔드포인트가 없어 폐기. # 값 하나: IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER. processing-lease가 이 값 이하면 기동 실패(재리뷰 RR-02-05). # behavior-change: retryable false→true는 web Envelope뿐 아니라 gRPC trailer error-retryable(status ABORTED)과 @@ -397,7 +397,7 @@ errors: compatibility_impact: behavior-change required_test: contract-verification:idempotency - # source: feature-rate-limit-idempotency-contract L72 — "fingerprint mismatch (same key + different body) = 422 IDEMPOTENT_REQUEST_MISMATCH" + # 출처: feature-rate-limit-idempotency-contract L72 — "fingerprint mismatch (same key + different body) = 422 IDEMPOTENT_REQUEST_MISMATCH" - code: IDEMPOTENT_REQUEST_MISMATCH category: VALIDATION http_status: 422 @@ -410,7 +410,7 @@ errors: compatibility_impact: none required_test: contract-verification:idempotency - # source: review-followup P15 (X2-P2-2a) — IdempotencyExecutor fail-closed refusal before the action + # 출처: review-followup P15 (X2-P2-2a) — IdempotencyExecutor가 동작 전에 닫힌 채 거절한다(fail-closed) - code: IDEMPOTENCY_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 @@ -423,7 +423,7 @@ errors: compatibility_impact: additive required_test: contract-verification:idempotency - # source: 재리뷰 2026-11-03 README 4절 결정, RR-02-03 — action이 돈 뒤 complete 단계에서 저장소가 응답하지 않음. + # 출처: 재리뷰 2026-11-03 README 4절 결정, RR-02-03 — action이 돈 뒤 complete 단계에서 저장소가 응답하지 않음. # 실행 전 거부(IDEMPOTENCY_UNAVAILABLE)와 code로 구분한다. 결과 불명: 같은 키로 재전송하면 서버가 replay·in-flight· # recovery-required로 판정한다. 새 키 금지. docs/web/http-contract.md §2. - code: IDEMPOTENCY_COMPLETION_UNKNOWN @@ -438,7 +438,7 @@ errors: compatibility_impact: additive required_test: contract-verification:idempotency - # source: review-followup P15 (X2-P2-2a) — replay cannot decide whether an external effect happened + # 출처: review-followup P15 (X2-P2-2a) — replay가 외부 효과가 일어났는지 정할 수 없다 - code: IDEMPOTENCY_RECOVERY_REQUIRED category: DATA_INTEGRITY http_status: 500 @@ -452,20 +452,19 @@ errors: required_test: contract-verification:idempotency # ============================================================ - # File / Resource (feature-file-resource-handling-contract) + # 파일 / 자원 (feature-file-resource-handling-contract) # ============================================================ - # source: feature-file-resource-handling-contract L69 — "spring.servlet.multipart.max-file-size 10MB ... Spring 단의 enforcement가 실패 시 envelope 응답 보장" / 테스트 계약 "oversized upload가 generic 500으로 처리되면 실패" + # 출처: feature-file-resource-handling-contract L69 — "spring.servlet.multipart.max-file-size 10MB ... Spring 단의 enforcement가 실패 시 envelope 응답 보장" / 테스트 계약 "oversized upload가 generic 500으로 처리되면 실패" # ============================================================ - # API contract transport-standard codes (feature-api-contract-baseline) + # API 계약의 전송 표준 코드 (feature-api-contract-baseline) # ============================================================ - # NOTE: feature-api-contract-baseline owns the transport-shape failure - # classification (D8 413/414, D9 406/415, D12 405, D15 412). These rows mirror - # dev.caskeleton.shared.error.OperationalError; the D11 status-mapping - # consistency test (owner: this branch, producer) fails the build when a code's - # registry http_status and the enum httpStatus() drift apart. + # 참고: 전송 모양 실패의 분류는 feature-api-contract-baseline이 가진다 + # (D8 413/414, D9 406/415, D12 405, D15 412). 이 행들은 dev.caskeleton.shared.error.OperationalError를 + # 그대로 옮긴 것이다. D11 상태 대응 일관성 테스트(소유: 이 branch, 생산자)가 코드의 레지스트리 http_status와 + # enum httpStatus()가 어긋나면 빌드를 실패시킨다. - # source: feature-api-contract-baseline.md D12 — "405 Method Not Allowed + Allow header 의무" + # 출처: feature-api-contract-baseline.md D12 — "405 Method Not Allowed + Allow header 의무" - code: METHOD_NOT_ALLOWED category: VALIDATION http_status: 405 @@ -478,7 +477,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # source: feature-api-contract-baseline.md D9 — "406 Not Acceptable = 응답 표현 협상 실패" + # 출처: feature-api-contract-baseline.md D9 — "406 Not Acceptable = 응답 표현 협상 실패" - code: NOT_ACCEPTABLE category: VALIDATION http_status: 406 @@ -491,7 +490,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # source: feature-api-contract-baseline.md D15 — "If-Match mismatch 시 412 Precondition Failed" + # 출처: feature-api-contract-baseline.md D15 — "If-Match mismatch 시 412 Precondition Failed" - code: PRECONDITION_FAILED category: CONFLICT http_status: 412 @@ -504,7 +503,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # source: feature-api-contract-baseline.md D8 — "request size limit 실패 분류 (413)" + # 출처: feature-api-contract-baseline.md D8 — "request size limit 실패 분류 (413)" - code: PAYLOAD_TOO_LARGE category: VALIDATION http_status: 413 @@ -517,10 +516,9 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # source: feature-api-contract-baseline.md D8 형제 — "URI 길이 실패 분류 (414)" - # NOTE: enforcement is Tomcat/gateway-owned (rejected before Spring dispatch); - # this row + code exist for status-mapping consistency. End-to-end 414 contract - # test is `planned` (gateway/Tomcat maxHttpHeaderSize 8KB boundary). + # 출처: feature-api-contract-baseline.md D8 형제 — "URI 길이 실패 분류 (414)" + # 참고: 강제는 Tomcat·gateway가 한다(Spring dispatch 전에 거절). 이 행과 코드는 상태 대응 일관성을 위해 + # 있다. 끝에서 끝까지의 414 계약 테스트는 `planned`다 (gateway/Tomcat maxHttpHeaderSize 8KB 경계). - code: URI_TOO_LONG category: VALIDATION http_status: 414 @@ -533,7 +531,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # source: feature-api-contract-baseline.md D9 — "415 Unsupported Media Type = 요청 본문 format 미지원" + # 출처: feature-api-contract-baseline.md D9 — "415 Unsupported Media Type = 요청 본문 format 미지원" - code: UNSUPPORTED_MEDIA_TYPE category: VALIDATION http_status: 415 @@ -550,7 +548,7 @@ errors: # Tenant (feature-tenant-context-policy) # ============================================================ - # source: feature-tenant-context-policy L71 — "tenant 미지원 모드에서 X-Tenant-Id 헤더 수신 시 400 TENANT_NOT_SUPPORTED (filter 단계)" + # 출처: feature-tenant-context-policy L71 — "tenant 미지원 모드에서 X-Tenant-Id 헤더 수신 시 400 TENANT_NOT_SUPPORTED (filter 단계)" # ============================================================ # Validation / Business rule (feature-business-rule-validation-contract) # ============================================================ @@ -560,17 +558,17 @@ errors: # (feature-operational-error-observability-foundation L110). 실제 도메인별 code는 # Phase D(도메인 feature 적용) 시 본 registry에 추가. - # source: feature-operational-error-observability-foundation L110 — "code: VALIDATION_EMAIL_FORMAT, // registry-registered code" (validation field error JSON shape example) + # 출처: feature-operational-error-observability-foundation L110 — "code: VALIDATION_EMAIL_FORMAT, // registry-registered code" (validation 필드 오류 JSON 모양 예) # ============================================================ - # Cache (feature-cache-consistency-contract) + # 캐시 (feature-cache-consistency-contract) # ============================================================ - # source: feature-cache-consistency-contract — Decisionized Work Items "Redis unavailable | degrade only if declared | fail-fast for required cache | generic INTERNAL | unavailable mapping" / 테스트 "Redis unavailable이 degrade 가능 여부 없이 INTERNAL로 처리되면 실패" + # 출처: feature-cache-consistency-contract — Decisionized Work Items "Redis unavailable | degrade only if declared | fail-fast for required cache | generic INTERNAL | unavailable mapping" / 테스트 "Redis unavailable이 degrade 가능 여부 없이 INTERNAL로 처리되면 실패" # ============================================================ - # Outbound HTTP (feature-outbound-http-client-baseline) + # 외부 HTTP 호출 (feature-outbound-http-client-baseline) # ============================================================ - # source: feature-outbound-http-client-baseline L70 — "outbound HTTP timeout default = connect 2s / read 5s / global call 10s" + scope "timeout/connect/DNS failure 분류" / 테스트 "upstream timeout은 retryable dependency failure로 분류되어야 함" + # 출처: feature-outbound-http-client-baseline L70 — "outbound HTTP timeout default = connect 2s / read 5s / global call 10s" + scope "timeout/connect/DNS failure 분류" / 테스트 "upstream timeout은 retryable dependency failure로 분류되어야 함" - code: DEPENDENCY_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 504 @@ -583,7 +581,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # source: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + L70 connect=2s timeout + # 출처: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + L70 connect=2s timeout - code: DEPENDENCY_CONNECT_FAILED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -596,7 +594,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # source: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + # 출처: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" - code: DEPENDENCY_DNS_FAILED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -609,7 +607,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # source: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" / 테스트 "401/403은 credential/scope/config 문제로 분류되어야 함" + # 출처: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" / 테스트 "401/403은 credential/scope/config 문제로 분류되어야 함" - code: DEPENDENCY_4XX_CLIENT category: PERMANENT_DEPENDENCY http_status: 502 @@ -622,7 +620,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # source: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" + # 출처: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" - code: DEPENDENCY_5XX_SERVER category: TRANSIENT_DEPENDENCY http_status: 502 @@ -635,7 +633,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # source: feature-outbound-http-client-baseline L69 — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + Decisionized "circuit breaker | Resilience4j optional env" + # 출처: feature-outbound-http-client-baseline L69 — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + Decisionized "circuit breaker | Resilience4j optional env" - code: DEPENDENCY_CIRCUIT_OPEN category: TRANSIENT_DEPENDENCY http_status: 503 @@ -652,7 +650,7 @@ errors: # Outbox (feature-domain-event-outbox-contract) # ============================================================ - # source: feature-domain-event-outbox-contract L67 — "outbox row status enum = PENDING / IN_FLIGHT / PUBLISHED / FAILED / DEAD" + scope "publish 실패 분류" / 판정 "publish 실패가 retry/DLQ/log/runbook 기준 없이 삼켜지면 실패" + # 출처: feature-domain-event-outbox-contract L67 — "outbox row status enum = PENDING / IN_FLIGHT / PUBLISHED / FAILED / DEAD" + scope "publish 실패 분류" / 판정 "publish 실패가 retry/DLQ/log/runbook 기준 없이 삼켜지면 실패" - code: OUTBOX_PUBLISH_FAILED category: TRANSIENT_DEPENDENCY http_status: 500 @@ -665,7 +663,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbox-publish - # source: feature-domain-event-outbox-contract L67 — outbox status enum "DEAD" / Outbox Defaults "DLQ | background-job branch owner" + # 출처: feature-domain-event-outbox-contract L67 — outbox status enum "DEAD" / Outbox Defaults "DLQ | background-job branch owner" - code: OUTBOX_DEAD_LETTER category: INTERNAL http_status: 500 @@ -679,10 +677,10 @@ errors: required_test: contract-verification:outbox-dlq # ============================================================ - # Background job / Async (feature-background-job-async-contract) + # 백그라운드 작업 / 비동기 (feature-background-job-async-contract) # ============================================================ - # source: feature-background-job-async-contract — Decisionized "saturation | bounded executor + rejection log" / L72 "saturation policy default = AbortPolicy" / 테스트 "executor rejection이 structured log 없이 발생하면 실패" + # 출처: feature-background-job-async-contract — Decisionized "saturation | bounded executor + rejection log" / L72 "saturation policy default = AbortPolicy" / 테스트 "executor rejection이 structured log 없이 발생하면 실패" - code: JOB_EXECUTOR_REJECTED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -695,7 +693,7 @@ errors: compatibility_impact: none required_test: contract-verification:async-saturation - # source: feature-background-job-async-contract L69 — "기본 backoff는 exponential backoff with jitter, max attempts 3, DLQ after exhausted attempts" + scope "shutdown 중 job 처리 기준" / L73 graceful shutdown ≤19s + # 출처: feature-background-job-async-contract L69 — "기본 backoff는 exponential backoff with jitter, max attempts 3, DLQ after exhausted attempts" + scope "shutdown 중 job 처리 기준" / L73 graceful shutdown ≤19s - code: JOB_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 500 @@ -708,7 +706,7 @@ errors: compatibility_impact: none required_test: contract-verification:async-timeout - # source: feature-background-job-async-contract L69 — "DLQ after exhausted attempts" + Decisionized "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted | ... | infinite retry" + # 출처: feature-background-job-async-contract L69 — "DLQ after exhausted attempts" + Decisionized "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted | ... | infinite retry" - code: JOB_DEAD_LETTER category: INTERNAL http_status: 500 @@ -722,10 +720,10 @@ errors: required_test: contract-verification:async-dlq # ============================================================ - # Distributed Lock (feature-distributed-lock-contract) + # 분산 lock (feature-distributed-lock-contract) # ============================================================ - # source: feature-distributed-lock-contract D7 — "lock 획득 실패/timeout 의 error code = + # 출처: feature-distributed-lock-contract D7 — "lock 획득 실패/timeout 의 error code = # LOCK_ACQUISITION_TIMEOUT (category CONFLICT, retryable true, client_safe true) + metric # lock.acquisition" / D5 — "try-lock + 유한 waitTime + lease(TTL) 필수, 무한 blocking 금지". # category CONFLICT 는 기존 enum 재사용; retryable=true — 락 보유자가 임계 구역을 빠져나오면 @@ -746,10 +744,10 @@ errors: required_test: contract-verification:lock-acquisition-timeout # ============================================================ - # Migration / Startup (feature-migration-startup-contract) + # Migration / 기동 (feature-migration-startup-contract) # ============================================================ - # source: feature-migration-startup-contract L71 — "startup exit code 표준 = ... migration 실패=70 ..." + Decisionized "startup failure log | structured log with startup.phase, error.code, error.category" + # 출처: feature-migration-startup-contract L71 — "startup exit code 표준 = ... migration 실패=70 ..." + Decisionized "startup failure log | structured log with startup.phase, error.code, error.category" - code: ADAPTER_DISABLED category: INTERNAL http_status: 500 @@ -762,12 +760,12 @@ errors: compatibility_impact: none required_test: adapter-contract:adapter-disabled-runtime-call - # source: feature-migration-startup-contract L71 — "startup exit code 표준 = ... profile mismatch=71" / 테스트 "prod profile에서 local-only 설정이 켜지면 실패" + # 출처: feature-migration-startup-contract L71 — "startup exit code 표준 = ... profile mismatch=71" / 테스트 "prod profile에서 local-only 설정이 켜지면 실패" # ============================================================ - # Management / Actuator (feature-management-actuator-security-contract) + # 관리 포트 / Actuator (feature-management-actuator-security-contract) # ============================================================ - # source: feature-management-actuator-security-contract — Exposure Policy "env/configprops | forbidden" "heapdump/threaddump | forbidden unless break-glass runbook" "shutdown | forbidden" / 테스트 "prod에서 env/configprops endpoint가 노출되면 실패" + # 출처: feature-management-actuator-security-contract — 노출 정책 "env/configprops | forbidden" "heapdump/threaddump | forbidden unless break-glass runbook" "shutdown | forbidden" / 테스트 "prod에서 env/configprops endpoint가 노출되면 실패" - code: ACTUATOR_FORBIDDEN category: AUTHZ http_status: 403 @@ -781,9 +779,9 @@ errors: required_test: contract-verification:management-actuator # ============================================================ - # CURRENT CODE RECONCILIATION (2026-09-21) - # Skeleton-wide OperationalError entries that were live in code but absent from the Phase-B - # registry. Product-specific ApiErrorCode enums remain owned by their product modules. + # 지금 코드와 맞춤 (2026-09-21) + # 코드에는 있었지만 Phase-B 레지스트리에 없던 저장소 전체 OperationalError 항목. 제품별 ApiErrorCode enum은 + # 자기 제품 모듈이 가진다. # ============================================================ - code: VALIDATION_FAILED diff --git a/docs/registries/headers.yaml b/docs/registries/headers.yaml index e8c8a3fe..21168e03 100644 --- a/docs/registries/headers.yaml +++ b/docs/registries/headers.yaml @@ -2,14 +2,14 @@ # Schema owner: feature-contract-registry-governance # Last updated: 2026-05-22 # -# Conventions: -# - HTTP header name: kebab-case (X-Request-Id, X-Correlation-Id) -# - W3C standard headers: lowercase (traceparent, tracestate) -# - mdc_key: snake_case (foundation SSOT) -# - envelope_meta_field: camelCase (envelope SSOT) +# 표기 규칙 +# - HTTP 헤더 이름: kebab-case (X-Request-Id, X-Correlation-Id) +# - W3C 표준 헤더: 소문자 (traceparent, tracestate) +# - mdc_key: snake_case (foundation이 정본) +# - envelope_meta_field: camelCase (envelope이 정본) headers: - # source: feature-operational-error-observability-foundation.md L97 + # 출처: feature-operational-error-observability-foundation.md L97 # "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id" - name: X-Request-Id direction: both @@ -23,7 +23,7 @@ headers: compatibility_impact: none required_test: contract-verification:envelope-headers - # source: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67 + # 출처: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67 # "idempotency header 이름은 Idempotency-Key" / "기본 scope는 (authenticatedPrincipal, idempotencyKey, useCaseName)" - name: Idempotency-Key direction: inbound @@ -37,7 +37,7 @@ headers: compatibility_impact: additive required_test: contract-verification:idempotency-replay - # source: feature-rate-limit-idempotency-contract.md L85 / foundation L85 + # 출처: feature-rate-limit-idempotency-contract.md L85 / foundation L85 # "RATE_LIMIT | ... | 429 | true (Retry-After 이후)" / "retry-after 기준 없이 429를 반환하면 실패" - name: Retry-After direction: outbound @@ -51,7 +51,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) + # 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) # app.rate-limit.enabled=true인 요청 경로에서만 생성되는 rate-limit 응답 표면 - name: X-RateLimit-Limit direction: outbound @@ -65,7 +65,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) + # 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) - name: X-RateLimit-Remaining direction: outbound type: numeric @@ -78,7 +78,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) + # 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) - name: X-RateLimit-Reset direction: outbound type: rfc3339-date @@ -91,7 +91,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # source: feature-api-compatibility-deprecation-contract.md L87 + # 출처: feature-api-compatibility-deprecation-contract.md L87 # "deprecation marker | OpenAPI deprecated: true + design record | response header optional" - name: Deprecation direction: outbound @@ -105,7 +105,7 @@ headers: compatibility_impact: additive required_test: contract-verification:deprecation-marker - # source: feature-api-compatibility-deprecation-contract.md L87 + # 출처: feature-api-compatibility-deprecation-contract.md L87 # "deprecation marker | OpenAPI deprecated: true + design record | response header optional" (RFC 8594 Sunset) - name: Sunset direction: outbound @@ -119,7 +119,7 @@ headers: compatibility_impact: additive required_test: contract-verification:deprecation-marker - # source: feature-distributed-tracing-contract.md L64, L85 + # 출처: feature-distributed-tracing-contract.md L64, L85 # "propagation header는 W3C traceparent default" / "HTTP | traceparent, tracestate (W3C)" - name: traceparent direction: both @@ -133,7 +133,7 @@ headers: compatibility_impact: none required_test: contract-verification:trace-propagation - # source: feature-distributed-tracing-contract.md L66, L85 + # 출처: feature-distributed-tracing-contract.md L66, L85 # "propagation format = W3C traceparent + tracestate only. B3 propagation은 forbidden" - name: tracestate direction: both @@ -147,7 +147,7 @@ headers: compatibility_impact: none required_test: contract-verification:trace-propagation - # source: feature-operational-error-observability-foundation.md L100 + # 출처: feature-operational-error-observability-foundation.md L100 # "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id" - name: X-Correlation-Id direction: both @@ -161,8 +161,8 @@ headers: compatibility_impact: none required_test: contract-verification:envelope-headers - # source: feature-security-operational-baseline.md L66 - # "JWT Resource Server를 baseline security model로 둠" (Bearer token via Authorization header) + # 출처: feature-security-operational-baseline.md L66 + # "JWT Resource Server를 baseline security model로 둠" (Authorization 헤더의 Bearer 토큰) - name: Authorization direction: inbound type: bearer-token @@ -175,8 +175,8 @@ headers: compatibility_impact: none required_test: contract-verification:jwt-resource-server - # source: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ Decision Matrix) - # 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server 표준 challenge header + # 출처: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ 판정 표) + # 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server의 표준 challenge 헤더 - name: WWW-Authenticate direction: outbound type: string diff --git a/docs/registries/mdc-keys.yaml b/docs/registries/mdc-keys.yaml index 3d041296..e3944d49 100644 --- a/docs/registries/mdc-keys.yaml +++ b/docs/registries/mdc-keys.yaml @@ -3,13 +3,13 @@ # MDC SSOT: feature-operational-error-observability-foundation # Last updated: 2026-05-22 # -# Conventions: -# - MDC key naming: snake_case (foundation L93 "snake_case 강제. camelCase / dot.case 금지.") +# 표기 규칙 +# - MDC key 이름: snake_case (foundation L93 "snake_case 강제. camelCase / dot.case 금지.") # - cardinality_safe_for_metric=true 인 key만 metric tag로 사용 가능 -# - foundation L93-102 표 "MDC Key Standard (final)" 6개가 core SSOT +# - foundation L93-102 표 "MDC Key Standard (final)"의 key들이 핵심 정본이다 mdc_keys: - # source: feature-operational-error-observability-foundation.md L97 + # 출처: feature-operational-error-observability-foundation.md L97 # "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id" - key: request_id type: ulid @@ -24,7 +24,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # source: feature-operational-error-observability-foundation.md L98 + # 출처: feature-operational-error-observability-foundation.md L98 # "trace_id | Micrometer Tracing | W3C traceparent header" - key: trace_id type: string @@ -39,7 +39,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # source: feature-operational-error-observability-foundation.md L99 + # 출처: feature-operational-error-observability-foundation.md L99 # "span_id | Micrometer Tracing | W3C traceparent" # NOTE: background-job-async-contract L71 "span_id는 Micrometer Observation context에서 자동 전파(MDC explicit copy 불필요)" - key: span_id @@ -55,7 +55,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # source: feature-operational-error-observability-foundation.md L100 + # 출처: feature-operational-error-observability-foundation.md L100 # "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id" - key: correlation_id type: ulid @@ -70,7 +70,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # source: feature-operational-error-observability-foundation.md L101 + feature-tenant-context-policy.md L70 + # 출처: feature-operational-error-observability-foundation.md L101 + feature-tenant-context-policy.md L70 # "tenant_id | tenant context (활성 시) | downstream HTTP X-Tenant-Id (with allowlist)" / # "tenant ID format = opaque ULID (26 chars Crockford base32)" # NOTE: tenant L73 "tenant_id ULID 원본은 metric tag에 직접 사용 금지" @@ -87,7 +87,7 @@ mdc_keys: compatibility_impact: additive required_test: contract-verification:tenant-leakage - # source: feature-operational-error-observability-foundation.md L102 + # 출처: feature-operational-error-observability-foundation.md L102 # "user_principal | security context (pseudonymized only) | log only, headers forbidden" - key: user_principal type: string @@ -102,10 +102,10 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # ── log type extensions (log-management-contract L101-109 "Log Type별 필수 필드") ── + # ── 로그 종류별 확장 (log-management-contract L101-109 "Log Type별 필수 필드") ── - # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" - # NOTE: application-port-usecase-contract / business 측 operation 식별자 (uri_template과 별도 application-set) + # 출처: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" + # 참고: application-port-usecase-contract / 업무 쪽 operation 식별자 (uri_template과 따로 application이 정한다) - key: operation type: string source: application_set @@ -119,7 +119,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" + # 출처: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" - key: method type: string source: inbound_filter @@ -133,8 +133,8 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" - # NOTE: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — bounded + # 출처: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" + # 참고: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — 값 개수가 정해져 있다 - key: status type: numeric source: inbound_filter @@ -148,7 +148,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L105-106 "request | ... duration_ms" / "dependency | ... duration_ms" + # 출처: feature-log-management-contract.md L105-106 "request | ... duration_ms" / "dependency | ... duration_ms" - key: duration_ms type: numeric source: application_set @@ -162,8 +162,8 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, duration_ms, outcome, error_code" - # NOTE: metrics L88 "dependency_name | 50" — bounded + # 출처: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, duration_ms, outcome, error_code" + # 참고: metrics L88 "dependency_name | 50" — 값 개수가 정해져 있다 - key: dependency_name type: string source: application_set @@ -177,7 +177,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, ..." + # 출처: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, ..." - key: dependency_type type: string source: application_set @@ -191,7 +191,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L106 + metrics L91 "outcome (resilience4j) | 5 (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED)" + # 출처: feature-log-management-contract.md L106 + metrics L91 "outcome (resilience4j) | 5 (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED)" - key: outcome type: string source: application_set @@ -205,8 +205,8 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L106 "dependency | ... error_code (실패 시)" - # NOTE: metrics L89 "error_code | 100 — error registry row 상한과 정합" — bounded + # 출처: feature-log-management-contract.md L106 "dependency | ... error_code (실패 시)" + # 참고: metrics L89 "error_code | 100 — error registry row 상한과 정합" — 값 개수가 정해져 있다 - key: error_code type: string source: application_set @@ -220,7 +220,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L107 + # 출처: feature-log-management-contract.md L107 # "security | event_type, user_principal (pseudonymized), source_ip (anonymized — last octet zeroed)" - key: event_type type: string @@ -235,7 +235,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L107 "security | ... source_ip (anonymized — last octet zeroed)" + # 출처: feature-log-management-contract.md L107 "security | ... source_ip (anonymized — last octet zeroed)" # NOTE: metrics L93 "high-cardinality 금지 tag: ... ip_address" - key: source_ip_anon type: string @@ -250,7 +250,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L108 "audit | actor, action, target, before_hash, after_hash, occurred_at" + # 출처: feature-log-management-contract.md L108 "audit | actor, action, target, before_hash, after_hash, occurred_at" - key: actor type: string source: security_context @@ -264,7 +264,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L108 "audit | actor, action, target, ..." + # 출처: feature-log-management-contract.md L108 "audit | actor, action, target, ..." - key: action type: string source: application_set @@ -278,7 +278,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # source: feature-log-management-contract.md L108 "audit | actor, action, target, ..." + # 출처: feature-log-management-contract.md L108 "audit | actor, action, target, ..." - key: target type: string source: application_set diff --git a/docs/registries/metrics.yaml b/docs/registries/metrics.yaml index a3ba89d8..8f7a6164 100644 --- a/docs/registries/metrics.yaml +++ b/docs/registries/metrics.yaml @@ -3,18 +3,20 @@ # Owner branch: feature-metrics-alerting-contract # Last updated: 2026-05-22 # -# Notes -# - Naming: Micrometer dot.case + unit suffix (.seconds | .bytes | .total). -# - Tag cardinality bounds are SSOT of feature-metrics-alerting-contract "Cardinality Bounds" table. -# - High-cardinality tags forbidden globally: user_id, request_id, raw_url, raw_query, -# raw_header_value, ip_address. These MUST NOT appear in any row. -# - tenant_id label is bounded mapping table id OR cohort bucket only (ULID raw forbidden). -# - error_code tag cardinality_limit follows error-codes.yaml row count (max 100). +# 읽는 법 +# - 이름: Micrometer dot.case에 단위 접미사(.seconds | .bytes | .total)를 붙인다. +# - tag 값 개수(cardinality) 상한의 정본은 feature-metrics-alerting-contract의 "Cardinality Bounds" 표다. +# - 값 개수가 많은 tag는 어디서도 쓰지 않는다: user_id, request_id, raw_url, raw_query, +# raw_header_value, ip_address. 어떤 행에도 나오면 안 된다. +# - tenant_id label은 크기가 정해진 매핑 표의 id나 cohort bucket만 쓴다(ULID 원문 금지). +# - error_code tag의 cardinality_limit은 error-codes.yaml 행 수를 따른다(최대 100). +# - alert_severity_thresholds 값은 경보 조건을 사람이 읽는 글로 적은 것이다. 지표 이름·연산자· +# 기간(5m, 1h)은 원문 그대로 두고, 테스트는 키(p1·p2·p3)와 값이 비어 있지 않은지만 본다. metrics: - # === HTTP server (inbound) === - # source: feature-metrics-alerting-contract — Metric/Alert Defaults + # === HTTP 서버 (inbound) === + # 출처: feature-metrics-alerting-contract — Metric/Alert Defaults # "HTTP metric | http.server.requests with method/status/uri-template | raw URL or user id tag" - name: http.server.requests type: timer @@ -32,15 +34,15 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p1: "error_rate > 5% for 5m OR > 10% for 1m" - p2: "error_rate > 1% for 10m" - p3: "error_rate > 0.1% for 1h" + p1: "error_rate > 5%가 5m 동안, 또는 > 10%가 1m 동안" + p2: "error_rate > 1%가 10m 동안" + p3: "error_rate > 0.1%가 1h 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [method, status, uri_template] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — P1/P2/P3 정량 기준 (HTTP latency p99) + # 출처: feature-metrics-alerting-contract — P1/P2/P3 정량 기준 (HTTP latency p99) # "P1: p99 > 5s 5분 / P2: p99 > 1s 10분 / P3: p99 > 500ms 30분" - name: http.server.requests.latency type: timer @@ -55,18 +57,18 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p1: "p99 > 5s for 5m" - p2: "p99 > 1s for 10m" - p3: "p99 > 500ms for 30m" + p1: "p99 > 5s가 5m 동안" + p2: "p99 > 1s가 10m 동안" + p3: "p99 > 500ms가 30m 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [method, uri_template, duration_ms] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === HTTP client (outbound dependency) === - # source: feature-metrics-alerting-contract — Metric/Alert Defaults + # === HTTP client (outbound 의존 대상) === + # 출처: feature-metrics-alerting-contract — Metric/Alert Defaults # "dependency metric | dependency.client.requests with dependency.name/type/outcome | endpoint with secret tag" - # source: feature-outbound-http-client-baseline — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + # 출처: feature-outbound-http-client-baseline — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" - name: dependency.client.requests type: timer unit: seconds @@ -82,17 +84,17 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p1: "required dep unavailable for 2m" - p2: "optional dep degraded for 5m" - p3: "spike alert (10x baseline)" + p1: "필수 의존 대상이 2m 동안 응답하지 않음" + p2: "선택 의존 대상이 5m 동안 저하됨" + p3: "급증 경보(기준선의 10배)" owner_branch: feature-metrics-alerting-contract log_field_mapping: [dependency_name, dependency_type, outcome, duration_ms] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-outbound-http-client-baseline — decisions - # "retry/circuit breaker 기본 라이브러리는 Resilience4j" - # source: feature-metrics-alerting-contract — "retry/CB minimum: resilience4j.retry.calls{outcome}" + # 출처: feature-outbound-http-client-baseline — 결정 + # "retry/circuit breaker 기본 라이브러리는 Resilience4j" + # 출처: feature-metrics-alerting-contract — "retry/CB minimum: resilience4j.retry.calls{outcome}" - name: resilience4j.retry.calls type: counter unit: total @@ -105,13 +107,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "retry exhaustion rate > 1% for 10m" + p2: "재시도 소진 비율 > 1%가 10m 동안" owner_branch: feature-outbound-http-client-baseline log_field_mapping: [dependency_name, outcome, retry_attempt] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.state" + # 출처: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.state" - name: resilience4j.circuitbreaker.state type: gauge unit: total @@ -124,14 +126,14 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p1: "state == OPEN for required dependency for 2m" - p2: "state == OPEN for optional dependency for 5m" + p1: "필수 의존 대상의 state == OPEN이 2m 동안" + p2: "선택 의존 대상의 state == OPEN이 5m 동안" owner_branch: feature-outbound-http-client-baseline log_field_mapping: [dependency_name] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.calls{outcome}" + # 출처: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.calls{outcome}" - name: resilience4j.circuitbreaker.calls type: timer unit: seconds @@ -144,16 +146,16 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p2: "CIRCUIT_OPEN rate > 1% for 10m" + p2: "CIRCUIT_OPEN 비율 > 1%가 10m 동안" owner_branch: feature-outbound-http-client-baseline log_field_mapping: [dependency_name, outcome, duration_ms] compatibility_impact: additive required_test: contract-verification:metrics-cardinality # === DB connection pool === - # source: feature-persistence-failure-baseline — Hikari Alert Threshold + # 출처: feature-persistence-failure-baseline — Hikari Alert Threshold # "pool wait p99 > 100ms 5분 지속 → P2 / pool exhaustion (active = max) > 1분 → P1" - # source: feature-metrics-alerting-contract — "hikaricp.connections.acquire{outcome='timeout'} p99 > 100ms" + # 출처: feature-metrics-alerting-contract — "hikaricp.connections.acquire{outcome='timeout'} p99 > 100ms" - name: hikaricp.connections.acquire type: timer unit: seconds @@ -166,14 +168,14 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p1: "pool exhaustion (active == max) for 1m" - p2: "acquire p99 > 100ms for 5m" + p1: "pool 고갈(active == max)이 1m 동안" + p2: "acquire p99 > 100ms가 5m 동안" owner_branch: feature-persistence-failure-baseline log_field_mapping: [pool, outcome] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-persistence-failure-baseline — In scope "Hikari metric 노출 기준" + Hikari Alert Threshold + # 출처: feature-persistence-failure-baseline — 범위 안 "Hikari metric 노출 기준" + Hikari Alert Threshold - name: hikaricp.connections.usage type: timer unit: seconds @@ -183,13 +185,13 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p2: "usage p99 elevated > 10m" + p2: "usage p99가 10m 넘게 높음" owner_branch: feature-persistence-failure-baseline log_field_mapping: [pool] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-persistence-failure-baseline — In scope "Hikari metric 노출 기준" + # 출처: feature-persistence-failure-baseline — 범위 안 "Hikari metric 노출 기준" - name: hikaricp.connections.active type: gauge unit: total @@ -199,13 +201,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p1: "active == max for 1m" + p1: "active == max가 1m 동안" owner_branch: feature-persistence-failure-baseline log_field_mapping: [pool] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — Histogram Buckets/Percentile "DB query: same" + # 출처: feature-metrics-alerting-contract — Histogram Buckets/Percentile "DB query: same" - name: db.query.duration type: timer unit: seconds @@ -219,14 +221,14 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p2: "p99 > 1s for 10m" + p2: "p99 > 1s가 10m 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [operation, outcome, duration_ms] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === Background job / async executor === - # source: feature-background-job-async-contract — Decisionized Work Items "saturation policy" + # === 백그라운드 작업 / 비동기 executor === + # 출처: feature-background-job-async-contract — Decisionized Work Items "saturation policy" # "AbortPolicy default (core=10, max=50, queue=200)" - name: executor.saturation type: gauge @@ -237,14 +239,14 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "queue size > 80% capacity for 5m" - p1: "rejection rate > 0 for 1m" + p2: "queue 크기 > 용량의 80%가 5m 동안" + p1: "거절 비율 > 0이 1m 동안" owner_branch: feature-background-job-async-contract log_field_mapping: [executor_name] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-background-job-async-contract — Decisionized Work Items "saturation | bounded executor + rejection log" + # 출처: feature-background-job-async-contract — 결정한 작업 항목 "saturation | bounded executor + rejection log" - name: executor.rejected.total type: counter unit: total @@ -257,13 +259,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p1: "rejection_count > 0 for 1m" + p1: "rejection_count > 0이 1m 동안" owner_branch: feature-background-job-async-contract log_field_mapping: [executor_name, policy] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-background-job-async-contract — Decisionized Work Items "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted" + # 출처: feature-background-job-async-contract — 결정한 작업 항목 "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted" - name: job.retry.total type: counter unit: total @@ -276,13 +278,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "EXHAUSTED rate > 1% for 10m" + p2: "EXHAUSTED 비율 > 1%가 10m 동안" owner_branch: feature-background-job-async-contract log_field_mapping: [job_name, outcome, retry_attempt] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-background-job-async-contract — "DLQ after exhausted attempts" + # 출처: feature-background-job-async-contract — "DLQ after exhausted attempts" - name: job.dlq.total type: counter unit: total @@ -292,14 +294,14 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p1: "DLQ rate sustained > 0 for 5m" + p1: "DLQ 비율 > 0이 5m 동안 계속" owner_branch: feature-background-job-async-contract log_field_mapping: [job_name] compatibility_impact: additive required_test: contract-verification:metrics-cardinality # === Distributed lock === - # source: feature-distributed-lock-contract D7 — "metric lock.acquisition (tag: outcome = + # 출처: feature-distributed-lock-contract D7 — "metric lock.acquisition (tag: outcome = # acquired/timeout/error) — 신규 제안" / D5 — try-lock + 유한 waitTime + lease(TTL). 분산 # 상호배제(distributedLockProvider) 획득 시도 결과를 센다. key 는 tag 로 넣지 않는다 # (무한 cardinality — 위 전역 금지 규칙). timeout outcome 은 LOCK_ACQUISITION_TIMEOUT 발생과 1:1. @@ -313,18 +315,17 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "timeout rate > 5% for 10m" + p2: "timeout 비율 > 5%가 10m 동안" owner_branch: feature-distributed-lock-contract log_field_mapping: [outcome] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-distributed-lock-contract §Edge / D5 (SI-LOCK-C5) — "lease 만료 후 unlock → - # ConcurrentModificationException — 삼킴 금지, 로그+metric 후 정상 흐름 복귀". Counts releases that - # found the lease already expired (the JdbcLock row was reclaimed by another instance before - # the holder called close()). A sustained nonzero rate means lease TTL is shorter than real - # critical-section duration — raise APP/lease TTL or shorten the protected work. Not an - # acquisition outcome, hence a separate counter from lock.acquisition. + # 출처: feature-distributed-lock-contract §Edge / D5 (SI-LOCK-C5) — "lease 만료 후 unlock → + # ConcurrentModificationException — 삼킴 금지, 로그+metric 후 정상 흐름 복귀". lease가 이미 만료된 뒤의 + # 해제를 센다(보유자가 close()를 부르기 전에 다른 인스턴스가 JdbcLock 행을 회수함). 0이 아닌 비율이 + # 이어지면 lease TTL이 실제 임계 구역 시간보다 짧다는 뜻이다 — APP/lease TTL을 늘리거나 보호하는 일을 + # 줄인다. 획득 결과가 아니라서 lock.acquisition과 다른 counter다. - name: lock.lease.expired type: counter unit: total @@ -332,14 +333,14 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "lease-expired rate sustained > 0 for 10m" + p2: "lease-expired 비율 > 0이 10m 동안 계속" owner_branch: feature-distributed-lock-contract log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === Outbox publisher === - # source: feature-domain-event-outbox-contract — Outbox Defaults + # === Outbox 발행기 === + # 출처: feature-domain-event-outbox-contract — Outbox Defaults # "DB outbox table with eventId, aggregateId, eventType, payload, occurredAt, status, attemptCount, nextAttemptAt" - name: outbox.publisher.published.total type: counter @@ -349,20 +350,20 @@ metrics: cardinality_limit: 50 - name: outcome cardinality_limit: 5 - # The relay cycle outcomes (OutboxRelayResult.Outcome), not row statuses: IN_FLIGHT is a status - # and is never counted. STALE: the relay's claim was taken over before its result could be - # written (V17 lease fence). RELEASED: a stopping relay gave back a claim it had not used. + # 행 상태가 아니라 relay 한 바퀴의 결과(OutboxRelayResult.Outcome)다. IN_FLIGHT는 상태라 세지 않는다. + # STALE: relay의 claim을 결과를 쓰기 전에 다른 쪽이 넘겨받았다(V17 lease fence). RELEASED: 멈추는 relay가 + # 쓰지 않은 claim을 돌려줬다. allowed_values: [PUBLISHED, FAILED, DEAD, STALE, RELEASED] percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "FAILED rate > 1% for 10m, or STALE > 0 for 10m (in-flight timeout shorter than a relay stall)" + p2: "FAILED 비율 > 1%가 10m 동안, 또는 STALE > 0이 10m 동안(in-flight timeout이 relay 정지보다 짧다)" owner_branch: feature-domain-event-outbox-contract log_field_mapping: [event_type, outcome, event_id] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-domain-event-outbox-contract — row status enum PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD + # 출처: feature-domain-event-outbox-contract — 행 상태 enum PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD - name: outbox.publisher.lag type: gauge unit: seconds @@ -372,15 +373,15 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "lag > 60s for 10m" - p1: "lag > 300s for 5m" + p2: "lag > 60s가 10m 동안" + p1: "lag > 300s가 5m 동안" owner_branch: feature-domain-event-outbox-contract log_field_mapping: [event_type] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-domain-event-outbox-contract — row status enum + Outbox Defaults attemptCount - # PARKED: an operator held a row that was retried without end (re-review 2026-11-03 RR-05-03). + # 출처: feature-domain-event-outbox-contract — row status enum + Outbox Defaults attemptCount + # PARKED: 끝없이 재시도되던 행을 운영자가 붙잡아 둠 (re-review 2026-11-03 RR-05-03). - name: outbox.pending.size type: gauge unit: total @@ -390,19 +391,19 @@ metrics: allowed_values: [PENDING, IN_FLIGHT, PUBLISHED, FAILED, DEAD, PARKED] percentiles: null histogram_buckets: null - # DEAD > 0: the claim moves a row it will not hand out to DEAD without a relay result, so - # outbox.publisher.published.total{outcome=DEAD} misses it (re-review round 2, RR-02-12). + # DEAD > 0: claim은 내주지 않을 행을 relay 결과 없이 DEAD로 옮기므로 + # outbox.publisher.published.total{outcome=DEAD}가 그것을 놓친다 (re-review round 2, RR-02-12). alert_severity_thresholds: p1: "DEAD > 0 (runbook://outbox/dead-letter)" - p2: "PENDING size growing for 10m" + p2: "PENDING 크기가 10m 동안 늘어남" owner_branch: feature-domain-event-outbox-contract log_field_mapping: [status] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: re-review 2026-11-03 RR-05-03 — a refusal for now and an unanswered publish are retried - # without end; these count the FAILED rows deferred at least 10 times (OutboxMetrics - # LONG_RETRY_DEFERRED_CLAIMS, the publish-failed runbook's §4.1 query) and age the oldest of them. + # 출처: re-review 2026-11-03 RR-05-03 — 지금의 거절과 답이 없는 발행은 끝없이 재시도된다. 이 둘은 + # 10번 이상 미뤄진 FAILED 행을 세고(OutboxMetrics LONG_RETRY_DEFERRED_CLAIMS, publish-failed runbook §4.1 + # 조회), 그중 가장 오래된 것의 나이를 잰다. - name: outbox.retry.long.size type: gauge unit: total @@ -410,7 +411,7 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "> 0 for 10m (runbook://outbox/publish-failed §4.1)" + p2: "> 0이 10m 동안 (runbook://outbox/publish-failed §4.1)" owner_branch: feature-domain-event-outbox-contract log_field_mapping: [] compatibility_impact: additive @@ -429,8 +430,8 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === Cache === - # source: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default" + # === 캐시 === + # 출처: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default" - name: cache.gets.total type: counter unit: total @@ -443,13 +444,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p3: "hit_ratio < baseline 0.5x for 1h" + p3: "hit_ratio < 기준선의 0.5배가 1h 동안" owner_branch: feature-cache-consistency-contract log_field_mapping: [cache_name, result] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-cache-consistency-contract — "invalidation = after-commit only", "invalidation 실패가 조용히 무시되면 실패" + # 출처: feature-cache-consistency-contract — "invalidation = after-commit only", "invalidation 실패가 조용히 무시되면 실패" - name: cache.invalidations.total type: counter unit: total @@ -462,13 +463,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "FAILURE rate > 0 for 5m" + p2: "FAILURE 비율 > 0이 5m 동안" owner_branch: feature-cache-consistency-contract log_field_mapping: [cache_name, outcome] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: redis-production-capability — optional bounded cache-only L1 + # 출처: redis-production-capability — 크기가 정해진 캐시 전용 L1 (선택) - name: cache.local.requests.total type: counter unit: total @@ -481,13 +482,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p3: "bypass or error rate above baseline for 15m" + p3: "bypass 또는 error 비율이 기준선보다 높은 상태가 15m 동안" owner_branch: redis-production-capability log_field_mapping: [cache_name, result] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: redis-production-capability — local stale-age bound + # 출처: redis-production-capability — 로컬 stale 나이 상한 - name: cache.local.entry.age.seconds type: timer unit: seconds @@ -497,13 +498,13 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p3: "p99 approaches configured local TTL for 30m" + p3: "p99가 설정한 로컬 TTL에 가까운 상태가 30m 동안" owner_branch: redis-production-capability log_field_mapping: [cache_name] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: redis-production-capability — bounded invalidation and generation reconciliation + # 출처: redis-production-capability — 크기가 정해진 무효화와 세대 대조(reconciliation) - name: cache.local.maintenance.total type: counter unit: total @@ -530,37 +531,36 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "reconcile_error, subscriber_overflow, or sustained disconnects for 5m" + p2: "reconcile_error, subscriber_overflow, 또는 끊김이 5m 동안 계속" owner_branch: redis-production-capability log_field_mapping: [cache_name, event] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === Redis connection lanes === - # source: review 2026-11-03 RR-04-02 — the cache's conditional writes got their own lane - # (CACHE_SCRIPT) so that cache fills cannot take the SCRIPT lane's connections from idempotency, - # rate limiting and leases. These meters show, per lane, whether that holds. Emitted by - # redis-runtime RedisLaneMetrics for every lane RedisRuntimeOwner pools, only when the context has - # a MeterRegistry. Every counter series is registered at zero at startup. + # === Redis 연결 lane === + # 출처: review 2026-11-03 RR-04-02 — 캐시의 조건부 쓰기는 자기 lane(CACHE_SCRIPT)을 받았다. 캐시 채우기가 + # idempotency·rate limiting·lease의 SCRIPT lane 연결을 가져가지 못하게 하려는 것이다. 이 meter들이 lane마다 + # 그것이 지켜지는지 보여 준다. redis-runtime RedisLaneMetrics가 RedisRuntimeOwner가 pool로 가진 모든 lane에 + # 대해, context에 MeterRegistry가 있을 때만 낸다. 모든 counter 계열은 기동 때 0으로 등록한다. - name: redis.lane.acquire.wait.seconds type: timer unit: seconds tags: - name: lane - # The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, - # TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution. + # lane 이름: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, + # TRANSACTION, ADMIN (redis-sdk), 그리고 서비스가 RedisLaneContribution으로 조립한 lane. cardinality_limit: 12 - name: outcome cardinality_limit: 2 allowed_values: [admitted, refused] - # As RedisLaneMetrics registers it: a percentile histogram (publishPercentileHistogram, expected - # range 1ms..10s) and no client-side percentiles and no SLO boundaries. The p99 below is a - # histogram_quantile over the buckets (re-review 2026-11-04 RR-03-17). + # RedisLaneMetrics가 등록하는 모양: percentile histogram(publishPercentileHistogram, 예상 범위 + # 1ms..10s)이고, client 쪽 percentile과 SLO 경계는 없다. 아래 p99는 bucket 위의 histogram_quantile이다 + # (re-review 2026-11-04 RR-03-17). percentiles: null histogram_buckets: percentile_histogram alert_severity_thresholds: - p2: "SCRIPT admitted p99 > 100ms for 10m (the correctness lane is queueing)" - p3: "CACHE_SCRIPT admitted p99 > 100ms for 30m" + p2: "SCRIPT admitted p99 > 100ms가 10m 동안(정확성 lane이 줄을 서고 있다)" + p3: "CACHE_SCRIPT admitted p99 > 100ms가 30m 동안" owner_branch: redis-production-capability log_field_mapping: [lane, outcome] compatibility_impact: additive @@ -571,8 +571,8 @@ metrics: unit: total tags: - name: lane - # The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, - # TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution. + # lane 이름: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, + # TRANSACTION, ADMIN (redis-sdk), 그리고 서비스가 RedisLaneContribution으로 조립한 lane. cardinality_limit: 12 - name: reason cardinality_limit: 4 @@ -580,8 +580,8 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p1: "SCRIPT or REGULAR saturated or connect_failed above zero for 2m while a correctness role is selected" - p2: "CACHE_SCRIPT saturated above baseline for 10m" + p1: "정확성 role을 고른 상태에서 SCRIPT 또는 REGULAR의 saturated나 connect_failed가 0보다 큰 상태가 2m 동안" + p2: "CACHE_SCRIPT saturated가 기준선보다 높은 상태가 10m 동안" owner_branch: redis-production-capability log_field_mapping: [lane, reason] compatibility_impact: additive @@ -592,13 +592,13 @@ metrics: unit: total tags: - name: lane - # The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, - # TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution. + # lane 이름: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, + # TRANSACTION, ADMIN (redis-sdk), 그리고 서비스가 RedisLaneContribution으로 조립한 lane. cardinality_limit: 12 percentiles: null histogram_buckets: null alert_severity_thresholds: - p3: "opened rate after warm-up above baseline for 15m (reconnect churn against a slow Redis)" + p3: "warm-up 뒤 opened 비율이 기준선보다 높은 상태가 15m 동안(느린 Redis에 다시 연결하며 흔들림)" owner_branch: redis-production-capability log_field_mapping: [lane] compatibility_impact: additive @@ -609,8 +609,8 @@ metrics: unit: total tags: - name: lane - # The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, - # TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution. + # lane 이름: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, + # TRANSACTION, ADMIN (redis-sdk), 그리고 서비스가 RedisLaneContribution으로 조립한 lane. cardinality_limit: 12 - name: reason cardinality_limit: 2 @@ -618,7 +618,7 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p3: "invalidated rate above baseline for 15m (timed-out or failed calls discarding connections)" + p3: "invalidated 비율이 기준선보다 높은 상태가 15m 동안(timeout·실패한 호출이 연결을 버림)" owner_branch: redis-production-capability log_field_mapping: [lane, reason] compatibility_impact: additive @@ -629,13 +629,13 @@ metrics: unit: total tags: - name: lane - # The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, - # TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution. + # lane 이름: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, + # TRANSACTION, ADMIN (redis-sdk), 그리고 서비스가 RedisLaneContribution으로 조립한 lane. cardinality_limit: 12 percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "SCRIPT active == configured maximum-script-connections for 5m" + p2: "SCRIPT active == 설정한 maximum-script-connections가 5m 동안" owner_branch: redis-production-capability log_field_mapping: [lane] compatibility_impact: additive @@ -646,20 +646,20 @@ metrics: unit: total tags: - name: lane - # The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, - # TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution. + # lane 이름: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING, + # TRANSACTION, ADMIN (redis-sdk), 그리고 서비스가 RedisLaneContribution으로 조립한 lane. cardinality_limit: 12 percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "SCRIPT pending > 0 for 5m" + p2: "SCRIPT pending > 0이 5m 동안" owner_branch: redis-production-capability log_field_mapping: [lane] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === Log appender === - # source: feature-log-management-contract — Sampling Policy (final) + # === 로그 appender === + # 출처: feature-log-management-contract — Sampling Policy (final) # "async appender overflow default: drop oldest INFO/DEBUG with counter metric (log.appender.dropped.total)" - name: log.appender.dropped.total type: counter @@ -673,14 +673,14 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "dropped > 0 sustained for 10m" + p2: "dropped > 0이 10m 동안 계속" owner_branch: feature-log-management-contract log_field_mapping: [appender, level] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === Distributed tracing === - # source: feature-distributed-tracing-contract — decisions + # === 분산 추적 === + # 출처: feature-distributed-tracing-contract — decisions # "trace sampling rate default = prod 1%, dev/local 100%; shipped runtime profiles are local|dev|prod" - name: tracing.sampling.rate type: gauge @@ -692,14 +692,14 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p3: "effective rate deviates from configured for 1h" + p3: "실제 비율이 설정값과 1h 동안 어긋남" owner_branch: feature-distributed-tracing-contract log_field_mapping: [profile] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # === JVM baseline === - # source: feature-metrics-alerting-contract — In scope "JVM/process metric" + # === JVM 기본 === + # 출처: feature-metrics-alerting-contract — In scope "JVM/process metric" - name: jvm.memory.used type: gauge unit: bytes @@ -712,13 +712,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p2: "heap used / max > 0.85 for 10m" + p2: "heap used / max > 0.85가 10m 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [area, id] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — In scope "JVM/process metric" + # 출처: feature-metrics-alerting-contract — 범위 안 \"JVM/process metric\" - name: jvm.gc.pause type: timer unit: seconds @@ -730,13 +730,13 @@ metrics: percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p2: "p99 pause > 500ms for 10m" + p2: "p99 pause > 500ms가 10m 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [action, cause] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — In scope "JVM/process metric" + # 출처: feature-metrics-alerting-contract — 범위 안 \"JVM/process metric\" - name: jvm.threads.live type: gauge unit: total @@ -744,13 +744,13 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p3: "thread count > 2x baseline for 30m" + p3: "thread 수 > 기준선의 2배가 30m 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # source: feature-metrics-alerting-contract — In scope "JVM/process metric" (process uptime) + # 출처: feature-metrics-alerting-contract — 범위 안 \"JVM/process metric\" (process uptime) - name: process.uptime type: gauge unit: seconds @@ -758,7 +758,7 @@ metrics: percentiles: null histogram_buckets: null alert_severity_thresholds: - p1: "uptime reset unexpectedly < 60s (crash loop signal)" + p1: "uptime이 예상 밖으로 < 60s로 초기화됨(crash loop 신호)" owner_branch: feature-metrics-alerting-contract log_field_mapping: [] compatibility_impact: additive diff --git a/docs/registries/object-storage-readiness.yaml b/docs/registries/object-storage-readiness.yaml index b9d2d0ae..9efa7038 100644 --- a/docs/registries/object-storage-readiness.yaml +++ b/docs/registries/object-storage-readiness.yaml @@ -14,9 +14,9 @@ claims: required_tasks: - ":adapter:outbound:objectstorage:check" limitations: - - single-process control CAS only; no multi-node linearizability - - fsync and atomic move tests do not prove power-loss durability - - local development provider is forbidden in production profiles + - 한 프로세스 안의 control CAS만 보장한다. 여러 노드의 선형성(linearizability)은 없다 + - fsync·atomic move 시험은 전원이 꺼져도 남는다는 것을 증명하지 않는다 + - 로컬 개발용 제공자는 production profile에서 쓸 수 없다 - card_id: object-storage-managed-upload-multipart provider_type: filesystem-local-dev @@ -28,7 +28,7 @@ claims: required_tasks: - ":application-core:check" limitations: - - multipart publication protocol is not implemented + - multipart 게시 프로토콜은 구현하지 않았다 - card_id: object-storage-managed-download provider_type: filesystem-local-dev @@ -40,8 +40,8 @@ claims: required_tasks: - ":adapter:outbound:objectstorage:check" limitations: - - local functional full and range reads are not production-provider qualification - - no multi-node or power-loss durability claim + - 로컬의 전체·범위 읽기 기능 시험은 운영 제공자 qualification이 아니다 + - 여러 노드나 전원 손실에 대한 내구성은 주장하지 않는다 - card_id: object-storage-direct-upload-single provider_type: filesystem-local-dev @@ -53,7 +53,7 @@ claims: required_tasks: - ":application-core:check" limitations: - - direct grant provider and public inbound endpoint are not implemented + - 직접 grant 제공자와 공개 inbound endpoint는 구현하지 않았다 - card_id: object-storage-direct-upload-multipart provider_type: filesystem-local-dev @@ -65,7 +65,7 @@ claims: required_tasks: - ":application-core:check" limitations: - - direct multipart session and public inbound endpoint are not implemented + - 직접 multipart session과 공개 inbound endpoint는 구현하지 않았다 - card_id: object-storage-direct-download provider_type: filesystem-local-dev @@ -77,7 +77,7 @@ claims: required_tasks: - ":application-core:check" limitations: - - direct download grant and public inbound endpoint are not implemented + - 직접 download grant와 공개 inbound endpoint는 구현하지 않았다 - card_id: object-storage-quarantine-publication provider_type: filesystem-local-dev @@ -89,7 +89,7 @@ claims: required_tasks: - ":application-core:check" limitations: - - scanner handoff and verdict fencing are not implemented + - scanner 인계와 판정 fencing은 구현하지 않았다 - card_id: object-storage-retention provider_type: filesystem-local-dev @@ -101,8 +101,8 @@ claims: required_tasks: - ":application-core:check" limitations: - - retention and legal-hold provider enforcement are not implemented - - privileged purge composition remains intentionally empty + - 보존(retention)·법적 보존(legal hold)의 제공자 쪽 강제는 구현하지 않았다 + - 특권 purge 조립은 일부러 비워 두었다 - card_id: object-storage-reconciliation provider_type: filesystem-local-dev @@ -114,5 +114,5 @@ claims: required_tasks: - ":application-core:check" limitations: - - local create resolution is single-process functional evidence only - - production response-loss and multi-node reconciliation are not implemented + - 로컬 create 해소는 한 프로세스 안의 기능 증거일 뿐이다 + - 운영 환경의 응답 유실과 여러 노드 사이의 맞춤(reconciliation)은 구현하지 않았다 diff --git a/docs/registries/secrets-classification.yaml b/docs/registries/secrets-classification.yaml index bddb0aeb..860b33f3 100644 --- a/docs/registries/secrets-classification.yaml +++ b/docs/registries/secrets-classification.yaml @@ -3,8 +3,8 @@ # Owner branch: feature-secrets-config-source-contract # Last updated: 2026-05-22 # -# Conventions: -# - 3-tier classification (feature-secrets-config-source-contract 2026-05-22): +# 표기 규칙 +# - 분류는 세 등급이다 (feature-secrets-config-source-contract 2026-05-22): # public-config | sensitive-config | secret # - `secret` rows: prod_default 항상 null. dev fake 식별자는 `__LOCAL_DEV_` prefix # (feature-secrets-config-source-contract 2026-05-22: "dev/local sentinel value prefix = __LOCAL_DEV_"). @@ -15,22 +15,23 @@ # RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS, # SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/` 참조가 # 가리키는 변수. HOSTNAME·앱 이름 같은 비밀이 아닌 값은 보지 않는다 (review 2026-11-04 RR2-04-01). -# - Masking 기본 = `full_except_last_4` (feature-secrets-config-source-contract 2026-05-22: -# "full mask except last 4 chars for non-secret tokens"). 진짜 secret(password/private key)은 `full`. -# - Naming suffix는 보조 신호 (feature-secrets-config-source-contract: "_TOKEN, _KEY, _PASSWORD"). +# - 가림(masking) 기본 = `full_except_last_4` (feature-secrets-config-source-contract 2026-05-22: +# "full mask except last 4 chars for non-secret tokens" — 비밀이 아닌 토큰은 끝 4자만 남기고 가린다). +# 진짜 secret(password/private key)은 `full`. +# - 이름 접미사는 보조 신호다 (feature-secrets-config-source-contract: "_TOKEN, _KEY, _PASSWORD"). # - public-config 항목은 env-keys.yaml에서 직접 정의되며 본 파일에는 reference row만 둠. secrets: - # === Tier 3: secret (true secret — password/private-key/HMAC-salt) === + # === 3등급: secret (진짜 비밀 — password/private-key/HMAC-salt) === - name: APP_DATASOURCE_PASSWORD - # source: feature-secrets-config-source-contract 2026-05-22 + # 출처: feature-secrets-config-source-contract 2026-05-22 # "DB credential은 dual-bind 60s" + "__LOCAL_DEV_FAKE_DB_PASSWORD" 예시 classification: secret source: secret-manager - # Contributed by persistence-jpa (JpaStartupAutoConfiguration#jpaProductionSecrets) while the - # module is on; the composition root's guard no longer reads the module switch (P22-new-1). + # persistence-jpa가 모듈이 켜진 동안 기여한다(JpaStartupAutoConfiguration#jpaProductionSecrets). 조립 루트의 + # 관문은 이제 모듈 스위치를 읽지 않는다(P22-new-1). required_when: app.persistence-jpa.enabled=true rotation_policy: dual-bind-60s prod_default: null @@ -41,8 +42,8 @@ secrets: required_test: secrets-contract:db-password-no-leak-in-actuator - name: SPRING_MAIL_PASSWORD - # source: notification/fileserver techlead review H2 — credential consumed natively by Spring - # Mail and therefore intentionally retains the SPRING_* name rather than gaining an APP_* alias. + # 출처: notification/fileserver techlead review H2 — Spring Mail이 직접 읽는 자격 증명이라 APP_* 별칭을 두지 + # 않고 일부러 SPRING_* 이름을 유지한다. classification: secret source: secret-manager rotation_policy: restart-only @@ -55,14 +56,14 @@ secrets: required_test: secrets-contract:smtp-password-no-leak - name: APP_CACHE_REDIS_PASSWORD - # source: feature-secrets-config-source-contract 2026-05-22 - # 3-tier classification "secret" + feature-integration-adapter-templates "Redis | disabled optional module" - # (Redis enabled + auth 사용 시 secret으로 분류) + # 출처: feature-secrets-config-source-contract 2026-05-22 + # 3등급 분류 "secret" + feature-integration-adapter-templates "Redis | disabled optional module" + # (Redis를 켜고 인증을 쓰면 secret으로 분류) classification: secret source: secret-manager rotation_policy: restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.capabilities.cache.bindings.default=redis dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: feature-secrets-config-source-contract @@ -71,7 +72,7 @@ secrets: required_test: secrets-contract:redis-password-no-leak - name: APP_CACHE_REDIS_TRUST_PEM - # Public CA bundle content, but integrity-sensitive and supplied by the mounted environment. + # 공개 CA bundle 내용이지만 무결성이 중요하고, 마운트된 환경이 준다. classification: sensitive-config source: mounted-env rotation_policy: restart-only @@ -83,12 +84,12 @@ secrets: required_test: secrets-contract:redis-trust-reference-no-leak - name: APP_CACHE_REDIS_KEY_HMAC_SECRET - # Stable cache-key HMAC material. It is distinct from the Redis authentication credential. + # 바뀌지 않는 캐시 key HMAC 자료. Redis 인증 자격 증명과 다르다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.capabilities.cache.bindings.default=redis dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: codex-phase-a-ci-recovery @@ -97,12 +98,12 @@ secrets: required_test: secrets-contract:redis-key-hmac-no-leak - name: APP_RATE_LIMIT_REDIS_PASSWORD - # Dedicated coordination-role Redis credential. It is never inherited from cache Redis. + # coordination role 전용 Redis 자격 증명. 캐시 Redis에서 물려받지 않는다. classification: secret source: secret-manager rotation_policy: restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.capabilities.rate-limit.provider=redis dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: redis-distributed-rate-limit @@ -111,7 +112,7 @@ secrets: required_test: secrets-contract:rate-limit-redis-password-no-leak - name: APP_RATE_LIMIT_REDIS_TRUST_PEM - # Coordination-role CA bundle content; integrity-sensitive but not credential material. + # coordination role CA bundle 내용. 무결성이 중요하지만 자격 증명 자료는 아니다. classification: sensitive-config source: mounted-env rotation_policy: restart-only @@ -123,12 +124,12 @@ secrets: required_test: secrets-contract:rate-limit-redis-trust-reference-no-leak - name: APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET - # Stable private-key derivation material for rate-limit subjects and policy revisions. + # rate-limit 대상과 정책 개정에 쓰는, 바뀌지 않는 비공개 key 파생 자료. classification: secret source: secret-manager rotation_policy: dual-read-restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.capabilities.rate-limit.provider=redis dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: redis-distributed-rate-limit @@ -137,12 +138,12 @@ secrets: required_test: secrets-contract:rate-limit-redis-key-hmac-no-leak - name: APP_SESSION_REDIS_PASSWORD - # Dedicated session-role ACL credential; never shared implicitly with cache or coordination. + # session role 전용 ACL 자격 증명. 캐시나 coordination과 몰래 함께 쓰지 않는다. classification: secret source: secret-manager rotation_policy: restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.security.auth-mode=redis-session dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: redis-production-capability @@ -151,7 +152,7 @@ secrets: required_test: secrets-contract:session-redis-password-no-leak - name: APP_SESSION_REDIS_TRUST_PEM - # Session-role CA bundle content; integrity-sensitive but not credential material. + # session role CA bundle 내용. 무결성이 중요하지만 자격 증명 자료는 아니다. classification: sensitive-config source: mounted-env rotation_policy: restart-only @@ -163,12 +164,12 @@ secrets: required_test: secrets-contract:session-redis-trust-reference-no-leak - name: APP_SESSION_REDIS_KEY_HMAC_SECRET - # Stable private derivation material for pseudonymous Redis session keys. + # 가명 Redis session key에 쓰는, 바뀌지 않는 비공개 파생 자료. classification: secret source: secret-manager rotation_policy: dual-read-restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.security.auth-mode=redis-session dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: redis-production-capability @@ -177,12 +178,12 @@ secrets: required_test: secrets-contract:session-redis-key-hmac-no-leak - name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET - # Owner-safe request-replay keys must not expose tenant/scope/request identifiers. + # owner-safe 요청 replay key가 tenant·scope·요청 식별자를 드러내면 안 된다. classification: secret source: secret-manager rotation_policy: cold-cutover-restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.capabilities.idempotency.provider=redis dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: redis-production-capability-completion @@ -191,12 +192,12 @@ secrets: required_test: secrets-contract:idempotency-redis-key-hmac-no-leak - name: APP_LEASE_REDIS_KEY_HMAC_SECRET - # Efficiency-lease resource and owner scopes use a dedicated derivation key. + # 효율 lease의 자원·소유자 scope는 전용 파생 key를 쓴다. classification: secret source: secret-manager rotation_policy: cold-cutover-restart-only prod_default: null - # Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets. + # app.redis.enabled=true이고 이 role을 고르면 필요하다. adapter-outbound-cache-redis의 RedisProductionSecrets가 확인한다. required_when: app.capabilities.lease.provider=redis dev_sentinel_prefix: __LOCAL_DEV_ owner_branch: redis-production-capability-completion @@ -205,7 +206,7 @@ secrets: required_test: secrets-contract:lease-redis-key-hmac-no-leak - name: APP_PRIVACY_PSEUDONYMIZATION_SALT - # source: feature-data-retention-privacy-contract 2026-05-22 + # 출처: feature-data-retention-privacy-contract 2026-05-22 # "pseudonymization key = HMAC-SHA-256 with rotating salt. salt rotation interval = 90일. # rotation 시 old salt 90일 retain (lookup 가능)." # + feature-tenant-context-policy "tenant identifier는 raw PII가 아니어야 하며 ... pseudonymized id" @@ -219,13 +220,12 @@ secrets: compatibility_impact: breaking required_test: secrets-contract:pseudonymization-salt-rotation - # === Tier 2: sensitive-config (token-bearing URL or id with exposure restriction) === + # === 2등급: sensitive-config (토큰이 든 URL이나 노출을 제한할 id) === - name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY - # Encrypts recipient contact points at rest — addresses and phone numbers. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # 저장된 수신자 연락처(주소와 전화번호)를 암호화한다. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -238,10 +238,9 @@ secrets: required_test: secrets-contract:notification-contact-encryption-no-leak - name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY - # Blind index over contact points, so a lookup never needs the plaintext. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # 연락처의 blind index. 조회에 평문이 필요 없게 한다. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -254,10 +253,9 @@ secrets: required_test: secrets-contract:notification-contact-lookup-hmac-no-leak - name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY - # Signs the callback URLs a provider posts delivery outcomes back to. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # provider가 전달 결과를 보내는 callback URL에 서명한다. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -270,10 +268,9 @@ secrets: required_test: secrets-contract:notification-callback-signing-no-leak - name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY - # Encrypts stored provider credentials, which are themselves secrets. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # 저장된 provider 자격 증명(그 자체가 비밀)을 암호화한다. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -286,10 +283,9 @@ secrets: required_test: secrets-contract:notification-provider-credential-no-leak - name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY - # Encrypts notification variables and retained callback bodies at rest. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # 저장된 알림 변수와 보관한 callback 본문을 암호화한다. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -302,10 +298,9 @@ secrets: required_test: secrets-contract:notification-payload-encryption-no-leak - name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY - # Keyed hash of provider request ids, which are provider-side identifiers. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # provider 쪽 식별자인 provider request id의 key 있는 hash. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -318,10 +313,9 @@ secrets: required_test: secrets-contract:notification-provider-request-lookup-hmac-no-leak - name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY - # Keyed fingerprint of callback bodies, used to detect replays. - # One of seven purpose-scoped keys. They must all differ: a single key reused across purposes - # means a compromise of any one of them is a compromise of all seven, and the platform enforces - # the distinction at startup rather than trusting the deployment to have noticed. + # callback 본문의 key 있는 fingerprint. replay를 찾는 데 쓴다. + # purpose별 key 일곱 중 하나다. 모두 달라야 한다: 한 key를 여러 용도에 다시 쓰면 하나가 털릴 때 일곱이 모두 + # 털린다. 플랫폼은 배포가 알아챘으리라 믿지 않고 기동할 때 구별을 강제한다. classification: secret source: secret-manager rotation_policy: dual-read-restart-only @@ -334,7 +328,7 @@ secrets: required_test: secrets-contract:notification-callback-fingerprint-hmac-no-leak - name: APP_NOTIFICATION_SLACK_WEBHOOK_URL - # source: feature-integration-adapter-templates 2026-05-22 + # 출처: feature-integration-adapter-templates 2026-05-22 # "Slack | disabled optional module | notification failure policy" # Slack webhook URL은 token을 path에 포함하므로 sensitive-config (URL 형태이지만 secret과 동급 취급) classification: sensitive-config @@ -348,8 +342,8 @@ secrets: required_test: secrets-contract:slack-webhook-no-leak - name: APP_SECURITY_GOOGLE_OAUTH_CLIENT_ID - # source: feature-secrets-config-source-contract 2026-05-22 - # "sensitive-config" tier (id이지만 노출 제한) + # 출처: feature-secrets-config-source-contract 2026-05-22 + # "sensitive-config" 등급 (id이지만 노출 제한) # + feature-integration-adapter-templates "Google Email | disabled optional module" classification: sensitive-config source: mounted-env @@ -362,7 +356,7 @@ secrets: required_test: secrets-contract:google-oauth-client-id-masked - name: APP_DATASOURCE_USERNAME - # source: feature-secrets-config-source-contract 2026-05-22 — "sensitive-config" tier + # 출처: feature-secrets-config-source-contract 2026-05-22 — "sensitive-config" 등급 # (DB user는 password와 함께 노출되면 위험하므로 sensitive-config) classification: sensitive-config source: mounted-env @@ -375,8 +369,8 @@ secrets: required_test: secrets-contract:datasource-username-masked-in-actuator - name: SPRING_MONGODB_URI - # MongoDB URIs can carry username/password material and must never be logged as public config. - # Typed-profile deployments should prefer uri-secret so the URI itself never becomes env data. + # MongoDB URI에는 사용자 이름·비밀번호가 들어 있을 수 있어 public config로 로그에 남기면 안 된다. + # typed profile 배포는 URI 자체가 env 데이터가 되지 않게 uri-secret을 쓰는 편이 낫다. classification: sensitive-config source: mounted-env rotation_policy: restart-only @@ -388,7 +382,7 @@ secrets: required_test: secrets-contract:mongodb-uri-masked - name: APP_DATASOURCE_URL - # source: feature-secrets-config-source-contract 2026-05-22 — JDBC URL은 host/db 포함하므로 sensitive-config + # 출처: feature-secrets-config-source-contract 2026-05-22 — JDBC URL은 host/db 포함하므로 sensitive-config # (env-keys.yaml에서는 public-config 처리; 본 파일에서는 노출 통제 관점에서 sensitive로 재분류 — masking 기준 명시 목적) classification: sensitive-config source: mounted-env @@ -400,10 +394,10 @@ secrets: compatibility_impact: breaking required_test: secrets-contract:datasource-url-masked-in-actuator - # === Tier 1: public-config (reference only — full row in env-keys.yaml) === + # === 1등급: public-config (참조만 — 행 전체는 env-keys.yaml에 있다) === - name: APP_PROFILE - # source: feature-env-driven-runtime-configuration — public-config tier reference + # 출처: feature-env-driven-runtime-configuration — public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -411,7 +405,7 @@ secrets: reference: env-keys.yaml#APP_PROFILE - name: APP_NAME - # source: feature-env-driven-runtime-configuration — public-config tier reference + # 출처: feature-env-driven-runtime-configuration — public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -419,7 +413,7 @@ secrets: reference: env-keys.yaml#APP_NAME - name: SERVER_PORT - # source: feature-env-driven-runtime-configuration — Spring native, public-config tier reference + # 출처: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -427,7 +421,7 @@ secrets: reference: env-keys.yaml#SERVER_PORT - name: SPRING_PROFILES_ACTIVE - # source: feature-env-driven-runtime-configuration — Spring native, public-config tier reference + # 출처: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -435,7 +429,7 @@ secrets: reference: env-keys.yaml#SPRING_PROFILES_ACTIVE - name: OTEL_EXPORTER_OTLP_ENDPOINT - # source: feature-distributed-tracing-contract — public-config tier reference + # 출처: feature-distributed-tracing-contract — public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-distributed-tracing-contract From ad859ca3a6b185b2bb9129b6583266a5c135e3c7 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:49:10 +0900 Subject: [PATCH 12/12] =?UTF-8?q?docs(registries):=20=EC=B6=9C=EC=B2=98=20?= =?UTF-8?q?=EC=A4=84=EC=9D=98=20=EA=BC=AC=EB=A6=AC=ED=91=9C=EC=99=80=20?= =?UTF-8?q?=EA=B8=B0=EB=A1=9D=20=EC=A0=88=20=EC=9D=B4=EB=A6=84=EC=9D=84=20?= =?UTF-8?q?=EC=9B=90=EB=AC=B8=EC=9C=BC=EB=A1=9C=20=EB=90=98=EB=8F=8C?= =?UTF-8?q?=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 앞 커밋이 레지스트리 주석의 `# source:`를 `# 출처:`로 바꾸고, 출처 줄 안의 기록 절 이름(「In scope」「Decisionized Work Items」「decisions」「Exposure Policy」「AuthN/AuthZ Decision Matrix」)까지 한국어로 옮겼다. 출처 줄은 기록 이름·날짜·절 이름으로 원문을 찾아가는 줄이라, 옮기면 그 기록에서 같은 이름을 찾을 수 없다. 또 metrics.yaml 주석 세 줄에 변환 실수로 `\"`(백슬래시가 붙은 따옴표)가 들어갔다. 고른 방법: 총괄 기준(2026-11-07)대로 나눈다. - 원문으로 둔다: 출처 줄의 꼬리표 `source:`, 기록 이름·날짜·절 이름, 따옴표 인용. - 한국어로 둔다: 같은 줄의 나머지 설명, 행마다의 이유·조건·주의 산문, 값 칸, 파일 머리 블록. - `\"`는 `"`로 고친다. 위험·한계: 출처가 가리키는 `feature-*` 계약 기록 24개는 저장소 어디에도(이력 포함) 그 이름의 파일이 없다. `docs/design/`에 있는 것은 `five-adapter-runtime-remediation`과 `redis-production-capability` 둘이고, 파일 이름에 날짜와 `-design`이 붙어 있다. 이름은 고치지 않았다. 검증: 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 앞 커밋과 같다(주석만 바뀜). `python3 scripts/check-docs.py` rc=0. --- docs/registries/capabilities.yaml | 22 +- docs/registries/env-keys.yaml | 306 ++++++++++---------- docs/registries/error-codes.yaml | 110 +++---- docs/registries/headers.yaml | 26 +- docs/registries/mdc-keys.yaml | 38 +-- docs/registries/metrics.yaml | 70 ++--- docs/registries/secrets-classification.yaml | 26 +- 7 files changed, 299 insertions(+), 299 deletions(-) diff --git a/docs/registries/capabilities.yaml b/docs/registries/capabilities.yaml index 157c27b8..049d314d 100644 --- a/docs/registries/capabilities.yaml +++ b/docs/registries/capabilities.yaml @@ -19,8 +19,8 @@ capabilities: - # 출처: feature-repository-access-permission-contract — 판정 기준 "Required capability: READ_REPOSITORY" - # 출처: feature-application-port-usecase-contract — "read-only query use case는 readOnly 와 READ_REPOSITORY capability만 선언 가능" + # source: feature-repository-access-permission-contract — 판정 기준 "Required capability: READ_REPOSITORY" + # source: feature-application-port-usecase-contract — "read-only query use case는 readOnly 와 READ_REPOSITORY capability만 선언 가능" - name: READ_REPOSITORY scope: use_case_method enforcement: archunit @@ -32,8 +32,8 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:read-repository-capability - # 출처: feature-repository-access-permission-contract — 판정 기준 "Required capability: WRITE_REPOSITORY" - # 출처: feature-application-port-usecase-contract — "write use case는 transactionMode, idempotency, repositoryAccess를 명시해야 함" + # source: feature-repository-access-permission-contract — 판정 기준 "Required capability: WRITE_REPOSITORY" + # source: feature-application-port-usecase-contract — "write use case는 transactionMode, idempotency, repositoryAccess를 명시해야 함" - name: WRITE_REPOSITORY scope: use_case_method enforcement: archunit @@ -45,7 +45,7 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:write-repository-capability - # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # source: feature-repository-access-permission-contract — decisions 2026-05-22 # "SENSITIVE_READ marker = registry-managed metadata table (entity FQN + field name 단위)" - name: SENSITIVE_READ scope: use_case_method @@ -58,7 +58,7 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:sensitive-read-capability - # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # source: feature-repository-access-permission-contract — decisions 2026-05-22 # "BULK_WRITE threshold = N > 100 또는 batch size > 100. 미만은 일반 WRITE_REPOSITORY로 충분" - name: BULK_WRITE scope: use_case_method @@ -71,9 +71,9 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:bulk-write-capability - # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # source: feature-repository-access-permission-contract — decisions 2026-05-22 # "TRANSACTION_REQUIRED는 application-port branch의 TransactionPort contract와 연결되어야 하며 Spring @Transactional 직접 import로 충족하지 않음" - # 출처: feature-application-port-usecase-contract — TransactionPort Contract + # source: feature-application-port-usecase-contract — TransactionPort Contract - name: TRANSACTION_REQUIRED scope: use_case_method enforcement: archunit @@ -85,9 +85,9 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:transaction-required-capability - # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # source: feature-repository-access-permission-contract — decisions 2026-05-22 # "EXTERNAL_OUTBOUND_ALLOWED 분류 = outbox row INSERT는 in-process(불요), polling publisher의 broker publish는 outbound(필요)" - # 출처: feature-application-port-usecase-contract — "outbound adapter 호출 use case에 EXTERNAL_OUTBOUND_ALLOWED가 없으면 실패" + # source: feature-application-port-usecase-contract — "outbound adapter 호출 use case에 EXTERNAL_OUTBOUND_ALLOWED가 없으면 실패" - name: EXTERNAL_OUTBOUND_ALLOWED scope: use_case_method enforcement: archunit @@ -99,7 +99,7 @@ capabilities: compatibility_impact: breaking required_test: architecture-enforcement:external-outbound-capability - # 출처: feature-repository-access-permission-contract — decisions 2026-05-22 + # source: feature-repository-access-permission-contract — decisions 2026-05-22 # "CROSS_TENANT_ADMIN capability를 capability vocabulary에 추가 (tenant branch feature-tenant-context-policy와 cross-link)" - name: CROSS_TENANT_ADMIN scope: use_case_method diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index 9fc9fb82..fb2a3b8a 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -21,7 +21,7 @@ env_keys: # === Profile / 정체성 (feature-env-driven-runtime-configuration) === - name: SPRING_PROFILES_ACTIVE - # 출처: feature-env-driven-runtime-configuration D6 (2026-06-06), five-adapter-runtime-remediation §7.1에서 + # source: feature-env-driven-runtime-configuration D6 (2026-06-06), five-adapter-runtime-remediation §7.1에서 # 고침. profile 선택자는 Spring 자체 키 하나뿐이다(APP_PROFILE은 지웠다). CSV 목록이 아니라 값 정확히 # 하나다: 두 환경의 안전 규칙이 함께 적용될 수 없고, 진 쪽은 소리 없이 빠졌다. type: enum @@ -41,7 +41,7 @@ env_keys: # feature-env-driven-runtime-configuration Claims (wont-fix) 참고. - name: APP_NAME - # 출처: feature-env-driven-runtime-configuration 2026-05-22 + # source: feature-env-driven-runtime-configuration 2026-05-22 # "Required config: APP_NAME, APP_PROFILE..." type: string default: null @@ -57,7 +57,7 @@ env_keys: # === HTTP 서버 (D2에 따라 APP_로 통일) === - name: APP_SERVER_PORT - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_로 전부 통일. server.port는 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_로 전부 통일. server.port는 # APP_SERVER_PORT에서 온다. # + feature-management-actuator-security-contract 2026-05-22 "management port default = 9001 (separate from app 8080)" # (관리 포트 기본값 9001, 앱 8080과 분리) @@ -73,7 +73,7 @@ env_keys: required_test: env-contract:server-port-bound - name: MANAGEMENT_SERVER_PORT - # 출처: feature-management-actuator-security-contract 2026-05-22 + # source: feature-management-actuator-security-contract 2026-05-22 # "management port default = 9001 (separate from app 8080). single-port는 platform ingress 보호 + 문서화 시만 허용." type: int default: 9001 @@ -87,7 +87,7 @@ env_keys: required_test: actuator-contract:management-port-separated - name: APP_SERVER_SHUTDOWN - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (server.shutdown 방식. graceful은 처리 중인 요청을 끝내고 내린다) type: enum default: graceful @@ -101,7 +101,7 @@ env_keys: required_test: env-contract:server-shutdown-mode - name: APP_SERVER_SHUTDOWN_TIMEOUT - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일. + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일. # 옛 APP_SHUTDOWN_TIMEOUT 행을 대신한다. k8s terminationGracePeriod 이하여야 한다 # (feature-container-runtime-contract 참고). type: duration @@ -116,7 +116,7 @@ env_keys: required_test: env-contract:server-shutdown-timeout-aligned - name: APP_SERVER_FORWARD_HEADERS_STRATEGY - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일. + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일. # 기본은 닫힘(fail closed): forwarded 헤더는 배포가 정리·신뢰 proxy 뒤에서 직접 켤 때만 믿는다. # native = Tomcat RemoteIpValve. server.tomcat.remoteip.internal-proxies에 맞는 상대에게서 온 헤더만 # 따른다. framework는 허용하지 않는다: 그 ForwardedHeaderFilter는 모든 상대를 믿고, rate limiter가 @@ -133,7 +133,7 @@ env_keys: required_test: env-contract:server-forward-headers-strategy - name: APP_SERVER_TOMCAT_MAX_THREADS - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (동시 요청 worker 상한) type: int default: 200 @@ -147,7 +147,7 @@ env_keys: required_test: env-contract:tomcat-max-threads-bounded - name: APP_SERVER_TOMCAT_MIN_SPARE_THREADS - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (쉬는 worker pool의 하한) type: int default: 10 @@ -161,7 +161,7 @@ env_keys: required_test: env-contract:tomcat-min-spare-threads-valid - name: APP_SERVER_TOMCAT_ACCEPT_COUNT - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (들어오는 TCP 연결의 OS backlog queue 깊이) type: int default: 100 @@ -175,7 +175,7 @@ env_keys: required_test: env-contract:tomcat-accept-count-valid - name: APP_SERVER_TOMCAT_MAX_CONNECTIONS - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (동시에 열린 연결 수의 상한) type: int default: 8192 @@ -189,7 +189,7 @@ env_keys: required_test: env-contract:tomcat-max-connections-bounded - name: APP_SERVER_TOMCAT_CONNECTION_TIMEOUT - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (Tomcat connector 연결 timeout) type: duration default: 20s @@ -203,7 +203,7 @@ env_keys: required_test: env-contract:tomcat-connection-timeout-set - name: APP_SERVER_COMPRESSION_ENABLED - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (server.compression 켜고 끄기) type: boolean default: true @@ -217,7 +217,7 @@ env_keys: required_test: env-contract:server-compression-toggle - name: APP_SERVER_COMPRESSION_MIN_RESPONSE_SIZE - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (이 크기보다 작은 응답은 압축하지 않는다) type: data_size default: 1KB @@ -231,7 +231,7 @@ env_keys: required_test: env-contract:server-compression-min-size - name: APP_SERVER_ERROR_INCLUDE_STACKTRACE - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (spring.web.error.include-stacktrace 정책) type: enum default: never @@ -245,7 +245,7 @@ env_keys: required_test: env-contract:server-error-stacktrace-policy - name: APP_SERVER_ERROR_INCLUDE_MESSAGE - # 출처: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 + # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 # (spring.web.error.include-message 정책) type: enum default: never @@ -259,7 +259,7 @@ env_keys: required_test: env-contract:server-error-message-policy - name: APP_MULTI_INSTANCE_ENABLED - # 출처: feature-env-driven-runtime-configuration D8 (2026-06-06) + # source: feature-env-driven-runtime-configuration D8 (2026-06-06) # true면 StartupSafetyValidator(다른 singleton보다 먼저 도는 StartupRule)가 이름이 # distributedLockProvider인 인스턴스 간 DistributedLockPort bean을 요구한다. 없으면 기동이 실패한다 # (exit 72). 이 값을 쓰는 곳: feature-runtime-health-lifecycle-contract, @@ -278,7 +278,7 @@ env_keys: required_test: env-contract:multi-instance-beans-present - name: APP_MIGRATION_ON_STARTUP - # 출처: feature-migration-startup-contract + # source: feature-migration-startup-contract # true면 애플리케이션이 기동하면서 Flyway migration을 자동으로 돌린다. # false면 migration을 건너뛴다(앱 밖의 container·pipeline job에 맡긴다). type: boolean @@ -295,7 +295,7 @@ env_keys: # === Datasource / pool (env-driven branch "Required config: datasource") === - name: APP_DATASOURCE_URL - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # + feature-persistence-failure-baseline "datasource/pool/timeout/connection exhaustion log field" # (datasource·pool·timeout·연결 고갈 로그 필드) type: url @@ -310,7 +310,7 @@ env_keys: required_test: env-contract:datasource-url-resolvable - name: APP_DATASOURCE_USERNAME - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" type: string default: null allowed_values: null @@ -323,7 +323,7 @@ env_keys: required_test: env-contract:datasource-credential-present - name: APP_DATASOURCE_PASSWORD - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # + feature-secrets-config-source-contract — secret 분류라 secrets-classification.yaml이 행을 가진다 type: string default: null @@ -337,7 +337,7 @@ env_keys: required_test: secrets-contract:db-password-not-leaked - name: APP_PERSISTENCE_VENDOR - # 출처: application-local.yml과 bootRunH2가 쓰는 영속성 vendor 선택자. + # source: application-local.yml과 bootRunH2가 쓰는 영속성 vendor 선택자. # PostgreSQL이 기본으로 들어 있고, H2는 개발자가 명시적으로 고를 때만 쓴다. property: app.persistence.vendor type: enum @@ -381,7 +381,7 @@ env_keys: required_test: jpa-contract:realtime-replay-env - name: APP_FLYWAY_ENABLED - # 출처: 로컬 PostgreSQL을 운영과 맞춤 / 명시적 H2 개발 lane. + # source: 로컬 PostgreSQL을 운영과 맞춤 / 명시적 H2 개발 lane. # 모든 profile이 기본으로 migration을 돌린다 — persistence-jpa 모듈 기본값이 이 키를 읽는다 # (07-08; dev/prod가 그 위에 값을 박지 않는다). bootRunH2는 migration tree가 PostgreSQL 전용이라 # 끈다. @@ -398,7 +398,7 @@ env_keys: required_test: jpa-contract:local-flyway-parity - name: APP_DATASOURCE_POOL_MAX_SIZE - # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # source: feature-env-driven-runtime-configuration "datasource/pool env" # + feature-persistence-failure-baseline "Hikari metric 노출 기준" type: int default: 10 @@ -412,7 +412,7 @@ env_keys: required_test: env-contract:pool-bounded - name: APP_DATASOURCE_POOL_MIN_IDLE - # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # source: feature-env-driven-runtime-configuration "datasource/pool env" type: int default: 2 allowed_values: null @@ -425,7 +425,7 @@ env_keys: required_test: env-contract:pool-min-idle-valid - name: APP_DATASOURCE_CONNECTION_TIMEOUT - # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # source: feature-env-driven-runtime-configuration "datasource/pool env" # + feature-persistence-failure-baseline "Hikari Alert Threshold: pool wait p99 > 100ms" # 단위: 밀리초. 이 값은 spring.datasource.hikari.connection-timeout으로 가고, 그 키는 # HikariConfig#setConnectionTimeout(long)에 바인딩된다 — "5s" 같은 duration 줄임 표기는 바인딩되지 않아 @@ -444,7 +444,7 @@ env_keys: required_test: env-contract:connection-timeout-set - name: APP_DATASOURCE_DRIVER - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # (설정한 datasource URL의 JDBC driver class) type: string default: org.postgresql.Driver @@ -458,7 +458,7 @@ env_keys: required_test: env-contract:datasource-driver-set - name: APP_DATASOURCE_DDL_AUTO - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # (Hibernate ddl-auto. prod는 validate|none이어야 하고, local은 update가 편하다) type: enum default: validate @@ -472,7 +472,7 @@ env_keys: required_test: env-contract:datasource-ddl-auto-safe - name: APP_DATASOURCE_SHOW_SQL - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # (SQL을 로그에 찍는다) type: boolean default: false @@ -486,7 +486,7 @@ env_keys: required_test: env-contract:datasource-show-sql-toggle - name: APP_DATASOURCE_FORMAT_SQL - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # (SQL을 보기 좋게 찍는다 — SHOW_SQL=true일 때만 쓸모 있다) type: boolean default: false @@ -500,7 +500,7 @@ env_keys: required_test: env-contract:datasource-format-sql-toggle - name: APP_DATASOURCE_OPEN_IN_VIEW - # 출처: feature-env-driven-runtime-configuration "Required config: datasource" + # source: feature-env-driven-runtime-configuration "Required config: datasource" # (Hibernate OSIV — prod에서 켜지 않는다) type: boolean default: false @@ -514,7 +514,7 @@ env_keys: required_test: env-contract:datasource-open-in-view-toggle - name: APP_DATASOURCE_POOL_IDLE_TIMEOUT - # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # source: feature-env-driven-runtime-configuration "datasource/pool env" # (Hikari 밀리초. 쉬는 연결을 내보내는 기준) type: int default: 600000 @@ -528,7 +528,7 @@ env_keys: required_test: env-contract:pool-idle-timeout-valid - name: APP_DATASOURCE_POOL_MAX_LIFETIME - # 출처: feature-env-driven-runtime-configuration "datasource/pool env" + # source: feature-env-driven-runtime-configuration "datasource/pool env" # (Hikari 밀리초. 연결 최대 수명 — broker timeout 전에 교체한다) type: int default: 1800000 @@ -544,7 +544,7 @@ env_keys: # === 추적 / 관측 (feature-distributed-tracing-contract) === - name: OTEL_EXPORTER_OTLP_ENDPOINT - # 출처: feature-distributed-tracing-contract 2026-05-22 + # source: feature-distributed-tracing-contract 2026-05-22 # "Micrometer Tracing + OpenTelemetry exporter를 기본 기준으로 둠" # OTLP 기본 주소(OpenTelemetry 규격). TracingEnvironmentPostProcessor가 이 값을 # management.opentelemetry.tracing.export.otlp.endpoint의 /v1/traces(OTLP/HTTP)로 잇는다. @@ -561,7 +561,7 @@ env_keys: required_test: tracing-contract:exporter-endpoint-resolvable - name: APP_TRACING_ENABLED - # 출처: feature-distributed-tracing-contract 2026-05-22 + # source: feature-distributed-tracing-contract 2026-05-22 # "tracing disabled profile에서도 envelope meta.traceId와 log traceId는 유지" type: boolean default: true @@ -575,7 +575,7 @@ env_keys: required_test: tracing-contract:meta-traceid-when-disabled - name: APP_TRACING_SAMPLE_RATE - # 출처: feature-distributed-tracing-contract 2026-05-22 + # source: feature-distributed-tracing-contract 2026-05-22 # "trace sampling rate default = prod 1%, dev/local 100%" # D-1 ISSUE-1 fix (2026-06-16): 빈 값 = profile별 resolver 기본값을 쓴다. # RuntimeEnvironment가 profile의 정본이다. resolver 정책은 prod=0.01, dev/local=1.0. @@ -597,7 +597,7 @@ env_keys: # — feature-log-management-contract가 만든 대로. - name: APP_LOG_LEVEL_ROOT - # 출처: feature-log-management-contract — root logger 레벨 + # source: feature-log-management-contract — root logger 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -610,7 +610,7 @@ env_keys: required_test: log-contract:root-level - name: APP_LOG_LEVEL_APP - # 출처: feature-log-management-contract — 애플리케이션 패키지 레벨 + # source: feature-log-management-contract — 애플리케이션 패키지 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -623,7 +623,7 @@ env_keys: required_test: log-contract:app-level - name: APP_LOG_LEVEL_SPRING - # 출처: feature-log-management-contract — Spring framework 패키지 레벨 + # source: feature-log-management-contract — Spring framework 패키지 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -636,7 +636,7 @@ env_keys: required_test: log-contract:spring-level - name: APP_LOG_LEVEL_WEB - # 출처: feature-log-management-contract — web/MVC 패키지 레벨 + # source: feature-log-management-contract — web/MVC 패키지 레벨 type: enum default: INFO allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -649,7 +649,7 @@ env_keys: required_test: log-contract:web-level - name: APP_LOG_LEVEL_SQL - # 출처: feature-log-management-contract — JPA/JDBC SQL 패키지 레벨 (DEBUG면 SQL을 찍는다) + # source: feature-log-management-contract — JPA/JDBC SQL 패키지 레벨 (DEBUG면 SQL을 찍는다) type: enum default: WARN allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF] @@ -662,7 +662,7 @@ env_keys: required_test: log-contract:sql-level - name: APP_LOG_FILE_ENABLED - # 출처: feature-log-management-contract — 순환(rolling) JSON 파일 appender 켜고 끄기 + # source: feature-log-management-contract — 순환(rolling) JSON 파일 appender 켜고 끄기 type: boolean default: false allowed_values: [true, false] @@ -675,7 +675,7 @@ env_keys: required_test: log-contract:file-appender-toggle - name: APP_LOG_FILE_PATH - # 출처: feature-log-management-contract — 파일 경로 (bootRun 실행 위치 기준 상대 경로 또는 절대 경로) + # source: feature-log-management-contract — 파일 경로 (bootRun 실행 위치 기준 상대 경로 또는 절대 경로) type: string default: logs/ca-skeleton.json allowed_values: null @@ -688,7 +688,7 @@ env_keys: required_test: log-contract:file-path-set - name: APP_LOG_FILE_MAX_SIZE - # 출처: feature-log-management-contract — 파일 하나의 순환 크기 상한 + # source: feature-log-management-contract — 파일 하나의 순환 크기 상한 type: data_size default: 100MB allowed_values: null @@ -701,7 +701,7 @@ env_keys: required_test: log-contract:file-max-size - name: APP_LOG_FILE_MAX_HISTORY - # 출처: feature-log-management-contract — 남길 순환 보관 파일 수 + # source: feature-log-management-contract — 남길 순환 보관 파일 수 type: int default: 14 allowed_values: null @@ -714,7 +714,7 @@ env_keys: required_test: log-contract:file-max-history - name: APP_LOG_FILE_TOTAL_SIZE_CAP - # 출처: feature-log-management-contract — 순환 파일 전체의 크기 상한 + # source: feature-log-management-contract — 순환 파일 전체의 크기 상한 type: data_size default: 3GB allowed_values: null @@ -727,7 +727,7 @@ env_keys: required_test: log-contract:file-total-size-cap - name: APP_LOG_ASYNC_ENABLED - # 출처: feature-log-management-contract — 막히지 않는 I/O를 위한 AsyncAppender 감싸기 + # source: feature-log-management-contract — 막히지 않는 I/O를 위한 AsyncAppender 감싸기 type: boolean default: true allowed_values: [true, false] @@ -740,7 +740,7 @@ env_keys: required_test: log-contract:async-appender-toggle - name: APP_LOG_ASYNC_QUEUE_SIZE - # 출처: feature-log-management-contract — 역압(back-pressure) 전 메모리 queue 깊이 + # source: feature-log-management-contract — 역압(back-pressure) 전 메모리 queue 깊이 type: int default: 512 allowed_values: null @@ -753,7 +753,7 @@ env_keys: required_test: log-contract:async-queue-size - name: APP_LOG_ASYNC_DISCARDING_THRESHOLD - # 출처: feature-log-management-contract — 남은 용량이 이 값 아래로 내려가면 + # source: feature-log-management-contract — 남은 용량이 이 값 아래로 내려가면 # TRACE/DEBUG/INFO 이벤트를 버린다(WARN/ERROR는 늘 남긴다). 0 = 버리지 않는다. type: int default: 20 @@ -767,7 +767,7 @@ env_keys: required_test: log-contract:async-discarding-threshold - name: APP_LOG_JSON_TIMEZONE - # 출처: feature-log-management-contract — JSON encoder 시각에 쓰는 IANA timezone + # source: feature-log-management-contract — JSON encoder 시각에 쓰는 IANA timezone type: string default: UTC allowed_values: null @@ -780,7 +780,7 @@ env_keys: required_test: log-contract:json-timezone - name: APP_LOG_JSON_TIMESTAMP_PATTERN - # 출처: feature-log-management-contract — JSON encoder 시각 형식 (기본 ISO 8601) + # source: feature-log-management-contract — JSON encoder 시각 형식 (기본 ISO 8601) type: string default: "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" allowed_values: null @@ -793,7 +793,7 @@ env_keys: required_test: log-contract:json-timestamp-pattern - name: APP_LOG_JSON_INCLUDE_CALLER_DATA - # 출처: feature-log-management-contract — 파일·메서드·줄 번호를 넣는다 (성능 비용이 크다) + # source: feature-log-management-contract — 파일·메서드·줄 번호를 넣는다 (성능 비용이 크다) type: boolean default: false allowed_values: [true, false] @@ -806,7 +806,7 @@ env_keys: required_test: log-contract:json-include-caller-data - name: APP_LOG_JSON_LOGGER_NAME_LENGTH - # 출처: feature-log-management-contract — logger 이름 줄이기 (0 = 전체 이름) + # source: feature-log-management-contract — logger 이름 줄이기 (0 = 전체 이름) type: int default: 0 allowed_values: null @@ -819,7 +819,7 @@ env_keys: required_test: log-contract:json-logger-name-length - name: APP_LOG_SAMPLING_RATE - # 출처: feature-log-management-contract 2026-05-22 + # source: feature-log-management-contract 2026-05-22 # "log sampling(prod 10%) > trace sampling(prod 1%)" + Sampling Policy 표 (prod 10%, dev/local 100%) type: string default: "1.0" @@ -835,7 +835,7 @@ env_keys: # === 개인정보: user_principal 가명화 (feature-data-retention-privacy-contract) === - name: APP_PRIVACY_PSEUDONYMIZATION_SALT - # 출처: feature-data-retention-privacy-contract — "pseudonymization key = HMAC-SHA-256 + # source: feature-data-retention-privacy-contract — "pseudonymization key = HMAC-SHA-256 # with rotating salt (90d)" (가명화 키는 90일마다 바뀌는 salt의 HMAC-SHA-256). feature-log-management-contract # (DRIFT-6)가 user_principal을 가명 형태로 남기는 데 쓴다. secret 분류라 secrets-classification.yaml이 행을 # 가진다. @@ -853,7 +853,7 @@ env_keys: # === Security / CORS / JWT (feature-security-operational-baseline) === - name: APP_SECURITY_CORS_ORIGINS - # 출처: feature-security-operational-baseline 2026-05-22 + # source: feature-security-operational-baseline 2026-05-22 # "allowlist origin은 env-driven runtime configuration의 APP_SECURITY_CORS_ORIGINS로 주입" type: csv_list default: null @@ -867,7 +867,7 @@ env_keys: required_test: security-contract:cors-allowlist - name: APP_SECURITY_CORS_ENABLED - # 출처: feature-security-operational-baseline — CORS filter 전체 켜고 끄기 + # source: feature-security-operational-baseline — CORS filter 전체 켜고 끄기 type: boolean default: false allowed_values: [true, false] @@ -880,7 +880,7 @@ env_keys: required_test: security-contract:cors-enabled-toggle - name: APP_SECURITY_CORS_ALLOWED_METHODS - # 출처: feature-security-operational-baseline — 허용 method + # source: feature-security-operational-baseline — 허용 method # (빈 값 -> CorsSettings의 무난한 method 기본값) type: csv_list default: null @@ -894,7 +894,7 @@ env_keys: required_test: security-contract:cors-allowed-methods - name: APP_SECURITY_CORS_ALLOWED_HEADERS - # 출처: feature-security-operational-baseline — 허용 요청 헤더 ("*" = 모두) + # source: feature-security-operational-baseline — 허용 요청 헤더 ("*" = 모두) type: csv_list default: "*" allowed_values: null @@ -907,7 +907,7 @@ env_keys: required_test: security-contract:cors-allowed-headers - name: APP_SECURITY_CORS_ALLOW_CREDENTIALS - # 출처: feature-security-operational-baseline 2026-05-22 + # source: feature-security-operational-baseline 2026-05-22 # "CORS는 allowlist default, credentials false default" / "wildcard with credentials forbidden" type: boolean default: false @@ -921,7 +921,7 @@ env_keys: required_test: security-contract:cors-credentials-policy - name: APP_SECURITY_CORS_MAX_AGE - # 출처: feature-security-operational-baseline 2026-05-22 + # source: feature-security-operational-baseline 2026-05-22 # "preflight max-age 600s default" type: duration default: 600s @@ -1159,7 +1159,7 @@ env_keys: required_test: redis-session-contract:serializer-bounded - name: APP_SECURITY_JWT_ISSUER - # 출처: feature-security-operational-baseline 2026-05-22 + # source: feature-security-operational-baseline 2026-05-22 # "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH" type: url default: null @@ -1173,7 +1173,7 @@ env_keys: required_test: security-contract:jwt-issuer-set - name: APP_SECURITY_JWT_AUDIENCE - # 출처: feature-security-operational-baseline 2026-05-22 + # source: feature-security-operational-baseline 2026-05-22 # "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH" type: csv_list default: null @@ -2379,7 +2379,7 @@ env_keys: compatibility_impact: additive required_test: redis-sdk:runtime-composition-binds-and-validates - name: APP_CACHE_REDIS_ENABLED - # 출처: feature-integration-adapter-templates 2026-05-22 + # source: feature-integration-adapter-templates 2026-05-22 # "Redis | disabled optional module | cache consistency" + Adapter Template Defaults 표 # 폐기 2026-08-10: 두 번째 Redis 전체 스위치였고, 이를 바인딩하던 settings class를 옛 Redis 세대와 함께 # 지워서 이 키는 어디에도 닿지 않는다. 전역 켜기는 APP_REDIS_ENABLED 하나가 정한다. 캐시 role은 @@ -2420,7 +2420,7 @@ env_keys: # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # 출처: feature-cache-consistency-contract — Redis adapter (켜면 endpoint가 필요하다) + # source: feature-cache-consistency-contract — Redis adapter (켜면 endpoint가 필요하다) type: string default: null allowed_values: null @@ -2437,7 +2437,7 @@ env_keys: # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # 출처: feature-cache-consistency-contract — Redis adapter endpoint + # source: feature-cache-consistency-contract — Redis adapter endpoint type: int default: 6379 allowed_values: null @@ -2801,7 +2801,7 @@ env_keys: # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # 출처: feature-cache-consistency-contract 2026-05-22 + # source: feature-cache-consistency-contract 2026-05-22 # "TTL | explicit per key family | no-cache for sensitive data | immortal cache forbidden" type: duration default: 300s @@ -2819,7 +2819,7 @@ env_keys: # 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다. deprecated_orphaned: true removal_deadline: 2026-11-30 - # 출처: feature-cache-consistency-contract 2026-05-22 + # source: feature-cache-consistency-contract 2026-05-22 # "negative cache 정책 = 존재하지 않는 row는 짧은 TTL(60s) 캐싱 허용" type: duration default: 60s @@ -2835,7 +2835,7 @@ env_keys: # === 메시징 / Kafka (feature-domain-event-outbox-contract + integration-adapter-templates) === - name: APP_MESSAGING_BROKER - # 출처: messaging multi-broker redesign 2026-06-16 — 활성 broker 하나를 고른다 + # source: messaging multi-broker redesign 2026-06-16 — 활성 broker 하나를 고른다 # (app.messaging.broker=). 들여온 메시징 플랫폼이 읽는다. 옛 Kafka 전용 APP_MESSAGING_KAFKA_ENABLED를 # 대신한다. 애플리케이션 bridge는 이제 읽지 않는다: 읽던 옛 KafkaSender seam은 canonical outbox와 함께 # 지웠다(2026-09-28). @@ -2852,7 +2852,7 @@ env_keys: required_test: adapter-contract:messaging-broker-selection - name: APP_MESSAGING_PRODUCER_ID - # 출처: canonical messaging platform bridge 2026-09-18 + # source: canonical messaging platform bridge 2026-09-18 # IntegrationEventPublishPort가 쓰는, 메시지를 내는 서비스의 논리 이름(명시값). # 비었거나 없음 = canonical 플랫폼 bridge를 내놓지 않는다. 이름을 짐작하지 않는다. # outbox relay를 포함해 모든 발행이 그 bridge를 거치므로, 메시징 모듈이 있고 켜진 상태에서 값이 비면 기동을 @@ -2870,7 +2870,7 @@ env_keys: required_test: adapter-contract:messaging-platform-producer-id - name: APP_MESSAGING_KAFKA_BROKERS - # 출처: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter" + # source: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter" # (broker를 켜면 endpoint가 필요하다) # Kafka 모듈의 config/module-defaults/messaging.yml을 거쳐 app.messaging.brokers.kafka.bootstrap-servers # (메시징 플랫폼의 Kafka transport)로 간다. spring.kafka.bootstrap-servers는 읽지 않는다. @@ -2888,7 +2888,7 @@ env_keys: # === 알림 adapter (feature-integration-adapter-templates) === - name: APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED - # 출처: R0 Slack webhook provider 스위치. app.notification.slack-webhook.enabled로 이어진다 + # source: R0 Slack webhook provider 스위치. app.notification.slack-webhook.enabled로 이어진다 type: boolean default: false allowed_values: [true, false] @@ -2901,7 +2901,7 @@ env_keys: required_test: adapter-contract:notification-slack-provider-selection - name: APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED - # 출처: R0 Google email provider 스위치. app.notification.google-email.enabled로 이어진다 + # source: R0 Google email provider 스위치. app.notification.google-email.enabled로 이어진다 type: boolean default: false allowed_values: [true, false] @@ -3679,7 +3679,7 @@ env_keys: # === 파일 / 업로드 (feature-file-resource-handling-contract) === - name: APP_ASYNC_EXECUTOR_CORE_SIZE - # 출처: feature-background-job-async-contract 2026-05-22 + # source: feature-background-job-async-contract 2026-05-22 # "executor pool sizing default = core=10, max=50, queue=200" type: int default: 10 @@ -3693,7 +3693,7 @@ env_keys: required_test: async-contract:executor-core-size - name: APP_ASYNC_EXECUTOR_MAX_SIZE - # 출처: feature-background-job-async-contract 2026-05-22 + # source: feature-background-job-async-contract 2026-05-22 # "core=10, max=50, queue=200" type: int default: 50 @@ -3707,7 +3707,7 @@ env_keys: required_test: async-contract:executor-max-size - name: APP_ASYNC_EXECUTOR_QUEUE_CAPACITY - # 출처: feature-background-job-async-contract 2026-05-22 + # source: feature-background-job-async-contract 2026-05-22 # "queue=200" + "unbounded queue forbidden" type: int default: 200 @@ -3725,7 +3725,7 @@ env_keys: # 가지므로, 플랫폼을 끈 배포는 아무것도 주지 않아도 된다. 참고: docs/notification/configuration-reference.md. - name: APP_PERSISTENCE_JPA_ENABLED - # 출처: five-adapter-runtime-remediation §5.1 — 관계형 영속성 스위치. persistence-jpa 모듈이 직접 + # source: five-adapter-runtime-remediation §5.1 — 관계형 영속성 스위치. persistence-jpa 모듈이 직접 # 가진다(config/module-defaults/persistence-jpa.yml). 모듈은 빌드 한 줄로 고르고, 있는 동안 켜진다. false면 # 이 모듈의 bean(entity scan, repository, store, 기동 관문)을 끈다. 빌드 줄을 지우면 기능과 이 키를 읽는 유일한 # 곳이 함께 사라진다. 옛 app.jpa-platform.enabled는 이 키처럼 읽혔지만 부가 bean 셋만 막았다. @@ -3817,7 +3817,7 @@ env_keys: - name: APP_PERSISTENCE_MONGO_ENABLED # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. - # 출처: five-adapter-runtime-remediation §5.1 — MongoDB 영속성 켜고 끄기. + # source: five-adapter-runtime-remediation §5.1 — MongoDB 영속성 켜고 끄기. type: boolean default: true allowed_values: [true, false] @@ -3829,7 +3829,7 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:persistence-mongo-disabled-safe - name: APP_PERSISTENCE_MONGO_ACTIVE_PROFILE - # 출처: five-adapter-runtime-remediation §5.1 — Mongo profile을 정확히 하나 고른다. 런타임은 sync client + # source: five-adapter-runtime-remediation §5.1 — Mongo profile을 정확히 하나 고른다. 런타임은 sync client # 하나와 pool 하나를 만든다. map에 있지만 고르지 않은 profile은 비밀을 풀지도, client를 만들지도 않는다. type: string default: "" @@ -3842,7 +3842,7 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:persistence-mongo-active-profile - name: SPRING_MONGODB_URI - # 출처: persistence-mongo techlead review C1. Spring Boot 4는 이 자체 키를 spring.mongodb.uri로 쓴다. + # source: persistence-mongo techlead review C1. Spring Boot 4는 이 자체 키를 spring.mongodb.uri로 쓴다. # 유효한 연결 출처 둘 중 하나다. 다른 하나는 고른 typed profile의 uri-secret을 MongoCredentialResolver로 푼 # 값이다. type: string @@ -3860,7 +3860,7 @@ env_keys: - name: APP_MESSAGING_ENABLED # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. - # 출처: five-adapter-runtime-remediation §5.1 — broker 발행 켜고 끄기. + # source: five-adapter-runtime-remediation §5.1 — broker 발행 켜고 끄기. # APP_MESSAGING_BROKER는 어느 transport인지만 고르고, 이제 사실상의 스위치가 아니다. type: boolean default: true @@ -4060,7 +4060,7 @@ env_keys: - name: APP_GRAPHQL_ENABLED # 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다). # false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. - # 출처: five-adapter-runtime-remediation §5.1 — GraphQL transport 켜고 끄기. + # source: five-adapter-runtime-remediation §5.1 — GraphQL transport 켜고 끄기. # false면 /graphql route를 내지 않는다. Spring GraphQL이 스스로 내는 route도 포함이다. type: boolean default: true @@ -4073,7 +4073,7 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:graphql-disabled-safe - name: APP_GRAPHQL_DEPLOYMENT_MODE - # 출처: five-adapter-runtime-remediation §5.1 / GQL-INT-002 — app.graphql.production과 + # source: five-adapter-runtime-remediation §5.1 / GQL-INT-002 — app.graphql.production과 # app.graphql.environment를 대신한다. 둘의 기본값이 production=false와 environment=PRODUCTION_PUBLIC이라, # 익명 principal과 기본 허용 권한 검사는 한 축을 읽고 다른 축은 production이라 주장했다. type: enum @@ -4238,7 +4238,7 @@ env_keys: required_test: graphql-contract:wired-operator-settings - name: APP_OUTBOX_ENABLED - # 출처: five-adapter-runtime-remediation §6.1 JPA-INT-004 — outbox 기능 스위치. + # source: five-adapter-runtime-remediation §6.1 JPA-INT-004 — outbox 기능 스위치. # 아래 relay-enabled는 scheduler만 시작한다. 둘을 섞으면 relay를 끈 배포도 DB 없는 런타임에는 없는 store # port 위에 outbox metrics를 조립했다. type: boolean @@ -4252,7 +4252,7 @@ env_keys: compatibility_impact: behavior-change required_test: adapter-contract:outbox-capability-disabled-safe - name: APP_OUTBOX_RELAY_ENABLED - # 출처: five-adapter-runtime-remediation §6.3 MSG-INT-001 — relay scheduler를 시작한다. + # source: five-adapter-runtime-remediation §6.3 MSG-INT-001 — relay scheduler를 시작한다. # APP_OUTBOX_ENABLED, APP_PERSISTENCE_JPA_ENABLED, APP_MESSAGING_ENABLED와 APP_MESSAGING_PRODUCER_ID가 # 필요하다. 예전 기본값은 broker가 빈 채로 true라 모든 기동을 거부했다. type: boolean @@ -4269,7 +4269,7 @@ env_keys: # 2026-09-25 capability 포장: notification-platform 모듈은 있으면 켜진다(모듈의 # config/module-defaults/notification.yml이 이 키를 기본 true로 잇는다). false가 명시적으로 끄는 값이고 # 아무것도 바인딩하지 않는다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다. - # 출처: NTF-025. + # source: NTF-025. type: boolean default: true allowed_values: [true, false] @@ -4296,7 +4296,7 @@ env_keys: required_test: application-contract:notification-default-locale - name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY - # 출처: NTF-INT-007 — 저장된 수신자 연락처(주소와 전화번호)를 암호화한다. + # source: NTF-INT-007 — 저장된 수신자 연락처(주소와 전화번호)를 암호화한다. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.contact-encryption-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4312,7 +4312,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY - # 출처: NTF-INT-007 — 연락처의 blind index. 조회에 평문이 필요 없게 한다. + # source: NTF-INT-007 — 연락처의 blind index. 조회에 평문이 필요 없게 한다. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.contact-lookup-hmac-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4328,7 +4328,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY - # 출처: NTF-INT-007 — provider가 전달 결과를 보내는 callback URL에 서명한다. + # source: NTF-INT-007 — provider가 전달 결과를 보내는 callback URL에 서명한다. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.callback-signing-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4344,7 +4344,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY - # 출처: NTF-INT-007 — 저장된 provider 자격 증명(그 자체가 비밀)을 암호화한다. + # source: NTF-INT-007 — 저장된 provider 자격 증명(그 자체가 비밀)을 암호화한다. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.provider-credential-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4360,7 +4360,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY - # 출처: NTF-INT-007 — 저장된 알림 변수와 보관한 callback 본문을 암호화한다. + # source: NTF-INT-007 — 저장된 알림 변수와 보관한 callback 본문을 암호화한다. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.payload-encryption-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4376,7 +4376,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY - # 출처: NTF-INT-007 — provider 쪽 식별자인 provider request id의 key 있는 hash. + # source: NTF-INT-007 — provider 쪽 식별자인 provider request id의 key 있는 hash. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.provider-request-lookup-hmac-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4392,7 +4392,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY - # 출처: NTF-INT-007 — callback 본문의 key 있는 fingerprint. replay를 찾는 데 쓴다. + # source: NTF-INT-007 — callback 본문의 key 있는 fingerprint. replay를 찾는 데 쓴다. # 행 전체는 secrets-classification.yaml이 가진다. 바인딩 위치: # app.notification.platform.secrets.callback-fingerprint-hmac-key. 플랫폼이 기동할 때 값을 풀고, # 비었거나 32바이트보다 짧거나 다른 용도의 key와 같으면 기동을 거부한다. @@ -4408,7 +4408,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID - # 출처: NTF-INT-007 — CONTACT_ENCRYPTION key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — CONTACT_ENCRYPTION key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CONTACT_ENCRYPTION. @@ -4424,7 +4424,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID - # 출처: NTF-INT-007 — CONTACT_LOOKUP_HMAC key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — CONTACT_LOOKUP_HMAC key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CONTACT_LOOKUP_HMAC. @@ -4440,7 +4440,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID - # 출처: NTF-INT-007 — CALLBACK_SIGNING key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — CALLBACK_SIGNING key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CALLBACK_SIGNING. @@ -4456,7 +4456,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID - # 출처: NTF-INT-007 — PROVIDER_CREDENTIAL key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — PROVIDER_CREDENTIAL key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.PROVIDER_CREDENTIAL. @@ -4472,7 +4472,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID - # 출처: NTF-INT-007 — PAYLOAD_ENCRYPTION key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — PAYLOAD_ENCRYPTION key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.PAYLOAD_ENCRYPTION. @@ -4488,7 +4488,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID - # 출처: NTF-INT-007 — PROVIDER_REQUEST_LOOKUP_HMAC key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — PROVIDER_REQUEST_LOOKUP_HMAC key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.PROVIDER_REQUEST_LOOKUP_HMAC. @@ -4504,7 +4504,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID - # 출처: NTF-INT-007 — CALLBACK_FINGERPRINT_HMAC key가 만드는 모든 envelope에 적는 id. + # source: NTF-INT-007 — CALLBACK_FINGERPRINT_HMAC key가 만드는 모든 envelope에 적는 id. # key 자료가 아니라 식별자라 public-config다. 자료 자체는 위의 # APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY 행이다. 바인딩 위치: # app.notification.platform.secrets.active-key-ids.CALLBACK_FINGERPRINT_HMAC. @@ -4520,7 +4520,7 @@ env_keys: required_test: adapter-contract:notification-secret-material-required - name: APP_NOTIFICATION_PLATFORM_SES_ENABLED - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: boolean default: false allowed_values: [true, false] @@ -4533,7 +4533,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_PRIMARY - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: boolean default: false allowed_values: [true, false] @@ -4546,7 +4546,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ENVIRONMENT - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: PRODUCTION allowed_values: null @@ -4559,7 +4559,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4572,7 +4572,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_TIMEOUT - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: duration default: 10s allowed_values: null @@ -4585,7 +4585,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_MAX_CONCURRENCY - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: int default: 8 allowed_values: null @@ -4598,7 +4598,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_RATE_PER_SECOND - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: int default: 20 allowed_values: null @@ -4611,7 +4611,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ENDPOINT - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: https://email.us-east-1.amazonaws.com allowed_values: null @@ -4624,7 +4624,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_REGION - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: us-east-1 allowed_values: null @@ -4637,7 +4637,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_SENDER_IDENTITY - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4650,7 +4650,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ACCESS_KEY_ID - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4663,7 +4663,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_CONFIGURATION_SET - # 출처: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. + # source: notification/fileserver H4-B — 기본으로 들어 있는 SES 발송 조립기. type: string default: null allowed_values: null @@ -4676,7 +4676,7 @@ env_keys: required_test: adapter-contract:notification-ses-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS - # 출처: 2026-09-24 module review Critical #10 — 기본 SES profile이 받는 SES 이벤트 callback의 SNS topic. + # source: 2026-09-24 module review Critical #10 — 기본 SES profile이 받는 SES 이벤트 callback의 SNS topic. # SNS 서명이 맞다는 것은 AWS가 보냈다는 것만 증명하고, topic은 누구나 가질 수 있다. 그래서 callback을 켰는데 # 이 값이 비면 바인딩이 실패한다. type: csv @@ -4691,7 +4691,7 @@ env_keys: required_test: adapter-contract:notification-ses-callback-topic-allowlist - name: APP_NOTIFICATION_PLATFORM_SMTP_ENABLED - # 출처: NTF-INT-001 — 기본 SMTP provider profile 켜고 끄기. false면 조립에서 통째로 뺀다. + # source: NTF-INT-001 — 기본 SMTP provider profile 켜고 끄기. false면 조립에서 통째로 뺀다. type: boolean default: false allowed_values: [true, false] @@ -4704,7 +4704,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY - # 출처: NTF-INT-001 — 이 profile이 EMAIL의 주 경로인지. 채널마다 주 경로는 정확히 하나다. + # source: NTF-INT-001 — 이 profile이 EMAIL의 주 경로인지. 채널마다 주 경로는 정확히 하나다. type: boolean default: true allowed_values: [true, false] @@ -4717,7 +4717,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT - # 출처: NTF-INT-001 — profile이 밝힌 환경. 모든 발송 기록에 실린다. + # source: NTF-INT-001 — profile이 밝힌 환경. 모든 발송 기록에 실린다. type: string default: local allowed_values: null @@ -4730,7 +4730,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE - # 출처: NTF-INT-001 — relay 자격 증명을 푸는 credential profile. + # source: NTF-INT-001 — relay 자격 증명을 푸는 credential profile. type: string default: default allowed_values: null @@ -4743,7 +4743,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT - # 출처: NTF-INT-001 — 이 profile의 시도마다 provider timeout. + # source: NTF-INT-001 — 이 profile의 시도마다 provider timeout. type: duration default: 10s allowed_values: null @@ -4756,7 +4756,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY - # 출처: NTF-INT-001 — 이 profile이 동시에 처리할 수 있는 시도 수. + # source: NTF-INT-001 — 이 profile이 동시에 처리할 수 있는 시도 수. type: int default: 4 allowed_values: null @@ -4769,7 +4769,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND - # 출처: NTF-INT-001 — profile의 시도 속도 제한. + # source: NTF-INT-001 — profile의 시도 속도 제한. type: int default: 10 allowed_values: null @@ -4782,7 +4782,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY - # 출처: NTF-INT-001 — 모든 메시지를 보내는 envelope 발신자. + # source: NTF-INT-001 — 모든 메시지를 보내는 envelope 발신자. type: string default: no-reply@example.invalid allowed_values: null @@ -4795,7 +4795,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY - # 출처: NTF-INT-001 — SMTP 발송이 도는, 크기가 정해진 executor의 크기. + # source: NTF-INT-001 — SMTP 발송이 도는, 크기가 정해진 executor의 크기. type: int default: 4 allowed_values: null @@ -4808,7 +4808,7 @@ env_keys: required_test: adapter-contract:notification-smtp-provider-assembled - name: SPRING_MAIL_HOST - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.host owner_module: adapter-outbound-notification @@ -4825,7 +4825,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PORT - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.port owner_module: adapter-outbound-notification @@ -4842,7 +4842,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_USERNAME - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.username owner_module: adapter-outbound-notification @@ -4859,7 +4859,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PASSWORD - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.password owner_module: adapter-outbound-notification @@ -4876,7 +4876,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.starttls.enable owner_module: adapter-outbound-notification @@ -4893,7 +4893,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_REQUIRED - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.starttls.required owner_module: adapter-outbound-notification @@ -4910,7 +4910,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_CONNECTIONTIMEOUT - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.connectiontimeout owner_module: adapter-outbound-notification @@ -4927,7 +4927,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_TIMEOUT - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.timeout owner_module: adapter-outbound-notification @@ -4944,7 +4944,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: SPRING_MAIL_PROPERTIES_MAIL_SMTP_WRITETIMEOUT - # 출처: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 + # source: notification/fileserver techlead review H2 — Spring Mail 자체 transport 설정. 기본 SMTP 조립기가 # 검증하고 쓰는 JavaMailSender가 읽는다. property: spring.mail.properties.mail.smtp.writetimeout owner_module: adapter-outbound-notification @@ -4961,7 +4961,7 @@ env_keys: required_test: adapter-contract:notification-smtp-transport - name: APP_OPENAPI_DOCS_ENABLED - # 출처: five-adapter-runtime-remediation §9 — /v3/api-docs를 내줄지. application-prod.yml이 false로 + # source: five-adapter-runtime-remediation §9 — /v3/api-docs를 내줄지. application-prod.yml이 false로 # 고정한다. 기본값에 맡기지 않고 적는 이유: 배포가 정할 때까지 SpringDoc이 기동마다 경고하고, 기동마다 나는 # 경고는 아무도 읽지 않는다. type: boolean @@ -4976,7 +4976,7 @@ env_keys: required_test: env-contract:openapi-exposure-decided - name: APP_OPENAPI_UI_ENABLED - # 출처: five-adapter-runtime-remediation §9 — Swagger UI를 내줄지. application-prod.yml이 false로 고정한다. + # source: five-adapter-runtime-remediation §9 — Swagger UI를 내줄지. application-prod.yml이 false로 고정한다. # 기본값에 맡기지 않고 적는 이유: 배포가 정할 때까지 SpringDoc이 기동마다 경고하고, 기동마다 나는 경고는 # 아무도 읽지 않는다. type: boolean @@ -4991,7 +4991,7 @@ env_keys: required_test: env-contract:openapi-exposure-decided - name: APP_NOTIFICATION_PLATFORM_MODE - # 출처: NTF-025 — SERVING은 동작하는 provider 없이 기동을 거부한다. INGEST_ONLY는 저장만 하고 보내지 않는다. + # source: NTF-025 — SERVING은 동작하는 provider 없이 기동을 거부한다. INGEST_ONLY는 저장만 하고 보내지 않는다. # 상수는 INGEST_ONLY다. 이 행은 ACCEPT_ONLY라 했는데, NotificationPlatformMode에 그런 이름은 없었다. 그래서 # 레지스트리를 따른 운영자는 문서에 없는 값을 지목하는 바인딩 실패를 받았다. NotificationModeSsotTest가 아래 # 목록을 enum에서 만든다. @@ -5007,7 +5007,7 @@ env_keys: required_test: adapter-contract:notification-platform-mode - name: APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE - # 출처: NTF-025 — scheduler 한 번이 claim하는 수신자 전달 수. 1..1000이고 밖이면 바인딩에서 거부한다 + # source: NTF-025 — scheduler 한 번이 claim하는 수신자 전달 수. 1..1000이고 밖이면 바인딩에서 거부한다 type: integer default: 50 allowed_values: null @@ -5020,7 +5020,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_LEASE_DURATION - # 출처: NTF-025 — provider 호출과 그 timeout보다 길어야 한다. 아니면 살아 있는 worker의 전달을 다른 worker가 claim한다 + # source: NTF-025 — provider 호출과 그 timeout보다 길어야 한다. 아니면 살아 있는 worker의 전달을 다른 worker가 claim한다 type: duration default: 2m allowed_values: null @@ -5033,7 +5033,7 @@ env_keys: required_test: adapter-contract:notification-lease-fencing - name: APP_NOTIFICATION_PLATFORM_POLL_INTERVAL - # 출처: NTF-025 — 지난 차례에 claim한 것이 없을 때 scheduler가 일을 다시 묻는 간격 + # source: NTF-025 — 지난 차례에 claim한 것이 없을 때 scheduler가 일을 다시 묻는 간격 type: duration default: 1s allowed_values: null @@ -5046,7 +5046,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY - # 출처: NTF-025 — 프로세스 전체에서 처리 중인 provider 호출 수 상한 + # source: NTF-025 — 프로세스 전체에서 처리 중인 provider 호출 수 상한 type: integer default: 64 allowed_values: null @@ -5059,7 +5059,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS - # 출처: NTF-025 — 첫 시도 뒤의 재시도 수. 0이면 한 번 시도하고 재시도하지 않는다 + # source: NTF-025 — 첫 시도 뒤의 재시도 수. 0이면 한 번 시도하고 재시도하지 않는다 type: integer default: 4 allowed_values: null @@ -5072,7 +5072,7 @@ env_keys: required_test: adapter-contract:notification-retry-policy - name: APP_NOTIFICATION_PLATFORM_ESTIMATED_DISPATCH_DURATION - # 출처: NTF-025 — lease·재시도 계획에 쓰는 발송 지연 추정값 + # source: NTF-025 — lease·재시도 계획에 쓰는 발송 지연 추정값 type: duration default: 2s allowed_values: null @@ -5085,7 +5085,7 @@ env_keys: required_test: adapter-contract:notification-dispatch-bounds - name: APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE - # 출처: NTF-025 — 이 시간이 지나면 queue의 전달은 늦게 보내지 않고 만료된다 + # source: NTF-025 — 이 시간이 지나면 queue의 전달은 늦게 보내지 않고 만료된다 type: duration default: 24h allowed_values: null @@ -5098,7 +5098,7 @@ env_keys: required_test: adapter-contract:notification-expiry - name: APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK - # 출처: NTF-025 — 결과를 읽지 못한 애매한 시도가 provider에 닿았다. 다른 경로로 넘기면 두 번 보낼 위험이 있다 + # source: NTF-025 — 결과를 읽지 못한 애매한 시도가 provider에 닿았다. 다른 경로로 넘기면 두 번 보낼 위험이 있다 type: boolean default: false allowed_values: [true, false] @@ -5113,7 +5113,7 @@ env_keys: - name: APP_NOTIFICATION_PLATFORM_SHUTDOWN_GRACE - # 출처: NTF-025 — 프로세스 종료 때 worker 정리 시간의 상한 + # source: NTF-025 — 프로세스 종료 때 worker 정리 시간의 상한 type: duration default: 20s allowed_values: null @@ -5126,7 +5126,7 @@ env_keys: required_test: adapter-contract:notification-shutdown-grace - name: APP_NOTIFICATION_PLATFORM_MAX_BACKLOG_DEPTH - # 출처: NTF-OBS-001 — 기한이 됐는데 claim되지 않은 전달의 readiness 기준 + # source: NTF-OBS-001 — 기한이 됐는데 claim되지 않은 전달의 readiness 기준 type: integer default: 100000 allowed_values: null @@ -5139,7 +5139,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_OLDEST_DUE_AGE - # 출처: NTF-OBS-001 — 기한이 된 가장 오래된 전달의 readiness 기준 + # source: NTF-OBS-001 — 기한이 된 가장 오래된 전달의 readiness 기준 type: duration default: 10m allowed_values: null @@ -5152,7 +5152,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_STUCK_LEASES - # 출처: NTF-OBS-001 — 만료되거나 멈춘 전달 lease의 readiness 기준 + # source: NTF-OBS-001 — 만료되거나 멈춘 전달 lease의 readiness 기준 type: integer default: 50 allowed_values: null @@ -5165,7 +5165,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_PENDING_PROJECTIONS - # 출처: NTF-OBS-001 — 적용되지 않은 provider 이벤트 projection의 readiness 기준 + # source: NTF-OBS-001 — 적용되지 않은 provider 이벤트 projection의 readiness 기준 type: integer default: 50000 allowed_values: null @@ -5178,7 +5178,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_FAILED_PROJECTIONS - # 출처: NTF-OBS-001 — 실패한 provider 이벤트 projection의 readiness 기준 + # source: NTF-OBS-001 — 실패한 provider 이벤트 projection의 readiness 기준 type: integer default: 1000 allowed_values: null @@ -5191,7 +5191,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_OLDEST_PENDING_PROJECTION_AGE - # 출처: NTF-OBS-001 — 가장 오래 기다린 projection의 readiness 기준 + # source: NTF-OBS-001 — 가장 오래 기다린 projection의 readiness 기준 type: duration default: 15m allowed_values: null @@ -5204,7 +5204,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_MAX_OLDEST_RECONCILIATION_AGE - # 출처: NTF-OBS-001 — 가장 오래 풀리지 않은 대조(reconciliation)의 readiness 기준 + # source: NTF-OBS-001 — 가장 오래 풀리지 않은 대조(reconciliation)의 readiness 기준 type: duration default: 30m allowed_values: null @@ -5217,7 +5217,7 @@ env_keys: required_test: adapter-contract:notification-serving-thresholds - name: APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED - # 출처: NTF-025 — 플랫폼이 provider callback endpoint를 내놓을지 + # source: NTF-025 — 플랫폼이 provider callback endpoint를 내놓을지 type: boolean default: false allowed_values: [true, false] @@ -5230,7 +5230,7 @@ env_keys: required_test: adapter-contract:notification-callback-ingestion - name: APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES - # 출처: NTF-025 — 상한 65251 = 암호문 칸 크기에서 가장 큰 envelope(version, key-id 길이, 255바이트 key id, AES-GCM nonce와 tag)를 뺀 값. 더 크면 바인딩에서 거부한다 + # source: NTF-025 — 상한 65251 = 암호문 칸 크기에서 가장 큰 envelope(version, key-id 길이, 255바이트 key id, AES-GCM nonce와 tag)를 뺀 값. 더 크면 바인딩에서 거부한다 type: integer default: 65251 allowed_values: null @@ -5243,7 +5243,7 @@ env_keys: required_test: adapter-contract:notification-callback-body-bound - name: APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW - # 출처: NTF-025 — callback 시각이 로컬 시각과 이만큼 넘게 다르면 replay로 본다 + # source: NTF-025 — callback 시각이 로컬 시각과 이만큼 넘게 다르면 replay로 본다 # review 05-20 — 1h는 SNS의 HTTP/S 재시도 기간 전체(최대 3,600 s)를 덮는다. 그 안의 replay는 ledger 중복이다 type: duration default: 1h diff --git a/docs/registries/error-codes.yaml b/docs/registries/error-codes.yaml index 929d5a8b..134ffd8f 100644 --- a/docs/registries/error-codes.yaml +++ b/docs/registries/error-codes.yaml @@ -38,7 +38,7 @@ errors: # AUTH (feature-security-operational-baseline / Decision Matrix) # ============================================================ - # 출처: feature-security-operational-baseline L82 — "token 누락 | 401 | AUTH_TOKEN_MISSING | AUTH" + # source: feature-security-operational-baseline L82 — "token 누락 | 401 | AUTH_TOKEN_MISSING | AUTH" - code: AUTH_TOKEN_MISSING category: AUTH http_status: 401 @@ -51,7 +51,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L83 — "token malformed (parse fail) | 401 | AUTH_TOKEN_MALFORMED | AUTH" + # source: feature-security-operational-baseline L83 — "token malformed (parse fail) | 401 | AUTH_TOKEN_MALFORMED | AUTH" - code: AUTH_TOKEN_MALFORMED category: AUTH http_status: 401 @@ -64,7 +64,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L84 — "token expired (clock skew tolerance 60s 초과) | 401 | AUTH_TOKEN_EXPIRED | AUTH" + # source: feature-security-operational-baseline L84 — "token expired (clock skew tolerance 60s 초과) | 401 | AUTH_TOKEN_EXPIRED | AUTH" - code: AUTH_TOKEN_EXPIRED category: AUTH http_status: 401 @@ -77,7 +77,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L85 — "invalid signature | 401 | AUTH_TOKEN_INVALID_SIGNATURE | AUTH" + # source: feature-security-operational-baseline L85 — "invalid signature | 401 | AUTH_TOKEN_INVALID_SIGNATURE | AUTH" - code: AUTH_TOKEN_INVALID_SIGNATURE category: AUTH http_status: 401 @@ -90,7 +90,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L86 — "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH | AUTH" + # source: feature-security-operational-baseline L86 — "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH | AUTH" - code: AUTH_ISSUER_MISMATCH category: AUTH http_status: 401 @@ -103,7 +103,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L87 — "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH | AUTH" + # source: feature-security-operational-baseline L87 — "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH | AUTH" - code: AUTH_AUDIENCE_MISMATCH category: AUTH http_status: 401 @@ -116,7 +116,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L88 — "unknown kid (JWKS 미캐시) | 401 + Retry-After 5s | AUTH_KID_UNKNOWN | AUTH" + # source: feature-security-operational-baseline L88 — "unknown kid (JWKS 미캐시) | 401 + Retry-After 5s | AUTH_KID_UNKNOWN | AUTH" - code: AUTH_KID_UNKNOWN category: AUTH http_status: 401 @@ -130,7 +130,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L89 — "JWKS endpoint outage ... | AUTH_JWKS_UNAVAILABLE | TRANSIENT_DEPENDENCY" + # source: feature-security-operational-baseline L89 — "JWKS endpoint outage ... | AUTH_JWKS_UNAVAILABLE | TRANSIENT_DEPENDENCY" - code: AUTH_JWKS_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 @@ -143,7 +143,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-security-operational-baseline L90 — "claim mapping failure ... | 401 | AUTH_CLAIM_MAPPING_FAILED | AUTH" + # source: feature-security-operational-baseline L90 — "claim mapping failure ... | 401 | AUTH_CLAIM_MAPPING_FAILED | AUTH" - code: AUTH_CLAIM_MAPPING_FAILED category: AUTH http_status: 401 @@ -160,7 +160,7 @@ errors: # AUTHZ (feature-security-operational-baseline) # ============================================================ - # 출처: feature-security-operational-baseline L91 — "valid token + 권한 부족 | 403 | AUTHZ_INSUFFICIENT_PERMISSION | AUTHZ" + # source: feature-security-operational-baseline L91 — "valid token + 권한 부족 | 403 | AUTHZ_INSUFFICIENT_PERMISSION | AUTHZ" - code: AUTHZ_INSUFFICIENT_PERMISSION category: AUTHZ http_status: 403 @@ -173,7 +173,7 @@ errors: compatibility_impact: none required_test: contract-verification:authz-category - # 출처: feature-security-operational-baseline L92 — "valid token + tenant cross-access | 403 | AUTHZ_TENANT_MISMATCH | AUTHZ" + # source: feature-security-operational-baseline L92 — "valid token + tenant cross-access | 403 | AUTHZ_TENANT_MISMATCH | AUTHZ" - code: AUTHZ_TENANT_MISMATCH category: AUTHZ http_status: 403 @@ -190,7 +190,7 @@ errors: # INTERNAL (feature-security-operational-baseline + container-runtime) # ============================================================ - # 출처: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL" + # source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL" - code: INTERNAL_AUTH_MISCONFIGURATION category: INTERNAL http_status: 500 @@ -203,7 +203,7 @@ errors: compatibility_impact: none required_test: contract-verification:auth-category - # 출처: feature-container-runtime-contract L113 — "JVM OutOfMemoryError → ExitOnOutOfMemoryError로 137 exit, log에 error.code=JVM_OOM 명시" + # source: feature-container-runtime-contract L113 — "JVM OutOfMemoryError → ExitOnOutOfMemoryError로 137 exit, log에 error.code=JVM_OOM 명시" - code: JVM_OOM category: INTERNAL http_status: 500 @@ -220,7 +220,7 @@ errors: # DB / 영속성 (feature-persistence-failure-baseline / SQLState Matrix) # ============================================================ - # 출처: feature-persistence-failure-baseline L85 — "08* | all | TRANSIENT_DEPENDENCY | DB_UNAVAILABLE | true" + # source: feature-persistence-failure-baseline L85 — "08* | all | TRANSIENT_DEPENDENCY | DB_UNAVAILABLE | true" - code: DB_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 @@ -233,7 +233,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L86 — "40001 | Postgres/MySQL | CONFLICT | DB_SERIALIZATION_FAILURE | true" + # source: feature-persistence-failure-baseline L86 — "40001 | Postgres/MySQL | CONFLICT | DB_SERIALIZATION_FAILURE | true" - code: DB_SERIALIZATION_FAILURE category: CONFLICT http_status: 409 @@ -246,7 +246,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L87 — "40P01 | Postgres | CONFLICT | DB_DEADLOCK | true (backoff)" + # source: feature-persistence-failure-baseline L87 — "40P01 | Postgres | CONFLICT | DB_DEADLOCK | true (backoff)" - code: DB_DEADLOCK category: CONFLICT http_status: 409 @@ -259,7 +259,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L88 — "23502 | Postgres | DATA_INTEGRITY | DB_NULL_VIOLATION | false" + # source: feature-persistence-failure-baseline L88 — "23502 | Postgres | DATA_INTEGRITY | DB_NULL_VIOLATION | false" - code: DB_NULL_VIOLATION category: DATA_INTEGRITY http_status: 409 @@ -272,7 +272,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L89 — "23503 | Postgres | DATA_INTEGRITY | DB_FK_VIOLATION | false" + # source: feature-persistence-failure-baseline L89 — "23503 | Postgres | DATA_INTEGRITY | DB_FK_VIOLATION | false" - code: DB_FK_VIOLATION category: DATA_INTEGRITY http_status: 409 @@ -285,7 +285,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L90 — "23505 | Postgres | CONFLICT | DB_UNIQUE_VIOLATION | false (business mapping)" + # source: feature-persistence-failure-baseline L90 — "23505 | Postgres | CONFLICT | DB_UNIQUE_VIOLATION | false (business mapping)" - code: DB_UNIQUE_VIOLATION category: CONFLICT http_status: 409 @@ -298,7 +298,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L91 — "23514 | Postgres | DATA_INTEGRITY | DB_CHECK_VIOLATION | false" + # source: feature-persistence-failure-baseline L91 — "23514 | Postgres | DATA_INTEGRITY | DB_CHECK_VIOLATION | false" - code: DB_CHECK_VIOLATION category: DATA_INTEGRITY http_status: 409 @@ -311,7 +311,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L92 — "25P03 | Postgres | TRANSIENT_DEPENDENCY | DB_IDLE_IN_TX_TIMEOUT | true" + # source: feature-persistence-failure-baseline L92 — "25P03 | Postgres | TRANSIENT_DEPENDENCY | DB_IDLE_IN_TX_TIMEOUT | true" - code: DB_IDLE_IN_TX_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 503 @@ -324,7 +324,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: feature-persistence-failure-baseline L93 — "57014 | Postgres | TRANSIENT_DEPENDENCY | DB_QUERY_CANCELED | false" + # source: feature-persistence-failure-baseline L93 — "57014 | Postgres | TRANSIENT_DEPENDENCY | DB_QUERY_CANCELED | false" - code: DB_QUERY_CANCELED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -337,7 +337,7 @@ errors: compatibility_impact: none required_test: contract-verification:persistence-mapping - # 출처: review-followup P15 (S2-lead-4) — JPA OPTIMISTIC_CONFLICT (flush·commit 때 @Version 검사 실패) + # source: review-followup P15 (S2-lead-4) — JPA OPTIMISTIC_CONFLICT (flush·commit 때 @Version 검사 실패) - code: DB_OPTIMISTIC_CONFLICT category: CONFLICT http_status: 409 @@ -350,7 +350,7 @@ errors: compatibility_impact: additive required_test: persistence-jpa:JpaPersistenceExceptionCodeTest - # 출처: review-followup P15 (S2-lead-4) — JPA COMPLETION_UNKNOWN (40003 / commit 단계 연결 끊김) + # source: review-followup P15 (S2-lead-4) — JPA COMPLETION_UNKNOWN (40003 / commit 단계 연결 끊김) - code: DB_COMPLETION_UNKNOWN category: DATA_INTEGRITY http_status: 500 @@ -367,7 +367,7 @@ errors: # Rate limit / Idempotency (feature-rate-limit-idempotency-contract) # ============================================================ - # 출처: feature-rate-limit-idempotency-contract — rate limit 응답·로그 기준 / Retry-After 헤더 기준 (scope L29, L33) + # source: feature-rate-limit-idempotency-contract — rate limit 응답·로그 기준 / Retry-After 헤더 기준 (scope L29, L33) - code: RATE_LIMIT_EXCEEDED category: RATE_LIMIT http_status: 429 @@ -380,7 +380,7 @@ errors: compatibility_impact: none required_test: contract-verification:rate-limit - # 출처: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지. + # source: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지. # 2초 = 기본 processing lease(30s)보다 짧은 고정값. 이전 "client는 polling"(retryable=false)은 조회 엔드포인트가 없어 폐기. # 값 하나: IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER. processing-lease가 이 값 이하면 기동 실패(재리뷰 RR-02-05). # behavior-change: retryable false→true는 web Envelope뿐 아니라 gRPC trailer error-retryable(status ABORTED)과 @@ -397,7 +397,7 @@ errors: compatibility_impact: behavior-change required_test: contract-verification:idempotency - # 출처: feature-rate-limit-idempotency-contract L72 — "fingerprint mismatch (same key + different body) = 422 IDEMPOTENT_REQUEST_MISMATCH" + # source: feature-rate-limit-idempotency-contract L72 — "fingerprint mismatch (same key + different body) = 422 IDEMPOTENT_REQUEST_MISMATCH" - code: IDEMPOTENT_REQUEST_MISMATCH category: VALIDATION http_status: 422 @@ -410,7 +410,7 @@ errors: compatibility_impact: none required_test: contract-verification:idempotency - # 출처: review-followup P15 (X2-P2-2a) — IdempotencyExecutor가 동작 전에 닫힌 채 거절한다(fail-closed) + # source: review-followup P15 (X2-P2-2a) — IdempotencyExecutor가 동작 전에 닫힌 채 거절한다(fail-closed) - code: IDEMPOTENCY_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 @@ -423,7 +423,7 @@ errors: compatibility_impact: additive required_test: contract-verification:idempotency - # 출처: 재리뷰 2026-11-03 README 4절 결정, RR-02-03 — action이 돈 뒤 complete 단계에서 저장소가 응답하지 않음. + # source: 재리뷰 2026-11-03 README 4절 결정, RR-02-03 — action이 돈 뒤 complete 단계에서 저장소가 응답하지 않음. # 실행 전 거부(IDEMPOTENCY_UNAVAILABLE)와 code로 구분한다. 결과 불명: 같은 키로 재전송하면 서버가 replay·in-flight· # recovery-required로 판정한다. 새 키 금지. docs/web/http-contract.md §2. - code: IDEMPOTENCY_COMPLETION_UNKNOWN @@ -438,7 +438,7 @@ errors: compatibility_impact: additive required_test: contract-verification:idempotency - # 출처: review-followup P15 (X2-P2-2a) — replay가 외부 효과가 일어났는지 정할 수 없다 + # source: review-followup P15 (X2-P2-2a) — replay가 외부 효과가 일어났는지 정할 수 없다 - code: IDEMPOTENCY_RECOVERY_REQUIRED category: DATA_INTEGRITY http_status: 500 @@ -455,7 +455,7 @@ errors: # 파일 / 자원 (feature-file-resource-handling-contract) # ============================================================ - # 출처: feature-file-resource-handling-contract L69 — "spring.servlet.multipart.max-file-size 10MB ... Spring 단의 enforcement가 실패 시 envelope 응답 보장" / 테스트 계약 "oversized upload가 generic 500으로 처리되면 실패" + # source: feature-file-resource-handling-contract L69 — "spring.servlet.multipart.max-file-size 10MB ... Spring 단의 enforcement가 실패 시 envelope 응답 보장" / 테스트 계약 "oversized upload가 generic 500으로 처리되면 실패" # ============================================================ # API 계약의 전송 표준 코드 (feature-api-contract-baseline) # ============================================================ @@ -464,7 +464,7 @@ errors: # 그대로 옮긴 것이다. D11 상태 대응 일관성 테스트(소유: 이 branch, 생산자)가 코드의 레지스트리 http_status와 # enum httpStatus()가 어긋나면 빌드를 실패시킨다. - # 출처: feature-api-contract-baseline.md D12 — "405 Method Not Allowed + Allow header 의무" + # source: feature-api-contract-baseline.md D12 — "405 Method Not Allowed + Allow header 의무" - code: METHOD_NOT_ALLOWED category: VALIDATION http_status: 405 @@ -477,7 +477,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # 출처: feature-api-contract-baseline.md D9 — "406 Not Acceptable = 응답 표현 협상 실패" + # source: feature-api-contract-baseline.md D9 — "406 Not Acceptable = 응답 표현 협상 실패" - code: NOT_ACCEPTABLE category: VALIDATION http_status: 406 @@ -490,7 +490,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # 출처: feature-api-contract-baseline.md D15 — "If-Match mismatch 시 412 Precondition Failed" + # source: feature-api-contract-baseline.md D15 — "If-Match mismatch 시 412 Precondition Failed" - code: PRECONDITION_FAILED category: CONFLICT http_status: 412 @@ -503,7 +503,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # 출처: feature-api-contract-baseline.md D8 — "request size limit 실패 분류 (413)" + # source: feature-api-contract-baseline.md D8 — "request size limit 실패 분류 (413)" - code: PAYLOAD_TOO_LARGE category: VALIDATION http_status: 413 @@ -516,7 +516,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # 출처: feature-api-contract-baseline.md D8 형제 — "URI 길이 실패 분류 (414)" + # source: feature-api-contract-baseline.md D8 형제 — "URI 길이 실패 분류 (414)" # 참고: 강제는 Tomcat·gateway가 한다(Spring dispatch 전에 거절). 이 행과 코드는 상태 대응 일관성을 위해 # 있다. 끝에서 끝까지의 414 계약 테스트는 `planned`다 (gateway/Tomcat maxHttpHeaderSize 8KB 경계). - code: URI_TOO_LONG @@ -531,7 +531,7 @@ errors: compatibility_impact: none required_test: contract-verification:api-contract-status-mapping - # 출처: feature-api-contract-baseline.md D9 — "415 Unsupported Media Type = 요청 본문 format 미지원" + # source: feature-api-contract-baseline.md D9 — "415 Unsupported Media Type = 요청 본문 format 미지원" - code: UNSUPPORTED_MEDIA_TYPE category: VALIDATION http_status: 415 @@ -548,7 +548,7 @@ errors: # Tenant (feature-tenant-context-policy) # ============================================================ - # 출처: feature-tenant-context-policy L71 — "tenant 미지원 모드에서 X-Tenant-Id 헤더 수신 시 400 TENANT_NOT_SUPPORTED (filter 단계)" + # source: feature-tenant-context-policy L71 — "tenant 미지원 모드에서 X-Tenant-Id 헤더 수신 시 400 TENANT_NOT_SUPPORTED (filter 단계)" # ============================================================ # Validation / Business rule (feature-business-rule-validation-contract) # ============================================================ @@ -558,17 +558,17 @@ errors: # (feature-operational-error-observability-foundation L110). 실제 도메인별 code는 # Phase D(도메인 feature 적용) 시 본 registry에 추가. - # 출처: feature-operational-error-observability-foundation L110 — "code: VALIDATION_EMAIL_FORMAT, // registry-registered code" (validation 필드 오류 JSON 모양 예) + # source: feature-operational-error-observability-foundation L110 — "code: VALIDATION_EMAIL_FORMAT, // registry-registered code" (validation 필드 오류 JSON 모양 예) # ============================================================ # 캐시 (feature-cache-consistency-contract) # ============================================================ - # 출처: feature-cache-consistency-contract — Decisionized Work Items "Redis unavailable | degrade only if declared | fail-fast for required cache | generic INTERNAL | unavailable mapping" / 테스트 "Redis unavailable이 degrade 가능 여부 없이 INTERNAL로 처리되면 실패" + # source: feature-cache-consistency-contract — Decisionized Work Items "Redis unavailable | degrade only if declared | fail-fast for required cache | generic INTERNAL | unavailable mapping" / 테스트 "Redis unavailable이 degrade 가능 여부 없이 INTERNAL로 처리되면 실패" # ============================================================ # 외부 HTTP 호출 (feature-outbound-http-client-baseline) # ============================================================ - # 출처: feature-outbound-http-client-baseline L70 — "outbound HTTP timeout default = connect 2s / read 5s / global call 10s" + scope "timeout/connect/DNS failure 분류" / 테스트 "upstream timeout은 retryable dependency failure로 분류되어야 함" + # source: feature-outbound-http-client-baseline L70 — "outbound HTTP timeout default = connect 2s / read 5s / global call 10s" + scope "timeout/connect/DNS failure 분류" / 테스트 "upstream timeout은 retryable dependency failure로 분류되어야 함" - code: DEPENDENCY_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 504 @@ -581,7 +581,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # 출처: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + L70 connect=2s timeout + # source: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + L70 connect=2s timeout - code: DEPENDENCY_CONNECT_FAILED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -594,7 +594,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # 출처: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + # source: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" - code: DEPENDENCY_DNS_FAILED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -607,7 +607,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # 출처: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" / 테스트 "401/403은 credential/scope/config 문제로 분류되어야 함" + # source: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" / 테스트 "401/403은 credential/scope/config 문제로 분류되어야 함" - code: DEPENDENCY_4XX_CLIENT category: PERMANENT_DEPENDENCY http_status: 502 @@ -620,7 +620,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # 출처: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" + # source: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" - code: DEPENDENCY_5XX_SERVER category: TRANSIENT_DEPENDENCY http_status: 502 @@ -633,7 +633,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbound-http - # 출처: feature-outbound-http-client-baseline L69 — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + Decisionized "circuit breaker | Resilience4j optional env" + # source: feature-outbound-http-client-baseline L69 — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + Decisionized "circuit breaker | Resilience4j optional env" - code: DEPENDENCY_CIRCUIT_OPEN category: TRANSIENT_DEPENDENCY http_status: 503 @@ -650,7 +650,7 @@ errors: # Outbox (feature-domain-event-outbox-contract) # ============================================================ - # 출처: feature-domain-event-outbox-contract L67 — "outbox row status enum = PENDING / IN_FLIGHT / PUBLISHED / FAILED / DEAD" + scope "publish 실패 분류" / 판정 "publish 실패가 retry/DLQ/log/runbook 기준 없이 삼켜지면 실패" + # source: feature-domain-event-outbox-contract L67 — "outbox row status enum = PENDING / IN_FLIGHT / PUBLISHED / FAILED / DEAD" + scope "publish 실패 분류" / 판정 "publish 실패가 retry/DLQ/log/runbook 기준 없이 삼켜지면 실패" - code: OUTBOX_PUBLISH_FAILED category: TRANSIENT_DEPENDENCY http_status: 500 @@ -663,7 +663,7 @@ errors: compatibility_impact: none required_test: contract-verification:outbox-publish - # 출처: feature-domain-event-outbox-contract L67 — outbox status enum "DEAD" / Outbox Defaults "DLQ | background-job branch owner" + # source: feature-domain-event-outbox-contract L67 — outbox status enum "DEAD" / Outbox Defaults "DLQ | background-job branch owner" - code: OUTBOX_DEAD_LETTER category: INTERNAL http_status: 500 @@ -680,7 +680,7 @@ errors: # 백그라운드 작업 / 비동기 (feature-background-job-async-contract) # ============================================================ - # 출처: feature-background-job-async-contract — Decisionized "saturation | bounded executor + rejection log" / L72 "saturation policy default = AbortPolicy" / 테스트 "executor rejection이 structured log 없이 발생하면 실패" + # source: feature-background-job-async-contract — Decisionized "saturation | bounded executor + rejection log" / L72 "saturation policy default = AbortPolicy" / 테스트 "executor rejection이 structured log 없이 발생하면 실패" - code: JOB_EXECUTOR_REJECTED category: TRANSIENT_DEPENDENCY http_status: 503 @@ -693,7 +693,7 @@ errors: compatibility_impact: none required_test: contract-verification:async-saturation - # 출처: feature-background-job-async-contract L69 — "기본 backoff는 exponential backoff with jitter, max attempts 3, DLQ after exhausted attempts" + scope "shutdown 중 job 처리 기준" / L73 graceful shutdown ≤19s + # source: feature-background-job-async-contract L69 — "기본 backoff는 exponential backoff with jitter, max attempts 3, DLQ after exhausted attempts" + scope "shutdown 중 job 처리 기준" / L73 graceful shutdown ≤19s - code: JOB_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 500 @@ -706,7 +706,7 @@ errors: compatibility_impact: none required_test: contract-verification:async-timeout - # 출처: feature-background-job-async-contract L69 — "DLQ after exhausted attempts" + Decisionized "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted | ... | infinite retry" + # source: feature-background-job-async-contract L69 — "DLQ after exhausted attempts" + Decisionized "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted | ... | infinite retry" - code: JOB_DEAD_LETTER category: INTERNAL http_status: 500 @@ -723,7 +723,7 @@ errors: # 분산 lock (feature-distributed-lock-contract) # ============================================================ - # 출처: feature-distributed-lock-contract D7 — "lock 획득 실패/timeout 의 error code = + # source: feature-distributed-lock-contract D7 — "lock 획득 실패/timeout 의 error code = # LOCK_ACQUISITION_TIMEOUT (category CONFLICT, retryable true, client_safe true) + metric # lock.acquisition" / D5 — "try-lock + 유한 waitTime + lease(TTL) 필수, 무한 blocking 금지". # category CONFLICT 는 기존 enum 재사용; retryable=true — 락 보유자가 임계 구역을 빠져나오면 @@ -747,7 +747,7 @@ errors: # Migration / 기동 (feature-migration-startup-contract) # ============================================================ - # 출처: feature-migration-startup-contract L71 — "startup exit code 표준 = ... migration 실패=70 ..." + Decisionized "startup failure log | structured log with startup.phase, error.code, error.category" + # source: feature-migration-startup-contract L71 — "startup exit code 표준 = ... migration 실패=70 ..." + Decisionized "startup failure log | structured log with startup.phase, error.code, error.category" - code: ADAPTER_DISABLED category: INTERNAL http_status: 500 @@ -760,12 +760,12 @@ errors: compatibility_impact: none required_test: adapter-contract:adapter-disabled-runtime-call - # 출처: feature-migration-startup-contract L71 — "startup exit code 표준 = ... profile mismatch=71" / 테스트 "prod profile에서 local-only 설정이 켜지면 실패" + # source: feature-migration-startup-contract L71 — "startup exit code 표준 = ... profile mismatch=71" / 테스트 "prod profile에서 local-only 설정이 켜지면 실패" # ============================================================ # 관리 포트 / Actuator (feature-management-actuator-security-contract) # ============================================================ - # 출처: feature-management-actuator-security-contract — 노출 정책 "env/configprops | forbidden" "heapdump/threaddump | forbidden unless break-glass runbook" "shutdown | forbidden" / 테스트 "prod에서 env/configprops endpoint가 노출되면 실패" + # source: feature-management-actuator-security-contract — Exposure Policy "env/configprops | forbidden" "heapdump/threaddump | forbidden unless break-glass runbook" "shutdown | forbidden" / 테스트 "prod에서 env/configprops endpoint가 노출되면 실패" - code: ACTUATOR_FORBIDDEN category: AUTHZ http_status: 403 diff --git a/docs/registries/headers.yaml b/docs/registries/headers.yaml index 21168e03..5530af1c 100644 --- a/docs/registries/headers.yaml +++ b/docs/registries/headers.yaml @@ -9,7 +9,7 @@ # - envelope_meta_field: camelCase (envelope이 정본) headers: - # 출처: feature-operational-error-observability-foundation.md L97 + # source: feature-operational-error-observability-foundation.md L97 # "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id" - name: X-Request-Id direction: both @@ -23,7 +23,7 @@ headers: compatibility_impact: none required_test: contract-verification:envelope-headers - # 출처: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67 + # source: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67 # "idempotency header 이름은 Idempotency-Key" / "기본 scope는 (authenticatedPrincipal, idempotencyKey, useCaseName)" - name: Idempotency-Key direction: inbound @@ -37,7 +37,7 @@ headers: compatibility_impact: additive required_test: contract-verification:idempotency-replay - # 출처: feature-rate-limit-idempotency-contract.md L85 / foundation L85 + # source: feature-rate-limit-idempotency-contract.md L85 / foundation L85 # "RATE_LIMIT | ... | 429 | true (Retry-After 이후)" / "retry-after 기준 없이 429를 반환하면 실패" - name: Retry-After direction: outbound @@ -51,7 +51,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) + # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) # app.rate-limit.enabled=true인 요청 경로에서만 생성되는 rate-limit 응답 표면 - name: X-RateLimit-Limit direction: outbound @@ -65,7 +65,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) + # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) - name: X-RateLimit-Remaining direction: outbound type: numeric @@ -78,7 +78,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) + # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) - name: X-RateLimit-Reset direction: outbound type: rfc3339-date @@ -91,7 +91,7 @@ headers: compatibility_impact: additive required_test: contract-verification:rate-limit-headers - # 출처: feature-api-compatibility-deprecation-contract.md L87 + # source: feature-api-compatibility-deprecation-contract.md L87 # "deprecation marker | OpenAPI deprecated: true + design record | response header optional" - name: Deprecation direction: outbound @@ -105,7 +105,7 @@ headers: compatibility_impact: additive required_test: contract-verification:deprecation-marker - # 출처: feature-api-compatibility-deprecation-contract.md L87 + # source: feature-api-compatibility-deprecation-contract.md L87 # "deprecation marker | OpenAPI deprecated: true + design record | response header optional" (RFC 8594 Sunset) - name: Sunset direction: outbound @@ -119,7 +119,7 @@ headers: compatibility_impact: additive required_test: contract-verification:deprecation-marker - # 출처: feature-distributed-tracing-contract.md L64, L85 + # source: feature-distributed-tracing-contract.md L64, L85 # "propagation header는 W3C traceparent default" / "HTTP | traceparent, tracestate (W3C)" - name: traceparent direction: both @@ -133,7 +133,7 @@ headers: compatibility_impact: none required_test: contract-verification:trace-propagation - # 출처: feature-distributed-tracing-contract.md L66, L85 + # source: feature-distributed-tracing-contract.md L66, L85 # "propagation format = W3C traceparent + tracestate only. B3 propagation은 forbidden" - name: tracestate direction: both @@ -147,7 +147,7 @@ headers: compatibility_impact: none required_test: contract-verification:trace-propagation - # 출처: feature-operational-error-observability-foundation.md L100 + # source: feature-operational-error-observability-foundation.md L100 # "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id" - name: X-Correlation-Id direction: both @@ -161,7 +161,7 @@ headers: compatibility_impact: none required_test: contract-verification:envelope-headers - # 출처: feature-security-operational-baseline.md L66 + # source: feature-security-operational-baseline.md L66 # "JWT Resource Server를 baseline security model로 둠" (Authorization 헤더의 Bearer 토큰) - name: Authorization direction: inbound @@ -175,7 +175,7 @@ headers: compatibility_impact: none required_test: contract-verification:jwt-resource-server - # 출처: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ 판정 표) + # source: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ Decision Matrix) # 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server의 표준 challenge 헤더 - name: WWW-Authenticate direction: outbound diff --git a/docs/registries/mdc-keys.yaml b/docs/registries/mdc-keys.yaml index e3944d49..fcf391c2 100644 --- a/docs/registries/mdc-keys.yaml +++ b/docs/registries/mdc-keys.yaml @@ -9,7 +9,7 @@ # - foundation L93-102 표 "MDC Key Standard (final)"의 key들이 핵심 정본이다 mdc_keys: - # 출처: feature-operational-error-observability-foundation.md L97 + # source: feature-operational-error-observability-foundation.md L97 # "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id" - key: request_id type: ulid @@ -24,7 +24,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # 출처: feature-operational-error-observability-foundation.md L98 + # source: feature-operational-error-observability-foundation.md L98 # "trace_id | Micrometer Tracing | W3C traceparent header" - key: trace_id type: string @@ -39,7 +39,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # 출처: feature-operational-error-observability-foundation.md L99 + # source: feature-operational-error-observability-foundation.md L99 # "span_id | Micrometer Tracing | W3C traceparent" # NOTE: background-job-async-contract L71 "span_id는 Micrometer Observation context에서 자동 전파(MDC explicit copy 불필요)" - key: span_id @@ -55,7 +55,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # 출처: feature-operational-error-observability-foundation.md L100 + # source: feature-operational-error-observability-foundation.md L100 # "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id" - key: correlation_id type: ulid @@ -70,7 +70,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-mdc-keys - # 출처: feature-operational-error-observability-foundation.md L101 + feature-tenant-context-policy.md L70 + # source: feature-operational-error-observability-foundation.md L101 + feature-tenant-context-policy.md L70 # "tenant_id | tenant context (활성 시) | downstream HTTP X-Tenant-Id (with allowlist)" / # "tenant ID format = opaque ULID (26 chars Crockford base32)" # NOTE: tenant L73 "tenant_id ULID 원본은 metric tag에 직접 사용 금지" @@ -87,7 +87,7 @@ mdc_keys: compatibility_impact: additive required_test: contract-verification:tenant-leakage - # 출처: feature-operational-error-observability-foundation.md L102 + # source: feature-operational-error-observability-foundation.md L102 # "user_principal | security context (pseudonymized only) | log only, headers forbidden" - key: user_principal type: string @@ -104,7 +104,7 @@ mdc_keys: # ── 로그 종류별 확장 (log-management-contract L101-109 "Log Type별 필수 필드") ── - # 출처: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" + # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" # 참고: application-port-usecase-contract / 업무 쪽 operation 식별자 (uri_template과 따로 application이 정한다) - key: operation type: string @@ -119,7 +119,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" + # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" - key: method type: string source: inbound_filter @@ -133,7 +133,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" + # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms" # 참고: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — 값 개수가 정해져 있다 - key: status type: numeric @@ -148,7 +148,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L105-106 "request | ... duration_ms" / "dependency | ... duration_ms" + # source: feature-log-management-contract.md L105-106 "request | ... duration_ms" / "dependency | ... duration_ms" - key: duration_ms type: numeric source: application_set @@ -162,7 +162,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, duration_ms, outcome, error_code" + # source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, duration_ms, outcome, error_code" # 참고: metrics L88 "dependency_name | 50" — 값 개수가 정해져 있다 - key: dependency_name type: string @@ -177,7 +177,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, ..." + # source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, ..." - key: dependency_type type: string source: application_set @@ -191,7 +191,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L106 + metrics L91 "outcome (resilience4j) | 5 (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED)" + # source: feature-log-management-contract.md L106 + metrics L91 "outcome (resilience4j) | 5 (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED)" - key: outcome type: string source: application_set @@ -205,7 +205,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L106 "dependency | ... error_code (실패 시)" + # source: feature-log-management-contract.md L106 "dependency | ... error_code (실패 시)" # 참고: metrics L89 "error_code | 100 — error registry row 상한과 정합" — 값 개수가 정해져 있다 - key: error_code type: string @@ -220,7 +220,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L107 + # source: feature-log-management-contract.md L107 # "security | event_type, user_principal (pseudonymized), source_ip (anonymized — last octet zeroed)" - key: event_type type: string @@ -235,7 +235,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L107 "security | ... source_ip (anonymized — last octet zeroed)" + # source: feature-log-management-contract.md L107 "security | ... source_ip (anonymized — last octet zeroed)" # NOTE: metrics L93 "high-cardinality 금지 tag: ... ip_address" - key: source_ip_anon type: string @@ -250,7 +250,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L108 "audit | actor, action, target, before_hash, after_hash, occurred_at" + # source: feature-log-management-contract.md L108 "audit | actor, action, target, before_hash, after_hash, occurred_at" - key: actor type: string source: security_context @@ -264,7 +264,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L108 "audit | actor, action, target, ..." + # source: feature-log-management-contract.md L108 "audit | actor, action, target, ..." - key: action type: string source: application_set @@ -278,7 +278,7 @@ mdc_keys: compatibility_impact: none required_test: contract-verification:log-fields - # 출처: feature-log-management-contract.md L108 "audit | actor, action, target, ..." + # source: feature-log-management-contract.md L108 "audit | actor, action, target, ..." - key: target type: string source: application_set diff --git a/docs/registries/metrics.yaml b/docs/registries/metrics.yaml index 8f7a6164..06f17143 100644 --- a/docs/registries/metrics.yaml +++ b/docs/registries/metrics.yaml @@ -16,7 +16,7 @@ metrics: # === HTTP 서버 (inbound) === - # 출처: feature-metrics-alerting-contract — Metric/Alert Defaults + # source: feature-metrics-alerting-contract — Metric/Alert Defaults # "HTTP metric | http.server.requests with method/status/uri-template | raw URL or user id tag" - name: http.server.requests type: timer @@ -42,7 +42,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — P1/P2/P3 정량 기준 (HTTP latency p99) + # source: feature-metrics-alerting-contract — P1/P2/P3 정량 기준 (HTTP latency p99) # "P1: p99 > 5s 5분 / P2: p99 > 1s 10분 / P3: p99 > 500ms 30분" - name: http.server.requests.latency type: timer @@ -66,9 +66,9 @@ metrics: required_test: contract-verification:metrics-cardinality # === HTTP client (outbound 의존 대상) === - # 출처: feature-metrics-alerting-contract — Metric/Alert Defaults + # source: feature-metrics-alerting-contract — Metric/Alert Defaults # "dependency metric | dependency.client.requests with dependency.name/type/outcome | endpoint with secret tag" - # 출처: feature-outbound-http-client-baseline — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + # source: feature-outbound-http-client-baseline — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" - name: dependency.client.requests type: timer unit: seconds @@ -92,9 +92,9 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-outbound-http-client-baseline — 결정 + # source: feature-outbound-http-client-baseline — decisions # "retry/circuit breaker 기본 라이브러리는 Resilience4j" - # 출처: feature-metrics-alerting-contract — "retry/CB minimum: resilience4j.retry.calls{outcome}" + # source: feature-metrics-alerting-contract — "retry/CB minimum: resilience4j.retry.calls{outcome}" - name: resilience4j.retry.calls type: counter unit: total @@ -113,7 +113,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.state" + # source: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.state" - name: resilience4j.circuitbreaker.state type: gauge unit: total @@ -133,7 +133,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.calls{outcome}" + # source: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.calls{outcome}" - name: resilience4j.circuitbreaker.calls type: timer unit: seconds @@ -153,9 +153,9 @@ metrics: required_test: contract-verification:metrics-cardinality # === DB connection pool === - # 출처: feature-persistence-failure-baseline — Hikari Alert Threshold + # source: feature-persistence-failure-baseline — Hikari Alert Threshold # "pool wait p99 > 100ms 5분 지속 → P2 / pool exhaustion (active = max) > 1분 → P1" - # 출처: feature-metrics-alerting-contract — "hikaricp.connections.acquire{outcome='timeout'} p99 > 100ms" + # source: feature-metrics-alerting-contract — "hikaricp.connections.acquire{outcome='timeout'} p99 > 100ms" - name: hikaricp.connections.acquire type: timer unit: seconds @@ -175,7 +175,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-persistence-failure-baseline — 범위 안 "Hikari metric 노출 기준" + Hikari Alert Threshold + # source: feature-persistence-failure-baseline — In scope "Hikari metric 노출 기준" + Hikari Alert Threshold - name: hikaricp.connections.usage type: timer unit: seconds @@ -191,7 +191,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-persistence-failure-baseline — 범위 안 "Hikari metric 노출 기준" + # source: feature-persistence-failure-baseline — In scope "Hikari metric 노출 기준" - name: hikaricp.connections.active type: gauge unit: total @@ -207,7 +207,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — Histogram Buckets/Percentile "DB query: same" + # source: feature-metrics-alerting-contract — Histogram Buckets/Percentile "DB query: same" - name: db.query.duration type: timer unit: seconds @@ -228,7 +228,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === 백그라운드 작업 / 비동기 executor === - # 출처: feature-background-job-async-contract — Decisionized Work Items "saturation policy" + # source: feature-background-job-async-contract — Decisionized Work Items "saturation policy" # "AbortPolicy default (core=10, max=50, queue=200)" - name: executor.saturation type: gauge @@ -246,7 +246,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-background-job-async-contract — 결정한 작업 항목 "saturation | bounded executor + rejection log" + # source: feature-background-job-async-contract — Decisionized Work Items "saturation | bounded executor + rejection log" - name: executor.rejected.total type: counter unit: total @@ -265,7 +265,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-background-job-async-contract — 결정한 작업 항목 "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted" + # source: feature-background-job-async-contract — Decisionized Work Items "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted" - name: job.retry.total type: counter unit: total @@ -284,7 +284,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-background-job-async-contract — "DLQ after exhausted attempts" + # source: feature-background-job-async-contract — "DLQ after exhausted attempts" - name: job.dlq.total type: counter unit: total @@ -301,7 +301,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === Distributed lock === - # 출처: feature-distributed-lock-contract D7 — "metric lock.acquisition (tag: outcome = + # source: feature-distributed-lock-contract D7 — "metric lock.acquisition (tag: outcome = # acquired/timeout/error) — 신규 제안" / D5 — try-lock + 유한 waitTime + lease(TTL). 분산 # 상호배제(distributedLockProvider) 획득 시도 결과를 센다. key 는 tag 로 넣지 않는다 # (무한 cardinality — 위 전역 금지 규칙). timeout outcome 은 LOCK_ACQUISITION_TIMEOUT 발생과 1:1. @@ -321,7 +321,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-distributed-lock-contract §Edge / D5 (SI-LOCK-C5) — "lease 만료 후 unlock → + # source: feature-distributed-lock-contract §Edge / D5 (SI-LOCK-C5) — "lease 만료 후 unlock → # ConcurrentModificationException — 삼킴 금지, 로그+metric 후 정상 흐름 복귀". lease가 이미 만료된 뒤의 # 해제를 센다(보유자가 close()를 부르기 전에 다른 인스턴스가 JdbcLock 행을 회수함). 0이 아닌 비율이 # 이어지면 lease TTL이 실제 임계 구역 시간보다 짧다는 뜻이다 — APP/lease TTL을 늘리거나 보호하는 일을 @@ -340,7 +340,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === Outbox 발행기 === - # 출처: feature-domain-event-outbox-contract — Outbox Defaults + # source: feature-domain-event-outbox-contract — Outbox Defaults # "DB outbox table with eventId, aggregateId, eventType, payload, occurredAt, status, attemptCount, nextAttemptAt" - name: outbox.publisher.published.total type: counter @@ -363,7 +363,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-domain-event-outbox-contract — 행 상태 enum PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD + # source: feature-domain-event-outbox-contract — 행 상태 enum PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD - name: outbox.publisher.lag type: gauge unit: seconds @@ -380,7 +380,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-domain-event-outbox-contract — row status enum + Outbox Defaults attemptCount + # source: feature-domain-event-outbox-contract — row status enum + Outbox Defaults attemptCount # PARKED: 끝없이 재시도되던 행을 운영자가 붙잡아 둠 (re-review 2026-11-03 RR-05-03). - name: outbox.pending.size type: gauge @@ -401,7 +401,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: re-review 2026-11-03 RR-05-03 — 지금의 거절과 답이 없는 발행은 끝없이 재시도된다. 이 둘은 + # source: re-review 2026-11-03 RR-05-03 — 지금의 거절과 답이 없는 발행은 끝없이 재시도된다. 이 둘은 # 10번 이상 미뤄진 FAILED 행을 세고(OutboxMetrics LONG_RETRY_DEFERRED_CLAIMS, publish-failed runbook §4.1 # 조회), 그중 가장 오래된 것의 나이를 잰다. - name: outbox.retry.long.size @@ -431,7 +431,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === 캐시 === - # 출처: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default" + # source: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default" - name: cache.gets.total type: counter unit: total @@ -450,7 +450,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-cache-consistency-contract — "invalidation = after-commit only", "invalidation 실패가 조용히 무시되면 실패" + # source: feature-cache-consistency-contract — "invalidation = after-commit only", "invalidation 실패가 조용히 무시되면 실패" - name: cache.invalidations.total type: counter unit: total @@ -469,7 +469,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: redis-production-capability — 크기가 정해진 캐시 전용 L1 (선택) + # source: redis-production-capability — 크기가 정해진 캐시 전용 L1 (선택) - name: cache.local.requests.total type: counter unit: total @@ -488,7 +488,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: redis-production-capability — 로컬 stale 나이 상한 + # source: redis-production-capability — 로컬 stale 나이 상한 - name: cache.local.entry.age.seconds type: timer unit: seconds @@ -504,7 +504,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: redis-production-capability — 크기가 정해진 무효화와 세대 대조(reconciliation) + # source: redis-production-capability — 크기가 정해진 무효화와 세대 대조(reconciliation) - name: cache.local.maintenance.total type: counter unit: total @@ -538,7 +538,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === Redis 연결 lane === - # 출처: review 2026-11-03 RR-04-02 — 캐시의 조건부 쓰기는 자기 lane(CACHE_SCRIPT)을 받았다. 캐시 채우기가 + # source: review 2026-11-03 RR-04-02 — 캐시의 조건부 쓰기는 자기 lane(CACHE_SCRIPT)을 받았다. 캐시 채우기가 # idempotency·rate limiting·lease의 SCRIPT lane 연결을 가져가지 못하게 하려는 것이다. 이 meter들이 lane마다 # 그것이 지켜지는지 보여 준다. redis-runtime RedisLaneMetrics가 RedisRuntimeOwner가 pool로 가진 모든 lane에 # 대해, context에 MeterRegistry가 있을 때만 낸다. 모든 counter 계열은 기동 때 0으로 등록한다. @@ -659,7 +659,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === 로그 appender === - # 출처: feature-log-management-contract — Sampling Policy (final) + # source: feature-log-management-contract — Sampling Policy (final) # "async appender overflow default: drop oldest INFO/DEBUG with counter metric (log.appender.dropped.total)" - name: log.appender.dropped.total type: counter @@ -680,7 +680,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === 분산 추적 === - # 출처: feature-distributed-tracing-contract — decisions + # source: feature-distributed-tracing-contract — decisions # "trace sampling rate default = prod 1%, dev/local 100%; shipped runtime profiles are local|dev|prod" - name: tracing.sampling.rate type: gauge @@ -699,7 +699,7 @@ metrics: required_test: contract-verification:metrics-cardinality # === JVM 기본 === - # 출처: feature-metrics-alerting-contract — In scope "JVM/process metric" + # source: feature-metrics-alerting-contract — In scope "JVM/process metric" - name: jvm.memory.used type: gauge unit: bytes @@ -718,7 +718,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — 범위 안 \"JVM/process metric\" + # source: feature-metrics-alerting-contract — In scope "JVM/process metric" - name: jvm.gc.pause type: timer unit: seconds @@ -736,7 +736,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — 범위 안 \"JVM/process metric\" + # source: feature-metrics-alerting-contract — In scope "JVM/process metric" - name: jvm.threads.live type: gauge unit: total @@ -750,7 +750,7 @@ metrics: compatibility_impact: additive required_test: contract-verification:metrics-cardinality - # 출처: feature-metrics-alerting-contract — 범위 안 \"JVM/process metric\" (process uptime) + # source: feature-metrics-alerting-contract — In scope "JVM/process metric" (process uptime) - name: process.uptime type: gauge unit: seconds diff --git a/docs/registries/secrets-classification.yaml b/docs/registries/secrets-classification.yaml index 860b33f3..af342bc9 100644 --- a/docs/registries/secrets-classification.yaml +++ b/docs/registries/secrets-classification.yaml @@ -26,7 +26,7 @@ secrets: # === 3등급: secret (진짜 비밀 — password/private-key/HMAC-salt) === - name: APP_DATASOURCE_PASSWORD - # 출처: feature-secrets-config-source-contract 2026-05-22 + # source: feature-secrets-config-source-contract 2026-05-22 # "DB credential은 dual-bind 60s" + "__LOCAL_DEV_FAKE_DB_PASSWORD" 예시 classification: secret source: secret-manager @@ -42,7 +42,7 @@ secrets: required_test: secrets-contract:db-password-no-leak-in-actuator - name: SPRING_MAIL_PASSWORD - # 출처: notification/fileserver techlead review H2 — Spring Mail이 직접 읽는 자격 증명이라 APP_* 별칭을 두지 + # source: notification/fileserver techlead review H2 — Spring Mail이 직접 읽는 자격 증명이라 APP_* 별칭을 두지 # 않고 일부러 SPRING_* 이름을 유지한다. classification: secret source: secret-manager @@ -56,7 +56,7 @@ secrets: required_test: secrets-contract:smtp-password-no-leak - name: APP_CACHE_REDIS_PASSWORD - # 출처: feature-secrets-config-source-contract 2026-05-22 + # source: feature-secrets-config-source-contract 2026-05-22 # 3등급 분류 "secret" + feature-integration-adapter-templates "Redis | disabled optional module" # (Redis를 켜고 인증을 쓰면 secret으로 분류) classification: secret @@ -206,7 +206,7 @@ secrets: required_test: secrets-contract:lease-redis-key-hmac-no-leak - name: APP_PRIVACY_PSEUDONYMIZATION_SALT - # 출처: feature-data-retention-privacy-contract 2026-05-22 + # source: feature-data-retention-privacy-contract 2026-05-22 # "pseudonymization key = HMAC-SHA-256 with rotating salt. salt rotation interval = 90일. # rotation 시 old salt 90일 retain (lookup 가능)." # + feature-tenant-context-policy "tenant identifier는 raw PII가 아니어야 하며 ... pseudonymized id" @@ -328,7 +328,7 @@ secrets: required_test: secrets-contract:notification-callback-fingerprint-hmac-no-leak - name: APP_NOTIFICATION_SLACK_WEBHOOK_URL - # 출처: feature-integration-adapter-templates 2026-05-22 + # source: feature-integration-adapter-templates 2026-05-22 # "Slack | disabled optional module | notification failure policy" # Slack webhook URL은 token을 path에 포함하므로 sensitive-config (URL 형태이지만 secret과 동급 취급) classification: sensitive-config @@ -342,7 +342,7 @@ secrets: required_test: secrets-contract:slack-webhook-no-leak - name: APP_SECURITY_GOOGLE_OAUTH_CLIENT_ID - # 출처: feature-secrets-config-source-contract 2026-05-22 + # source: feature-secrets-config-source-contract 2026-05-22 # "sensitive-config" 등급 (id이지만 노출 제한) # + feature-integration-adapter-templates "Google Email | disabled optional module" classification: sensitive-config @@ -356,7 +356,7 @@ secrets: required_test: secrets-contract:google-oauth-client-id-masked - name: APP_DATASOURCE_USERNAME - # 출처: feature-secrets-config-source-contract 2026-05-22 — "sensitive-config" 등급 + # source: feature-secrets-config-source-contract 2026-05-22 — "sensitive-config" 등급 # (DB user는 password와 함께 노출되면 위험하므로 sensitive-config) classification: sensitive-config source: mounted-env @@ -382,7 +382,7 @@ secrets: required_test: secrets-contract:mongodb-uri-masked - name: APP_DATASOURCE_URL - # 출처: feature-secrets-config-source-contract 2026-05-22 — JDBC URL은 host/db 포함하므로 sensitive-config + # source: feature-secrets-config-source-contract 2026-05-22 — JDBC URL은 host/db 포함하므로 sensitive-config # (env-keys.yaml에서는 public-config 처리; 본 파일에서는 노출 통제 관점에서 sensitive로 재분류 — masking 기준 명시 목적) classification: sensitive-config source: mounted-env @@ -397,7 +397,7 @@ secrets: # === 1등급: public-config (참조만 — 행 전체는 env-keys.yaml에 있다) === - name: APP_PROFILE - # 출처: feature-env-driven-runtime-configuration — public-config 등급 참조 + # source: feature-env-driven-runtime-configuration — public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -405,7 +405,7 @@ secrets: reference: env-keys.yaml#APP_PROFILE - name: APP_NAME - # 출처: feature-env-driven-runtime-configuration — public-config 등급 참조 + # source: feature-env-driven-runtime-configuration — public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -413,7 +413,7 @@ secrets: reference: env-keys.yaml#APP_NAME - name: SERVER_PORT - # 출처: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조 + # source: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -421,7 +421,7 @@ secrets: reference: env-keys.yaml#SERVER_PORT - name: SPRING_PROFILES_ACTIVE - # 출처: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조 + # source: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-env-driven-runtime-configuration @@ -429,7 +429,7 @@ secrets: reference: env-keys.yaml#SPRING_PROFILES_ACTIVE - name: OTEL_EXPORTER_OTLP_ENDPOINT - # 출처: feature-distributed-tracing-contract — public-config 등급 참조 + # source: feature-distributed-tracing-contract — public-config 등급 참조 classification: public-config source: application-yml owner_branch: feature-distributed-tracing-contract