docs(src): src/README의 영어 제목과 코드와 다른 주장을 고친다
문제: `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(예외 줄 둘을 지움).
This commit is contained in:
@@ -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
|
||||
|
||||
+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 포트를 둡니다.
|
||||
|
||||
Reference in New Issue
Block a user