Merge branch 'claude/d2a-entry-docs-12a342' — 루트 README·문서 지도·검사 K5·K6·레지스트리 설명 칸
This commit is contained in:
@@ -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 검사를
|
||||
유지한다.
|
||||
|
||||
@@ -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·설정 변경, 마이그레이션 필요 여부, 배포·되돌리기 영향, 외부 차단 요인을 적는다. -->
|
||||
|
||||
@@ -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$
|
||||
@@ -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가 실제로 실행하는
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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`에 더한다.
|
||||
|
||||
## 여기에 없는 것
|
||||
|
||||
|
||||
@@ -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 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
|
||||
-> 임시 디렉터리 삭제
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
+596
-650
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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,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)은 구현하지 않았다
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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절).
|
||||
|
||||
@@ -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
@@ -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]:
|
||||
|
||||
@@ -47,6 +47,7 @@ ROOT_ALLOWED = {
|
||||
# 파일
|
||||
".gitattributes": "Git 설정",
|
||||
".gitignore": "Git 설정",
|
||||
".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다",
|
||||
".tool-versions": "JDK 버전 고정",
|
||||
".trivyignore.yaml": "취약점 검사 예외",
|
||||
"AGENTS.md": "규칙 정본",
|
||||
|
||||
@@ -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
@@ -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 포트를 둡니다.
|
||||
|
||||
+2
-2
@@ -137,8 +137,8 @@ class DeveloperExperienceContractTest {
|
||||
assertThat(readme)
|
||||
.contains("scripts/bootstrap-local.sh")
|
||||
.contains("GET /api/healthcheck")
|
||||
.contains("## 퀵스타트")
|
||||
.contains("첫 실행 진입점은 하나입니다.");
|
||||
.contains("## 시작하기")
|
||||
.contains("첫 실행 진입점은 하나다.");
|
||||
}
|
||||
|
||||
@Test
|
||||
|
||||
Reference in New Issue
Block a user