Files
clean-architecture-backend-…/docs/registries/headers.yaml
T
DongHyeonka 05e2145d22 docs(registries): 레지스트리 yaml의 설명 칸과 주석을 한국어로 옮긴다
문제: 소유자 결정(2026-11-07, design-docs `repo-structure/README.md` 3.2절)은 레지스트리
yaml의 설명 칸을 번역하라고 한다. 지금 값 칸 중 영어 산문은 env-keys `required_when`
7개, metrics `alert_severity_thresholds` 51개, object-storage-readiness `limitations`
15개이고, 주석은 약 940줄이 영어다. 주석 하나는 없는 파일
`docs/notification/configuration.md`를 가리킨다(있는 것은
`configuration-reference.md`).

고른 방법:
- 값 칸: 뜻을 그대로 옮기고 속성 이름·지표 이름·연산자·기간(5m, 1h)·식별자는 원문으로
  둔다. `required_when`의 `<속성>=<값>` 꼴(공백 없음)은 `RequiredWhenIsEnforcedTest`가
  기계로 읽으므로 그대로 두고, 공백이 든 설명 꼴만 옮긴다. 옮긴 값도 공백을 가져 그
  테스트가 계속 건너뛴다.
- 주석: 파일 머리의 설명 블록과 행마다의 설명·출처 주석을 옮긴다. `# source:`는
  `# 출처:`로 바꾸고, 설계 문서에서 따온 인용("...")은 원문으로 둔다.
- 그대로 둔 것: `RegistryGovernanceCatalog`가 글자 그대로 비교하는 머리 줄
  (`# Schema owner: ...`, object-storage-readiness 머리 넷)과 `# Registry:` 등 메타
  줄.
- 없는 문서 경로는 `docs/notification/configuration-reference.md`로 고친다.

이 칸을 읽는 테스트(먼저 찾음):
- `RegistryGovernanceCatalog`(ContractRegistrySchemaGovernanceTest): 머리 주석 줄을 글자
  그대로 본다 — 해당 줄은 바꾸지 않았다.
- `RequiredWhenIsEnforcedTest`(redis-runtime): 공백 없는 `required_when`만 조건으로 쓴다.
- `SecretsClassificationRegistryTest`: `required_when`이 null인지만 본다.
- `MetricsAlertingContractTest`: 경보 키가 `AlertSeverity`로 풀리는지와 값이 비어 있지
  않은지만 본다.
- `ObjectStorageReadinessRegistryTest`: `limitations`가 비어 있지 않은지만 본다.
- `NotificationModeSsotTest`: `name: APP_NOTIFICATION_PLATFORM_MODE` 뒤 첫 `default: `를
  찾는다 — 옮긴 주석에 `default: ` 글자를 넣지 않았다.

위험·한계: 행마다의 주석은 설계 문서 ID와 날짜를 그대로 둔다. 남은 영어는 인용과
식별자뿐이다.

검증: 바꾸기 전후 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 값 칸 말고는 같다(주석만
바꾼 파일은 완전히 같다). `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:24:54 +09:00

191 lines
6.9 KiB
YAML

# Registry: HTTP Headers
# Schema owner: feature-contract-registry-governance
# Last updated: 2026-05-22
#
# 표기 규칙
# - HTTP 헤더 이름: kebab-case (X-Request-Id, X-Correlation-Id)
# - W3C 표준 헤더: 소문자 (traceparent, tracestate)
# - mdc_key: snake_case (foundation이 정본)
# - envelope_meta_field: camelCase (envelope이 정본)
headers:
# 출처: feature-operational-error-observability-foundation.md L97
# "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id"
- name: X-Request-Id
direction: both
type: ulid
required: false
generated_if_missing: true
mdc_key: request_id
envelope_meta_field: requestId
owner_branch: feature-operational-error-observability-foundation
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
# 출처: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67
# "idempotency header 이름은 Idempotency-Key" / "기본 scope는 (authenticatedPrincipal, idempotencyKey, useCaseName)"
- name: Idempotency-Key
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-rate-limit-idempotency-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:idempotency-replay
# 출처: feature-rate-limit-idempotency-contract.md L85 / foundation L85
# "RATE_LIMIT | ... | 429 | true (Retry-After 이후)" / "retry-after 기준 없이 429를 반환하면 실패"
- name: Retry-After
direction: outbound
type: duration-seconds
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-rate-limit-idempotency-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
# 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
# app.rate-limit.enabled=true인 요청 경로에서만 생성되는 rate-limit 응답 표면
- name: X-RateLimit-Limit
direction: outbound
type: numeric
required: false
generated_if_missing: true
mdc_key: null
envelope_meta_field: null
owner_branch: feature-rate-limit-idempotency-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
# 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
- name: X-RateLimit-Remaining
direction: outbound
type: numeric
required: false
generated_if_missing: true
mdc_key: null
envelope_meta_field: null
owner_branch: feature-rate-limit-idempotency-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
# 출처: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
- name: X-RateLimit-Reset
direction: outbound
type: rfc3339-date
required: false
generated_if_missing: true
mdc_key: null
envelope_meta_field: null
owner_branch: feature-rate-limit-idempotency-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
# 출처: feature-api-compatibility-deprecation-contract.md L87
# "deprecation marker | OpenAPI deprecated: true + design record | response header optional"
- name: Deprecation
direction: outbound
type: http-date
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-api-compatibility-deprecation-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:deprecation-marker
# 출처: feature-api-compatibility-deprecation-contract.md L87
# "deprecation marker | OpenAPI deprecated: true + design record | response header optional" (RFC 8594 Sunset)
- name: Sunset
direction: outbound
type: http-date
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-api-compatibility-deprecation-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:deprecation-marker
# 출처: feature-distributed-tracing-contract.md L64, L85
# "propagation header는 W3C traceparent default" / "HTTP | traceparent, tracestate (W3C)"
- name: traceparent
direction: both
type: string
required: false
generated_if_missing: true
mdc_key: trace_id
envelope_meta_field: traceId
owner_branch: feature-distributed-tracing-contract
case_style: kebab
compatibility_impact: none
required_test: contract-verification:trace-propagation
# 출처: feature-distributed-tracing-contract.md L66, L85
# "propagation format = W3C traceparent + tracestate only. B3 propagation은 forbidden"
- name: tracestate
direction: both
type: comma-separated
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-distributed-tracing-contract
case_style: kebab
compatibility_impact: none
required_test: contract-verification:trace-propagation
# 출처: feature-operational-error-observability-foundation.md L100
# "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id"
- name: X-Correlation-Id
direction: both
type: ulid
required: false
generated_if_missing: true
mdc_key: correlation_id
envelope_meta_field: correlationId
owner_branch: feature-operational-error-observability-foundation
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
# 출처: feature-security-operational-baseline.md L66
# "JWT Resource Server를 baseline security model로 둠" (Authorization 헤더의 Bearer 토큰)
- name: Authorization
direction: inbound
type: bearer-token
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-security-operational-baseline
case_style: kebab
compatibility_impact: none
required_test: contract-verification:jwt-resource-server
# 출처: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ 판정 표)
# 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server의 표준 challenge 헤더
- name: WWW-Authenticate
direction: outbound
type: string
required: false
generated_if_missing: true
mdc_key: null
envelope_meta_field: null
owner_branch: feature-security-operational-baseline
case_style: kebab
compatibility_impact: none
required_test: contract-verification:jwt-resource-server