Merge branch 'claude/d2a-entry-docs-12a342' — 루트 README·문서 지도·검사 K5·K6·레지스트리 설명 칸

This commit is contained in:
DongHyeonka
2026-11-07 18:06:49 +09:00
24 changed files with 1483 additions and 1259 deletions
+67 -67
View File
@@ -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 검사를
유지한다.
+12 -13
View File
@@ -1,18 +1,17 @@
## What changed and why
## 무엇을 왜 바꿨나
<!-- Summarize the behavior, architecture boundary, or policy being changed. -->
<!-- 바꾼 동작, 아키텍처 경계, 정책을 요약한다. -->
## Verification
## 검증
- [ ] I ran focused `:<changed-leaf>: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.
- [ ] 바꾼 모듈마다 `:<changed-leaf>:check`를 돌렸다.
- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다.
- [ ] registry에 없는 production 모듈 의존을 더하지 않았다.
- [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다.
- [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다.
- [ ] 간헐 실패 테스트는 격리하지 않고 고치거나 지웠다(격리 레지스트리는 없다).
- [ ] 돌리지 못한 검사와 그 때문에 남은 위험을 적었다.
## Compatibility and operations
## 호환성과 운영
<!-- Note public API/config changes, migration needs, rollout/rollback impact, and external blockers. -->
<!-- 공개 API·설정 변경, 마이그레이션 필요 여부, 배포·되돌리기 영향, 외부 차단 요인을 적는다. -->
+13
View File
@@ -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$
+1 -1
View File
@@ -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가 실제로 실행하는
+89 -115
View File
@@ -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 <gradle-path>: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 <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다.
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) 양식을 채운다.
+25 -29
View File
@@ -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는 아무도
시험하지 않는 두 번째 입구가 된다.
+55 -49
View File
@@ -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://…/<VAR>` 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://…/<VAR>` 자격 증명 참조가 가리키는 변수
코드에 있는 참조(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://<account>@environment/<variable>` 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://<account>@environment/<variable>` 참조를 거치고, 그 변수가 위 fixture 비밀번호를 가진다.
여기의 모든 계정이 `~prod:*`로 묶여 있어서, lane은 Redis namespace 환경을 `prod`로 두고 돈다.
`scripts/verify-compose-profile-contracts.sh`가 Redis lane마다 참조·비밀번호·namespace를 이 파일의 계정 줄과
비교한다. 그래서 lane을 고치지 않고 여기의 비밀번호나 key 패턴만 바꾸면, lane의 첫 명령이 아니라 그 검사가
실패한다.
+88 -35
View File
@@ -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`에 더한다.
## 여기에 없는 것
+1 -1
View File
@@ -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 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
-> 임시 디렉터리 삭제
```
+15 -15
View File
@@ -3,19 +3,19 @@
# 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:
@@ -46,7 +46,7 @@ capabilities:
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 단위)"
# "SENSITIVE_READ marker = registry-managed metadata table (entity FQN + field name 단위)"
- name: SENSITIVE_READ
scope: use_case_method
enforcement: archunit
@@ -59,7 +59,7 @@ capabilities:
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로 충분"
# "BULK_WRITE threshold = N > 100 또는 batch size > 100. 미만은 일반 WRITE_REPOSITORY로 충분"
- name: BULK_WRITE
scope: use_case_method
enforcement: archunit
@@ -72,7 +72,7 @@ capabilities:
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로 충족하지 않음"
# "TRANSACTION_REQUIRED는 application-port branch의 TransactionPort contract와 연결되어야 하며 Spring @Transactional 직접 import로 충족하지 않음"
# source: feature-application-port-usecase-contract — TransactionPort Contract
- name: TRANSACTION_REQUIRED
scope: use_case_method
@@ -86,7 +86,7 @@ capabilities:
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(필요)"
# "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가 없으면 실패"
- name: EXTERNAL_OUTBOUND_ALLOWED
scope: use_case_method
@@ -100,7 +100,7 @@ capabilities:
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)"
# "CROSS_TENANT_ADMIN capability를 capability vocabulary에 추가 (tenant branch feature-tenant-context-policy와 cross-link)"
- name: CROSS_TENANT_ADMIN
scope: use_case_method
enforcement: archunit
File diff suppressed because it is too large Load Diff
+31 -33
View File
@@ -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 면제 가능.
@@ -217,7 +217,7 @@ 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"
@@ -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)
# 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
# source: review-followup P15 (S2-lead-4) — JPA COMPLETION_UNKNOWN (40003 / commit-phase connection loss)
# 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)
# ============================================================
# source: feature-rate-limit-idempotency-contract — rate limit response/log 기준 / Retry-After header 기준 (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
@@ -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
# source: review-followup P15 (X2-P2-2a) — IdempotencyExecutor가 동작 전에 닫힌 채 거절한다(fail-closed)
- code: IDEMPOTENCY_UNAVAILABLE
category: TRANSIENT_DEPENDENCY
http_status: 503
@@ -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
# source: review-followup P15 (X2-P2-2a) — replay가 외부 효과가 일어났는지 정할 수 없다
- code: IDEMPOTENCY_RECOVERY_REQUIRED
category: DATA_INTEGRITY
http_status: 500
@@ -452,18 +452,17 @@ 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으로 처리되면 실패"
# ============================================================
# 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 의무"
- code: METHOD_NOT_ALLOWED
@@ -518,9 +517,8 @@ errors:
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).
# 참고: 강제는 Tomcat·gateway가 한다(Spring dispatch 전에 거절). 이 행과 코드는 상태 대응 일관성을 위해
# 있다. 끝에서 끝까지의 414 계약 테스트는 `planned`다 (gateway/Tomcat maxHttpHeaderSize 8KB 경계).
- code: URI_TOO_LONG
category: VALIDATION
http_status: 414
@@ -560,14 +558,14 @@ 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)
# source: 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로 처리되면 실패"
# ============================================================
# 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로 분류되어야 함"
@@ -679,7 +677,7 @@ 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 없이 발생하면 실패"
@@ -722,7 +720,7 @@ 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 =
@@ -746,7 +744,7 @@ 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"
@@ -764,7 +762,7 @@ errors:
# source: 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가 노출되면 실패"
@@ -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
+7 -7
View File
@@ -2,11 +2,11 @@
# 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
@@ -162,7 +162,7 @@ headers:
required_test: contract-verification:envelope-headers
# source: feature-security-operational-baseline.md L66
# "JWT Resource Server를 baseline security model로 둠" (Bearer token via Authorization header)
# "JWT Resource Server를 baseline security model로 둠" (Authorization 헤더의 Bearer 토큰)
- name: Authorization
direction: inbound
type: bearer-token
@@ -176,7 +176,7 @@ headers:
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
# 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server의 표준 challenge 헤더
- name: WWW-Authenticate
direction: outbound
type: string
+8 -8
View File
@@ -3,10 +3,10 @@
# 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
@@ -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)
# 참고: application-port-usecase-contract / 업무 쪽 operation 식별자 (uri_template과 따로 application이 정한다)
- key: operation
type: string
source: application_set
@@ -134,7 +134,7 @@ mdc_keys:
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
# 참고: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — 값 개수가 정해져 있다
- key: status
type: numeric
source: inbound_filter
@@ -163,7 +163,7 @@ mdc_keys:
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
# 참고: metrics L88 "dependency_name | 50" — 값 개수가 정해져 있다
- key: dependency_name
type: string
source: application_set
@@ -206,7 +206,7 @@ mdc_keys:
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
# 참고: metrics L89 "error_code | 100 — error registry row 상한과 정합" — 값 개수가 정해져 있다
- key: error_code
type: string
source: application_set
+104 -104
View File
@@ -3,17 +3,19 @@
# 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) ===
# === HTTP 서버 (inbound) ===
# 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
@@ -32,9 +34,9 @@ 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
@@ -55,15 +57,15 @@ 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) ===
# === HTTP client (outbound 의존 대상) ===
# source: 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로 허용"
@@ -82,16 +84,16 @@ 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"
# "retry/circuit breaker 기본 라이브러리는 Resilience4j"
# source: feature-metrics-alerting-contract — "retry/CB minimum: resilience4j.retry.calls{outcome}"
- name: resilience4j.retry.calls
type: counter
@@ -105,7 +107,7 @@ 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
@@ -124,8 +126,8 @@ 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
@@ -144,7 +146,7 @@ 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
@@ -166,8 +168,8 @@ 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
@@ -183,7 +185,7 @@ 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
@@ -199,7 +201,7 @@ 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
@@ -219,13 +221,13 @@ 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 ===
# === 백그라운드 작업 / 비동기 executor ===
# source: feature-background-job-async-contract — Decisionized Work Items "saturation policy"
# "AbortPolicy default (core=10, max=50, queue=200)"
- name: executor.saturation
@@ -237,8 +239,8 @@ 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
@@ -257,7 +259,7 @@ 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
@@ -276,7 +278,7 @@ 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
@@ -292,7 +294,7 @@ 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
@@ -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.
# ConcurrentModificationException — 삼킴 금지, 로그+metric 후 정상 흐름 복귀". lease가 이미 만료된 뒤의
# 해제를 센다(보유자가 close()를 부르기 전에 다른 인스턴스가 JdbcLock 행을 회수함). 0이 아닌 비율이
# 이어지면 lease TTL이 실제 임계 구역 시간보다 짧다는 뜻이다 — APP/lease TTL을 늘리거나 보호하는 일을
# 줄인다. 획득 결과가 아니라서 lock.acquisition과 다른 counter다.
- name: lock.lease.expired
type: counter
unit: total
@@ -332,13 +333,13 @@ 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 ===
# === Outbox 발행기 ===
# 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
@@ -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
# source: 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).
# 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.
# 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
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,7 +430,7 @@ metrics:
compatibility_impact: additive
required_test: contract-verification:metrics-cardinality
# === Cache ===
# === 캐시 ===
# source: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default"
- name: cache.gets.total
type: counter
@@ -443,7 +444,7 @@ 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
@@ -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
# source: 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
# source: 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
# source: 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 ===
# 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으로 등록한다.
- 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,19 +646,19 @@ 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 ===
# === 로그 appender ===
# 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
@@ -673,13 +673,13 @@ 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
# "trace sampling rate default = prod 1%, dev/local 100%; shipped runtime profiles are local|dev|prod"
- name: tracing.sampling.rate
@@ -692,13 +692,13 @@ 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 ===
# === JVM 기본 ===
# source: feature-metrics-alerting-contract — In scope "JVM/process metric"
- name: jvm.memory.used
type: gauge
@@ -712,7 +712,7 @@ 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
@@ -730,7 +730,7 @@ 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
@@ -744,7 +744,7 @@ 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
@@ -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
+14 -14
View File
@@ -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)은 구현하지 않았다
+63 -69
View File
@@ -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://…/<VAR>` 참조가
# 가리키는 변수. 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
# "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.
# source: notification/fileserver techlead review H2 — Spring Mail이 직접 읽는 자격 증명이라 APP_* 별칭을 두지
# 않고 일부러 SPRING_* 이름을 유지한다.
classification: secret
source: secret-manager
rotation_policy: restart-only
@@ -56,13 +57,13 @@ secrets:
- 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으로 분류)
# 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
@@ -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
@@ -349,7 +343,7 @@ secrets:
- name: APP_SECURITY_GOOGLE_OAUTH_CLIENT_ID
# source: feature-secrets-config-source-contract 2026-05-22
# "sensitive-config" tier (id이지만 노출 제한)
# "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
# source: 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
@@ -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
# source: 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
# source: 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
# source: 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
# source: 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
# source: feature-distributed-tracing-contract — public-config 등급 참조
classification: public-config
source: application-yml
owner_branch: feature-distributed-tracing-contract
+1 -1
View File
@@ -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절).
-11
View File
@@ -5,10 +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
language docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md
language docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md
@@ -170,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
@@ -180,13 +175,8 @@ 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
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
@@ -194,7 +184,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
+140 -6
View File
@@ -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]:
+1
View File
@@ -47,6 +47,7 @@ ROOT_ALLOWED = {
# 파일
".gitattributes": "Git 설정",
".gitignore": "Git 설정",
".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다",
".tool-versions": "JDK 버전 고정",
".trivyignore.yaml": "취약점 검사 예외",
"AGENTS.md": "규칙 정본",
+121
View File
@@ -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)
+29 -29
View File
@@ -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 <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 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 포트를 둡니다.
@@ -137,8 +137,8 @@ class DeveloperExperienceContractTest {
assertThat(readme)
.contains("scripts/bootstrap-local.sh")
.contains("GET /api/healthcheck")
.contains("## 퀵스타트")
.contains("첫 실행 진입점은 하나입니다.");
.contains("## 시작하기")
.contains("첫 실행 진입점은 하나다.");
}
@Test