Commit Graph
9 Commits
Author SHA1 Message Date
DongHyeonka 354b7fc959 fix(observability)!: 지표·MDC·헤더 registry를 코드가 실제로 내는 것과 맞춘다
pr / done (pull_request) Canceled after 0s
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.

- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
  (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
  상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
  Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
  생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
  다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
  상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
  집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
  방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
  graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
  이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
  SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.

위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.

검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.

Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
  fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
  CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
2026-11-13 13:12:27 +09:00
DongHyeonka ad859ca3a6 docs(registries): 출처 줄의 꼬리표와 기록 절 이름을 원문으로 되돌린다
문제: 앞 커밋이 레지스트리 주석의 `# source:`를 `# 출처:`로 바꾸고, 출처 줄 안의 기록 절
이름(「In scope」「Decisionized Work Items」「decisions」「Exposure Policy」「AuthN/AuthZ
Decision Matrix」)까지 한국어로 옮겼다. 출처 줄은 기록 이름·날짜·절 이름으로 원문을
찾아가는 줄이라, 옮기면 그 기록에서 같은 이름을 찾을 수 없다. 또 metrics.yaml 주석 세 줄에
변환 실수로 `\"`(백슬래시가 붙은 따옴표)가 들어갔다.

고른 방법: 총괄 기준(2026-11-07)대로 나눈다.
- 원문으로 둔다: 출처 줄의 꼬리표 `source:`, 기록 이름·날짜·절 이름, 따옴표 인용.
- 한국어로 둔다: 같은 줄의 나머지 설명, 행마다의 이유·조건·주의 산문, 값 칸, 파일 머리 블록.
- `\"`는 `"`로 고친다.

위험·한계: 출처가 가리키는 `feature-*` 계약 기록 24개는 저장소 어디에도(이력 포함) 그 이름의
파일이 없다. `docs/design/`에 있는 것은 `five-adapter-runtime-remediation`과
`redis-production-capability` 둘이고, 파일 이름에 날짜와 `-design`이 붙어 있다. 이름은 고치지
않았다.

검증: 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 앞 커밋과 같다(주석만 바뀜).
`python3 scripts/check-docs.py` rc=0.
2026-11-07 17:49:10 +09:00
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
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00
donghyeon-ka 9da00eb782 refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링 2026-09-23 17:27:09 +09:00
donghyeon-ka 567422f2e5 feat: add production capability foundations 2026-07-31 23:50:44 +09:00
DongHyeonka 821fe00c32 init: 클린 아키텍처 백엔드 2026-07-24 14:29:36 +09:00