From 145ae00f90e110a4e874854b40d10c9c7a40b141 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH] =?UTF-8?q?docs(src):=20src/README=EC=9D=98=20=EC=98=81?= =?UTF-8?q?=EC=96=B4=20=EC=A0=9C=EB=AA=A9=EA=B3=BC=20=EC=BD=94=EB=93=9C?= =?UTF-8?q?=EC=99=80=20=EB=8B=A4=EB=A5=B8=20=EC=A3=BC=EC=9E=A5=EC=9D=84=20?= =?UTF-8?q?=EA=B3=A0=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `src/README.md`에 영어 제목(「Local bootstrap」「App identity」 등)과 영어 문장이 남아 있다. 지운 게이트 표 `.github/ci-gate-matrix.yml`과 검사기 `.github/scripts/verify-gate-matrix.sh`를 지금 있는 것처럼 인라인 코드로 적어 참조 검사의 예외 줄 둘이 남아 있다. 코드와 다른 주장도 둘이다. - `SPRING_PROFILES_ACTIVE`를 「보통 local | dev | stage | prod」라 한다. registry `allowed_values`와 `RuntimeEnvironment`는 local·dev·prod뿐이다. - 추적 샘플 비율 기본값에 「staging = 0.10」이 있다. `TracingSampleRateResolver`는 PROD 0.01, LOCAL·DEV 1.0만 안다. 고른 방법: 영어 제목과 문장을 한국어로 옮기고, 지운 두 파일 이야기는 「> 이력」 인용 블록으로 옮긴다. 두 주장은 코드에 맞춘다. 다른 문서가 이름으로 가리키는 「기능 추가 = 한 줄 + env」 제목은 그대로 둔다. 위험·한계: 문서 전체가 「~합니다」체다. 문체를 「~한다」로 바꾸는 일은 하지 않았다. 검증: `python3 scripts/check-docs.py` rc=0(예외 줄 둘을 지움). --- scripts/check-docs-exceptions.txt | 2 -- src/README.md | 58 +++++++++++++++---------------- 2 files changed, 29 insertions(+), 31 deletions(-) diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 1bff4f87..d384cec2 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -185,8 +185,6 @@ reference docs/mongodb/consumer-leaf-guide.md :adapter:outbound:persistence-note reference docs/web/http-contract.md docs/architecture/backend-api-and-server-state-contract.md reference docs/work/operate.md :a:test reference docs/work/operate.md :b:test -reference src/README.md .github/ci-gate-matrix.yml -reference src/README.md .github/scripts/verify-gate-matrix.sh # 숫자: 정본(src/gradle/libs.versions.toml, registry)이 정하는 값을 복사한 곳. 정본을 가리키게 고치면 지운다. number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 diff --git a/src/README.md b/src/README.md index d51064ec..f9fcbcff 100644 --- a/src/README.md +++ b/src/README.md @@ -44,7 +44,7 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 `verifyConfigurationPropertiesProcessor`(`ca.spring-config` convention plugin이 대체). 근거는 `docs/design/2026-09-16-verification-surface-reduction-design.md`. -### Local bootstrap +### 로컬 첫 실행 `scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 → app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰 @@ -54,7 +54,7 @@ DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`( env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 example/registry/shipped YAML을 함께 검사합니다. -### Traceable version + dependency locking +### 추적 가능한 버전과 의존성 잠금 - leaf version은 release version뿐입니다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`). revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙습니다. revision은 jar @@ -71,7 +71,7 @@ env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 - lock 갱신은 `./gradlew resolveAndLockAll --write-locks` 한 가지 명령으로 수행합니다. 이 task는 `--write-locks`가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 합니다. -### Reproducible archives (D10) +### 재현 가능한 아카이브 (D10) 모든 `AbstractArchiveTask`는 file timestamp 보존을 끄고, file order를 재현 가능하게 정렬하며, directory/file mode를 각각 `0755`/`0644`로 고정합니다. Java toolchain은 21이고 로컬·CI patch @@ -192,10 +192,10 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 소유합니다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체입니다. - `.github/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 `.github/scripts/verify-gate-matrix.sh` - (568줄)는 삭제했습니다. 그 표는 이미 두 그래프에 있는 정보의 세 번째 사본이었고, 검사기는 세 사본을 - 서로 같게 유지하는 일을 했습니다. 결과적으로 체크 하나를 추가하려면 Gradle · workflow · 표 · - 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했습니다. + > 이력: 게이트 표 `.github/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 그 검사기 + > `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했습니다. 그 표는 이미 두 그래프에 있는 정보의 + > 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했습니다. 결과적으로 체크 하나를 + > 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했습니다. - **워크플로.** `.github/workflows/ci-quality-gates.yml` 의 `release-gate` 잡이 모든 release-blocking 게이트의 fan-in(단일 required status check)입니다. included build 테스트는 경로 필터가 걸린 `build-logic.yml`이, main 단계(`mainCheck`)·configuration-cache·JPA candidate evidence는 @@ -211,13 +211,13 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 이 파일이 잡힙니다). 아래는 섹션별 키 설명입니다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동 필요)로 간주하세요. -### App identity +### 앱 이름과 profile - **`APP_NAME`** — `spring.application.name` 과 JSON 로그의 `app` 필드. 자유 문자열. -- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. 보통 `local` | `dev` | `stage` | `prod`. JSON +- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. `local` | `dev` | `prod` 중 정확히 하나입니다. JSON 로그의 `profile` 필드도 이 값을 씁니다. -### Runtime safety (기동 시 fail-fast 검사, D8) +### 런타임 안전 검사 (기동할 때 바로 실패시킨다, D8) - **`APP_SERVER_ERROR_INCLUDE_STACKTRACE` / `APP_SERVER_ERROR_INCLUDE_MESSAGE`** — 로컬 디버깅용. prod에서 `never`가 아니면 `ErrorDetailExposureSafetyValidator`가 기동을 막습니다(exit 71, @@ -226,7 +226,7 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, - **`APP_MULTI_INSTANCE_ENABLED`** — `true` 면 cross-instance `DistributedLockPort` (`distributedLockProvider`)가 조립돼 있어야 하며, 없으면 기동이 실패합니다(exit 72, `StartupSafetyValidator`). -- **`APP_RATE_LIMIT_ENABLED`** — provider-neutral edge rate-limit interceptor 활성화 +- **`APP_RATE_LIMIT_ENABLED`** — 제공자에 묶이지 않은 앞단 요청 수 제한(rate limit) interceptor를 켠다 (429 + `Retry-After` + `X-RateLimit-*` 응답). 기본값은 `false`이며, `true`로 바꿀 때는 `APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 합니다. 비인증 요청의 키는 `getRemoteAddr()` 입니다. 프록시 뒤라면 @@ -240,7 +240,7 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부합니다. 24h보다 올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올립니다. -### Async executor +### 비동기 executor `@Async` `ThreadPoolTaskExecutor` 풀 크기 설정입니다. @@ -313,14 +313,14 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle` `--lane `는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아닙니다. -### Optional integration adapters +### 선택형 연동 adapter Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니다. 모듈이 있으면 켜지고, 없으면 그 포트를 구현하는 bean이 아예 없습니다. 아래는 모듈을 고른 뒤 동작을 고르는 키입니다. - **`APP_CACHE_REDIS_ENABLED`** — deprecated(2026-11-30 제거 예정). 읽는 곳이 없고, 기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`입니다. -- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — canonical default semantic region 선택. +- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — 기본 캐시 영역(canonical default semantic region)의 제공자를 고른다. `disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구합니다. - **`APP_CACHE_REDIS_CLIENT_MODE`** — `managed`는 내장 Lettuce runtime, `external`은 프로젝트가 제공한 `RedisClient` bean을 사용합니다. @@ -334,11 +334,11 @@ Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니 - **`APP_MESSAGING_KAFKA_BROKERS`** — `host:port` CSV. Kafka 모듈을 고르면 필수. messaging platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 이 값을 씁니다. `spring.kafka.bootstrap-servers`는 읽지 않습니다. -- **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 provider enable flag. notification 플랫폼이 +- **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 제공자를 켜는 값. notification 플랫폼이 켜졌을 때 어떤 provider를 쓸지 고르는 값입니다. -- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 provider enable flag. 위와 같습니다. +- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 제공자를 켜는 값. 위와 같습니다. -### Outbound HTTP client +### 외부 HTTP 호출 (HTTP client) 현재 canonical activation은 다음 두 설정 트리만 사용합니다. @@ -366,7 +366,7 @@ app: timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider readiness를 증명하지 않습니다. -### Logging +### 로그 **Root / app 레벨** — 허용값은 모두 `TRACE` | `DEBUG` | `INFO` | `WARN` | `ERROR` | `OFF`. @@ -407,31 +407,31 @@ app: - **`APP_LOG_SAMPLING_RATE`** — `INFO` 이하 로그를 남길 확률. [0.0, 1.0] float. prod 는 `0.1`(10% 샘플링)이 권장, `WARN`/`ERROR` 는 항상 유지. `1.0` = 샘플링 없음(dev/local/staging 기본). -### Distributed tracing +### 분산 추적 - **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증합니다. - **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는 `WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성합니다(D4 disabled-fallback 보장). - **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float. - - per-profile 기본값(D6): prod = `0.01`, staging = `0.10`, dev/local = `1.0`. + - profile별 기본값(D6): prod = `0.01`, dev/local = `1.0`. - **결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix).** 빈 값이어야 per-profile resolver 의 기본값이 실제 tracer sampler 까지 도달합니다(`TracingSampleRateResolver` 가 SSOT). 값을 박으면 프로필별 기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채웁니다. -### Privacy: user_principal pseudonymization +### 개인정보: user_principal 가명화 - **`APP_PRIVACY_PSEUDONYMIZATION_SALT`** — secret 등급 HMAC-SHA-256 salt. `__LOCAL_DEV_` prefix 는 로컬 전용 sentinel 값이며, **prod 에서는 secret-manager 가 주입하는 실제 값**을 써야 합니다. -### Spring Boot bootstrap +### Spring Boot 기동 - **`SPRING_BANNER_MODE`** — `off` | `console` | `log`. - **`SPRING_MAIN_LAZY_INITIALIZATION`** — `true` 면 빈 생성을 첫 사용 시점까지 지연. - **`SPRING_MAIN_LOG_STARTUP_INFO`** — `true` 면 `Starting`/`Started` 로그 출력. - **`SPRING_THREADS_VIRTUAL_ENABLED`** — `true` 면 Tomcat 요청 처리에 Java 21 virtual threads 사용. -### Jackson — deserialization policy +### Jackson — 역직렬화 정책 모든 request DTO 는 Jackson 경계를 지납니다. 아래 4개 스위치는 잘못된 입력을 **조용히 강제 변환하지 않고 즉시 실패**하게 만듭니다. 개별 DTO 에 클래스 레벨 `@JsonIgnoreProperties(ignoreUnknown = true)` @@ -447,7 +447,7 @@ app: - **`..._READ_UNKNOWN_ENUM_VALUES_AS_NULL`** — `false`(Jackson 기본 유지): 모르는 enum 값이 조용히 `null` 이 되지 않고 throw 되어 `VALIDATION_FAILED` 로 드러나게 합니다. -### Jackson — serialization policy +### Jackson — 직렬화 정책 응답 생성 쪽 정책입니다. 현재 Jackson/Spring Boot 기본값과 같지만 **명시적으로 못박아**, 미래에 Spring Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니다(`spring.mvc.problemdetails.enabled=false` @@ -463,7 +463,7 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니 금지합니다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둡니다(공개/금융 API 는 string, 내부 API 는 number+plain). -### Server / Tomcat +### 서버 / Tomcat - **`APP_SERVER_PORT`** — 1~65535 정수. - **`APP_SERVER_SHUTDOWN`** — `graceful` | `immediate`. @@ -482,12 +482,12 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니 - **`APP_SERVER_ERROR_INCLUDE_STACKTRACE`** — `always` | `never` | `on_param`. - **`APP_SERVER_ERROR_INCLUDE_MESSAGE`** — `always` | `never` | `on_param`. -### Presentation +### 표현 계층 (presentation) - **`PRESENTATION_API_BASE_PATH`** — 모든 controller 앞에 붙는 leading-slash 경로(예: `/api` | `/v1` | `""`). -### Auth (OIDC resource server) +### 인증 (OIDC resource server) - **`APP_SECURITY_JWT_ISSUER`** — OIDC issuer URI(Keycloak realm, Auth0 tenant 등). **필수** — 없으면 기동 실패. 예: `https://keycloak.example.com/realms/ca-skeleton`. @@ -547,7 +547,7 @@ docker compose up -d --wait db 스위치입니다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 `h2` 이거나 datasource URL 이 `jdbc:h2:` 이면 `PersistenceVendorProdSafetyValidator` 가 기동을 거부합니다(env 로 덮어써도 동일). -### Database (Postgres) +### 데이터베이스 (PostgreSQL) - **`APP_DATASOURCE_URL`** — JDBC URL(예: `jdbc:postgresql://host:5432/dbname`). `dev`·`prod` 에서 쓰이며, 커밋된 기본값 `jdbc:postgresql://localhost:5433/ca_skeleton` 은 위 compose `db` 서비스의 @@ -570,7 +570,7 @@ docker compose up -d --wait db - **`APP_DATASOURCE_POOL_MAX_LIFETIME`** — 연결의 최대 수명(ms). broker timeout 전에 rotate 하도록 설정합니다. -### Management / Actuator +### 관리 포트 / Actuator - **결정 — management 포트 분리.** actuator 엔드포인트를 앱 API 와 **같은 소켓에 노출하지 않으려고** 별도 management 포트를 둡니다.