From ecc74b7df724eb373c4af1b5b654764e89620660 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 00:21:51 +0900 Subject: [PATCH] =?UTF-8?q?docs(review):=202=EC=B0=A8=20=EC=9E=AC=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=20=EA=B2=B0=EA=B3=BC=EC=99=80=20=ED=8C=8C=EC=83=9D=20?= =?UTF-8?q?=EC=84=9C=EB=B9=84=EC=8A=A4=20=EC=97=85=EA=B7=B8=EB=A0=88?= =?UTF-8?q?=EC=9D=B4=EB=93=9C=20=EC=95=88=EB=82=B4=EB=A5=BC=20=EB=8D=94?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 1차 재리뷰 수정(bbe944bd)도 앞 라운드처럼 새 결함을 만들었는지 아무도 다시 읽지 않았다. 이 브랜치는 파생 서비스가 깨지는 변경이 많은데 따라올 안내가 없었다. 방법: 수정 커밋만 대상으로 리뷰어 4명이 1차와 같은 템플릿·스킬 방식으로 봤다(round2/). Critical·회귀 0, Important 7(이번 라운드가 새로 만든 것 4), Minor 22. 3차 수정에 쓸 결정을 README 9.1절에 적었다. 파생 서비스용 docs/upgrade/2026-11-maturity-review.md에 깨지는 변경 38건, 마이그레이션 영향, 따라오는 순서를 diff 근거와 함께 정리했다. 위험·한계: 이 커밋은 기록만 담는다. Important 7건은 다음 수정에서 고친다. 업그레이드 안내는 tech-log-backend에 실제로 적용해 보지 않았다. 검증: 문서만. 리뷰어별 실행 명령은 각 문서 "범위" 절. Refs: docs/reviews/2026-11-03-rereview/README.md 9절 --- docs/reviews/2026-11-03-rereview/README.md | 33 ++ .../round2/01-core-app-inbound.md | 314 ++++++++++++++++++ .../round2/02-persistence-messaging.md | 246 ++++++++++++++ .../2026-11-03-rereview/round2/03-outbound.md | 268 +++++++++++++++ .../round2/04-bootstrap-build-sample.md | 306 +++++++++++++++++ docs/upgrade/2026-11-maturity-review.md | 271 +++++++++++++++ 6 files changed, 1438 insertions(+) create mode 100644 docs/reviews/2026-11-03-rereview/round2/01-core-app-inbound.md create mode 100644 docs/reviews/2026-11-03-rereview/round2/02-persistence-messaging.md create mode 100644 docs/reviews/2026-11-03-rereview/round2/03-outbound.md create mode 100644 docs/reviews/2026-11-03-rereview/round2/04-bootstrap-build-sample.md create mode 100644 docs/upgrade/2026-11-maturity-review.md diff --git a/docs/reviews/2026-11-03-rereview/README.md b/docs/reviews/2026-11-03-rereview/README.md index 484d3913..5fbe2cb2 100644 --- a/docs/reviews/2026-11-03-rereview/README.md +++ b/docs/reviews/2026-11-03-rereview/README.md @@ -110,3 +110,36 @@ Minor 41건은 각 문서에 있다. - **짝 프론트**: `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, 결과 불명)을 인계 문서에 더했다. - **이 환경에서 확인할 수 없는 것**: 실제 CI runner 실행. + +## 9. 2차 재리뷰 (수정 커밋 `bbe944bd`만, 2026-11-04) + +1차 재리뷰 수정(`bbe944bd`, 406파일)을 리뷰어 4명이 같은 템플릿·스킬 방식으로 다시 봤다(`round2/01~04-*.md`). 저장소 전체가 아니라 이 커밋만 본 이유: 원래 리뷰와 1차 재리뷰가 전 영역을 이미 봤고, 위험은 "수정이 새 결함을 만든다"는 반복 패턴이다. + +| 문서 | Important | Minor | 이번 라운드가 새로 만든 Important | 회귀 | +|---|---|---|---|---| +| [round2/01 core·inbound](round2/01-core-app-inbound.md) | 2 | 5 | RR-01-12 | 0 | +| [round2/02 persistence·messaging](round2/02-persistence-messaging.md) | 1 | 7 | RR-02-09 | 0 | +| [round2/03 outbound](round2/03-outbound.md) | 1 | 7 | 없음 | 0 | +| [round2/04 bootstrap·build·sample](round2/04-bootstrap-build-sample.md) | 3 | 3 | RR2-04-01, RR2-04-02 | 0 | + +Important 7건: +- RR-01-11 — `http-contract.md`는 결과 불명 503 뒤 같은 키 재전송이 lease 뒤 500으로 막힌다고 적었지만, Redis store는 lease가 지난 EXECUTING을 넘겨받아 작업을 다시 실행한다(실 Redis 확인). RR-02-03 부분. +- RR-01-12 — 새 `@SystemInvoked` 규칙 두 개가 매뉴얼 09장의 이벤트 소비 handler → 쓰기 use case 경로를 막는다. +- RR-03-11 — Redis claim이 key TTL을 replay TTL로 둬서, replay TTL < processing lease인 배포에서 lease 도중 key가 사라져 같은 키가 두 번 실행된다(실 Redis Lua 확인). RR-04-08 부분. +- RR-02-09 — V22가 `outbox_event`에 가장 강한 잠금을 걸면서 `lock_timeout`이 없다(실 PG16: 19초 대기, 그동안 읽기·쓰기 막힘). +- RR2-04-01 — prod `fixture-` 거부가 비밀이 아닌 값(`HOSTNAME` 등)까지 막는다. +- RR2-04-02 — 데모 허용 목록의 `test`·`demo` 프로필로 sample이 뜨지 않는다(이미지 실행 문서대로 하면 기동 거부). +- RR2-04-03 — 기동 rule runner에 검사 없는 면제 경로가 남아 `@Value` 필드·JavaBean 설정이 조용히 null(RR-06-01 부분). + +### 9.1 결정 (3차 수정용, 2026-11-04) + +| 항목 | 결정 | 이유 | +|---|---|---| +| RR-01-11 결과 불명 뒤 재전송 | 두 멱등성 store(PostgreSQL·Redis)가 같은 공유 계약을 따른다: lease가 지난 실행 중 기록은 작업을 다시 돌리지 않고 "회복 필요"로 답한다. 계약 문서와 코드를 맞춘다 | 결과 불명인 작업을 서버가 몰래 다시 실행하면 이번 계약의 목적(중복 효과 방지)이 무너진다 | +| RR-03-11 Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease). 설정 검사도 둔다 | lease가 남아 있는 동안 key가 사라지면 안 된다 | +| RR-01-12 소비 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked` use case에 닿지 못한다. 시스템이 부르는 inbound(메시지 소비자·스케줄러)는 명시적 표시로 허용하고, 매뉴얼 09장 경로를 실제 테스트로 고정한다 | 규칙의 목적은 "사용자 요청이 권한 검사 없이 쓰기에 닿지 않게"다. 시스템 경로까지 막으면 매뉴얼이 거짓이 된다 | +| RR2-04-01 fixture 값 거부 범위 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사한다 | 운영 hostname·이름은 비밀이 아니다 | +| RR2-04-02 데모 프로필 | 허용 목록의 각 프로필은 sample이 실제로 뜨는 프로필이어야 한다. 뜨게 고치거나, 독립 실행용이 아니면 목록에서 뺀다. 문서·Dockerfile과 맞춘다 | 허용한 프로필로 뜨지 않으면 허용 목록이 거짓이다 | +| RR-02-09 V22 잠금 | V21과 같은 `SET LOCAL lock_timeout`과 같은 모양의 lane 테스트 | 같은 커밋 안의 두 마이그레이션이 다른 규칙을 따르면 안 된다 | + +멈추는 기준: 3차 수정 뒤 그 diff만 보는 확인 리뷰에서 새 Important가 0이면 멈춘다. diff --git a/docs/reviews/2026-11-03-rereview/round2/01-core-app-inbound.md b/docs/reviews/2026-11-03-rereview/round2/01-core-app-inbound.md new file mode 100644 index 00000000..9864771f --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round2/01-core-app-inbound.md @@ -0,0 +1,314 @@ +# 01 core·application·inbound 재리뷰 (2026-11-03, 2차) + +경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +- 리뷰 범위: Base `7ef8d0b4` → Head `bbe944bd`(커밋 1개) 중 아래 pathspec. 152파일, +5,757 −692. + ```text + src/domain-core src/shared-contract src/application-core src/application-fileserver + src/application-objectstorage src/composition src/adapter/inbound src/grpc src/grpc-advanced + scripts docs/manual docs/web + ``` +- 맡은 1차 재리뷰 발견: RR-01-01~10, RR-02-01~08, RR-07-01, RR-07-06, RR-04-04(=RR-01-05). +- 이 문서의 새 발견 ID는 `RR-01-11`부터다. 1차의 `RR-01-01~10`과 겹치지 않게 이어 붙였다. +- 읽은 방식: diff가 커서 여러 번에 나눠 직접 읽었다(하위 에이전트 없음). + 1. application-core main diff 전부(멱등성 executor·예외, `IntegrationEventDraft`·`IntegrationIdentity`, + `SubmitDurableOperationUseCase`, outbox 포트·relay·`OutboxPublishAttempt`, `SystemInvoked`). + 2. application-core testFixtures 중 멱등성 저장소 계약, outbox 순서 계약·fake, `OverlappingWrites`, + `DirectTransactionPort`, 캐시 계약 추가분. + 3. composition: service-runtime(`PermissionEnforcementGuard`), outbox-relay(조립·지표·설정), + idempotency(`IdempotencySettings`), fileserver-platform(move 조립). + 4. web main diff 전부(`EnvelopeErrorController`, `HttpStatusErrorCodes`, `EnvelopeBodyAdvice`, + `SecurityConfig`, `WebMvcPlatformAutoConfiguration`, `RetryAfterAdvisor`)와 새 시스템 테스트·testkit. + 5. GraphQL scorer diff와 새 union·interface 테스트. 같은 leaf의 page 크기 계산 복사본을 grep으로 전수 확인. + 6. gRPC: `GrpcClaimToken`, 포트, JPA adapter·repository·entity·V003, in-memory fake, 공유 계약 diff, + interceptor·decision, 기동 검증기. + 7. application-fileserver: move use case, `FileAccessSubject.owns`, 새 계약 6개의 케이스 목록과 상속 관계, + 쿼터 fake. + 8. 생성 명령 템플릿·탐침·`verify-feature-scaffold.sh` diff, 매뉴얼 04·05·06·07·09 diff, `docs/web/http-contract.md` diff. +- 범위 밖에서 확인용으로 읽은 것: `ApplicationBoundaryArchitectureTest`(D4·새 ArchUnit 2개), + `RequiresPermissionAuthorizationManager`, `adapter/inbound/messaging/README.md`·통합 테스트의 handler 모양, + Redis 멱등성 Lua(`IdempotencyScripts.java`)와 adapter, `PostgreSqlIdempotencyStore`와 그 PG 테스트, + `JpaFileQuota`·`JpaQuotaReclaim`(호출자 트랜잭션 요구 여부), `docs/registries/error-codes.yaml` diff, + ADR-GRPC-004 diff. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 실제 심각도로 분류, 읽지 않은 코드에 판정 금지 | 문서 양식 전체. 발견마다 "고치는 법"과 4절 결정을 코드로 대조 | +| `clean-architecture` | 의존은 안쪽으로, 포트는 안쪽이 소유, composition root(Main)가 조립, 경계에서 framework 격리 | `@SystemInvoked` 조립 규칙이 시스템 호출자(relay·이벤트 소비자)를 composition에서 조립할 수 있게 두는지, web leaf가 application-core 상수를 읽는 방향, 계약 키트 위치 | +| `api-and-interface-design` | 일관된 오류 의미, Hyrum's Law(관찰되는 동작이 계약), 멱등 키의 세 결과(성공·실패·불명)와 in-flight 중복 처리, 계약과 구현의 일치 | `IDEMPOTENCY_COMPLETION_UNKNOWN`이 약속한 재전송 판정을 저장소 구현이 지키는지, `/error` 응답 status·모양, gRPC·GraphQL wire 변경 표시 | +| `security-and-hardening` | 인가는 모든 요청에서, 오류 본문에 내부 정보 금지, 자원 상한(DoS), 숨은 우회 경로 | ERROR 디스패치 허용이 새 노출을 만드는지, `@SystemInvoked` 우회 경로, GraphQL union 아래 page 상한, 파일 move 쿼터 우회 | + +### 실행한 명령과 결과 + +| 명령 | 결과 | +| --- | --- | +| `git diff --stat / --shortstat 7ef8d0b4..bbe944bd -- ` | 152파일 +5,757 −692 | +| `git grep`으로 `@SystemInvoked` 사용처, `new PublishPendingOutboxEventsUseCase`, `effectivePageSize`, `sendError(`, `SecurityFilterChain`, `extends <각 fileserver 계약>` 전수 확인 | 아래 표·발견의 근거 | +| `git worktree add --detach /rr2-01 bbe944bd` 후 `IdempotencyStoreContract`에 탐침 메서드 1개 추가, `flock … ./gradlew :adapter:outbound:cache-redis:redisContainerContractTest --console=plain -i` | 첫 실행은 탐침의 Error Prone `ReturnValueIgnored`로 컴파일 실패(탐침 코드 문제). 고친 뒤 `BUILD SUCCESSFUL in 44s`, 출력 `RR2-PROBE … duringLease=InProgress afterLease=TakenOverClaimed`(RR-01-11) | +| `git worktree remove --force /rr2-01` | 탐침과 함께 삭제 | + +### 못 본 것 + +- 전체 게이트는 다시 돌리지 않았다. 재리뷰 README 7절 결과를 읽기만 했다. +- gRPC ledger의 PG lane(`JpaGrpcOperationLedgerContractIT`)은 다시 돌리지 않았다. 동시 commit 경쟁은 그 lane이 + 7절 게이트(`-p optional-platforms … integrationCheck`)에서 통과했다는 기록과 SQL을 읽은 것에 기댄다. +- Jetty의 오류 디스패치, 관리 포트를 따로 둔 배포의 오류 처리는 보지 않았다. +- application-core의 outbox·messaging 변경(RR-05-xx, 06-10~14)은 diff를 읽었지만 판정은 05 영역 리뷰어 몫으로 두었다 + (「Declined to judge」). +- sample-portfolio(데모 체인의 ERROR 디스패치 허용, `WorkLogReservedPayload`)는 pathspec 밖이라 grep으로 수정 여부만 봤다. + +## Strengths + +- `@SystemInvoked` 빈은 advisor가 있어도 기동을 멈춘다. 검사가 advisor 검사보다 먼저다 + (`src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:57-70`). 테스트가 "advisor가 있어도 + 실패"를 고정한다(`PermissionEnforcementGuardTest.aSystemInvokedUseCaseRegisteredAsABeanFailsStartupEvenWithAnAdvisor`). +- relay는 여전히 `new`로 조립돼 scheduler에만 들어간다(`src/composition/outbox-relay/.../OutboxRelayAutoConfiguration.java:80`). + 새 기동 차단이 relay를 막지 않는다. +- gRPC ledger의 모든 전이가 `claim_attempt`를 조건에 넣은 UPDATE 한 문장이다 + (`GrpcOperationLedgerRepository.java` `tryReclaimFailed`·`tryReclaimStale`·`tryMarkCommitted`·`tryMarkFailed`). + load-check-save가 사라졌다. 공유 계약에 "옛 owner의 실패 무시"(`GrpcOperationLedgerContract.java:439`)와 + "동시 commit은 하나만"(`:515`)이 들어가 fake와 PG adapter가 같이 받는다. +- claim이 "충돌인데 행이 없음"을 보면 insert를 한 번 더 한다(`JpaGrpcOperationLedger.java:49-62`). 1차의 purge 경쟁이 닫혔다. +- GraphQL scorer가 `GraphQLCompositeType`으로 내려간다(`GraphQlDocumentComplexityScorer.java:154,232,265`). union과 + interface 각각 "중첩 list 곱셈"과 "page 상한 거부"를 테스트한다(`GraphQlDocumentComplexityScorerTest.java:299` 등). +- `/error` 응답이 요청에서 아무것도 싣지 않는다(`EnvelopeErrorController.java:60-71`). 실제 Tomcat에서 방화벽 거부 + 경로를 단언하고, 기본 JWT 체인에서 "오류 디스패치는 원래 400, `/error` 직접 호출은 401"을 둘 다 확인한다 + (`JwtChainErrorDispatchIT`). +- status → code 표가 한 곳이다(`HttpStatusErrorCodes.java:18`). 예외 처리기와 오류 컨트롤러가 같은 표를 쓴다. +- move의 쿼터 이동이 relocate와 같은 트랜잭션이다(`MoveFileApplicationUseCase.java:92-109`). JPA 쪽 세 포트가 모두 + 호출자 트랜잭션을 요구하므로(`JpaFileQuota.java:39,58,71`, `JpaQuotaReclaim.java:42`) 버전 충돌이면 쿼터도 롤백된다. +- 생성 계약에 `inTransaction` hook이 생겼고(`__Feature__RepositoryContract.java.tmpl:41`), 왕복 검사가 "호출자 + 트랜잭션 밖이면 거부하는 저장소"로 계약을 한 번 더 돌린다(`scripts/verify-feature-scaffold.sh:140-161`). 확인할 + 결과 XML 목록도 템플릿에서 만든다(`:102`). +- Retry-After 2초가 상수 하나이고(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`), lease가 그 이하면 기동이 실패한다 + (`IdempotencySettings.java:57`). +- 파일 소유자 규칙이 `FileAccessSubject.owns` 하나다(`FileAccessSubject.java:63`). fake와 `RoleBasedFileAccessPolicy`가 + 둘 다 부르고, `FileAccessPolicyPortContract`를 둘 다 상속한다. + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| RR-01-01 | 닫힘 | 템플릿 계약의 모든 호출이 `inTransaction`을 거친다(`__Feature__RepositoryContract.java.tmpl:41` 이하). 탐침 `CallerTransaction__Feature__RepositoryContractTest.java.tmpl`이 트랜잭션 요구 저장소로 계약을 통과시키고, `verify-feature-scaffold.sh:140-161`이 그 결과 XML을 확인한다. 매뉴얼 04장 4단계에 hook 사용을 적었다 | +| RR-01-02 = RR-07-01 | 닫힘(결정대로) | 4절 결정 두 가지가 다 들어갔다: 빈이면 기동 실패(`PermissionEnforcementGuard.java:57-70`), inbound adapter 의존 금지 ArchUnit(`ApplicationBoundaryArchitectureTest.java:455-467`). 결정이 만든 새 위험 → RR-01-12 | +| RR-01-03 | 닫힘 | 07장(`docs/manual/07-authorization.md:65-89`), 09장(`docs/manual/09-outbox-events.md:56-87`), 06장(`:44-46`) 문장이 코드와 맞다. `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`(`ApplicationBoundaryArchitectureTest.java:475`), `application-core/CLAUDE.md` 표에 두 타입 | +| RR-01-04 (+RR-07-06) | 닫힘 | 저장 포트 9개 모두 계약이 있고 fake와 PG 테스트가 각각 상속한다(`extends` grep: ContentReferenceLedger·FileQuotaLedger·RecoveryQueue·StagingUploadLocator·UploadSession·FileMetadata·CleanupQueue). `FileQuotaLedgerContract`가 만료·해제 뒤 확정·연장 거부를 같은 표로 본다. build.gradle 주석도 사실대로 고쳤다 | +| RR-01-05 = RR-04-04 | 닫힘 | `MoveFileApplicationUseCase.java:100-109`가 대상 `requireRoom` → 예약·확정 → 출발 회수를 relocate와 한 트랜잭션에서 한다. 테스트 두 개(`FileLifecycleUseCasesTest.java:467,485`). 남은 작은 틈 → RR-01-17 | +| RR-01-06 | 닫힘 | 2^53 경우(`CacheRegionContract`), 트랜잭션 밖 거부·롤백 번호 재사용(`OutboxAggregateSequenceContract`), 시간 경우는 시계 없으면 abort(`IdempotencyStoreContract.java:94`). 새로 넣은 겹침 경우의 fake 실행 방식 → RR-01-16 | +| RR-01-07 | 닫힘 | `__Feature__Config.java.tmpl:36` `afterName = PersistenceJpaAutoConfiguration` | +| RR-01-08 | 닫힘(범위 밖 grep) | `sample-portfolio/.../WorkLogReservedPayload.java:15`가 `IntegrationIdentity.isCanonical`을 부른다 | +| RR-01-09 | 닫힘 | `shared-contract/README.md:369-370`, `RuntimeEnvironment.java:32-33`, application-core README 알림 절 정리 | +| RR-01-10 | 닫힘 | `verify-feature-scaffold.sh:102-127`이 템플릿의 `*Test.java.tmpl` 전부에서 결과 XML 경로를 만들고 `tests="0"`도 거부한다 | +| RR-02-01 | 닫힘 | 위 Strengths. union·interface 아래 곱셈·page 상한 테스트 4개 | +| RR-02-02 | 닫힘 | `EnvelopeErrorController` + `SecurityConfig.java:91` ERROR 디스패치만 허용 + `EnvelopeBodyAdvice`가 4xx·5xx를 감싸지 않음. 실 Tomcat·JWT 체인 테스트. 문서와 다른 작은 점 → RR-01-13 | +| RR-02-03 | 부분 | 코드 분기(`IdempotencyExecutor.java:251,286`)와 테스트는 들어갔다. 그러나 이 코드를 실제로 내는 저장소는 Redis뿐이고, Redis는 lease가 지난 EXECUTING 기록을 넘겨받아 작업을 다시 돌린다. 계약 문서가 약속한 "lease 뒤 500 RECOVERY_REQUIRED"가 지켜지지 않는다 → RR-01-11 | +| RR-02-04 | 닫힘 | 토큰·V003·조건부 UPDATE·계약 케이스(Strengths). `release`만 토큰 밖에 남았다 → RR-01-15 | +| RR-02-05 | 닫힘 | `IdempotencySettings.java:57`, `RetryAfterAdvisor`가 같은 상수를 읽는다 | +| RR-02-06 | 닫힘 | `GrpcStatusMapperTest`·`GraphQlWireErrorMapperTest` 케이스, 두 README, registry `compatibility_impact: behavior-change` | +| RR-02-07 | 닫힘 | 검증기 문구(`GrpcPlatformStartupValidator.java` keyed-method 메시지), ADR-GRPC-004 "(b)" 기록, `src/grpc/CLAUDE.md:168` | +| RR-02-08 | 부분 | ② Javadoc은 고쳤다(`GraphQlDeadline.java:17-19`). ① calculator의 복사본은 지웠지만 같은 규칙의 세 번째 복사본이 `GraphQlClientPolicy.java:101`에 남았다 → RR-01-14 | +| RR-07-01 | 닫힘(결정대로) | = RR-01-02 | +| RR-07-06 | 닫힘 | `FileAccessSubject.owns` 한 곳, `FileAccessPolicyPortContract`를 `FakeFileAccessPolicyContractTest`와 `RoleBasedFileAccessPolicyContractTest`가 상속 | +| RR-04-04 | 닫힘 | = RR-01-05 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-01-11 · `IDEMPOTENCY_COMPLETION_UNKNOWN` 뒤 "같은 키 재전송은 안전" 약속을 Redis 저장소가 지키지 않는다 — lease가 지나면 작업을 다시 돌린다 + +- **위치**: `docs/web/http-contract.md:108-114`, `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyCompletionUnknownException.java:16-17`, + `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java:50`(주석), `docs/registries/error-codes.yaml:448-450`(주석), + `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java:71-79`, + `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:136-137` +- **무엇이 틀렸나**: + - 새 계약은 "결과 불명 503을 받으면 같은 키로 다시 보내라. 서버가 판정한다 — 기록됐으면 재생, lease 안이면 409, + lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`"라고 적는다(`http-contract.md:111-113`, 예외 Javadoc `:16-17`). + - 이 예외는 `complete`가 `UNAVAILABLE`을 돌려줄 때만 난다. `UNAVAILABLE`을 돌려주는 저장소는 Redis뿐이다 + (`RedisIdempotencyStoreAdapter.java:248,251` — lane이 보내기 전에 거절). PostgreSQL 저장소에는 `UNAVAILABLE` 결과가 + 아예 없다(`PostgreSqlIdempotencyStore`에서 grep 0건). 즉 결과 불명은 실제로 Redis 배포에서만 생긴다. + - 그때 Redis 기록은 `EXECUTING`으로 남는다(complete가 보내지지 않았다). 그런데 Redis CLAIM 스크립트는 상태를 가리지 + 않고 lease가 끝난 기록을 넘겨준다: `if state == 'FAILED_RETRYABLE' or (leaseUntil ~= nil and leaseUntil <= nowMillis)` + → `TAKEN_OVER`(`IdempotencyScripts.java:71-79`). executor는 `TakenOverClaimed`를 받으면 `startAndRun`으로 작업을 다시 + 돌린다(`IdempotencyExecutor.java:136-137`). + - PostgreSQL은 반대다. lease가 지난 `EXECUTING`은 `ABANDONED`로 바꾸고 `RecoveryRequired`를 준다 + (`PostgreSqlIdempotencyStore.java:153-155`, 테스트 이름 `expiredExecutingRecordRequiresReconciliationAndIsNeverBlindlyTakenOver`). + 공유 `IdempotencyStoreContract`는 이 경우를 묶지 않는다("expiry and take-over … stay with each store's own tests", `:34-35`). + 그래서 두 저장소가 갈라진 채 게이트를 통과한다. +- **왜 중요한가**: + - 4절 결정이 막으려던 것은 "결과 불명을 '안 됨'으로 믿고 다시 실행"이다. 새 코드는 클라이언트에게 "같은 키면 안전"이라고 + 말하는데, 이 코드가 나는 유일한 저장소에서 같은 키 재전송이 lease(기본 30초) 뒤 작업을 다시 실행한다. + - 발생 조건: `provider=redis` + complete 단계에서 lane이 포화·종료 중 + action이 트랜잭션 밖 효과(외부 호출·메일)를 가짐 + + 클라이언트가 계약대로 30초 넘게 재시도. 결과: 외부 효과가 두 번 일어난다. 클라이언트는 "같은 키라 안전"이라고 믿었으므로 + 이상을 알아챌 근거가 없다. + - DB만 쓰는 action이고 `execute`가 `tx.inWrite` 안이면(sample `PublishPosterImageUseCase.java:109-118`) DB 효과는 롤백되므로 + 다시 돌리는 것이 오히려 맞다. 하지만 그것도 계약 문장("500 RECOVERY_REQUIRED")과 다르다. 어느 쪽이든 문서가 틀렸다. + - 사용자 원칙: 위험이 코드에 드러나야 한다. 지금은 두 저장소의 차이가 각자의 테스트에만 있고, 계약 문서는 PG 쪽만 말한다. +- **고치는 법**: 4절 결정 문장("lease 뒤 회복 필요")을 기준으로 맞춘다. + 1. Redis CLAIM 스크립트: `state == 'EXECUTING'`이고 lease가 끝났으면 `ABANDONED`로 바꾸고 `RECOVERY_REQUIRED`를 돌려준다. + lease 만료 넘겨받기는 `CLAIMED`(실행 전)와 `FAILED_RETRYABLE`만 한다. PG와 같은 규칙이다. + 2. `IdempotencyStoreContract`에 시간 경우 하나: "실행 시작 뒤 lease가 지나면 다른 claim은 `RecoveryRequired`". + in-memory는 abort되고 Live Redis·PG lane이 실제로 돈다(아래 탐침이 그 모양이다). + 3. 예외 Javadoc의 "Effects inside the action's own transaction roll back"을 "`execute`를 쓰기 트랜잭션 안에서 부른 경우"로 + 좁힌다. action이 자기 트랜잭션을 따로 커밋하면 DB 효과도 남는다. + - Redis 스크립트 변경은 04 영역 파일이다. 계약 문서·계약 테스트·Javadoc은 이 영역이다. +- **가이드 심각도·우선순위**: Medium · P2 (Redis 배포·complete 단계 lane 거절·외부 효과가 겹칠 때만. 기본 조립은 멱등성 비활성) +- **증거**: E3 — 아래 탐침. 코드 경로는 E1. + - 탐침: worktree에서 `IdempotencyStoreContract`에 메서드 하나를 넣었다. claim(lease 1s) → `markExecutionStarted` → + 다른 attempt로 claim(lease 안) → `elapse(2s)` → 다른 attempt로 claim. `LiveRedisIdempotencyStoreContractTest`(Testcontainers + Redis, 실제 서버 시계)로 `redisContainerContractTest` lane을 돌렸다. + - 출력: `RR2-PROBE LiveRedisIdempotencyStoreContractTest duringLease=InProgress afterLease=TakenOverClaimed`, + `BUILD SUCCESSFUL in 44s`. lease 안에서는 409가 되고, lease 뒤에는 계약이 말한 `RecoveryRequired`가 아니라 + `TakenOverClaimed`다 — executor는 이것을 받으면 작업을 다시 돌린다. + - PG 쪽 반대 동작은 기존 테스트 `PostgreSqlIdempotencyIntegrationTest.java:164`가 고정한다(E2, 다시 돌리지 않음). + +#### RR-01-12 · 새 `@SystemInvoked` 규칙 둘이 매뉴얼 09장의 이벤트 소비 경로(쓰기 use case 호출)를 막는다 — 규칙을 지키는 방법이 문서에 없다 + +- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:455-467`, + `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java:57-70`, + `docs/manual/09-outbox-events.md:115-117`, `docs/manual/07-authorization.md:65-89`, `src/adapter/inbound/messaging/README.md:32,95` +- **무엇이 틀렸나**: + - 매뉴얼 09장 4단계는 소비 handler(`MessageHandler`)를 `adapter:inbound:messaging`에 두고 "delivery 하나를 use case 호출 + 하나로 바꾸라, use case는 평소처럼 `tx.inWrite`로 쓴다"고 가르친다. 소유자 결정 10(Kafka 소비)의 정식 경로다. + - 그 use case는 쓰기다(`WRITE_REPOSITORY`). 지금 쓰기 use case가 고를 수 있는 길은 셋인데, 소비 handler에서는 셋 다 막힌다. + 1. `@RequiresPermission` + bean: 소비 스레드에는 `Authentication`이 없다. `RequiresPermissionAuthorizationManager.java:56`이 + `auth == null`이면 거부한다. 메시지는 재시도 후 DLQ로 간다. + 2. `@SystemInvoked`(07장이 말하는 "시스템이 부르는 쓰기"): bean이면 이번 라운드의 가드가 기동을 막는다. handler가 그 + 클래스에 의존하면 이번 라운드의 ArchUnit이 막는다 — 규칙이 `..adapter.inbound..` 전체를 대상으로 하므로 + `dev.caskeleton.adapter.inbound.messaging`도 들어간다(`:458`). + 3. 표시 없음: D4(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)가 빌드를 막는다. + - 남는 길은 "handler가 구체 클래스 대신 `CommandUseCase` 같은 인터페이스에 의존하고, composition이 `new`로 만든 + `@SystemInvoked` use case를 handler bean에 넣는다"뿐이다. 이 방법은 07장·09장·messaging README·ArchUnit 메시지 어디에도 + 없다. ArchUnit 메시지는 "scheduler에 넘긴다"고만 한다. 게다가 messaging README는 handler를 app-bootstrap에서 등록하는 + 안을 버렸다(`:95`). + - 이번 라운드 전에는 `@SystemInvoked` use case를 bean으로 만들어 handler에 넣는 길이 있었다(그래서 RR-01-02가 위험했다). + 그 문을 닫으면서 정당한 시스템 호출자 하나(소비자)의 길을 문서 없이 함께 닫았다. +- **왜 중요한가**: + - 첫 소비자를 붙이는 파생 서비스는 매뉴얼대로 하면 기동·빌드·런타임 중 하나에서 반드시 실패한다. + - 실패를 끄는 가장 쉬운 우회가 위험하다. `repositoryAccess`를 낮춰 D4를 피하면 권한 표시 없는 쓰기 use case가 bean으로 + 생기고, 컨트롤러도 그것을 주입받을 수 있다. RR-01-02가 막으려던 "검사 없는 쓰기"가 다른 문으로 돌아온다. + - 사용자 원칙: 선택지가 여럿이면 고른 방법·버린 대안·이유가 남아야 하고, 개발자가 따로 기억해야 하는 규칙은 결함이다. +- **고치는 법**: 둘 중 하나를 고르고 기록한다. + - (a) 경로를 문서로 고정: 09장 4단계와 07장 「시스템이 부르는 쓰기」에 "소비 handler는 use case를 인터페이스(또는 + application-core가 소유한 함수형 포트)로 받고, `@SystemInvoked` use case는 소비 조립(composition)이 `new`로 만들어 + handler bean에 넣는다"를 적는다. 예시 조립 하나(`InboxRedeliveryIntegrationTest`의 handler 모양을 그 방식으로)와 + ArchUnit 메시지에 "scheduler 또는 소비 handler"를 넣는다. + - (b) 규칙을 좁힘: ArchUnit 대상에서 `..adapter.inbound.messaging..`을 빼고, 대신 "messaging inbound는 HTTP·gRPC·GraphQL· + WebSocket 패키지에 의존하지 않는다"로 노출 경로를 막는다. 가드는 그대로 둔다(소비 handler가 use case를 `new`로 만들면 bean이 + 아니다). + - 어느 쪽이든 07장 "지금 이해하면 되는 것"의 "시스템만 부르는 쓰기" 줄에 소비자를 넣는다. +- **가이드 심각도·우선순위**: Medium · P2 (런타임 결함이 아니라 매뉴얼이 가르치는 경로와 새 규칙의 충돌. 템플릿에 소비자는 아직 없다) +- **증거**: E1 — 규칙 대상 패키지(`:458`), 가드 조건(`:57`), 인가 관리자의 무인증 거부(`:56`), 매뉴얼 4단계(`:115-117`)를 대조했다. + ArchUnit을 fixture로 돌려 보지는 않았다. + +### Minor (Nice to Have) + +#### RR-01-13 · `/error` 응답이 표에 없는 status를 400·500으로 바꾸는데, 정본은 "원래 status가 그대로 나간다"고 적는다 + +- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/EnvelopeErrorController.java:65-70`, + `HttpStatusErrorCodes.java:32-35`, `EnvelopeResponseWriter.java:37`, `docs/web/http-contract.md:59` +- **무엇이 틀렸나**: 오류 컨트롤러는 디스패치 status를 `HttpStatusErrorCodes`로 코드에 바꾼 뒤 그 코드의 status를 다시 쓴다. + 표에 없는 4xx(408·409·410·422 등)는 `BAD_PARAMETER` 400, 표에 없는 5xx(501·502·504)는 `INTERNAL_ERROR` 500이 된다. + Boot 기본 컨트롤러는 원래 status를 그대로 냈다. 지금 main 코드에 `sendError`는 없어서(grep 0건) 나오는 경우는 컨테이너· + 라이브러리가 낸 오류뿐이다. +- **왜 중요한가**: 정본 1절의 "원래 status가 그대로"는 표에 있는 status에서만 참이다. 필터를 더하는 서비스가 `sendError(409)`를 + 쓰면 400으로 바뀌어 클라이언트 분기가 틀어진다. +- **고치는 법**: 문장을 "표에 있는 status는 그대로, 그 밖은 400·500으로 접힌다"로 고치거나, 오류 컨트롤러가 status는 원래 값을 + 두고 code만 표로 고르게 한다(`EnvelopeResponseWriter`에 status를 따로 받는 overload). +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1 + +#### RR-01-14 · page 크기 규칙의 세 번째 복사본이 남았다(RR-02-08 ① 부분) + +- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/policy/GraphQlClientPolicy.java:101-107` +- **무엇이 틀렸나**: 지운 `GraphQlComplexityCalculator.effectivePageSize`와 같은 "둘 다 있으면 `first`" 규칙이 public 메서드로 + `GraphQlClientPolicy`에 있다. 상한 검사도 없다. main 호출자는 없고 테스트(`GraphQlClientPolicyTest.java:45-47`)만 부른다. + 실제 점수는 `connectionCost`(큰 쪽), 실제 resolver 쪽은 `GraphQlConnectionPolicy.effectivePageSize`(방향 섞임 거부)다. +- **왜 중요한가**: 갈라진 복사본이다. adopter가 이름만 보고 이것을 resolver에서 부르면 상한 없는 page를 받는다. +- **고치는 법**: 지우고 테스트를 `GraphQlConnectionPolicy` 쪽으로 옮긴다. +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1(grep) + +#### RR-01-15 · gRPC ledger `release`는 토큰 밖에 있고, 행이 지워지면 시도 번호가 1로 돌아간다 + +- **위치**: `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedger.java:143`, + `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:204-207`, + `GrpcOperationLedgerRepository.java:48`, `GrpcClaimToken.java:14-15` +- **무엇이 틀렸나**: 다른 전이는 모두 토큰을 받는데 `release(identity)`는 토큰 없이 `deleteById`한다. 지운 뒤 새 claim은 + `claim_attempt = 1`로 시작한다. 그래서 `GrpcClaimToken` Javadoc의 "두 시도는 같은 값을 나눠 갖지 않는다"는 release·purge 뒤에는 + 거짓이다. 옛 attempt 1 owner가 그때 살아 있으면 새 attempt 1의 claim에 commit·실패를 기록할 수 있다(ABA). +- **왜 중요한가**: 지금 main에 `release` 호출자는 없고, purge는 24h 지난 완료 행만 지우므로 실제 창은 아주 좁다. 다만 포트에 + "토큰 없는 파괴 연산"이 남아 있고 Javadoc이 반대로 말한다. +- **고치는 법**: `release(identity, claimToken)`으로 바꿔 `DELETE … WHERE claim_attempt = :token AND state = 'IN_PROGRESS'`로 하거나, + 포트에서 지운다. Javadoc 문장을 "같은 행이 살아 있는 동안"으로 좁힌다. +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1 + +#### RR-01-16 · 새 "첫 쓰기 두 개가 겹침" 계약 케이스가 fake에서는 겹치지 않는다 + +- **위치**: `src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/OutboxAggregateSequenceContract.java:71-83`, + `src/application-core/src/testFixtures/java/dev/caskeleton/application/transaction/testkit/DirectTransactionPort.java:47,115-118` +- **무엇이 틀렸나**: `OverlappingWrites`는 두 스레드에서 트랜잭션을 연다. in-memory 계약 테스트의 `DirectTransactionPort`는 + 스레드를 구분하지 않는 필드 하나(`current`)로 "열린 트랜잭션"을 기억한다. 둘째 스레드는 첫 스레드의 트랜잭션이 열려 있는 것을 + 보고 거기에 join한다(`:117`). fake에서는 "겹친 두 트랜잭션"이 아니라 "한 트랜잭션 안의 두 호출"을 검사한다. `ArrayList`도 + 두 스레드가 같이 고친다. +- **왜 중요한가**: 실제 대상인 PG에서는 의미대로 돈다. fake에서는 녹색이 아무것도 말하지 않고, 경쟁 상태가 있는 테스트 코드라 + 드물게 흔들릴 수 있다. +- **고치는 법**: `DirectTransactionPort`의 `current`를 `ThreadLocal`로 바꾸거나, fake 계약 테스트에서 이 케이스를 순차 실행으로 + 바꾸고 그렇게 적는다. +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1 + +#### RR-01-17 · move의 "거절되면 아무것도 바뀌지 않는다"는 쓰기 전 거절에서만 테스트된다 + +- **위치**: `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/MoveFileApplicationUseCase.java:38-40,92-109`, + `FileLifecycleUseCasesTest.java:485` +- **무엇이 틀렸나**: 테스트는 `requireRoom`에서 거절되는 경우(아직 아무것도 안 씀)만 본다. 쿼터를 옮긴 뒤 `relocate`가 버전 충돌로 + 실패하는 경우의 롤백은 JPA 포트들이 호출자 트랜잭션에 합류한다는 사실에만 기댄다. 쿼터 fake는 롤백을 모르므로 use case 테스트로는 + 볼 수 없고, PG lane에도 move 케이스가 없다. 또 이번 수정 전에 move된 파일은 여전히 출발 namespace에 잡혀 있고, 그 파일을 지우면 + 지금 namespace에서 회수한다. 이 과거 데이터의 처리 방법이 어디에도 없다. +- **왜 중요한가**: 지금 코드는 맞다(E1). 나중에 누가 quota 포트 하나를 `inNew`로 바꾸면 잡을 테스트가 없다. +- **고치는 법**: persistence-fileserver PG lane에 "move 중 버전 충돌 → 양쪽 사용량 그대로" 하나. `NamespaceQuota` 또는 fileserver + runbook에 "수정 전 move된 파일은 장부가 틀릴 수 있다, 재계산 SQL"을 한 줄. +- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1 + +## Declined to judge + +- application-core outbox 변경(`OutboxPublishAttempt`, `last_failure_code`, `PARKED`, `longRetries`, 포트 시그니처 변경): diff는 읽었고 + 눈에 띄는 결함은 없었다. RR-05-xx·06-10~14의 닫힘 판정은 05 영역 리뷰어 몫이다. +- `SubmitDurableOperationUseCase`의 파생 UUIDv7 event id: 클라이언트가 고른 operation id가 남의 파생 id와 같으면 inbox가 두 이벤트를 + 같은 것으로 본다. 옛 `operation-` 방식에도 같은 성질이 있었고 남의 operation id를 알아야 하므로 이번 라운드 결함으로 보지 않았다. +- `PermissionEnforcementGuard`가 못 보는 경우(lazy·prototype bean의 선언 타입이 인터페이스, `registerSingleton`, 람다 wrapper): + 일부러 우회해야 생기는 경우라 판정하지 않았다. +- ERROR 디스패치 허용의 새 노출: 컨테이너 오류 페이지가 `/error` 하나이고 컨트롤러가 요청 값을 쓰지 않으며, 다른 체인 + (actuator·알림 콜백)은 `/error`와 맞지 않는다. 새 노출은 찾지 못했다. Jetty와 관리 포트 분리 배포는 보지 않았다. +- V003의 `CHECK` 제약은 `NOT VALID` 없이 붙어 테이블 전체를 검사한다. 마이그레이션 주석대로 플랫폼이 아직 어디에도 채택되지 않아 + 판정하지 않았다. +- 필터가 던진 예외의 오류 디스패치가 span 오류 기록을 남기지 않는 것(예외 처리기는 남긴다): 1차 이전부터 같았다. + +## 수렴 판단 + +**이 라운드가 만든 새 Important가 있다: 2건.** + +- RR-01-11: 이번 라운드가 새로 쓴 계약 문장(같은 키 재전송 판정)이 그 코드를 실제로 내는 유일한 저장소(Redis)와 반대다. 원인인 + Redis 동작은 이전부터 있었지만, 그 위에 "안전"이라는 약속을 이번에 얹었다. +- RR-01-12: 이번 라운드의 `@SystemInvoked` 규칙 둘이 매뉴얼의 이벤트 소비 경로를 문서 없이 막는다. + +둘 다 기본 조립(멱등성 비활성, 소비자 없음)에서는 동작하지 않는 경로라 Critical·High는 아니다. 고치는 범위도 작다(Redis 스크립트 한 +분기 + 계약 케이스 하나 + 문서, 그리고 매뉴얼 두 장과 ArchUnit 메시지). 그래도 둘 다 "계약·매뉴얼대로 한 사람이 틀린 결과를 받는다"는 +종류라 다음 수정 라운드가 필요하다. Minor 5건은 같은 라운드에 묶을 수 있다. + +## Assessment + +**Ready to merge? With fixes** + +맡은 1차 발견은 중복(RR-07-01=RR-01-02, RR-04-04=RR-01-05)을 빼면 19건이다. 17건이 닫혔고 2건이 부분이며 회귀는 없다. RR-02-03은 결과 불명 계약이 Redis 저장소와 맞지 않아 부분이고(RR-01-11), +`@SystemInvoked` 규칙은 결정대로 들어갔지만 소비자 경로를 막는 새 Important를 만들었다(RR-01-12). diff --git a/docs/reviews/2026-11-03-rereview/round2/02-persistence-messaging.md b/docs/reviews/2026-11-03-rereview/round2/02-persistence-messaging.md new file mode 100644 index 00000000..487fe9da --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round2/02-persistence-messaging.md @@ -0,0 +1,246 @@ +# 02 persistence·messaging 재리뷰 (2026-11-03, 2차) + +경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +- 리뷰 범위: Base `7ef8d0b4` → Head `bbe944bd`(커밋 1개) 중 아래 pathspec. 90파일, +2,924 −454. + ```text + src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-mongo + src/adapter/outbound/persistence-fileserver src/adapter/outbound/persistence-notification + src/messaging src/adapter/outbound/messaging src/adapter/outbound/messaging-kafka + src/adapter/inbound/messaging src/application-notification docs/runbooks docs/messaging docs/jpa + docs/reviews/2026-11-01-maturity-review/06-messaging.md + ``` + `persistence-mongo`와 `adapter/inbound/messaging`은 이 커밋에 바뀐 파일이 없다. +- 맡은 1차 재리뷰 발견: RR-03-01~10, RR-05-01~10, 06-10~06-14. +- 새 발견 ID는 `RR-02-09`부터다. 1차의 `RR-02-01~08`은 inbound 영역의 발견이라 겹치지 않게 이어 붙였다. +- 읽은 방식: 하위 에이전트 없이 여러 번에 나눠 직접 읽었다. + 1. persistence-jpa main 전부(`JpaOutboxStore`, `OutboxEventJpaRepository`, floor entity, `OutboxEventEntity`, + `SpringTransaction`, `PersistenceExceptionTranslator`, V21·V22)와 build.gradle. + 2. persistence-jpa 테스트: `PostgreSqlOutboxOrderKeyRunbookIntegrationTest`, `PostgreSqlOutboxDispositionRunbookIntegrationTest`, + `OutboxRunbookSql`, `PostgreSqlOutboxAggregateSequenceIntegrationTest`, `SpringTransactionDeadlineTest`, + `PostgreSqlTransactionIntegrationTest` 추가분, `JpaOutboxStoreTest`, 아키텍처 규칙·fixture. + 3. runbook 두 개(`outbox-dead-letter.md`, `outbox-publish-failed.md`) 전문과 나머지 runbook diff. + 4. messaging bridge·relay 포트 diff, vendored messaging diff 전부(`KafkaConsumerRegistrar`, + `KafkaQuarantinePublisher`, `KafkaDeadLetterQuarantine`, `FailureDescriptor`, `MessagingShutdownLifecycle`), + `KafkaConsumerRegistrarTest` 추가분. + 5. notification·fileserver persistence diff, `ReconciliationJobWorker`(시도 한도가 실제로 걸리는지). +- 판단에 필요해서 pathspec 밖에서 읽은 것(전체 diff 리뷰는 아님): application-core의 `OutboxPublishAttempt`, + `PublishPendingOutboxEventsUseCase`, `OutboxEventStatus`, `OutboxAggregateSequencePort`, `IntegrationEventDraft`, + `IntegrationIdentity`, `SubmitDurableOperationUseCase`, `ReleasedPayloadSchemaContract`, `OutboxAggregateSequenceContract`, + `OverlappingWrites`; composition의 `OutboxSettings`, `OutboxRelayAutoConfiguration`, `OutboxMetrics`; + `DefaultMessagePublisher`의 기한 처리, `KafkaMessagingAutoConfiguration`의 producer 설정, `docs/registries/metrics.yaml` + outbox 항목, `docs/manual/09-outbox-events.md`. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +|---|---|---| +| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항 정합, mock이 아닌 실제 동작 테스트, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정, 읽지 않은 코드를 칭찬하지 않기 | 발견마다 "고치는 법"·4절 결정 대조, 테스트가 실제 DB·실제 문서를 쓰는지, V21·V22의 배포 경로 | +| `jpa-patterns` | Flyway 마이그레이션은 additive·재실행 가능, Hibernate는 validate만, 짧은 트랜잭션, 연관관계 규칙(사용자 원칙 "양방향 금지"를 스킬의 `mappedBy` 예시보다 우선) | V21·V22, `insertable/updatable=false` 필드의 실제 SELECT 동작(RR-02-13), `SingleSidedAssociationCondition`의 그래프 판정(RR-02-15), 트랜잭션 마감 분류 | +| `supabase-postgres-best-practices` | `lock-short-transactions`(DDL은 `lock_timeout`으로 잠금 대기를 묶는다), `data-upsert`(`ON CONFLICT`로 경쟁을 DB가 판정), `lock-skip-locked`, `schema-constraints`(제약·상태 값의 재실행 안전성) | V21 `lock_timeout`·무효 인덱스 거부·floor, V22의 잠금 대기(RR-02-09, 실 PG), counter `ON CONFLICT DO NOTHING` 경쟁, PARKED를 DDL 없이 둔 결정의 영향(RR-02-11) | +| `doubt-driven-development` | 주장(CLAIM)을 적고 반증을 시도한다 | 아래 7개 주장. 브리프가 하위 에이전트를 금지해 새 맥락 리뷰어 대신 자기 반증(축소 적용)으로 했다. 비대화 실행이라 교차 모델 검토는 건너뛰었다 | + +반증을 시도한 주장과 결과: + +1. "V21은 실패해도 다시 돌리면 된다" → 반증 못 함. 한 트랜잭션이라 lock_timeout·중복·무효 인덱스 실패 모두 V20에 남고, floor는 다시 돌 때의 시각으로 다시 기록된다. 해당 lane 테스트 3개가 확인한다. +2. "rolling 배포 중 옛 인스턴스의 벽시계 번호 뒤에 새 번호가 온다" → **일부 반증**. 같은 identity면 맞다. tenant scope가 바뀌는 배포에서는 옛 scope 행을 보지 못해 새 번호가 더 작다(RR-02-10, 실 PG). +3. "counter 첫 생성 경쟁에서 두 쓰기 모두 성공한다" → 반증 못 함. PG(공용 계약의 겹침 테스트)와 H2 PostgreSQL 모드(직접 실험) 둘 다 맞다. +4. "이번 라운드의 마이그레이션은 잠금 대기가 묶여 있다" → **반증**. V21은 5초로 묶었지만 같은 커밋의 V22는 ACCESS EXCLUSIVE를 상한 없이 기다리고, 그동안 outbox 읽기·쓰기가 모두 멈춘다(RR-02-09, 실 PG). +5. "runbook SQL은 lane이 문서에서 읽어 실 PG로 돌린다" → 반증 못 함. 두 lane이 system property로 문서 경로를 받고 문서를 Gradle 입력으로 선언한다. 표지 없는 SQL은 돌지 않는다(Declined 참고). +6. "draft의 UUIDv7 거부는 기존 데이터·재시도를 막지 않는다" → 반증 못 함. draft는 새 이벤트에만 쓰이고, 저장된 행 복원은 draft를 거치지 않는다. durable operation 재시도는 같은 UUIDv7을 다시 만든다. +7. "PARKED는 DDL 없이 안전하다" → **일부 반증**. 새 버전에서는 맞다. 옛 버전(배포 중·롤백 후)은 상태 이름을 몰라 `outbox.pending.size` 게이지 전체가 꺼진다(RR-02-11, 코드). + +### 실행한 명령과 결과 + +메인 작업 트리·index·HEAD는 바꾸지 않았다. Gradle은 돌리지 않았다. 실험은 scratchpad에 마이그레이션 파일을 복사해서 했다. + +| 명령 | 실행 직전 부하 | 결과 | +|---|---|---| +| `git diff --stat 7ef8d0b4..bbe944bd -- `, `git diff ...` | — | 90파일. 나눠서 전부 읽었다 | +| `java -cp h2-2.4.240.jar H2Check.java` (scratchpad, `nextSequence`의 세 문장을 그대로 H2 `MODE=PostgreSQL`에서 실행) | — | `first=1 second=2 third=3`, 이미 있는 counter에 생성 문장 → `0`. 두 연결 겹침: 첫째가 생성 후 커밋 보류, 둘째 `next=2`, 최종 `2`. 커밋에 적힌 "H2가 `ON CONFLICT DO NOTHING`을 받는다"를 확인 | +| `flock heavy.lock scratchpad/rr2-02/exp.sh` (postgres:16-alpine, 컨테이너 안 psql로 HEAD의 V1~V21 적용 후 실험) | load 16.65 | rc=0. 첫 시도는 다른 작업이 잠금을 잡고 있어 대기 중 시간 초과(rc=124)였고 재실행했다 | +| └ EXP1: 세션 A가 `outbox_event`를 읽은 트랜잭션을 20초 열어 둠 → 세션 B가 V22 실행 → 세션 C·D가 3초 제한으로 읽기·쓰기 | | `pg_locks`: A `AccessShareLock` granted, V22 `AccessExclusiveLock` 대기. C 읽기 `canceling statement due to statement timeout`(3.09초), D 쓰기 같은 오류(3.20초). **V22는 19.1초 기다린 뒤 rc=0** | +| └ EXP2: floor 뒤 30초에 옛 버전이 `portfolio` scope로 쓴 행(번호 floor+30,000,000) → 새 버전이 같은 aggregate를 `global` scope로 `nextSequence` 문장 실행 | | floor=1793718324464623, 옛 행=1793718354464623, **새 번호=1793718324464624(옛 행보다 작음)** | + +### 못 본 것 + +- Gradle lane을 직접 돌리지 않았다. `postgresqlOutboxDispositionRunbookIntegrationTest`·`postgresqlOutboxOrderKeyRunbookIntegrationTest`· + `postgresqlOutboxAggregateSequenceIntegrationTest`·Kafka relay lane·`KafkaConsumerRegistrarTest`의 통과는 재리뷰 README 7절 게이트 기록을 따랐다. +- persistence-jpa에 새로 들어온 fileserver PG 계약 테스트(`FileserverPostgreSqlStack`, `PostgreSqlFileQuotaLedgerContractTest` 등)는 + RR-01-04 몫이라 stack만 읽었다. 계약 케이스 목록은 01 영역 리뷰가 본다. +- 실제 Kafka·SIGTERM·다중 인스턴스 동시 기동은 실행하지 않았다. +- idempotency·redis·grpc·job-timeout runbook diff는 다른 영역 발견의 문서라 이 영역 코드와 모순이 없는지만 봤다. + +## Strengths + +- **counter 첫 생성 경쟁을 DB가 판정한다.** `JpaOutboxStore.java:125-139`는 `UPDATE` → `INSERT … ON CONFLICT DO NOTHING` → 다시 `UPDATE`다. 두 번째 쓰기는 첫째의 커밋을 기다렸다가 증가만 한다. 공용 계약 `OutboxAggregateSequenceContract.java:71`이 `OverlappingWrites`로 겹침을 운에 맡기지 않고 만들고, PG 테스트가 상속한다. H2 개발 경로도 직접 실험으로 같은 결과였다. +- **번호가 뒤로 가지 않게 두 겹으로 막았다.** 새 counter는 floor와 남은 행 최대값 중 큰 값 다음에서 시작한다(`OutboxEventJpaRepository.java:164`). 기존 counter의 증가도 그 aggregate의 가장 큰 행 아래로 내려가지 않는다(`:140`). 롤백 후 재배포처럼 옛 번호가 다시 섞여도 다음 번호가 그 뒤에 온다. +- **V21의 실패 경로를 실 PG로 고정했다.** 잠금 대기 초과(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java:227`), 실패한 CONCURRENTLY가 남긴 무효 인덱스 거부(`:263`), runbook대로 미리 만든 인덱스 재사용(`:298`), counter 선생성(`:185`)이 있다. 각 테스트가 "DB가 V20에 남는다"를 함께 단언한다. +- **runbook SQL이 문서 그대로 실행된다.** `OutboxRunbookSql`이 `` 블록을 문서에서 읽고, 두 lane이 문서를 Gradle 입력으로 선언한다(`persistence-jpa/build.gradle:252-260`). 재발행 테스트(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:63`)는 옛 SQL이면 실패하는 RED가 성립한다. "다음 claim이 그 행을 가져가는가"로 결과를 본다. +- **PARKED가 순서를 지키는지 실제로 본다.** 보류 행 뒤의 행이 claim되지 않음을 단언한다(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:149`). +- **마감 초과 분류를 자기가 연 트랜잭션으로 좁혔다.** `SpringTransaction.java:201-232`는 이 호출이 시작한 트랜잭션이고 마감이 지났고 다른 분류가 없을 때만 `translateAfterDeadline`을 부른다. 운영 조합(`JpaTransactionManager`)의 실 PG 테스트(`PostgreSqlTransactionIntegrationTest.java:305`)와 "업무 예외는 그대로" 테스트(`SpringTransactionDeadlineTest.java:113`)가 있다. +- **ACL이 원인 코드를 잃지 않는다.** bridge가 platform 코드를 그대로 옮기고, 문법 밖이면 platform의 category 이름으로 바꾼다(`PlatformIntegrationEventPublishAdapter.java:205-233`). 메시지가 아니라 이름만 옮긴다. +- **06-12 검사가 값이 만나는 곳에 있다.** 발행 포트만 아는 최악 시간과 설정이 relay 조립에서 만난다(`OutboxRelayAutoConfiguration.java:76`, `OutboxSettings.java:80`). Kafka `max.block.ms`를 같은 기본 기한으로 묶은 설정과 계산이 맞다. +- **정산 job의 버려진 claim이 시도로 셈된다.** `JdbcReconciliationJobStore.java:74`, 그리고 worker가 provider를 부르기 전에 한도를 본다(`ReconciliationJobWorker.java:111`). 매번 죽는 job도 끝난다. +- **격리 분류가 재시도 경로에서도 유지된다.** 읽을 수 없는 레코드는 첫 격리 쓰기가 실패해도 DESERIALIZATION으로 남는다(`KafkaConsumerRegistrar.java:351,357`, 테스트 `anUndecodableRecordStaysDeserializationWhenItsQuarantineIsRetried`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +|---|---|---| +| RR-03-01 | 닫힘 | `JpaOutboxStore.java:132-137`, `OutboxEventJpaRepository.java:169`. PG 겹침 계약 `OutboxAggregateSequenceContract.java:71`. H2 경로는 이 리뷰의 직접 실험으로 확인(E3) | +| RR-03-02 = RR-05-02 | 결정으로 닫힘(잔여 RR-02-10) | V21 floor(`V21:54-56`)·counter 선생성(`:58-65`), 생성 `GREATEST(MAX, floor)`, 증가 `GREATEST(last, MAX)`. PG 테스트 reaper·scope 변경·rolling(`PostgreSqlOutboxAggregateSequenceIntegrationTest.java:108,126`). manual 09에 첫 번호 안내. scope가 바뀌는 배포의 rolling 구간은 막지 못한다(RR-02-10, E3) | +| RR-03-03 | 닫힘 | `SpringTransaction.java:209,220`, `PersistenceExceptionTranslator.java:159-179`. H2 본문 flush·커밋 flush, 실 PG `JpaTransactionManager` 테스트 | +| RR-03-04 | 닫힘(잔여 RR-02-15) | `SingleSidedAssociationCondition.java:84-117` 그래프 판정, fixture `JoinColumnParentEntity`·`JoinColumnChildEntity`, 가이드 `entity-mapping-guide.md:75-91`. 서로 다른 두 FK를 양방향으로 오판한다(Minor) | +| RR-03-05 | 닫힘 | `V21:28-34` `lock_timeout 5s`, `:73-93` 고른 이유·무효 인덱스 거부, runbook §8 Step 0, lane 테스트 3개. 같은 커밋의 V22가 같은 종류의 빈틈을 새로 만들었다(RR-02-09) | +| RR-03-06 | 닫힘 | 두 `positional` helper와 그 테스트 삭제, Javadoc 정정(`CleanupClaimSql.java:17-19`) | +| RR-03-07 | 닫힘 | `WorkerCrashRecoveryContractTest` 이름·`as()`를 단언 범위로 줄이고 한국어 DisplayName, `CleanupClaimSqlTest` 이름을 "문장 텍스트"로 | +| RR-03-08 | 닫힘 | `JdbcReconciliationJobStore.java:74`, 한도 판정 `ReconciliationJobWorker.java:111`, 계약 `ReconciliationJobStoreContract` 추가분 | +| RR-03-09 | 닫힘 | `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`, `JpaProductionArchitectureTest`가 notification·fileserver에 적용, red/green fixture(`OrderEntityReader`) | +| RR-03-10 | 결정으로 닫힘 | `FailureCategory.java` Javadoc 첫 문장 "Not a transaction timeout", 이름 변경은 다음 호환성 깨짐 때로 기록 | +| RR-05-01 | 닫힘 | runbook §4 두 SQL에 `deferred_attempt_count = 0`, `runbook-sql` 표지와 실 PG lane, claim의 WARN이 `ATTEMPT_COUNTERS_INCONSISTENT`로 원인을 말함(`JpaOutboxStore.java:166-177`). CHECK 제약은 결정으로 넣지 않음 | +| RR-05-03 | 결정으로 닫힘(잔여 RR-02-11·12·14) | `OutboxPublishAttempt`, V22 `last_failure_code`, 실패 로그 `error.reason`, `outbox.retry.long.size/age` 게이지·registry·경보, PARKED와 runbook §4.1 SQL 4개(실 PG lane) | +| RR-05-04 | 닫힘 | `IntegrationEventDraft`가 비UUIDv7 event id·causation id 거부, durable operation은 결정적 UUIDv7 파생(`SubmitDurableOperationUseCase.java:177-193`), bridge 주석·README의 "until it does" 제거 | +| RR-05-05 | 닫힘 | 게이지가 자기 스레드(`OutboxMetrics` SmartLifecycle, `outbox-gauges`)에서 poll 주기로 갱신 | +| RR-05-06 | 닫힘 | registry `outcome` 허용 값에 RELEASED, IN_FLIGHT 제거, `OutboxStatusRegistryContractTest`가 outcome label도 비교 | +| RR-05-07 | 닫힘 | `FailureDescriptor` Javadoc, vendored 주석에서 소비자 이름 제거, `src/messaging/CLAUDE.md`에 수정 목록과 버린 대안 | +| RR-05-08 | 닫힘 | `MessagingShutdownLifecycle.java` POLL Javadoc 위치 복구. 같은 모양의 떨어진 Javadoc이 `OutboxEventEntity`에 새로 생겼다(RR-02-13) | +| RR-05-09 | 닫힘 | V21 주석의 클래스명, manual 09 문단, leader election 토큰 삭제, runbook `last_updated` | +| RR-05-10 | 닫힘 | 2026-11-01 README 12절 색인에 06-10~06-14와 정정 문단 | +| 06-10 | 닫힘(다른 방법, 이유 기록) | 출시한 schema 버전 해시 고정(`ReleasedPayloadSchemaContract`, application-core·sample 적용), manual 09 6단계. 버전 간 diff를 하지 않는 이유를 Javadoc에 적었다 | +| 06-11 | 닫힘 | `outbox-inbox.md` 머리말과 두 모델 상태 대응표, `configuration-reference.md` 문장 정정 | +| 06-12 | 닫힘 | `batch-size × longestAttempt ≥ in-flight-timeout`이면 기동 실패. 최악 시간 = 기본 기한 5초 × 2(Kafka `max.block.ms`) | +| 06-13 | 닫힘 | 낡은 문장 정정, `OutboxLeaderElectionToken` 삭제, `composition:outbox-relay`·`messaging-kafka` CLAUDE.md 신설 | +| 06-14 | 닫힘(잔여 RR-02-16) | 읽을 수 없는 레코드 DESERIALIZATION, 예산 소진은 실패의 category 또는 POISON_MESSAGE. 테스트는 SPI 인자를 단언하고 header 쓰기는 테스트가 없다 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-02-09 — V22가 `outbox_event`의 ACCESS EXCLUSIVE 잠금을 상한 없이 기다려, 그동안 outbox 읽기·쓰기가 모두 멈춘다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V22__outbox_event_last_failure_code.sql:20-21`. 비교: 같은 커밋의 `V21__outbox_aggregate_sequence.sql:28-34`, `docs/runbooks/outbox-dead-letter.md:119-122`. +- **무엇이 틀렸나**: + - V22는 `ALTER TABLE outbox_event ADD COLUMN`이다. 이 문장은 ACCESS EXCLUSIVE 잠금을 잡는다. + - 열려 있는 트랜잭션 하나가 `outbox_event`를 읽기만 했어도 V22는 그 트랜잭션이 끝날 때까지 기다린다. + - 기다리는 동안 뒤에 오는 모든 읽기·쓰기가 V22 뒤에 줄을 선다. ACCESS EXCLUSIVE는 읽기와도 충돌한다. + - V22에는 `lock_timeout`이 없다. 같은 커밋이 RR-03-05를 고치며 V21에 "Without a bound, the migration queues behind any open outbox write and every outbox write after it queues behind the migration"이라고 적고 5초 상한을 넣었다. 그 규칙이 바로 다음 마이그레이션에 빠졌다. +- **증거(E3, 실 PG 16)**: 세션 A가 `outbox_event`를 읽은 트랜잭션을 20초 열어 두었다. V22는 19.1초 기다린 뒤 적용됐다. 그동안 `pg_locks`에 V22의 `AccessExclusiveLock`이 granted=false로 있었다. 3초 제한을 건 일반 읽기(`SELECT count(*)`)와 일반 쓰기(`UPDATE`)가 둘 다 `canceling statement due to statement timeout`으로 끝났다. +- **왜 중요한가**: + - 발생 조건: V21 이하 DB를 올리는 첫 배포. Flyway는 기본으로 기동 때 돈다(`persistence-jpa.yml` `flyway.enabled: ${APP_FLYWAY_ENABLED:true}`). 옛 버전이 트래픽을 받는 rolling 배포 중이다. + - 영향: 기다리는 시간만큼 outbox를 쓰는 모든 업무 쓰기, relay claim, 모든 인스턴스의 게이지 갱신이 멈춘다. 멈춘 요청은 Hikari 연결을 쥔 채 기다리므로 outbox와 무관한 요청도 연결을 못 받을 수 있다. + - 기다리는 시간은 그 순간 가장 오래 열린, `outbox_event`를 건드린 트랜잭션의 남은 시간이다. 앱 트랜잭션은 30초 마감이 있다. 운영자가 runbook 조회를 `BEGIN` 안에서 하고 둔 psql 세션, 백업·분석 질의처럼 앱 밖의 세션에는 상한이 없다. + - 1차의 RR-03-05(같은 종류, V21)는 Low였다. 이것을 Medium으로 올린 이유: (1) ACCESS EXCLUSIVE는 SHARE와 달리 읽기까지 막아 relay와 게이지도 선다. (2) 이 라운드가 규칙과 이유를 V21·runbook에 적고 바로 옆 파일에서 어겼다 — 사용자 원칙 "위험은 코드에 드러나야 한다"에 걸리고, 같은 정책의 갈라진 복사본이다. +- **고치는 법**: + 1. V22 맨 앞에 `SET LOCAL lock_timeout = '5s';`와 이유 한 줄을 둔다. V22도 아직 어디에도 적용되지 않았으니 V21처럼 직접 고치고 `applied-migrations.sha256`을 갱신한다. + 2. `PostgreSqlOutboxOrderKeyRunbookIntegrationTest.v21GivesUpOnALock…`와 같은 테스트를 V22에 둔다. "읽기 트랜잭션이 잡고 있으면 V22는 실패하고 DB는 V21에 남는다". + 3. 다음 마이그레이션이 같은 빈틈을 다시 만들지 않게 `docs/jpa/migration-guide.md`에 "운영 중인 테이블에 잠금을 거는 DDL은 `SET LOCAL lock_timeout`을 둔다"를 적는다. 가능하면 마이그레이션 테스트가 `ALTER TABLE`/`CREATE INDEX`(비동시)가 있는 파일에 `lock_timeout`이 있는지 검사한다. + 4. runbook §8에 V22 실패 시 동작(롤백, V21에 남음, 새 버전 기동 실패)을 한 줄 더한다. +- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3. **통제**: V22에 대해 M0(V21은 M3). + +### Minor (Nice to Have) + +#### RR-02-10 — tenant scope가 바뀌는 배포의 rolling 구간에서는 새 번호가 옛 버전이 막 쓴 번호보다 작다 + +- **위치**: `docs/runbooks/outbox-dead-letter.md:124-131`, `src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxAggregateSequencePort.java:29-31`, `OutboxEventJpaRepository.java:140-169`. +- **무엇이 틀렸나**: + - floor는 V21이 돈 순간의 값이다. rolling 중 옛 버전은 그 뒤에도 벽시계 번호(초당 10⁶씩 커짐)를 쓴다. + - 새 버전의 `GREATEST(…, MAX(행))`는 같은 identity의 행만 본다. + - 샘플처럼 scope를 바꾸면 옛 버전은 `portfolio`로, 새 버전은 `global`로 쓴다. 새 번호는 floor+1부터라 옛 버전이 방금 쓴 번호보다 작다. + - runbook 124행은 rolling 중 새 번호가 "그 행 뒤에" 온다고 말한다. 포트 계약은 "written under an identity that has since changed" 행보다도 크다고 약속한다. 두 문장이 이 경우에 틀린다. + - runbook 128행의 대응은 "배포 전에 옛 scope 미발행 행 확인"뿐이다. 배포 중에 옛 버전이 새로 쓰는 행은 다루지 않는다. +- **증거(E3)**: 실 PG에서 floor+30초 번호의 `portfolio` 행 뒤에 `global` scope로 `nextSequence` 문장을 돌리자 floor+1이 나왔다. +- **왜 중요한가**: scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한 소비자는 rolling 구간의 새 이벤트를 버린다. 발생은 scope를 바꾸는 배포(현재는 샘플)에 한정된다. +- **고치는 법**: runbook §8에 "scope를 바꾸는 배포는 옛 writer를 모두 멈춘 뒤(혼합 버전 금지) 한다"를 적는다. 포트 Javadoc의 그 구절을 "배포 전에 쓰인 행"으로 좁힌다. 또는 샘플만 옛 scope를 유지한다. +- Low · P3 · E3. + +#### RR-02-11 — PARKED 행이 하나라도 있으면 옛 버전 인스턴스의 `outbox.pending.size` 게이지가 통째로 꺼진다 + +- **위치**: `JpaOutboxStore.java:264`(`OutboxEventStatus.valueOf`), 옛 버전 같은 줄(`7ef8d0b4`·`origin/main`의 `countByStatus`), `V22__outbox_event_last_failure_code.sql:16-19`(PARKED는 DDL 없음). +- **무엇이 틀렸나**: `countByStatus`는 DB의 상태 문자열을 enum `valueOf`로 바꾼다. PARKED를 모르는 옛 버전은 `IllegalArgumentException`을 던지고, 게이지 갱신은 그 상태 하나가 아니라 전체가 실패한다(WARN). rolling 배포 중의 옛 인스턴스와, 운영자가 행을 보류한 뒤 롤백한 버전이 해당한다. DB CHECK가 없으니(결정) 수동 SQL 오타 상태값도 같은 일을 일으킨다. +- **왜 중요한가**: 보류는 장애 중에 하는 일이고, 장애 중 롤백은 흔하다. 그때 `PENDING size growing` 경보의 입력이 사라진다. 결정(DDL 없음·CHECK 없음)을 뒤집자는 것이 아니라 그 결정이 만든 호환성 위험이다. +- **고치는 법**: `countByStatus`가 모르는 상태를 건너뛰거나 `UNKNOWN`으로 모아 세게 한다(새 버전부터라도 이후 상태 추가에 대비). runbook §4.1 Step 2에 "롤백한 버전은 PARKED를 모른다 — 게이지가 꺼지므로 롤백 전에 resume 또는 skip"을 적는다. +- Low · P3 · E1. + +#### RR-02-12 — claim이 DEAD로 옮긴 행은 `last_failure_code`가 낡은 값으로 남고 DEAD 경보도 울리지 않는다 + +- **위치**: `JpaOutboxStore.java:166-189`, `OutboxEventEntity.java:70`(`updatable = false`), `docs/runbooks/outbox-dead-letter.md` §1·§2 Step 1. +- **무엇이 틀렸나**: + - claim 때의 DEAD 전이(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 entity flush로 쓴다. `lastFailureCode`는 읽기 전용이라 이 경로는 원인 코드를 행에 쓰지 못한다. 행에는 이전 재시도의 코드(예: `KAFKA_AUTHENTICATIONEXCEPTION`)가 그대로 남는다. + - 이 경로는 relay 결과를 거치지 않아 `outbox.publisher.published.total{outcome=DEAD}`가 오르지 않는다. runbook §1의 경보 조건이 이 카운터다. `outbox.pending.size{status=DEAD}`에는 경보가 없다. +- **왜 중요한가**: 운영자가 `SELECT … WHERE status='DEAD'`로 보면 원인을 잘못 읽는다. 경보도 없어 WARN 로그를 찾지 않으면 모른다. 카운터 공백은 1차 RR-05-01이 적은 기존 문제이고, 낡은 원인 코드는 V22가 새로 만든 부분이다. +- **고치는 법**: claim의 DEAD 전이를 조건부 UPDATE로 바꿔 `last_failure_code`에 `error.reason`과 같은 값을 쓴다. `outbox.pending.size{status=DEAD} > 0`을 경보 조건에 더하거나 claim DEAD도 카운터에 센다. +- Low · P3 · E1. + +#### RR-02-13 — `OutboxEventEntity`에 주인 없는 Javadoc이 생겼고, 새 필드 주석이 사실과 다르다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/jpa/entity/OutboxEventEntity.java:60-74`. +- **무엇이 틀렸나**: + - `nextAttemptAt`의 Javadoc("Dual-purpose per status …", 60행)이 새 필드의 Javadoc 바로 위로 떨어졌다. `nextAttemptAt`(74행)에는 설명이 없어졌다. 이 커밋이 RR-05-08로 고친 것과 같은 모양이다. + - 새 필드 주석은 append·claim이 "need the column on a database that has not run V22 yet"가 아니라고 말한다. `insertable/updatable = false`는 INSERT·UPDATE에서만 빠진다. Hibernate는 SELECT에 이 열을 넣으므로 claim은 V22 없는 DB에서 실패한다. +- **고치는 법**: 60행 주석을 `nextAttemptAt` 위로 옮긴다. 새 필드 주석의 V22 문장을 "INSERT와 flush는 이 열을 쓰지 않는다"로 줄인다. +- Low · P3 · E1. + +#### RR-02-14 — "오래 재시도" 기준 10이 세 곳에 따로 적혀 있고 서로 묶여 있지 않다 + +- **위치**: `src/composition/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java:52`, `docs/runbooks/outbox-publish-failed.md:97`, `src/composition/outbox-relay/README.md:118`. +- **무엇이 틀렸나**: 게이지는 상수를, runbook SQL은 리터럴 `10`을 쓴다. runbook은 "같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다"고 말하지만 이를 확인하는 테스트가 없다. runbook lane의 테스트 데이터(12와 1)는 상수가 2~12 사이로 바뀌어도 통과한다. +- **왜 중요한가**: 상수만 바꾸면 경보가 센 행과 runbook 조회가 보여 주는 행이 달라진다. 사용자 원칙의 "갈라진 복사본"이다. +- **고치는 법**: 문서 계약 테스트(`document-contract`)가 runbook 블록의 숫자와 상수를 비교한다. 또는 disposition lane이 경계값(기준-1, 기준)으로 runbook 조회와 `longRetries`를 같이 단언한다. +- Low · P3 · E1. + +#### RR-02-15 — 서로 다른 두 FK로 서로를 가리키는 두 엔티티를 양방향 쌍으로 오판한다 + +- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/SingleSidedAssociationCondition.java:84-117`, `docs/jpa/entity-mapping-guide.md:84-91`. +- **무엇이 틀렸나**: 규칙은 A의 연관이 B를, B의 연관이 A를 가리키면 위반으로 본다. `Order.@OneToOne latestInvoice`와 `Invoice.@ManyToOne order`처럼 FK가 둘인 두 단방향 링크도 걸린다. 메시지는 "two fields map one link"라고 하지만 링크가 둘이다. 같은 클래스 안의 두 링크(manager·mentor)는 예외로 두면서 두 클래스 사이의 같은 모양은 예외가 없다. +- **왜 중요한가**: 금지 쪽으로 틀린 것이라 데이터 위험은 없다. 개발자가 정당한 모델을 바꾸거나 규칙을 끄는 쪽으로 밀린다. 이유를 말하는 메시지가 틀리면 규칙을 믿지 않게 된다. +- **고치는 법**: 같은 join column을 두 쪽이 매핑하는지(`@JoinColumn` 이름 비교, 또는 `@OneToMany`↔`@ManyToOne`·`@ManyToMany`↔`@ManyToMany` 짝)로 좁힌다. 아니면 가이드와 메시지를 "서로 가리키는 연관은 FK가 달라도 금지"로 고쳐 의도를 적는다. 어느 쪽이든 그 모양의 fixture를 둔다. +- Low · P3 · E1. + +#### RR-02-16 — 06-14의 header 쓰기는 테스트가 없고, 공개 SPI 시그니처 변경이 깨지는 변경 목록에 없다 + +- **위치**: `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java:42-52`, `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java:36`, 재리뷰 README 8절. +- **무엇이 틀렸나**: + - 06-14 완료 기준은 "두 경로가 다른 header 값을 남긴다"다. 새 테스트는 registrar가 SPI에 넘기는 category만 본다. category를 `msg.failure-category` header로 쓰는 `KafkaDeadLetterQuarantine`에는 테스트가 없다. + - `KafkaQuarantinePublisher.quarantine`에 인자가 하나 늘었다. 파생 서비스가 이 public SPI를 구현했다면 컴파일이 깨진다. README 8절의 "소유자 확인이 필요한 결정"은 발행·저장소 포트 변경만 적는다. +- **고치는 법**: `KafkaDeadLetterQuarantine` 단위 테스트에서 두 category의 header 바이트를 단언한다. 깨지는 변경 목록에 SPI 변경을 더한다. +- Low · P3 · E1. + +## Declined to judge + +- `ValidatedIntegrationEvent`는 public record라 draft를 거치지 않고 만들면 UUIDv7 검사를 건너뛴다 — 운영 코드의 생성처는 encoder와 저장 행 복원 둘뿐이고, 테스트의 v4 id는 의도된 것이다. +- 06-12의 최악 시간에 platform admission 대기(최대 남은 기한)가 들어 있지 않다 — relay는 한 번에 하나씩 보내고, 템플릿에는 같은 destination에 직접 발행하는 다른 publisher가 없다. +- 06-12 검사는 `<`라 행마다의 DB 쓰기 시간을 위한 여유가 없다 — 기본값(200초 대 300초)에서는 여유가 크다. +- `translateAfterDeadline`은 원인 사슬 전체를 본다. 마감이 지난 뒤 `DataAccessException`을 cause로 감싼 업무 예외는 `DB_QUERY_CANCELED`로 바뀐다 — 그렇게 감싸는 코드를 찾지 못했다(`PosterRepositoryAdapter`는 cause를 넘기지 않는다). +- 두 aggregate를 서로 다른 순서로 쓰는 두 트랜잭션의 counter 행 교착 — 1400dc15부터 있던 성질이고 이번 수정이 바꾸지 않았다. +- REPEATABLE READ에서 `ON CONFLICT DO NOTHING`은 직렬화 실패를 낸다 — 템플릿은 풀에서 READ COMMITTED를 강제하고 기동 검사가 있다(09-05). +- 옛 인스턴스의 시계가 DB보다 느려 floor 아래 번호를 쓰는 경우 — 옛 벽시계 방식이 보장하지 않던 것이고 runbook이 그렇게 적는다. +- V21의 `IF NOT EXISTS`는 같은 이름의 "다른 열" 유효 유일 인덱스를 받아들인다 — runbook 문장을 그대로 쓰면 생기지 않는다. +- runbook의 표지 없는 SQL(§2 차단 범위 조회, §8 scope 확인, `DROP INDEX CONCURRENTLY`)은 lane이 돌리지 않는다 — runbook 문장이 시험되는 범위를 정확히 적는다. 모든 `runbook-sql` 표지가 어느 테스트에서 쓰이는지 검사하는 장치는 없다. +- runbook lane이 문서 절대 경로를 `systemProperty`로 받아 build cache가 다른 경로에서 재사용되지 않는다 — 기존 lane과 같은 방식이고 정확성 문제는 아니다. +- idempotency runbook의 "action 자신의 트랜잭션 안 효과는 롤백된다" — 호출자가 executor를 트랜잭션으로 감쌀 때 참이다(샘플은 감싼다). inbound 영역 몫이다. +- 06-10이 버전 간 schema diff 대신 출시 버전 불변을 고른 것 — 이유가 Javadoc에 있고, 새 버전은 소비자가 먼저 읽는 절차(application-core README)를 따른다. + +## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가 + +**있다. 1건(RR-02-09).** 이 라운드에서 새로 들어온 V22가 V21에 넣은 잠금 대기 상한을 빠뜨렸다. 실 PG에서 읽기·쓰기가 모두 막히는 것을 확인했다. + +고치는 범위는 좁다. V22 한 줄, 같은 모양의 lane 테스트 하나, migration-guide 규칙 한 줄이다. 맡은 1차 발견 25건(RR-03 10건, RR-05 10건, 06-10~14)은 모두 닫혔거나 결정으로 닫혔고 회귀는 없다. 새 Minor 7건 중 6건은 이번 수정이 만든 잔여·문서 불일치이고, 데이터 손상으로 이어지는 것은 없다. + +그래서 이 영역은 전체 재리뷰 라운드가 아니라 RR-02-09만 고치고 그 lane을 돌리는 좁은 수정으로 수렴할 수 있다고 본다. + +## Assessment + +**Ready to merge? With fixes.** + +순서 번호·runbook SQL·원인 코드·PARKED·마감 분류는 결정대로 구현됐고 실제 PG·문서 원문으로 검증된다. 다만 같은 커밋의 V22가 outbox 테이블 잠금을 상한 없이 기다려 배포 중 outbox 읽기·쓰기를 멈출 수 있으므로(RR-02-09, E3), V22에 `lock_timeout`과 그 테스트를 넣은 뒤 병합한다. diff --git a/docs/reviews/2026-11-03-rereview/round2/03-outbound.md b/docs/reviews/2026-11-03-rereview/round2/03-outbound.md new file mode 100644 index 00000000..904573f6 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round2/03-outbound.md @@ -0,0 +1,268 @@ +# 03 outbound 재리뷰 (2026-11-03) + +> 2차 재리뷰. 대상은 재리뷰 수정 커밋 `bbe944bd`(Base `7ef8d0b4`)의 outbound capability 영역이다. +> 경로는 따로 적지 않으면 `src/adapter/outbound/`를 생략한다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +- `src/adapter/outbound/{support, identifier, redis-runtime, redis-sdk, cache-redis, httpclient, objectstorage, notification, fileserver}`, + `docs/httpclient`, `docs/notification`, `docs/registries/metrics.yaml`, `infra/redis-sdk`. + `git diff --stat 7ef8d0b4..bbe944bd -- ` 기준 78파일, +2,750 −364. diff 전체를 읽었다. +- 재확인한 1차 발견: RR-04-01·02·03·05~11(RR-04-04 제외), RR-07-03, RR-07-04, RR-07-07. +- pathspec 밖 파일은 판정에 필요한 줄만 읽었다: `application-core` `IdempotencyExecutor`·`IdempotencyClaimRequest`, + `composition/idempotency` `IdempotencySettings`·`idempotency.yml`, `persistence-notification` `JpaProviderEventLedger`, + `persistence-jpa` 멱등성 claim SQL·reaper, `app-bootstrap` `SecretSourceValidator`, `docs/runbooks/redis-capability-incident.md`, + `docker-compose.infra.yml`, `.github/workflows/object-storage-qualification.yml`. +- 이 문서의 새 발견 ID는 `RR-03-11`부터다. 1차의 `RR-03-01~10`(그때 03 영역은 persistence)과 겹치지 않게 이어서 매겼다. + 01 영역 2차 리뷰어(`RR-01-11~`)와 같은 방식이다. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(1차 "고치는 법"·4절 결정) 대비 정렬, Critical/Important/Minor, 읽은 코드에만 판정 | 출력 양식 전체, 발견 재확인 표 | +| `performance-optimization` | "추정 말고 잰다", 바꾼 뒤 다시 잰다, 측정이 잡음 안이면 문제로 올리지 않는다 | JDK read-idle 타이머의 read당 비용과 JVM 전체 상한(측정해 Minor로), lane 대기 Timer의 borrow당 등록 비용(측정 결과 무시할 수준이라 기각), 캐시 전용 lane의 연결 예산 | +| `observability-and-instrumentation` | 태그는 닫힌 작은 집합, 지표가 on-call 질문에 답하는가, 계측 실패가 결과를 바꾸지 않되 보이는가, runbook이 실제 신호를 가리키는가 | `redis.lane.*` 태그·histogram 버킷, listener 실패 격리·로그 수준, opened 지표의 뜻, 레지스트리·runbook과 코드의 일치 | +| `security-and-hardening` | trust boundary마다 "누가 이 값을 썼나", STRIDE의 R(감사)·D(자원), 공개 비밀값, 서명 범위 | SNS 인증서 4xx를 위조로 보는 근거, `MessageId`가 서명 문자열 안인지, `fixture-` 비밀 거부, ACL fixture 표기 | + +### 실행한 명령과 결과 + +checkout은 바꾸지 않았다. Gradle과 worktree는 쓰지 않았다. 탐침은 `git show bbe944bd:`로 꺼낸 사본을 scratchpad에서 +컴파일했고, Redis는 버리는 컨테이너 하나로 돌렸다. + +| 명령 | 결과 | +| --- | --- | +| `git diff --stat` / `git diff 7ef8d0b4..bbe944bd -- ` | 78파일 | +| `javap java.io.FilterInputStream`, `javap java.io.InputStream`, `javap --module java.net.http 'jdk.internal.net.http.ResponseSubscribers$HttpResponseInputStream'` | `FilterInputStream`은 `transferTo`·`readAllBytes`를 재정의하지 않는다 → 감시되는 `read(byte[],int,int)`를 지난다. JDK 응답 stream은 `skip`을 재정의하지 않는다 → `InputStream.skip`이 `read`를 여러 번 부른다 | +| `javap -c` Spring 7.0.9 `JdkClientHttpRequest`(Gradle cache) | `disallowedHeaders()`가 `jdk.httpclient.allowRestrictedHeaders`를 읽는다 | +| `SkipProbe` — `bbe944bd`의 `ReadIdleInputStream`, 100ms마다 1바이트 주는 stream 30바이트, read-idle 1s | `readAllBytes`: 30바이트 3,018ms 성공. **`skip(30)`: 1,001ms에 `SocketTimeoutException`**(공백은 모두 100ms) | +| `Bench` — `guarded()`와 같은 `completeOnTimeout` 걸기 + `cancel` 반복 | 1스레드 3.9~4.6µs/회. 8·32스레드에서 JVM 전체 0.35~0.51M회/초에서 멈춘다. 측정 당시 load average 14~22(22코어) | +| `TimerBench` — Micrometer 1.16.7 `SimpleMeterRegistry` | borrow마다 `Timer.builder(..).register(..).record(..)` 152~241ns, 미리 만든 Timer `record` 64ns. Redis 왕복(100µs 이상)에 비해 무시할 수준 → 발견으로 올리지 않음 | +| `docker run redis:7.4`(로컬 이미지 `b6b6e3dc0c09`, 고정 digest와 같은 id) + `bbe944bd`의 CLAIM Lua를 `redis-cli EVAL` | owner A claim(lease 3000ms, replay TTL 1000ms) → `ACQUIRED`, `PTTL 996`. 1.3s 뒤 `EXISTS 0`. owner B claim → **`ACQUIRED`**. A의 lease는 1.7s 남아 있었다 | + +### 못 본 것 + +- Gradle 테스트와 게이트는 다시 돌리지 않았다(재리뷰 README 7절을 읽기만 했다). +- Redis 컨테이너 lane·topology lane, MinIO·Toxiproxy lane은 돌리지 않았다. 캐시 전용 배포의 ACL probe가 실제 Redis의 + 거절 메시지(`NOPERM …`)를 맞게 분류하는지는 합성 메시지 테스트로만 확인됐다. +- 실제 AWS SNS 인증서 호스트가 없는 인증서에 주는 status, VPC endpoint 경유 동작은 확인하지 못했다. +- JDK HTTP/2 스트리밍, TLS 소켓을 JVM 공용 delay 스레드에서 닫을 때의 지연은 보지 않았다. +- PostgreSQL 멱등성 저장소(claim SQL, reaper)는 RR-03-11의 범위를 가늠하려고 읽기만 했다. +- `app-bootstrap` `SecretSourceValidator`는 RR-07-04 판정에 필요한 diff만 읽었다. + +## Strengths + +- breaker가 deadline 출처를 구분한다. `Deadline.Source`(`httpclient/.../resilience/Deadline.java:28`)를 계산기가 정하고, 같으면 + profile 쪽으로 기운다(`DeadlineCalculator.java:24-26`). 호출자 deadline으로 끝난 시도는 `releasePermission()`으로 permit만 + 돌려준다(`AttemptResiliencePipeline.java:136-137`). 회귀 테스트가 두 transport × 두 출처를 실제 서버로 본다 + (`CircuitBreakerStatusAccountingTest.java:178,221`). +- JDK 스트리밍이 setup 전용 scope를 따로 연다(`AttemptDeadline.openStreamSetup`, `BlockingStreamingGateway.java:86`). 그래서 + setup 상한과 본문 gap 상한이 섞이지 않는다. 테스트는 헤더 timeout·전체 예산보다 긴 본문과 read-idle보다 긴 공백을 두 + transport에서 모두 본다(`StreamingBodyLifetimeTest`). +- 캐시 전용 lane의 결정이 코드에 남아 있다. 버린 대안 둘과 이유가 `CacheScriptLane.java:20-24`와 README + 「Why the cache has its own script lane」(`cache-redis/README.md:192`)에 있다. lane 분리를 SCRIPT 1개를 잡은 상태로 + 증명하는 테스트가 있다(`RedisCacheRegionAdapterTest.java:442`). +- lane 지표가 닫힌 이름만 태그로 쓴다. 거절·폐기 counter는 기동 때 0으로 미리 만든다(`RedisLaneMetrics.java:89-108`). + listener는 lock 밖에서 부르고, 실패해도 borrow를 깨지 않는다(`RedisRuntimeOwner.java:350-356`, 테스트 + `RedisLaneMetricsTest.java:277`). +- renew의 TTL 연장이 같은 Lua 안에 있어 원자적이다(`IdempotencyScripts.java:186-189`). 공유 계약에 실제 시간이 흐르는 경우가 + 생겼고(`IdempotencyStoreContract.java:373`), 시계를 못 움직이는 저장소는 통과 대신 abort로 보고된다. +- ACL probe가 "거절"을 허용 목록으로 판정한다(`RedisSemanticScriptAclProbe.java:124-145`). 끊김·`LOADING`·`BUSY`는 기동을 + 막지 않고, 읽은 값이 틀린 경우는 막는다. 둘 다 테스트가 있다. +- `MessageId`는 서명 검증을 통과한 envelope에서만 읽는다(`SesCallbackAdapter.java:126-129`). ledger가 두 유일 인덱스를 모두 + 먼저 조회하고 `ON CONFLICT DO NOTHING`을 대상 없이 쓴다(`JpaProviderEventLedger.java:237`). 그래서 event id가 새로 생겨도 + 제약 위반 예외가 아니라 중복으로 답한다. +- SNS 인증서 4xx 중 408·429를 장애 쪽에 남겼다(`NotificationCallbackProviderConfig.java:93`). 검증기는 + `IllegalArgumentException`을 서명 실패로 바꾼다(`SnsSignatureVerifier.java:89`). +- 기동 rule이 앞당긴 bean을 이름으로 보고한다(`StartupRuleRunner.java:66-81`). 정적·무인자 `RequiredProductionSecrets`만 + 예외로 두고, 그 이유가 Javadoc에 있다. +- 파일 소유자 규칙이 한 벌이 됐다(`RoleBasedFileAccessPolicy.java:78`의 `subject.owns`). 운영 policy가 fake와 같은 계약을 + 상속한다(`RoleBasedFileAccessPolicyContractTest`). + +## 발견 재확인 표 + +| ID | 상태 | 근거 | +| --- | --- | --- | +| RR-04-01 | 닫힘 | `BlockingAttemptExecutor.java:156` `deadline.setByCaller() && scope.expired()` → `AttemptResiliencePipeline.java:136-137` `releasePermission()`. total-call로 끊긴 시도는 계속 센다(결정). 두 transport 회귀 테스트. 남은 문서 공백은 RR-03-16 | +| RR-04-02 | 닫힘(4절 결정대로) | 캐시 조건부 쓰기가 `CacheScriptLane.CACHE_SCRIPT`(기본 4)로(`RedisCacheRegionAdapter.java:138`, `RedisCacheConfig.java:74-79`). 기여 조건이 캐시 region bean과 같다(`:37`, `:74`). lane별 대기·거절·재연결 지표(`RedisLaneMetrics`). 문서 표류는 RR-03-17 | +| RR-04-03 | 닫힘 | `DeadlineAwareJdkRequestFactory.java:49` → `JdkStreamingClientHttpRequest`, 본문은 `ReadIdleInputStream`, 실패는 `ClassifiedBodyInputStream`. 두 transport 테스트. 새 Minor 넷: RR-03-12(skip), RR-03-13(read당 타이머 비용), RR-03-14(unchecked 예외), RR-03-15(헤더 목록 사본) | +| RR-04-05 | 닫힘 | `cache-redis/build.gradle:89` `requires`에 `LiveRedisIdempotencyStoreContractTest`. CLAUDE.md 목록도 맞췄다. 결과적으로 lane은 `integrationCheck`에서만 돈다(mainCheck 중복 제거). README 목록 누락은 RR-03-18 | +| RR-04-06 | 닫힘 | `package-info.java`, `identifier/CLAUDE.md` Allowed 4개, README가 `build.gradle`과 `modules.json`(`domain-core, application-core, shared-contract`)에 맞는다 | +| RR-04-07 | 닫힘 | `RedisSemanticScriptAclProbe.java:124-145` 허용 목록 판정, `LOADING`·끊김·`BUSY` 테스트. 실제 서버 메시지로는 미확인(못 본 것) | +| RR-04-08 | **부분** | renew는 고쳤다(`IdempotencyScripts.java:186-189`, 계약 `:373`). claim·takeover는 여전히 key TTL을 replay TTL로 둔다(`:44,77`). replay TTL < processing lease면 lease 중에 key가 사라진다 → RR-03-11(E3) | +| RR-04-09 | 닫힘 | `StartupRuleRunner.java:66-81,103-131`(RR-06-01과 같은 수정), 테스트 3건(non-static 규칙, 비정적 secrets, 정적 secrets 허용) | +| RR-04-10 | 닫힘 | 순서 키가 `redis-runtime/.../module-defaults/redis-runtime.yml`로 옮겨졌고 cache-redis에서는 빠졌다(중복 키면 기동 실패라 한 곳뿐). `RedisRuntimeHealthStatusOrderTest` | +| RR-04-11 | 닫힘 | `JavaMailSenderSmtpDispatch.java:120` `400 <= code < 600`, 테스트 | +| RR-07-03 | 닫힘 | 4xx(408·429 제외) → `IllegalArgumentException` → 서명 실패 → 거절·감사. 5xx·408·429·IO → 503. `SnsCertificateFetchTest`. 4xx가 SNS 자신의 답이라는 가정은 Declined to judge | +| RR-07-04 | 닫힘 | 파일 이름 `lane-fixture-accounts.acl`, `acl/README.md`가 "배포 파일 아님"과 계정 구성을 실제대로 적는다, compose 4개·`docker-compose.infra.yml` 주석, `SecretSourceValidator`가 prod에서 `fixture-` 값 거부. 프로필 범위는 Declined to judge | +| RR-07-07 | 닫힘 | SES 이벤트의 `provider_event_id` = SNS `MessageId`(`SesEventNormalizer.normalize(payload, id)`), Javadoc이 실제 인덱스를 적는다. fingerprint는 event id를 입력으로 쓰지 않아 배포 경계의 재전송도 중복으로 잡힌다(`AesGcmCallbackPayloadProtection.java:112-124`) | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR-03-11 · replay TTL이 processing lease보다 짧으면 Redis 멱등성 key가 lease 도중 사라져, 같은 키의 두 번째 요청이 작업을 다시 돌린다 (RR-04-08 부분) + +- **위치**: `cache-redis/.../idempotency/IdempotencyScripts.java:44`(claim `PEXPIRE ARGV[7]` = replay TTL), `:77`(takeover도 같음), + `:186-189`(renew만 늘림). 설정: `src/composition/idempotency/.../IdempotencySettings.java:57,65`(lease와 replay TTL을 따로만 검사), + `src/application-core/.../IdempotencyClaimRequest.java:23-24`(관계 검사 없음), `idempotency.yml`의 `replay-ttl: ${APP_IDEMPOTENCY_TTL:24h}`. +- **무엇이 틀렸나**: + - 이번 수정은 "key TTL이 lease보다 먼저 끝나면 실행 중에 key가 사라져 같은 부작용이 다시 돈다"를 renew 경로에서만 막았다. + 수정 Javadoc 자신이 원인을 "Claim sets it to the replay TTL, which may be shorter than a lease"라고 적는다. + - claim은 여전히 key TTL을 replay TTL로 둔다. replay TTL이 processing lease보다 짧은 설정은 거부되지 않는다. + `processing-lease`는 `IN_FLIGHT_RETRY_AFTER`보다 길어야 한다는 검사만 있고, `replay-ttl`은 72h 상한만 있다. + - 그 설정에서 action이 replay TTL보다 오래 걸리면 key가 lease 도중 사라진다. 다음 claim은 `ACQUIRED`를 받고 executor는 + 작업을 처음부터 돌린다(`IdempotencyExecutor.java:132-133`). 첫 실행은 아직 진행 중이다. +- **왜 중요한가**: + - 멱등성이 막으려는 바로 그 피해다. 외부 호출·메일 같은 트랜잭션 밖 효과가 두 번 일어난다. 두 실행이 동시에 돈다. + - 발생 조건: `provider=redis` + `APP_IDEMPOTENCY_TTL` < `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s) + action이 replay TTL보다 + 오래 걸림 + 그동안 같은 키 재전송. 변수 이름이 `..._TTL`이고 env 레지스트리 설명도 "완료 응답을 재생하는 시간"뿐이라, + "짧은 재생 창"을 원해 10s를 넣는 설정은 그럴듯하다. 두 값의 관계는 어디에도 적혀 있지 않다. 사용자 원칙의 "숨은 위험"이다. + - 탐지가 어렵다. 두 번째 요청은 정상 `ACQUIRED` 경로라 로그·지표에 이상이 없다. + - RR-01-11(만료된 `EXECUTING`을 `RECOVERY_REQUIRED`로)을 고쳐도 이 경로는 남는다. 기록이 lease가 끝나기 전에, 또는 renew 뒤 + lease와 같은 순간에 사라지므로 "만료된 EXECUTING"을 볼 기록이 없다. renew가 TTL을 lease와 정확히 같게 두기 때문이다(`:187-188`). + - PostgreSQL 저장소도 claim에서 `expires_at = now + replay TTL`을 쓰고 reaper가 상태와 lease를 보지 않고 지운다 + (`IdempotencyClaimGateway.java:44`, `IdempotencyRecordJpaRepository.java:22-24`, E1). reaper 주기만큼 늦을 뿐 같은 원인으로 보인다. +- **고치는 법**: + 1. 설정에서 막는다(두 저장소를 한 번에): `IdempotencySettings`가 `replay-ttl < processing-lease`이면 기동 실패. env 레지스트리와 + `idempotency.yml` 주석에 관계를 적는다. 고른 방법·버린 대안을 Javadoc에 남긴다. + 2. 저장소도 스스로 지킨다: Redis claim·takeover·renew가 key TTL을 `max(replay TTL, lease + 여유)`로 둔다. 여유는 RR-01-11의 + 만료 처리가 기록을 볼 수 있을 만큼(예: replay TTL)이다. "lease와 정확히 같은 TTL"은 피한다. + 3. 계약에 시간 경우 하나: "replay TTL보다 긴 lease로 claim하면 lease 안의 다른 claim은 `InProgress`". Live Redis·PG lane이 실제로 돈다. +- **가이드 심각도·우선순위**: Medium · P2. 피해는 High급(업무 중복 실행)이지만 비기본 설정에서만 도달한다. 기본 조립은 멱등성 비활성. +- **증거**: E3 — `redis:7.4` 컨테이너에서 `bbe944bd`의 CLAIM Lua를 직접 실행. lease 3000ms·replay TTL 1000ms claim → 1.3s 뒤 + key 없음 → 다른 owner claim `ACQUIRED`(A의 lease 1.7s 남음). 설정 경로(`IdempotencySettings`→executor→claim)는 E1. + 이번 라운드가 만든 결함은 아니다. 1차 RR-04-08이 renew만 짚었고, 같은 원인의 claim 경로가 남았다. + +### Minor (Nice to Have) + +#### RR-03-12 · JDK `ReadIdleInputStream.skip`이 gap이 아니라 skip 전체 시간을 read-idle로 묶는다 + +- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:49-51`(`skip`을 `guarded` 한 번으로), `:53-57`. +- **무엇**: JDK 응답 stream은 `skip`을 재정의하지 않는다. 그래서 `InputStream.skip`이 안에서 `read`를 여러 번 부른다. 타이머는 + 그 묶음 전체에 한 번 걸린다. 데이터가 꾸준히 와도 큰 `skip`이 read-idle보다 오래 걸리면 거짓 `SocketTimeoutException`이 나고 + stream이 닫힌다. 문서는 "본문은 gap마다 read-idle로만 묶인다"고 적는다. `skipNBytes`도 `skip`을 쓴다. +- **고치는 법**: `skip`을 직접 구현한다. 작은 버퍼로 `read`를 반복하고, 각 `read`만 `guarded`로 감싼다. 위 탐침을 단위 테스트로 둔다. +- **심각도·우선순위**: Low · P3(JDK transport + 스트리밍 + skip 사용에서만). **증거**: E3 — `SkipProbe`: 공백 100ms, read-idle 1s에서 + `readAllBytes`는 30바이트 성공, `skip(30)`은 1,001ms에 `SocketTimeoutException`. + +#### RR-03-13 · JDK 스트리밍의 read마다 JVM 공용 delay 스케줄러에 타이머를 걸고 지운다 + +- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:53-69`. +- **무엇**: `read` 한 번마다 `CompletableFuture.completeOnTimeout`으로 JVM에 하나뿐인 delay 스케줄러 큐에 작업을 넣고 지운다. + 지울 때 큐의 맨 앞이 바뀌면 그 스레드를 깨운다. 측정: 1스레드 read당 3.9~4.6µs, 여러 스레드에서는 JVM 전체 약 0.5M회/초에서 + 멈춘다. 같은 큐를 `AttemptDeadline`과 Spring JDK 요청 timeout도 쓴다. 16KB read라면 영향이 작다(1GB에 약 0.2초 CPU). 1바이트씩 + 읽는 소비자(`DataInputStream` 등)는 JVM 전체 약 0.5MB/초가 상한이 된다. Apache는 소켓 timeout이라 이 비용이 없다. +- **고치는 법**: stream마다 "마지막 진행 시각"(volatile `nanoTime`)만 read에서 갱신한다. 타이머는 read-idle 주기로 한 번 걸고, + 깨어났을 때 진행이 없으면 닫고 있으면 다시 건다. 전용 `ScheduledExecutorService`를 transport가 하나 갖는 방법도 있다. 고른 방법을 + 주석에 남기고, 위 측정을 전후로 다시 잰다. +- **심각도·우선순위**: Low · P3(기본 transport는 Apache). **증거**: E3 — `Bench`(load average 14~22에서 측정, 수치는 크기 정도로만 읽는다). + +#### RR-03-14 · 스트리밍 본문 `InputStream.read`가 이제 unchecked `HttpClientException`을 던지는데, 공개 타입에 적혀 있지 않다 + +- **위치**: `httpclient/.../restclient/ClassifiedBodyInputStream.java:34,43,52,61`, `api/result/BlockingStreamingResponse.java`(`body()` Javadoc), + `api/error/HttpClientException.java:12`(`extends RuntimeException`). +- **무엇**: 이전에는 본문 실패가 `IOException`이었다. 이제는 `HttpResponseTimeoutException`·`HttpResponseTruncatedException` + (RuntimeException)이다. 두 transport 모두다(Apache도 바뀌었다). `catch (IOException)`으로 부분 파일을 지우거나 재시도하는 소비자 + 코드는 이 예외를 놓친다. `InputStream` 계약상 `read`가 던지는 것은 `IOException`이다. README와 configuration-reference에는 + 적혔지만 소비자가 보는 `BlockingStreamingResponse.body()`에는 없다. +- **고치는 법**: (a) `IOException`을 상속한 본문 예외(예: `HttpBodyReadException`)를 두고 분류된 `HttpClientException`을 cause·accessor로 + 싣는다. 또는 (b) 지금 방식을 유지하되 `body()` Javadoc과 README에 "read는 unchecked `HttpClientException`을 던진다, + `IOException` catch로는 잡히지 않는다"를 적는다. 고른 쪽과 이유를 남긴다. +- **심각도·우선순위**: Low · P3(템플릿 안 운영 소비자 없음, 파생 서비스의 기존 catch가 영향). **증거**: E1. + +#### RR-03-15 · JDK 스트리밍 요청이 Spring의 금지 헤더 목록을 사본으로 갖고, 원본과 갈라졌다 + +- **위치**: `httpclient/.../jdk/JdkStreamingClientHttpRequest.java:44,89,123-127`. +- **무엇**: 사본은 다섯 이름을 고정으로 둔다. Spring 7.0.9 `JdkClientHttpRequest.disallowedHeaders()`는 + `jdk.httpclient.allowRestrictedHeaders` 시스템 속성을 읽어 허용된 이름을 뺀다. 그 속성을 켠 배포에서 같은 profile의 일반 호출은 + `Host` 등을 보내고 스트리밍 호출은 조용히 버린다. 사용자 원칙의 "갈라진 중복 복사본"이다. +- **고치는 법**: 같은 시스템 속성을 읽는다. 또는 사본을 둔 이유와 원본 위치를 주석에 적고, 두 목록이 같은지 보는 테스트를 둔다. +- **심각도·우선순위**: Low · P3. **증거**: E1(`javap -c`로 Spring 쪽 확인). + +#### RR-03-16 · 호출자 예산이 stage timeout보다 짧은 profile에서는 죽은 상대를 breaker가 보지 못한다 — 문서에 없다 + +- **위치**: `httpclient/.../restclient/BlockingAttemptExecutor.java:156`, `resilience/AttemptResiliencePipeline.java:26-29`(Javadoc), + `docs/httpclient/configuration-reference.md` "Two deadlines" 표. +- **무엇**: + - 코드는 "호출자 deadline이 profile보다 이르고, 실패 시점에 scope가 만료됐으면" 기록하지 않는다. + - Javadoc은 "상대가 profile 한도 안에서 답하던 중"인 시도라고 적는다. 코드는 그 조건을 보지 않는다. + - 결과: 모든 호출자가 connect·response-header timeout(기본 2s)보다 짧은 예산을 넘기면, 블랙홀이 된 상대(패킷 버림)의 시도는 하나도 + breaker에 기록되지 않는다. circuit이 열리지 않아 모든 호출이 자기 예산을 끝까지 기다린다. + - connect 거절 같은 즉시 실패는 계속 센다. +- **고치는 법**: 이 맹점을 configuration-reference 표와 Javadoc에 적는다("호출자 예산이 stage timeout보다 짧으면 hang하는 상대는 + breaker가 못 본다. 그런 profile은 stage timeout을 호출자 예산보다 짧게 둔다"). Javadoc의 조건 문장을 코드에 맞춘다. +- **심각도·우선순위**: Low · P3(결정의 부작용 기록). **증거**: E1. + +#### RR-03-17 · Redis 관측 문서가 지금 나오는 신호와 어긋난다 + +- **위치**: `docs/runbooks/redis-capability-incident.md:50,60-63,64-67,74`, `cache-redis/README.md:218`, + `docs/registries/metrics.yaml`의 `redis.lane.acquire.wait.seconds` 행, `redis-runtime/.../RedisRuntimeOwner.java:354`. +- **무엇**: + - runbook의 Detection 절은 "`redis.capability.*`는 내보내지 않는다"로 고쳤다. 그런데 같은 문서의 다른 줄은 그 지표가 있는 것처럼 + 남았다. "semantic operation 계측은 … 결과를 기록한다", "앞선 success 표본과 이 실패를 두 operation으로 합산하지 않는다", + "이 meter와 단일-process lifecycle test는…", "reconnect, cache source-load, session repository error 지표의 변화를 함께 본다" + (cache source-load·session 지표를 내는 코드가 없다). 레지스트리에서 뺀 `redis.capability.*`의 이름을 직접 부르는 곳은 없다 + (`git grep` 결과 README 「아직 내보내지 않는 지표」와 runbook 해명 줄뿐). + - README는 `opened`를 "warm-up 뒤에는 모두 재연결"이라고 적는다. routed lease(Cluster `TRANSACTION`)는 borrow마다 새로 열고 + pool에 돌려주지 않으며 `discarded`로도 세지 않는다(`RedisRuntimeOwner.java:265-267`, 반환 시 `discarded == null`). 그 lane에서는 + 정상 동작이 재연결 급증처럼 보인다. + - 레지스트리는 대기 timer를 `percentiles: [0.5,0.9,0.95,0.99]`, `histogram_buckets: slo_driven`으로 적는다. 코드는 SLO 경계 없이 + `publishPercentileHistogram()`만 쓴다(`RedisLaneMetrics.java:117`). p99 경보는 histogram으로 계산되니 동작은 맞고, 표기만 다르다. + - listener 실패는 DEBUG로만 남는다(`RedisRuntimeOwner.java:354`). 결과를 바꾸지 않는 것은 맞다. 다만 registry 충돌 등으로 + 지표가 통째로 사라져도 운영 로그에는 흔적이 없다. +- **고치는 법**: runbook의 남은 줄을 "설계(미구현)"로 옮기거나 지운다. README에 "routed lease는 매번 연다"를 적거나 routed 열기를 + 다른 reason으로 센다. 레지스트리 행을 코드에 맞춘다. listener 실패는 처음 한 번 WARN으로 남긴다. +- **심각도·우선순위**: Low · P3. **증거**: E1. + +#### RR-03-18 · lane의 자리·구성을 바꾼 뒤 옛 문장이 남은 문서 + +- **위치**: `objectstorage/README.md:108`("(in `mainCheck`)"), `.github/workflows/object-storage-qualification.yml:4` + ("they run in its `mainCheck` on main and here"), `cache-redis/README.md:337-338`. 원인 변경: `objectstorage/build.gradle:158-162` + (mainCheck 의존 삭제), `cache-redis/build.gradle:89`(멱등성 계약 추가). +- **무엇**: + - build는 MinIO lane을 `integrationCheck`에만 둔다. 두 문서는 leaf `mainCheck`가 돌린다고 적는다. cache-redis의 같은 변경은 + README·CLAUDE.md를 함께 고쳤다(`cache-redis/README.md:339-340`). + - cache-redis README는 컨테이너 lane이 "cache-region and lease port contracts"를 돈다고 적는다. RR-04-05로 멱등성 계약이 + 더해졌는데 README에는 없다. CLAUDE.md(`:131-139`)는 맞다. + - 같은 종류의 사소한 것: `SesEventNormalizer.java:58-59` 주석이 "is keyed / by / the active"로 잘못 줄바꿈됐다. +- **고치는 법**: MinIO 두 문장을 "`integrationCheck`(main push·nightly)와 이 workflow"로 고친다. cache-redis README의 계약 목록에 + 멱등성 계약을 넣는다. +- **심각도·우선순위**: Low · P3. **증거**: E1. + +## Declined to judge + +- SNS 인증서 URL의 4xx를 "SNS가 없다고 답했다 = 위조"로 보는 가정. 호스트 검사를 통과해도 TLS를 가로채는 egress 장비나 + private DNS를 켠 SNS VPC endpoint가 답할 수 있다. 그 경로에서 정상 콜백이 400으로 영구 거절되고(SNS는 4xx에 재전송을 멈춘다) + 감사 로그가 위조로 찬다. 명시 proxy의 CONNECT 실패는 JDK가 `IOException`으로 주므로 503 쪽이다. AWS가 없는 인증서·VPC endpoint + 경유에 어떤 status를 주는지 확인하지 못해 판단을 미룬다. 확인할 것: 운영과 같은 네트워크에서 존재하지 않는 `.pem`을 받아 보기. +- `SecretSourceValidator`의 `fixture-` 거부가 `isProduction()`(prod 프로필)에서만 돈다. 프로필 없음·`staging`은 그대로 기동한다. + 기존 sentinel 검사와 같은 범위이고, RR-07-02가 문제 삼은 "거부 목록이 prod 하나" 구조와 닮았다. pathspec 밖(app-bootstrap)이라 07 영역에 넘긴다. +- PostgreSQL 멱등성 reaper가 `expires_at`만 보고 진행 중 기록도 지우는 것(RR-03-11 근거로 읽음). persistence 영역의 판단이 필요하다. +- 캐시 전용 배포에서 advanced 계정 비밀번호가 틀리면(`WRONGPASS`) 연결 단계 실패라 "장애"로 WARN 후 기동한다. 이번 diff 전부터의 + 동작이다. 설정 오류로 볼지는 판단하지 않았다. +- `CACHE_SCRIPT`가 pod당 advanced 계정 연결을 최대 4개 늘린다(SCRIPT 8 + 4). Redis `maxclients`와 ACL 계정별 연결 예산에 주는 영향은 판단하지 않았다. +- read-idle 타이머가 만료되면 JDK 공용 delay 스레드에서 `in.close()`를 부른다. JDK 응답 stream의 close는 구독 취소라 막히지 않는다고 + 보지만, HTTP/2·TLS에서 재 보지 않았다(1차 Declined와 같은 질문). +- lane 대기 Timer를 borrow마다 builder로 등록하는 비용. 측정 결과 152~241ns로 Redis 왕복 대비 무시할 수준이라 발견으로 올리지 않았다. + +## 수렴 판단 + +- **이 라운드가 만든 새 Important 이상: 없음.** 수정 diff가 새로 만든 결함은 모두 Minor다(RR-03-12~18). 그중 실행으로 확인한 것은 + RR-03-12(E3)와 RR-03-13(E3)이고, 둘 다 기본이 아닌 JDK transport의 스트리밍에만 닿는다. +- **남은 Important 1건은 덜 닫힌 1차 발견이다.** RR-03-11은 RR-04-08과 같은 원인의 claim 경로다. 이번 라운드가 만든 것이 아니라 + 1차가 renew만 짚어 남은 것이다. 고치는 비용은 설정 검사 몇 줄이다. RR-01-11의 수정과 TTL 규칙을 함께 정해야 한다. +- 따라서 이 영역만 보면 수정 라운드는 수렴했다. 다음 라운드가 필요하다면 RR-03-11(및 RR-01-11과의 묶음) 때문이다. + +## Assessment + +**Ready to merge: With fixes.** 1차 발견 13건 중 12건이 코드와 실제 서버 테스트로 닫혔고, 회귀와 이 라운드가 만든 새 Important는 없다. +다만 RR-04-08의 claim 경로가 남아 있어(RR-03-11, E3) replay TTL을 processing lease보다 짧게 둔 Redis 배포에서 멱등 작업이 두 번 돈다. diff --git a/docs/reviews/2026-11-03-rereview/round2/04-bootstrap-build-sample.md b/docs/reviews/2026-11-03-rereview/round2/04-bootstrap-build-sample.md new file mode 100644 index 00000000..8389a4f5 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round2/04-bootstrap-build-sample.md @@ -0,0 +1,306 @@ +# 04 bootstrap·build·sample 재리뷰 (2026-11-03) + +리뷰 대상: Base `7ef8d0b4` → Head `bbe944bd`(재리뷰 수정 커밋), 영역 번호 04(slug `bootstrap-build-sample`). +1차 재리뷰 발견 중 이 영역이 맡은 것: RR-06-01~12, RR-07-02, RR-07-05, RR-04-09. 경로는 저장소 루트 기준이다. + +## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것 + +### 본 pathspec + +```text +src/app-bootstrap src/sample-portfolio src/build-logic src/build.gradle src/settings.gradle src/gradle +src/gradle.properties src/optional-platforms src/config src/.env.example .github docker-compose*.yml +infra/postgres infra/fileserver AGENTS.md CLAUDE.md docs/registries docs/capability-status.md docs/testing +``` + +`git diff --stat` 기준 83파일 +2,159 −413. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다. + +- 전부 읽은 것: build-logic main diff 전체(`StrictLaneStagesPlugin`, `WorkflowGradleInvocations`, + `StrictTestLanePlugin`, `ConfigContractPlugin`, `ConfigurationMetadataClasspath`, `EnvContractVerifier`, + `VerifyEnvKeysTask`)와 그 테스트 diff, workflow diff 3개, `src/optional-platforms/build.gradle`, + `src/config/spotbugs/exclude.xml` diff, app-bootstrap main·test·architectureTest diff, sample main diff 전체와 + `application.yml` 전문, sample 보안 테스트 diff, AGENTS.md·CLAUDE.md·`docs/capability-status.md`· + `src/build-logic/README.md`·`src/app-bootstrap/README.md`·`CLAUDE.md` diff, `.env.example` diff. +- 표본으로 읽은 것: `docs/registries/env-keys.yaml`·`error-codes.yaml`·`secrets-classification.yaml` diff, + `metrics.yaml` diff(키 이름만), `docs/testing/TESTING_STRATEGY.md` diff, `OutboxStatusRegistryContractTest` diff. +- pathspec 밖에서 확인용으로 읽은 것: `src/adapter/outbound/support/.../startup/StartupRuleRunner.java`· + `StartupRule.java`·`RequiredProductionSecrets.java`와 그 테스트 diff(RR-06-01 수정 본체), + `src/Dockerfile.sample`, `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, + `src/adapter/outbound/objectstorage/build.gradle`·`ObjectStorageAutoConfiguration.java`, + `src/grpc/grpc-testkit/build.gradle`·`GrpcPerformanceLaneTest.java`, `docs/runbooks/job-timeout.md` diff, + `scripts/run-compose-runtime-smoke.sh`, `infra/redis-sdk/acl/*.acl`. + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 무엇을 봤나 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "spec이 말하지 않은 동작은 합리적인 사용자의 기대로 판단", 읽기 전용, 의심 결함은 별도 worktree에서 확인 | 수정이 1차 발견의 "고치는 법"을 채웠는지, 수정이 만든 새 결함. 의심 5건을 worktree 실험으로 확인 | +| `ci-cd-and-automation` | "No gate can be skipped", Red flag "CI failures ignored or silenced", 캐시 최적화가 결과를 바꾸면 안 된다 | `verifyStrictLaneStages`의 workflow 해석(`-x`·`continue-on-error`·`if:`·`-p`)이 실제 Gradle 계획과 같은지, lane 정책 입력이 캐시 재사용을 불필요하게 깨는지, optional 빌드 단계 연결 | +| `security-and-hardening` | 비밀값은 환경에서, 기본값은 닫힘, 오류 메시지는 내부를 드러내지 않음, CSRF는 ambient 자격이 있을 때 의미가 있다 | 데모 계정 허용 목록·기본 프로필 제거, prod `fixture-` 거부 범위, SpotBugs CSRF 제외 축소와 `EnvelopeErrorController` 제외의 근거 | + +### 실행한 명령과 결과 + +worktree `scratchpad/rr2-04`(HEAD `bbe944bd`)에서 Gradle을 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 6~40. +probe 파일은 worktree에만 만들었고, 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다. + +| # | 명령 | 결과 | +| --- | --- | --- | +| 1 | build-logic에 reader probe 추가 → `./gradlew -p build-logic test --tests '*RR2WorkflowProbeTest*' --tests '*StrictLaneStagesFunctionalTest.rr2*'` | rc=0. `on: workflow_dispatch`만 있는 workflow의 `:integrationCheck`는 실행으로 셈(`reason=null`). `working-directory: src/optional-platforms` + `../gradlew ci`는 main 빌드 `ci` 실행으로 셈. job `if: ${{ !cancelled() && !failure() }}`는 안 셈. `with: run:`(action 입력)은 실행으로 셈. TestKit: `:integrationCheck -x databaseL --dry-run` 계획에서 Gradle은 `:leaf:databaseLane`을 뺐는데, 같은 줄을 가진 workflow로 `verifyStrictLaneStages`는 **"every strict lane is in an executed stage"로 통과** | +| 2 | support·app-bootstrap·sample에 probe 추가 → `./gradlew :adapter:outbound:support:test --tests '*RR2ProbeTest*' :app-bootstrap:test --tests '*RR2FixturePrefixProbeTest*' :sample-portfolio:test --tests '*RR2DemoProfile*' --continue` | rc=1(의도한 실패 14건). 아래 2-a~2-e | +| 2-a | support: JavaBean `@ConfigurationProperties("probe2")`가 `RequiredProductionSecrets`를 구현, static 규칙이 `ObjectProvider.orderedStream()`으로 읽음, `probe2.name=bound` | runner 없음: `name=bound`. runner 있음: **기동 성공, `name=null`**, 경고 없음 | +| 2-b | support: `@Import`한 `StartupRule` 클래스에 `@Value("${probe3.mode}")` 필드, `probe3.mode=strict` | **기동 성공, 규칙이 본 값 `null`, 기동 뒤 bean 필드도 `null`** | +| 2-c | support: raw `FactoryBean` 컴포넌트(생성자 의존 1개) + 같은 static 규칙 | 기동 성공(오탐 없음). 규칙 없는 대조군도 성공 | +| 2-d | app-bootstrap: prod 프로필, `HOSTNAME=fixture-api-6d5f7c9b8-x2k4q`(시스템 환경 소스), `spring.application.name=fixture-service`, `app.messaging.topic=fixture-updates` | 세 이름 모두 위반: `'fixture-' repository fixture password (public, infra/redis-sdk/acl) is configured for HOSTNAME` 등 | +| 2-e | sample: `SampleDemoSecurityConfigTest`를 복사해 `app.object-storage.enabled=false`만 빼고 프로필을 `demo`·`test`·`local`로 | `local` 7건 통과. `demo`·`test` 각 7건 **전부 실패**: `Error creating bean with name 'objectStorageCapability' ... object-storage binding is incomplete or invalid` | +| 3 | `./gradlew :sample-portfolio:qualityCheck` | rc=0 (PR sample job이 새로 부르는 태스크) | +| 4 | `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run`, `./gradlew :verifyStrictLaneStages --dry-run` | 둘 다 rc=0 | +| 4-b | worktree의 `integration-main.yml` optional performance 줄에 `-x grpcPerformanceT` 추가 → 같은 optional 검사, 그리고 `./gradlew -p optional-platforms performanceCheck -x grpcPerformanceT --dry-run` | 검사는 **통과**. 실제 계획에는 `:grpc:grpc-testkit:grpcPerformanceTest`가 없고 `performanceTestLaneCheck`만 있다 — RR-06-03이 닫은 lane이 다시 어디서도 돌지 않는데 검사가 모른다 | + +돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 7절 오케스트레이터 실행을 근거로 삼았다), `docker build`· +`docker run`(Dockerfile.sample은 정적 확인), compose 실제 기동, GitHub Actions 실행. + +### 못 본 것 + +- 실제 CI runner에서의 workflow 실행, `gradle/actions/setup-gradle`의 캐시 복원 범위. +- `docs/registries/metrics.yaml`의 새 `redis.lane.*` 행과 코드가 내보내는 이름의 대조(03·04 outbound 영역 소관). +- `env-keys.yaml`에 새로 넣은 행 중 `APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS` 외 다른 영역 행의 의미. +- architectureTest의 새 ArchUnit 규칙 2개의 적용 범위(01 core 영역 소관). 실패 fixture가 있다는 것까지만 봤다. + +## Strengths + +- **기동 규칙이 앞당긴 bean을 이제 실제로 잡는다.** `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:64-83,100-131`. + 1차 probe와 같은 모양(설정 bean을 받는 non-static `@Bean` 규칙)이 `probeRule`·`probe-dev.caskeleton`을 대며 기동 실패한다 + (`StartupRuleRunnerTest.java` 새 테스트 3건). 같은 수정 때문에 기존 테스트 설정 2곳이 static으로 바뀌었다 + (`ErrorDetailExposureSafetyValidatorTest.java:71`, `RuntimeNumericBoundsValidatorTest.java:81`). 검사가 장식이 아니라는 증거다. +- **정상 구성에서 오탐하지 않는다.** 실험 2-c에서 생성자 의존이 있는 raw `FactoryBean`이 있어도 규칙이 `RequiredProductionSecrets`를 + 읽는 동안 다른 singleton이 생기지 않았다. 템플릿의 모든 조립(app-bootstrap·sample·qualification)은 README 7절 게이트에서 기동했다. +- **lane 정책이 캐시 입력이 됐고, 바뀌지 않은 lane의 캐시는 그대로 쓴다.** `StrictTestLanePlugin.java:227-240`. + 정책만 바꾼 두 번째 실행이 "forbids skipped tests"로 실패하는 TestKit(`StrictTestLaneConventionTest.java:549-583`)과, + 정책을 그대로 둔 hermetic lane이 여전히 `FROM_CACHE`인 기존 TestKit(`:505-547`)이 둘 다 HEAD에서 통과한다. 입력은 모두 + 상수 값(Boolean·String·List)이라 머신 간 캐시 키가 갈라지지 않는다. +- **optional 빌드가 자기 lane 도달성을 스스로 검사한다.** `src/optional-platforms/build.gradle:1-7,55-83`, + `StrictLaneStagesExtension.java:19-25`. 실험 4에서 `grpcPerformanceTest`가 `-p optional-platforms performanceCheck`로 덮인다. + `performanceCheck`·`releaseCheck` 집계로 바뀌어 lane을 더해도 workflow를 고칠 필요가 없다(`release.yml:135`). +- **`-x` 경로 지정·`continue-on-error`·비상태 `if:`를 Gradle 계획 위에서 판정한다.** `StrictLaneStagesPlugin.java:120-183`. + 전체 경로 `-x`는 lane과 그 아래 의존을 계획에서 잘라 낸다. TestKit 4건(`StrictLaneStagesFunctionalTest.java:189-316`). +- **env 계약이 leaf 이름을 모른다.** `ConfigContractPlugin.java:21-66`, `VerifyEnvKeysTask.java:50-118`, + `src/app-bootstrap/build.gradle:483-488`. metadata classpath가 비면 실패한다(`VerifyEnvKeysTask.java:67-71`). +- **CSRF 제외가 클래스 이름으로 좁혀졌고 sample이 처음으로 분석된다.** `src/config/spotbugs/exclude.xml:19-50`, + `.github/workflows/ci-quality-gates.yml:73`. 실험 3에서 `:sample-portfolio:qualityCheck`가 통과한다. +- **데모 계정 허용 목록이 섞인 프로필도 거부한다.** `SampleDemoAccountsProductionGuard.java:51-65`. + `local,prod`·`test,staging`·프로필 없음이 거부되는 테스트가 있다(`SampleDemoAccountsProductionGuardTest.java:70-94`). +- **Poster 포트의 충돌 규칙이 코드로 묶였다.** domain 예외(`domain/poster/PosterTitleAlreadyExistsException.java`)와 + `PosterRepositoryContract`를 in-memory fake와 실 PostgreSQL adapter(`integrationTest` source set)가 함께 상속한다. +- **종료 예산의 web drain을 compose가 실제로 주는 값에서 읽는다.** `DeveloperExperienceContractTest.java:412-418,632-639`. + runbook도 49초 기준으로 고쳤다(`docs/runbooks/job-timeout.md:51-54`). + +## 발견 재확인 표 + +상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘. `>`는 다른 영역 소관. + +| ID | 상태 | 근거 | +| --- | --- | --- | +| RR-06-01 | 부분 | 1차 probe 모양(non-static `@Bean` 규칙이 설정 bean을 받음)은 기동 실패로 잡힌다(`StartupRuleRunner.java:100-131`). 그러나 새로 생긴 singleton이 `StartupRule`·`RequiredProductionSecrets` 타입이면 묻지 않고 허용한다(`:108-109`). 그 bean 자신이 BPP 없이 만들어지는 경우 — 필드 주입 컴포넌트 규칙, JavaBean 설정 클래스가 비밀 목록을 겸함 — 는 여전히 조용히 바인딩되지 않는다(실험 2-a·2-b) → RR2-04-03 | +| RR-06-02 | 닫힘 | `StrictTestLanePlugin.java:227-240` 정책 5개를 입력으로. TestKit `:549-583`. release job `--rerun-tasks`는 결정으로 넣지 않음(README 6절 r4-f) | +| RR-06-03 | 닫힘(잔여 RR2-04-04) | `src/optional-platforms/build.gradle:1-7,55-83`, `ci-quality-gates.yml:83-87`, `integration-main.yml:206-211`. 실험 4 통과. 다만 축약 `-x`로 같은 lane을 빼도 검사는 모른다(실험 4-b) | +| RR-06-04 | 부분 → RR2-04-04 | 지목한 세 가지(`-x` 전체 경로, `continue-on-error`, 비상태 `if:`)는 닫힘(`WorkflowGradleInvocations.java:236-307`). 축약 `-x`, `on:` 트리거, `working-directory`는 여전히 안 본다(실험 1·4-b) | +| RR-06-05 | 닫힘 | sample PR job에 `:sample-portfolio:qualityCheck`(`ci-quality-gates.yml:73`), CSRF Match FQCN화(`exclude.xml:19-50`). 실험 3 통과 | +| RR-06-06 | 닫힘 | 죽은 블록 3개 삭제(`sample application.yml`), `SampleRuntimeDefaultsContractTest.java:83-176`이 `app.*` 최상위 묶음마다 sample classpath의 읽는 코드를 요구. 하위 키까지는 보지 않는다(고치는 법이 요구한 수준) | +| RR-06-07 | 부분 → RR2-04-05 | lane json·smoke 래퍼의 `APP_*` 키는 이제 등록·읽힘 검사 대상(`ConfigContractPlugin.java:45-62`, `EnvContractVerifier.java:44,216-224`). 1차 발견을 낳은 `CASKELETON_GRPC_ENABLED` 같은 비-`APP_` 키는 여전히 아무 검사도 받지 않는다 | +| RR-06-08 | 닫힘 | `DeveloperExperienceContractTest.java:412-418`, `docs/runbooks/job-timeout.md:51-54` | +| RR-06-09 | 닫힘 | `src/adapter/outbound/objectstorage/build.gradle:158-162` mainCheck 의존 삭제 | +| RR-06-10 | 닫힘 | `ConfigContractPlugin.java`에서 redis-runtime 경로·`dependsOn` 삭제, `ConfigurationMetadataClasspath`, `app-bootstrap/build.gradle:483-488` | +| RR-06-11 | 닫힘(새 drift RR2-04-06) | 지목한 7곳 모두 고침(build-logic README:64, grpc-testkit 주석, CLAUDE.md·AGENTS.md mainCheck, runtime.yml·observability.yml, SampleManagementSecurityConfig:24-29, capability-status idempotency 행, sample build.gradle). 이번 수정이 같은 종류의 새 drift를 만들었다 | +| RR-06-12 | 닫힘 | domain 예외 + `PosterRepositoryContract`(fake·PG adapter 상속), `PosterRepository.java:12-23`, `WorkLogRepository.java:11-17`이 두 갈래의 이유를 적음 | +| RR-07-02 | 결정으로 닫힘(새 결함 RR2-04-02) | 허용 목록 `local`·`test`·`demo`(`SampleDemoAccountsProductionGuard.java:30,51-65`), yml 기본 프로필 삭제(`application.yml:29-32`), bootRun만 `local`을 넘김(`sample-portfolio/build.gradle:248-254`). 결정대로 구현됐다. 그런데 허용한 `test`·`demo`로는 sample이 기동하지 않고, 이미지 실행 문서가 깨졌다 | +| RR-07-05 | 닫힘 | `exclude.xml:19-50`. sample 데모 체인은 별도 Match와 이유 | +| RR-04-09 | 닫힘 | non-static `@Bean` 규칙은 그 설정 클래스를 만들므로 이름을 대며 실패한다(`StartupRuleRunnerTest` 새 테스트 1·2). 남은 경로는 RR2-04-03 | + +회귀로 판정한 발견은 없다. + +## Issues + +### Critical (Must Fix) + +없음. + +### Important (Should Fix) + +#### RR2-04-01 · prod의 `fixture-` 거부가 모든 설정값을 보아서, 비밀이 아닌 정당한 값으로 운영 기동이 막힌다 (이번 라운드가 만든 결함) + +- **위치**: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:48,51-54,113-140`. + 문서: `src/app-bootstrap/README.md:132-136`, `docs/registries/secrets-classification.yaml:13-15`. +- **무엇이 틀렸나**: prod 프로필이면 모든 property source의 모든 값을 훑어 `fixture-`로 시작하면 기동을 거부한다. + OS 환경 변수도 포함한다. `fixture-`는 이 저장소의 lane 비밀번호 접두사이기 전에 평범한 영어 단어다. + 거부 대상은 비밀번호가 아니라 "그 접두사로 시작하는 모든 문자열"이다. +- **증거 (E3)**: 실험 2-d. prod에서 `HOSTNAME=fixture-api-6d5f7c9b8-x2k4q`, `spring.application.name=fixture-service`, + `app.messaging.topic=fixture-updates`가 모두 위반이 됐다. 메시지는 셋 다 "repository fixture password (public, + infra/redis-sdk/acl)"라고 말한다. +- **왜 중요한가**: + - 발생 조건: Kubernetes는 pod 이름을 `HOSTNAME`으로 넣는다. Deployment 이름이 `fixture-`로 시작하면(경기 일정 + "fixture" 도메인, 테스트 데이터 서비스 등) 모든 pod가 이 값을 가진다. 앱 이름·topic·bucket·key prefix도 같다. + - 발견 시점: 검사는 prod 프로필에서만 돈다. dev·staging은 통과하고 첫 운영 배포가 crash loop가 된다. + - 우회 수단: 없다. 이름을 바꾸거나 이 클래스를 고쳐야 한다. README는 "설정값이면 이름을 바꾼다"고 적지만, + 운영자가 `HOSTNAME`을 설정값으로 떠올릴 이유가 없다. + - 막으려던 것은 공개된 lane 비밀번호 7개다(`infra/redis-sdk/acl/lane-fixture-accounts.acl`의 `fixture-admin`· + `fixture-advanced`·`fixture-application`·`fixture-bootstrap`·`fixture-raw`·`fixture-replication`·`fixture-sentinel`). + 정확한 값 목록으로도 같은 사고를 막을 수 있어서, 넓은 접두사 일치가 얻는 것은 없다. +- **고치는 법**: 결정(prod에서 lane fixture 비밀번호 거부)은 그대로 두고 범위만 좁힌다. + 1. 접두사가 아니라 저장소가 공개한 값 집합과 정확히 같을 때만 거부한다. 값 목록은 ACL fixture 파일에서 한 번만 + 정의하고, 그 파일과 목록이 같은지 테스트로 묶는다. + 2. 또는 검사 대상을 비밀값으로 좁힌다: 레지스트리에서 `secret`으로 분류된 키와, `secret://…@environment/` + 참조가 가리키는 변수. + 3. 메시지는 "lane fixture 비밀번호와 같은 값"이라고 말하고, `HOSTNAME`·`spring.application.name` 같은 값이 통과하는 + 테스트를 둔다. +- **가이드 심각도·우선순위**: Medium · P2. 운영에서만 드러나는 기동 실패이고, 원인이 된 값이 정당하다. +- **증거 등급**: E3(실험 2-d), prod 전용 경로는 E1(`SecretSourceValidator.java:98`). + +#### RR2-04-02 · 허용 목록의 `test`·`demo`로는 sample이 기동하지 않고, sample 이미지의 실행 문서가 깨졌다 (이번 라운드가 만든 결함) + +- **위치**: `src/sample-portfolio/src/main/resources/application.yml:215-227`(object storage를 끄는 것은 `local` 문서뿐), + `SampleDemoAccountsProductionGuard.java:30,44`(remedy가 "local (or test or demo)"를 권함), + `src/sample-portfolio/README.md:54-57`(jar·이미지는 "`local`(또는 `test`·`demo`)"), `src/Dockerfile.sample:7-9,14-17` + (pathspec 밖), `src/sample-portfolio/src/systemTest/resources/application-test.yml:176-177`(테스트만 object storage를 끔). +- **무엇이 틀렸나**: + 1. object storage 모듈은 classpath에 있으면 켜진다. sample main 설정은 `local` 프로필에서만 끈다. + `test`·`demo`로 jar나 이미지를 띄우면 목적지 없는 object storage가 기동을 막는다. `demo` 프로필 문서는 아예 없다. + 2. `Dockerfile.sample`의 실행 예시는 프로필을 주지 않는다. 이제 그 명령은 종료 코드 71로 끝난다. 머리말의 + "필요한 외부 의존은 PostgreSQL 하나"도 틀렸다. + 3. 게이트가 이를 못 본 이유: sample의 모든 Spring 테스트는 `local`이거나, `test` 프로필에 테스트 리소스 + `application-test.yml`이 object storage를 끈다. 실제 jar의 `test`·`demo`를 띄우는 테스트는 없다. +- **증거 (E3)**: 실험 2-e. 같은 slice를 `demo`·`test`로 띄우면 14건 모두 `objectStorageCapability ... object-storage binding + is incomplete or invalid`로 실패했고, `local`은 7건 통과했다. 이번 diff의 `SampleDemoSecurityConfigTest.java:57-59`도 + 같은 이유로 `app.object-storage.enabled=false`를 손으로 더했다(주석이 그렇게 말한다). +- **왜 중요한가**: sample은 도입자가 가장 먼저 띄우고 복제하는 실행 경로다(가이드 35.3: 템플릿에서는 개발자 경험의 + 실행 경로가 도입 차단 항목이 될 수 있다). 결정이 `demo` 프로필을 새로 허용했지만 그 프로필로는 아무것도 뜨지 + 않는다. 이미지 사용자는 문서대로 하면 거부되고, 거부 메시지가 권하는 두 번째·세 번째 선택지에서 다시 + 프로필과 무관해 보이는 object storage 오류를 만난다. 보안 결함은 아니다(실패는 닫힌 쪽이다). +- **고치는 법**: + 1. sample의 lean demo 기본값(object storage off 등)을 `local` 문서가 아니라 기본 문서에 두거나, 세 데모 프로필 + 모두에 같은 문서를 둔다(`on-profile: local | test | demo`). + 2. `Dockerfile.sample` 실행 예시에 `-e SPRING_PROFILES_ACTIVE=demo`(또는 `local`)를 넣고, 머리말을 고친다. + 이미지에 기본 프로필을 굽지 않는 것은 결정대로 둔다. + 3. 회귀 방지: 허용 목록의 각 프로필로 `SamplePortfolioApplication`을 테스트 리소스 없이 띄우는 테스트 하나 + (`DEMO_PROFILES`를 파라미터로). +- **가이드 심각도·우선순위**: Medium · P2. +- **증거 등급**: E3(실험 2-e), Dockerfile 부분은 E1. + +#### RR2-04-03 · 기동 규칙 검사가 `StartupRule`·`RequiredProductionSecrets` 타입이면 묻지 않고 통과시켜, RR-06-01과 같은 "조용히 바인딩 안 됨"이 남는다 (RR-06-01 부분) + +- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:104-110` + (타입 면제), `:44-49`(Javadoc "the two kinds that are declared static and argument-free"), `src/app-bootstrap/CLAUDE.md:88-92`, + prod 전용 경로 `SecretSourceValidator.java:98,142-147`·`SecretSourceConfig.java:31-35`. +- **무엇이 틀렸나**: 검사는 "규칙을 만들거나 돌리는 동안 새로 생긴 singleton"을 본다. 그 singleton이 규칙이나 비밀 목록 + 자신이면 무조건 허용한다. Javadoc은 이 두 종류가 static·인자 없음으로 선언된다고 말하지만, 그 사실은 검사하지 않는다. + 그래서 bean 자신이 BPP 없이 만들어지는 모양은 빠져나간다. + - JavaBean `@ConfigurationProperties` 클래스가 `RequiredProductionSecrets`를 겸하면 바인딩되지 않는다. + - `@Component` 규칙의 `@Value` 필드·`@Autowired` 필드는 주입되지 않는다(생성자 `@Value`는 된다). + 둘 다 다른 singleton을 만들지 않으므로 검사가 볼 것이 없다. +- **증거 (E3)**: 실험 2-a. runner가 없으면 `name=bound`, runner가 있으면 기동 성공·`name=null`·경고 없음. + 실험 2-b. 규칙이 본 값과 기동 뒤 bean의 필드가 모두 `null`, 기동 성공. +- **왜 중요한가**: + - `RequiredProductionSecrets`는 `SecretSourceValidator`가 prod에서만 꺼낸다(`SecretSourceValidator.java:98`). 그래서 2-a + 모양은 dev·test·staging에서는 정상 바인딩되고 prod에서만 기본값으로 돈다. 그 설정 bean을 쓰는 런타임 코드도 + prod에서만 기본값을 본다. + - 2-b 모양은 Spring에서 가장 흔한 컴포넌트 작성법이다. 규칙이 항상 `null`을 보면 그 안전 검사가 조용히 꺼진다. + - 1차 발견의 핵심은 "개발자가 기억해야 하는 숨은 제약"이었다. 수정 뒤 문서(`StartupRuleRunner` Javadoc, app-bootstrap + CLAUDE.md)는 "runner가 막아 준다"고 읽히지만, 이 두 모양은 막지 못한다. 지금 템플릿의 규칙·비밀 목록 선언은 + 모두 static `@Bean`이라 터지는 곳은 없다. +- **고치는 법**: 1차 리뷰의 첫째 안을 면제 대상에만 적용한다. 새로 생긴 singleton이 규칙·비밀 목록 타입이면 + `beanFactory.getBeanDefinition(name)`이 `AnnotatedBeanDefinition`이고 `getFactoryMethodMetadata()`가 static이며 매개변수가 + `Environment`·`ListableBeanFactory`·`ObjectProvider`뿐일 때만 허용한다. 그 밖(컴포넌트 스캔·`@Import`· + `@EnableConfigurationProperties`로 등록된 클래스)은 이름을 대며 실패시킨다. 실험 2-a·2-b를 RED 테스트로 쓴다. +- **가이드 심각도·우선순위**: Medium · P2(1차 RR-06-01과 같은 근거·같은 등급). +- **증거 등급**: E3(실험 2-a·2-b), prod 전용 경로는 E1. + +### Minor (Nice to Have) + +#### RR2-04-04 · `verifyStrictLaneStages`의 workflow 해석에 남은 틈 — 축약 `-x`, `on:` 트리거, `working-directory` + +- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:102-110` + (`excludes`: 전체 이름만 비교), `:197-230`(트리거·`working-directory`를 읽지 않음), `:236-278`. +- **무엇이 틀렸나**: + 1. Gradle은 `-x`에 축약 이름(camel-case)을 받는다. reader는 이름이 정확히 같을 때만 제외로 본다. + 2. `if: github.event_name == 'workflow_dispatch'`는 "실행 아님"으로 거부하면서, 같은 뜻의 `on: workflow_dispatch`만 있는 + workflow는 실행으로 센다. + 3. `working-directory: src/optional-platforms` + `../gradlew ci`를 main 빌드의 `ci` 실행으로 센다. optional 빌드에는 안 센다. + 4. `uses:` 단계의 `with: run:` 입력을 실행으로 센다(이전부터). +- **증거 (E3)**: 실험 1과 4-b. 실제 `integration-main.yml`에 `-x grpcPerformanceT`를 넣으면 Gradle 계획에서 + `grpcPerformanceTest`가 빠지는데 optional 검사는 통과한다. 지금 workflow에는 이런 줄이 없다. +- **왜 중요한가**: 검사는 "lane이 실제로 돈다"를 증명한다고 문서(AGENTS.md:79-86, CLAUDE.md:40-44)에 적혀 있다. + 축약 `-x`는 사람이 터미널에서 흔히 쓰는 형태라 workflow로 그대로 옮겨질 수 있다. 그러면 RR-06-03이 막은 상태가 + 조용히 돌아온다. +- **고치는 법**: `-x` 판정을 문자열 비교가 아니라 Gradle에 맡긴다. 각 실행 명령의 `-x` 값을 `--dry-run` 계획을 + 다시 만들 때 `StartParameter.excludedTaskNames`로 넘기거나, 계획의 태스크 이름에 Gradle과 같은 camel-case 일치를 + 적용한다. 트리거가 `workflow_dispatch`뿐인 workflow는 `if:`와 같은 이유로 세지 않는다. `working-directory`가 + 있으면 그 경로를 `-p`처럼 읽는다. 각각 reader 단위 테스트 1건. +- **심각도·우선순위·증거**: Low · P3 · E3. + +#### RR2-04-05 · lane 활성화 키 검사가 `APP_` 키만 봐서, RR-06-07을 낳은 비-`APP_` 키는 여전히 아무도 안 본다 (RR-06-07 부분) + +- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/EnvContractVerifier.java:44`(`JSON_KEY`는 + `"APP_…"`만), `:225-233`(레지스트리 행에 `property:`가 있으면 "읽힘"), `ConfigContractPlugin.java:45-49`(주석), + `EnvContractVerifierTest.java:236-253`. +- **무엇이 틀렸나**: 1차 발견의 실제 사례는 `CASKELETON_GRPC_ENABLED`, 즉 `APP_`가 아닌 아무도 읽지 않는 키였다. + 새 검사는 그 키를 패턴에서부터 건너뛴다. 새 테스트 fixture에 이 키가 들어 있지만 단언하지 않는다. plugin 주석은 + "이 태스크가 아니라 손으로 찾았다"를 들어 이제는 잡힌다고 읽힌다. 또 레지스트리 행에 `property:`만 있으면 그 property가 + 실제로 있는지(`app.redis.` 밖) 보지 않고 "읽힘"으로 친다. +- **왜 중요한가**: compose lane에 오타 난 비-`APP_` 스위치를 넣어도 lane은 다른 이유로 녹색일 수 있다. 1차 결함과 같은 모양이다. +- **고치는 법**: lane json의 `activationEnv` 키 중 `APP_`·`SPRING_`·`MANAGEMENT_`·`SERVER_`·`REDIS_LANE_`(문서화된 비밀번호 + 변수) 같은 허용 접두사 밖의 키를 거부한다. fixture의 `CASKELETON_GRPC_ENABLED`를 실패로 단언한다. `property:` 행은 + qualification classpath metadata에서 그 이름을 찾는다. +- **심각도·우선순위·증거**: Low · P3 · E1(테스트 본문으로 확인). + +#### RR2-04-06 · 이번 수정이 새로 만든 문서·주석 불일치 + +- **무엇이 틀렸나** (모두 E1): + - `docs/capability-status.md:42` gRPC transport 행: "`ca-skeleton.grpc.server.enabled` (no `APP_*` row)". 이번 diff가 + `APP_GRPC_SERVER_ENABLED`(property `app.grpc.server.enabled`, `GrpcServerSettings.java:27`)를 등록했다. object storage 행만 고쳤다. + - `src/.env.example:297-299`: "Explicit offs for two more capabilities"라고 쓰고 값은 `true`다. + - `src/config/spotbugs/exclude.xml:474-478`: "Only DispatcherType.ERROR reaches it ... meets the normal chain (and its CSRF + rules)". 인증된 직접 요청도 이 메서드에 닿고(`EnvelopeErrorController.java:35-37`가 그렇게 말한다), JWT 체인은 CSRF를 끈다. + 제외가 성립하는 진짜 이유는 "상태를 바꾸지 않고 고정된 실패 envelope만 쓴다"이다. 결론은 맞고 근거 문장이 틀렸다. + - `src/Dockerfile.sample:7-9,14-17`: RR2-04-02 참조. + - `StartupRuleRunner.java:44-49`, `src/app-bootstrap/CLAUDE.md:88-92`: RR2-04-03 참조. +- **고치는 법**: 위 줄을 코드에 맞춘다. exclude 이유는 "부작용 없음, 직접 요청은 인증 체인을 거친다"로 바꾼다. +- **심각도·우선순위·증거**: Low · P3 · E1. + +## Declined to judge + +- 데모 허용 목록에 `test`가 있는 것 — 회사마다 외부에 열린 공유 "test" 환경이 있을 수 있다. 4절 결정이라 뒤집지 않는다. +- release job이 `--rerun-tasks` 없이 캐시 결과를 증거로 올리는 것 — README 6절 r4-f 결정. 이유는 문서에 없지만, tag 필터가 + task 입력이라 "tag가 무언가를 고른다"는 증거 의미는 캐시로도 유지된다. +- job·단계의 비상태 `if:`(`github.event_name == 'push'`, `!cancelled() && !failure()`)를 실행으로 세지 않는 것 — 정상 + workflow를 거부할 수 있지만 닫힌 쪽 실패이고 메시지가 이유를 말한다. 결함으로 세지 않았다. +- `verifyEnvKeys`가 이제 모든 capability jar를 만든다(qualification classpath) — mainCheck 비용 증가를 측정하지 않았다. +- lane 입력 중 `tag`·`mainStage`는 판정에 쓰이지 않거나 이미 다른 입력에 들어 있다 — 캐시를 불필요하게 깨는 경우는 + 그 값을 바꿀 때뿐이라 해가 없다. +- IDE에서 `SamplePortfolioApplication`을 프로필 없이 바로 실행하면 거부된다 — 결정의 직접 결과이고 메시지가 해결책을 말한다. +- sample 관리 포트에서 데모 체인이 모든 GET을 허용 — 이전부터의 상태(1차 06 Declined). +- 새 ArchUnit 규칙 2개(`INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`, `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`)의 + 범위 — 01 영역 소관. +- `metrics.yaml`의 `redis.lane.*`·`outbox.retry.long.*` 행과 코드의 일치 — 03·04·05 영역 소관. +- `SampleRuntimeDefaultsContractTest`가 `app.*` 최상위 묶음만 보는 것 — RR-06-06 고치는 법이 요구한 수준이다. + +## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가 + +**있다. 2건이다.** + +- RR2-04-01: RR-07-04 수정(prod `fixture-` 거부)이 모든 설정값을 보아서, 정당한 값(예: Kubernetes pod 이름 `HOSTNAME`)으로 + 운영 기동만 막힌다. +- RR2-04-02: RR-07-02 결정 구현(허용 목록·기본 프로필 삭제)이 허용한 `test`·`demo`로는 sample이 뜨지 않고, sample 이미지 + 실행 문서가 깨졌다. + +그 밖에 1차 Important 하나가 덜 닫혔다. RR-06-01(RR2-04-03)은 1차 probe 모양은 막았지만, 규칙·비밀 목록 bean 자신이 +바인딩되지 않는 모양은 여전히 조용하다. + +세 건 모두 고치는 범위가 작다. 정확한 값 목록 하나, yml 문서 하나와 Dockerfile 주석, runner의 면제 조건 하나다. +다음 수정 라운드는 필요하다. 다만 이 영역에서 구조를 다시 바꿀 일은 아니다. + +## Assessment + +**Ready to merge? With fixes.** + +RR-06-02·03·05~12, RR-07-05, RR-04-09는 코드와 실행으로 닫혔고 회귀는 없다. 다만 이번 라운드의 보안·데모 수정이 새 +Medium 2건(운영에서만 터지는 `fixture-` 오거부, 허용한 데모 프로필로 sample이 뜨지 않음)을 만들었다. RR-06-01도 면제 +경로가 남았다. 셋 다 merge 전에 고치는 것이 맞다. diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md new file mode 100644 index 00000000..6a96a80a --- /dev/null +++ b/docs/upgrade/2026-11-maturity-review.md @@ -0,0 +1,271 @@ +# 업그레이드 안내 — 2026-11 성숙도 리뷰 수정 + +- 범위: `01a8a2a70..bbe944bd` (main → `refactor/maturity-review-2026-11`, 커밋 5개) +- 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 · + `7ef8d0b4` 재리뷰 기록(문서만) · `bbe944bd` 재리뷰 결함 +- 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md` + 4·6·8절, 각 커밋의 `BREAKING CHANGE:` 꼬리말 +- 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에 + 모았다. + +## 1. 누가 읽나 + +이 템플릿을 `upstream` remote로 두고 변경을 merge해 받는 파생 서비스(예: `tech-log-backend` — `origin`=서비스, +`upstream`=이 템플릿)의 개발자가 읽는다. 이 브랜치가 main에 합쳐진 뒤 `git merge upstream/main`을 하기 전에 본다. + +## 2. 한눈에 + +### 반드시 할 일 + +| # | 할 일 | 안 하면 | 해당 서비스 | +|---|---|---|---| +| 1 | JWT 모드면 `APP_SECURITY_JWT_AUDIENCE`에 이 서비스의 client id를 쉼표로 넣는다 | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required` | JWT 모드(기본값) 전부 | +| 2 | dev·prod 환경 변수의 `APP_FLYWAY_ENABLED` 값을 확인한다 | `false`가 남아 있으면 이제 정말로 마이그레이션이 안 돈다 | persistence-jpa 선택 | +| 3 | prod 설정 어디에도 `fixture-`로 시작하는 값이 없게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 | +| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾼다 | 기동 실패 `startup rule '<이름>' created [...]`(exit 78) | 자기 rule이 있는 서비스 | +| 5 | 직접 구현한 outbox·발행·알림·파일 서버 포트를 새 시그니처로 고친다(3.1절) | 컴파일 오류 | 해당 포트를 구현·호출하는 서비스 | +| 6 | `dev.caskeleton.application.outbound.*` import를 `application.secret.*`·`application.objectstorage.content.CallBudget`으로 바꾼다 | 컴파일 오류 | 해당 타입을 쓰는 서비스 | +| 7 | 이벤트 id를 소문자 UUIDv7로 만들고 `IntegrationEventDraft`는 `IntegrationEventDrafts.draft(...)`로만 만든다 | 쓰기 요청이 `IllegalArgumentException`으로 실패, architectureTest 실패 | 통합 이벤트를 내는 서비스 | +| 8 | V21 배포 전에 `docs/runbooks/outbox-dead-letter.md` §8 Step 1 쿼리를 운영 DB에 돌린다 | 중복 순서 키가 있으면 기동 실패(exit 70, V20에 남음) | persistence-jpa + outbox | +| 9 | 이 브랜치의 이전 V21을 적용한 개발 DB를 다시 만든다(4.2절) | Flyway checksum 불일치로 기동 실패(exit 70) | 이 브랜치를 미리 받아 돌린 개발 DB | +| 10 | 자기 SecurityFilterChain이 있으면 `DispatcherType.ERROR`를 허용한다 | 핸들러 밖 오류가 401로 바뀌어 나간다 | 자기 보안 체인을 둔 서비스 | +| 11 | 짝 프론트(또는 다른 클라이언트)에 7절 계약을 맞추게 한다 | 409를 재시도 불가로 읽거나, `null` 키를 기대하다 깨진다 | HTTP 클라이언트가 있는 서비스 | +| 12 | 자기 Flyway 마이그레이션 번호가 템플릿의 새 번호와 겹치지 않는지 본다(4절) | 같은 버전 두 개로 Flyway 실패 | 같은 stream에 자기 마이그레이션을 둔 서비스 | +| 13 | `.env`에 옛 `.env.example` 값을 복사해 두었다면 5.6절 키를 다시 맞춘다 | 새 기본값이 안 먹거나(JDBC batch), 기동 실패(알림 콜백 상한) | `.env`를 복사해 쓰는 서비스 | + +### 되돌릴 수 없는 것 + +- 이 repo에는 down 마이그레이션이 없다(`U*__*.sql` 파일 0개). 되돌리려면 배포 전 백업을 복원한다(4.4절). +- notification V12는 중복 수신 거부(suppression) 행을 **지운다**. 알림을 쓰는 서비스는 배포 전 백업이 필수다. + +## 3. 호환성을 깨는 변경 + +증상 칸의 exit 코드는 `StartupErrorCode`(`src/adapter/outbound/support/.../startup/StartupErrorCode.java`)를 따른다: +70 `MIGRATION_FAILED`, 71 `PROFILE_MISMATCH`, 72 `REQUIRED_ADAPTER_DISABLED`, 78 `STARTUP_VALIDATION_FAILED`. + +### 3.1 Java API — 컴파일이 깨진다 + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-01 | `OutboxStorePort`: `markFailed(OutboxLease, Instant)` → `markFailed(OutboxLease, Instant, String failureCode)`, `markDead(OutboxLease)` → `markDead(OutboxLease, String failureCode)`. 추상 메서드 추가: `markDeferred(OutboxLease, Instant, String)`, `releaseLease(OutboxLease, Instant)`, `longRetries(int, Instant)`(반환 `OutboxLongRetries`) | 직접 만든 store·fake가 `does not override abstract method` 컴파일 오류, 호출부 인자 수 오류 | 템플릿 `JpaOutboxStore`만 쓰면 할 일 없음. 직접 구현했다면 다섯 메서드를 구현한다. `failureCode`는 메시지가 아닌 코드다(`OutboxPublishAttempt.isFailureCode`) | `1400dc15`(markDeferred·releaseLease), `bbe944bd`(failureCode·longRetries) · `src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java` | +| B-02 | 발행 포트 반환형: `IntegrationEventPublishPort.publish(ValidatedIntegrationEvent)`가 `CompletionStage` → `CompletionStage`. `OutboxMessagePublishPort.publishForOutcome(ClaimedOutboxEvent)`가 `OutboxPublishOutcome` → `OutboxPublishAttempt`. 둘 다 default `longestAttempt()` 추가 | 구현체 반환형 불일치 컴파일 오류 | 결과를 `OutboxPublishAttempt.confirmed()`, `OutboxPublishAttempt.of(outcome)`, `OutboxPublishAttempt.failed(outcome, code)`로 감싼다 | `bbe944bd` · `.../messaging/event/IntegrationEventPublishPort.java`, `.../outbox/OutboxMessagePublishPort.java` | +| B-03 | enum 값 추가: `OutboxPublishOutcome.REJECTED_RETRYABLE`(`retryable()`=true), `OutboxRelayResult.Outcome.RELEASED`, `OutboxEventStatus.PARKED` | `default` 없는 switch 식이 "does not cover all possible input values" 컴파일 오류 | 새 값 분기를 더한다 | `34565130`(REJECTED_RETRYABLE), `1400dc15`(RELEASED), `bbe944bd`(PARKED) | +| B-04 | `OutboxRelayFailureReport`에 `failureCode` 필드 추가, `retryableFailure(...)`·`deadLetter(...)`에 `String failureCode` 인자 추가. `PublishPendingOutboxEventsCommand()` → `PublishPendingOutboxEventsCommand(BooleanSupplier stopRequested)` | 직접 생성하는 코드 컴파일 오류 | 보고서는 code를 넘긴다. command는 `PublishPendingOutboxEventsCommand.INSTANCE`를 쓰거나 supplier를 넘긴다 | `bbe944bd`(report), `1400dc15`(command) | +| B-05 | 알림: `ReconciliationJobStorePort.claimDue(int, Instant)` → `claimDue(int limit, Instant now, Duration lease)`. `ReconciliationJob`에 `long claimFence` 필드 추가. `reschedule`·`complete`는 fence가 다르면 아무것도 안 바꾼다 | 직접 구현한 store·job 생성 코드 컴파일 오류 | lease 인자를 받고, claim마다 fence를 올리고, 쓰기에 fence 조건을 건다. 계약은 `application-notification` testFixtures의 공유 계약 테스트로 확인 | `34565130`, `bbe944bd` · `src/application-notification/.../dispatch/ReconciliationJobStorePort.java` | +| B-06 | 파일 서버: `CleanupQueuePort.claimDue(Instant, int)` → `claimDue(Instant, int, Duration lease)`, `markAbandoned(CleanupItem, String reasonCode)` 추가. `CleanupItem`에 `UUID claimToken` 필드 추가. `FileQuotaPort.usedBytes(QuotaScope)` 추가. `UploadContentPort.releaseLease(UploadSession, RequestContext)` 삭제 | 직접 구현한 포트·`CleanupItem` 생성 코드 컴파일 오류 | 새 메서드 구현, `releaseLease` 호출 제거 | `1400dc15`(cleanup), `5786126c`(quota·upload) · `src/application-fileserver/.../cleanup/CleanupQueuePort.java`, `.../api/metadata/FileQuotaPort.java`, `.../upload/UploadContentPort.java` | +| B-07 | 패키지 이동: `dev.caskeleton.application.outbound.SecretSourcePort`·`SecretReference` → `dev.caskeleton.application.secret.*`. `dev.caskeleton.application.outbound.CallBudget` → `dev.caskeleton.application.objectstorage.content.CallBudget`(leaf `application-objectstorage`). `application.outbound` 패키지 삭제 | `package dev.caskeleton.application.outbound does not exist` | import를 바꾼다. `CallBudget`을 쓰는 leaf가 `application-objectstorage`에 의존해도 되는지 `modules.json` 간선을 확인 | `5786126c` · `src/application-core/.../secret/`, `src/application-objectstorage/.../content/CallBudget.java` | +| B-08 | `shared-contract`에서 `dev.caskeleton.shared.operation.Operation`·`OperationStatus` 삭제. sample-portfolio(`...sample.portfolio.adapter.inbound.web.operation`)로 옮겨졌다 | import 실패 | 쓰고 있었다면 자기 inbound adapter로 복사한다 | `1400dc15` · `src/shared-contract/src/main/java/dev/caskeleton/shared/operation/`(삭제) | +| B-09 | `SecuritySettings`(adapter:inbound:web): `audience`가 `String` → `List`. `@ConfigurationProperties` 제거, `SecuritySettings.bind(Environment)`로 strict 바인딩. 생성자 `(String, String, List)` → `(String, List, List)`. `bootstrap.security.AuthenticationModeSettings` 삭제 | `audience()`를 문자열로 쓰는 코드, 직접 생성하는 테스트 컴파일 오류 | `List`으로 바꾼다. 인증 모드는 `SecuritySettings.authMode()`에서 읽는다 | `34565130`(List), `5786126c`(strict·삭제) · `src/adapter/inbound/web/.../settings/SecuritySettings.java` | +| B-10 | adapter 공개 타입 삭제·이동: graphql `execution.GraphQlTimeoutPolicy`·`dataloader.GraphQlDataLoaderRequestRegistry` 삭제(`runtime.GraphQlDeadlineInstrumentation`·`GraphQlPerParentFetchInstrumentation` 추가). jpa `experimental.tenant.TenantId` 삭제 → `dev.caskeleton.application.tenant.TenantId`. persistence-notification의 엔티티는 `...platform.entity`, 저장소는 `...platform.repository`로 이동, `inbox` 하위 클래스는 `platform`으로 올라옴, `PreferenceJpaRepository`·`SuppressionJpaRepository` 삭제, `JpaNotificationSideEffect` → application-notification `dispatch.SuppressionSideEffect` | import 실패. leaf `check`의 API surface 비교가 스냅샷과 달라 실패(자기 공개 타입을 더했다면 merge 충돌) | import를 바꾼다. 스냅샷 파일은 upstream 것을 받고 자기 추가분을 다시 승인한다 | `1400dc15`·`5786126c` · `docs/architecture/graphql-api-surface.txt`, `docs/architecture/jpa-api-surface.txt`(166→165), `docs/notification/api-surface-snapshot.txt`(362→364) | +| B-11 | 조립·지원 타입: `bootstrap.autoconfigure.operation.DurableOperationConfig` → `composition:durable-operation`의 `composition.operation.DurableOperationAutoConfiguration`. `bootstrap.settings.LoggingSettings` 삭제. `composition.outbox.OutboxLeaderElectionToken` 삭제. `TracingSamplingEnvironmentPostProcessor` → `TracingEnvironmentPostProcessor`, `StartupOrder.TRACING_SAMPLING` → `TRACING_PROPERTIES`. `StartupRuleRunner(Environment, List)` → `StartupRuleRunner(Environment)`. `SecretSourceValidator(ConfigurableEnvironment, SecretSourcePort, List)` → `SecretSourceValidator(Supplier>)` | 이 타입을 참조하는 코드·테스트 컴파일 오류 | 새 이름으로 바꾼다 | `1400dc15`, `34565130`, `bbe944bd` · `src/composition/durable-operation/`, `src/adapter/outbound/support/.../startup/` | + +### 3.2 설정·기동 — 기동이 실패하거나 런타임 예외가 난다 + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-12 | JWT 모드에서 `APP_SECURITY_JWT_AUDIENCE` 필수(빈 값 거부, `${...}`가 안 풀린 값도 없는 값으로 봄). 토큰 `aud`가 목록 중 하나를 담아야 통과. `resource_access` role은 audience에 적은 client 것만 읽는다(realm role은 그대로) | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required`(exit 코드 확인 못 함). `.env.example`이 `APP_SECURITY_JWT_AUDIENCE=`(빈 값)를 싣고 있다. 다른 client의 role에 기대던 권한이 사라짐 | client id를 쉼표로 넣는다. 다른 client role로 권한을 받던 사용자가 있는지 IdP에서 확인 | `34565130`(필수·role), `1400dc15`(안 풀린 `${...}`) · `src/adapter/inbound/web/.../auth/JwtDecoderConfig.java`, `.../JwtToAuthenticatedPrincipalConverter.java`, `.../settings/SecuritySettings.java` | +| B-13 | `app.security.*` strict 바인딩: 접두어 아래 오타 키, 또는 설정·placeholder 어디에도 쓰이지 않는 `APP_SECURITY_*` 환경 변수가 기동을 막는다 | 기동 실패(메시지는 `StrictSettingsBinder`가 키 이름을 담아 냄, 정확한 문구 확인 못 함) | 쓰지 않는 `APP_SECURITY_*` 변수를 지운다 | `5786126c` · `SecuritySettings.bind`, `src/adapter/outbound/support/.../StrictSettingsBinder.java` | +| B-14 | prod 프로필에서 `fixture-`로 시작하는 설정 값(변수 이름 무관)을 거부. Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl` | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로 | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` | +| B-15 | 기동 rule이 모든 singleton보다 먼저 돈다(`StartupRuleRunner`가 `BeanFactoryPostProcessor`). `StartupRule`과 `RequiredProductionSecrets` bean은 `static @Bean`이고 `Environment`, bean factory, static 무인자 `RequiredProductionSecrets`의 `ObjectProvider`만 받아야 한다 | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule '<이름>' created [] while creating it ... Declare the rule with a static @Bean method ...`(exit 78) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 다른 bean이 필요한 검사는 rule이 아니라 일반 bean으로 둔다 | `34565130`, `bbe944bd` · `src/adapter/outbound/support/.../startup/StartupRule.java`, `StartupRuleRunner.java` | +| B-16 | 권한 가드(새 `PermissionEnforcementGuard`): `@SystemInvoked` 유스케이스가 bean이면 기동 실패. `@RequiresPermission`을 단 bean에 적용되는 advisor가 없어도 기동 실패. ArchUnit `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`, `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES` 추가 | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). inbound adapter가 그 유스케이스를 부르면 architectureTest 실패 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 호출자(scheduler 등)에 넘긴다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd` · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.java` | +| B-17 | `IntegrationEventDraft`: `eventId`·`causationId`는 소문자 UUIDv7만. ArchUnit `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`: `new IntegrationEventDraft<>(...)` 금지, `IntegrationEventDrafts.draft(...)`만 | 이벤트를 만드는 쓰기 요청이 `IllegalArgumentException: eventId must be a canonical lower-case UUIDv7...`로 실패. architectureTest 실패 | event id를 UUIDv7로 만든다(예: sample `UuidOutboxEventIdFactory`가 `UuidCreator.getTimeOrderedEpochPlus1()`). draft는 헬퍼로 만든다. tenant가 없는 이벤트는 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`) | `1400dc15`, `bbe944bd` · `src/application-core/.../messaging/event/IntegrationEventDraft.java`, `IntegrationEventDrafts.java` | +| B-18 | `MessageHandler.schemaVersions()`(vendored `messaging-core-api`, default `{v1}`): 소비자 decode 목록을 handler 선언으로 만든다. 같은 (메시지 타입, 버전)에 다른 payload class를 선언하면 실패 | 컴파일은 된다. v1이 아닌 메시지는 `SCHEMA_VERSION_NOT_REGISTERED`로 거부. 발행 등록(`MessageContracts`)과 class가 다르면 기동 실패 `MESSAGING_CONTRACT_CONFLICT` | v2 이상을 읽는 handler는 `schemaVersions()`를 override한다. 소비 타입을 `MessageContracts`에 따로 등록하던 코드는 지운다 | `5786126c` · `src/messaging/messaging-core-api/.../delivery/MessageHandler.java`, `messaging-spring-boot-starter/.../MessageContracts.java` | +| B-19 | `APP_FLYWAY_ENABLED`가 모든 프로필에서 읽힌다. dev·prod 프로필 파일의 `spring.flyway.enabled: true`·`app.persistence.vendor` 고정값을 지우고 persistence-jpa `config/module-defaults`가 `${APP_FLYWAY_ENABLED:true}`를 싣는다 | dev·prod 환경에 `APP_FLYWAY_ENABLED=false`가 있으면 전에는 무시됐지만 이제 기동 때 마이그레이션이 안 돈다 | dev·prod 환경 값을 확인한다. 자기 `application-dev.yml`·`application-prod.yml`에 같은 고정값을 다시 넣지 않는다 | `5786126c` · `src/app-bootstrap/src/main/resources/application-{dev,prod}.yml`, `src/adapter/outbound/persistence-jpa/.../module-defaults/persistence-jpa.yml` | +| B-20 | JDBC batch 기본 켜짐: `APP_JPA_HIBERNATE_BATCH_SIZE` 0→50, `APP_JPA_HIBERNATE_ORDER_INSERTS`·`ORDER_UPDATES` false→true(registry `compatibility_impact: behavior-change`) | 컴파일·기동은 그대로. SQL이 묶여 나가고 insert·update 순서가 바뀐다. IDENTITY 키 엔티티는 batch가 조용히 꺼진다. `.env`에 옛 값(0·false)이 있으면 새 기본값이 안 먹는다 | 문장 순서에 기대는 코드가 있는지 본다. 끄려면 0·false를 명시 | `1400dc15` · `persistence-jpa.yml`, `docs/registries/env-keys.yaml` | +| B-21 | 트랜잭션 제한: `TransactionPort` 쓰기·읽기 트랜잭션 30초(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`, env 키 아님) | 30초를 넘는 트랜잭션은 문장이 취소되고 `DB_QUERY_CANCELED`로 실패 | 긴 일괄 작업은 쪼갠다. 꼭 필요하면 프로필 yml에서 값을 올린다 | `1400dc15` · `persistence-jpa.yml` | +| B-22 | 격리 수준을 Hikari에서 고정: `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`. 다른 값이면 거부. `TransactionPort`는 트랜잭션마다 격리 수준을 정하지 않는다 | 다른 격리 수준을 설정했다면 기동 실패(`HikariPoolConstraintValidator`) | 값을 지운다. 더 높은 격리가 필요한 곳은 따로 설계한다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/.../startup/HikariPoolConstraintValidator.java` | +| B-23 | H2 드라이버가 운영 jar에서 빠짐(persistence-jpa `runtimeOnly` → `testRuntimeOnly`). `bootRunH2` 작업만 따로 넣는다 | `APP_PERSISTENCE_VENDOR=h2`로 `bootRunH2` 밖에서 띄우면 드라이버가 없다(정확한 오류 확인 못 함) | 로컬은 Compose PostgreSQL 또는 `bootRunH2`를 쓴다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/build.gradle` | +| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다 | 2초 이하면 기동 실패 | 값을 2초보다 길게(기본 30s) | `5786126c`, `bbe944bd` · `src/composition/idempotency/.../IdempotencySettings.java` | +| B-25 | 알림 콜백 본문 상한 65508 → 65251(바인딩에서 상한 검사) | `.env`에 옛 예제 값 `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508`이 있으면 기동 실패 `max-body-bytes must be 1..65251` | 값을 지우거나 65251 이하로 | `5786126c` · `src/adapter/outbound/notification/.../autoconfigure/NotificationPlatformSettings.java` | +| B-26 | `config/module-defaults/`에 같은 이름 파일이 둘이거나, 두 파일이 같은 키를 실으면 기동 실패 | 기동 실패 `two capability modules ship config/module-defaults/` 또는 `... both ship `(exit 78) | 자기 leaf의 module-defaults 파일 이름·키가 템플릿 모듈과 겹치지 않게 한다 | `1400dc15` · `src/adapter/outbound/support/.../startup/ModuleDefaultsEnvironmentPostProcessor.java` | +| B-27 | (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=local` 등으로 띄우거나 sample 보안 설정을 지운다 | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` | + +### 3.3 HTTP wire — 응답이 달라진다 + +정본은 `docs/web/http-contract.md`다. 클라이언트는 `success`와 `error.code`로 가른다. + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-28 | 처리 중 409 `IDEMPOTENT_IN_FLIGHT`: `retryable` false→true, `Retry-After: 2` 추가. gRPC trailer `error-retryable`과 GraphQL extension `retryable`도 true | 409를 "재시도 금지"로 처리하던 클라이언트가 틀린다 | **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송하게 한다. 새 키 금지 | `34565130` · `src/shared-contract/.../error/OperationalError.java`, `docs/registries/error-codes.yaml` | +| B-29 | Envelope의 `null` 필드를 키째 생략: 성공은 `error` 키 없음, 실패는 `data` 키 없음, `meta.page`·`meta.correlationId`·`error.details`도 값이 없으면 키 없음. 빈 목록은 그대로 | `"error": null`·`"data": null`을 기대하던 클라이언트·계약 테스트가 깨진다 | `success`로 가르고 키 존재로 판단하지 않는다 | `34565130` · `src/adapter/inbound/web/.../envelope/EnvelopeWireFormatConfig.java` | +| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송 | `bbe944bd` · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java` | +| B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` | +| B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` | +| B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` | + +### 3.4 빌드 게이트·아키텍처 규칙 — `ci`가 빨개진다 + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c` · `src/app-bootstrap/src/architectureTest/.../TemplatePackageOwnership.java` | +| B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` | +| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c` · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` | +| B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` | + +### 3.5 모듈 registry·새 leaf + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-38 | 새 leaf: `adapter-inbound-messaging`(`:adapter:inbound:messaging`, 이벤트 소비+inbox, 기본 조립에 없음), `composition-durable-operation`(`:composition:durable-operation`, `/operations`). 새 간선: `application-objectstorage`·`adapter-outbound-persistence-mongo`·`adapter-outbound-identifier`·`adapter-outbound-redis-sdk` → `shared-contract`, `adapter-inbound-web` → `adapter-outbound-support`, `sample-portfolio` → `adapter-outbound-support`, `app-bootstrap` → 두 새 leaf. 지운 간선: `composition-fileserver-platform` → `adapter-outbound-identifier`. `app-bootstrap/build.gradle`에 `runtimeOnly project(':composition:durable-operation')` 추가 | 자기 leaf를 더한 서비스는 `modules.json`·`app-bootstrap/build.gradle`에서 merge 충돌. 충돌을 풀다 durable-operation 줄을 빠뜨리면 `/operations` 조립이 없다(`DurableOperationConfig`가 app-bootstrap에서 빠졌기 때문) | 두 파일을 손으로 합친다. 합친 뒤 `architectureCheck`로 간선을 확인 | `1400dc15`, `5786126c` · `src/config/architecture/modules.json`, `src/app-bootstrap/build.gradle` | + +## 4. DB 마이그레이션 + +### 4.1 새 버전과 영향 + +| stream (history 표) | 버전 | 하는 일 | 기존 데이터 영향 | 실패 조건 | 근거 | +|---|---|---|---|---|---| +| postgresql (`flyway_schema_history`, persistence-jpa 선택 시) | V20 | `outbox_event.deferred_attempt_count INTEGER NOT NULL DEFAULT 0` + CHECK ≥ 0 | 기존 행 0. 지난 claim은 전부 시도 예산에 센다 | 확인된 것 없음 | `1400dc15` | +| 〃 | V21 | `outbox_aggregate_sequence`(aggregate별 counter), `outbox_aggregate_sequence_floor`(V21 적용 시각 마이크로초 한 행), 남은 행 최대 번호로 counter 미리 생성, 유일 인덱스 `ux_outbox_event_aggregate_order (tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` | 새로 생기는 aggregate의 첫 번호가 floor+1(약 1.7×10¹⁵)부터. 순서 열이 NULL인 옛 행은 비교 안 함 | ① 같은 순서 키 행이 이미 둘 이상 → 실패, V21 전체 롤백, V20에 남음(exit 70). ② `SET LOCAL lock_timeout = '5s'` 안에 `outbox_event` 잠금을 못 잡으면 실패·롤백. ③ 같은 이름 인덱스가 유효한 유일 인덱스가 아니면(실패한 CONCURRENTLY) `RAISE EXCEPTION` | `1400dc15`, `bbe944bd` · `docs/runbooks/outbox-dead-letter.md` §8 | +| 〃 | V22 | `outbox_event.last_failure_code VARCHAR(120)` NULL, 기본값 없음. 새 상태 `PARKED`는 DDL 없음 | 행 재작성 없음. 기존 행은 다음 실패 때까지 NULL | 확인된 것 없음 | `bbe944bd` | +| notification (`flyway_jpa_notification_history`, notification-platform 선택 시) | V11 | `notification_reconciliation_job.claimed_until timestamptz`, `claim_fence bigint NOT NULL DEFAULT 0` + CHECK | 기존 job은 fence 0, lease 없음 | 확인된 것 없음 | `34565130` | +| 〃 | V12 | `notification_suppression`의 `(tenant_id, normalized_target_hmac, reason)` 중복 행을 **삭제**(만료 없는 것 > 늦은 만료 > 이른 `effective_at` > 이른 `created_at` > 작은 id 순으로 하나 남김) 후 UNIQUE `uk_notification_suppression_target` | 지운 행의 `SuppressionId`는 더 이상 조회되지 않는다. 되돌리려면 백업 필요 | 확인된 것 없음(잠금 대기 제한 없음) | `1400dc15` | +| 〃 | V13 | `notification_request.acceptance varchar(40) NOT NULL DEFAULT 'ACCEPTED'` + CHECK(`ACCEPTED`, `DROPPED_AS_DUPLICATE`) | 기존 요청은 모두 `ACCEPTED` | 확인된 것 없음 | `5786126c` | +| sample (`flyway_sample_schema_history`, sample-portfolio를 남긴 경우) | V8_1 | 유일 인덱스 `uq_poster_title_ci ON poster (upper(title))` | 없음 | 대소문자만 다른 제목이 있으면 `poster has titles that differ only by case or repeat: ...`로 실패 | `34565130` | +| grpc-ledger (optional-platforms, history 표 확인 못 함) | V002 | 부분 인덱스 `ix_grpc_operation_ledger_finished_completed_at` (일반 `CREATE INDEX`) | 없음 | 큰 ledger면 만드는 동안 쓰기가 멈춘다. 파일 주석은 손으로 `CONCURRENTLY`를 먼저 돌리라고 한다 | `1400dc15` | +| 〃 | V003 | `grpc_operation_ledger.claim_attempt BIGINT NOT NULL DEFAULT 1` + CHECK > 0 | 기존 행은 첫 시도(1) | 확인된 것 없음 | `bbe944bd` | + +- **새로 연결된 stream**: `adapter:inbound:messaging`을 `runtimeOnly`로 넣으면 platform의 `V1101__messaging_inbox.sql`을 + `MessagingInboxSchemaStream`이 `flyway_messaging_inbox_history`에 적용한다(baseline 1100). 넣지 않으면 영향 없음 + (`src/adapter/inbound/messaging/README.md`). +- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, sample V8_1, grpc V002·V003을 쓴다. 파생 서비스가 같은 + 위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다 + (이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다). +- **migration-on-startup=false로 운영하는 서비스**: `infra/postgres/apply-capability-streams.sh`가 바뀌었다(stream을 + `/flyway/streams/`에서 먼저 찾음). 운영자가 직접 적용한다. + +### 4.2 이 브랜치의 이전 V21을 적용한 DB + +V21은 `bbe944bd`에서 V22를 따로 두지 않고 직접 고쳤다(floor 표와 counter 미리 만들기를 넣음). `1400dc15`·`5786126c` 시점의 +V21(sha256 `f830cda5…`)을 적용한 DB는 새 V21(sha256 `21744ea1…`, `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`)과 +checksum이 달라 Flyway 검증에서 기동이 실패한다(exit 70 `MIGRATION_FAILED`). + +- 해당 여부 확인: V21이 history에 있는데 floor 표가 없으면 이전 V21이다. + + ```sql + SELECT version, success FROM flyway_schema_history WHERE version = '21'; + SELECT to_regclass('outbox_aggregate_sequence_floor'); -- NULL이면 이전 V21 + ``` + +- 할 일: 그 개발 DB를 다시 만든다(예: Compose PostgreSQL 볼륨 삭제 후 재기동). `flyway repair`로 checksum만 맞추지 않는다. + 이전 V21에는 floor 표와 counter 미리 만들기가 없어서 스키마가 새 코드와 맞지 않는다. +- 운영 DB: 이 브랜치는 main에 합쳐지기 전이라 어느 배포에도 V21이 없다는 것이 커밋 메시지의 전제다(`bbe944bd`). 파생 서비스가 + 이 브랜치를 운영에 미리 배포했다면 이 전제가 깨진다. 그 경우는 DB 담당과 정한다. + +### 4.3 V21 배포 전 절차 + +`docs/runbooks/outbox-dead-letter.md` §8을 따른다. 요약: + +1. **Step 1 — 중복 확인(읽기 전용)**: §8의 `v21-duplicate-order-keys` 쿼리. 0행이면 배포한다. +2. **Step 2**: 미발행 행이 있는 키는 relay가 비울 때까지 기다린다. `DEAD` 행은 §4 처분을 먼저 한다. +3. **Step 3**: 모두 `PUBLISHED`인 키의 중복을 `outbox_event_v21_duplicates`로 복사한 뒤 지운다(`v21-remove-published-duplicates`). +4. **Step 0 — outbox가 커서 V21이 거는 SHARE 잠금을 견딜 수 없으면**: 중복을 없앤 뒤 같은 이름 인덱스를 transaction 밖에서 + `CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS ux_outbox_event_aggregate_order ...`로 먼저 만든다. V21의 `IF NOT EXISTS`가 그것을 쓴다. + CONCURRENTLY가 실패해 INVALID 인덱스가 남으면 `DROP INDEX CONCURRENTLY` 후 Step 1부터. +5. tenant scope를 바꾼 서비스는 옛 scope의 미발행 행이 없는지 §8의 `GROUP BY tenant_scope` 쿼리로 본다. + +이 절의 SQL 블록은 `:adapter:outbound:persistence-jpa:postgresqlOutboxOrderKeyRunbookIntegrationTest` lane이 실제 PostgreSQL에서 돌린다. +V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failure"에 추가됐다. + +### 4.4 되돌리기 + +- **down 마이그레이션 없음.** 이 repo에 `U*__*.sql`(Flyway undo) 파일이 없다. `migration-failed.md`는 앞으로 고치는 마이그레이션을 + 먼저 쓰고, 적용된 파일 수정·history 고쳐 쓰기·`clean`을 금지한다. +- **배포 전 백업**: 마이그레이션을 돌리기 전에 DB 백업(또는 PITR 지점)을 남긴다. 특히 notification V12는 행을 지운다. + 스키마를 되돌려야 하면 백업 복원이 유일한 길이고, `migration-failed.md` Escalation에 따라 DB 담당이 결정한다. +- **V21 실패 시**: V21은 transaction 하나라 실패하면 V20에 그대로 남는다. 원인(중복·잠금)을 없애고 다시 배포한다. +- **앱만 옛 버전으로 되돌릴 때**: 이번 범위의 마이그레이션은 열·표·인덱스·제약을 더하기만 하고(V12의 중복 행 삭제 제외) 열을 지우거나 + 이름을 바꾸지 않는다. 새 열은 기본값이 있거나 NULL을 허용해서 옛 코드의 insert가 막히지 않는다. 다만 V21 유일 인덱스와 V12·V8_1 + 유일 제약은 옛 코드가 같은 키를 두 번 쓰면 이제 DB가 거부한다. 옛 앱의 Flyway가 자기가 모르는 최신 버전(V20~V22 등)이 적용된 + DB에서 기동하는지는 **확인 못 함**(이 repo는 해당 Flyway 옵션을 설정하지 않음). 스테이징에서 먼저 확인한다. + +## 5. 동작 변경 — 코드는 안 깨지지만 결과가 달라진다 + +| 영역 | 바뀐 것 | 영향 | 근거 | +|---|---|---|---| +| outbox relay | 일시 거부(`REJECTED_RETRYABLE`)·무응답(`AMBIGUOUS`)은 시도 예산을 쓰지 않고 최대 5분 간격(`OutboxBackoffPolicy.MAX_DELAY`)으로 끝없이 재시도. 실패 원인 코드를 `last_failure_code`에 남김. 수동 보류 상태 `PARKED`. 지표 `outbox.retry.long.size`·`outbox.retry.long.age` | 진짜 인증 오류도 DEAD가 아니라 계속 재시도한다. 경보는 새 지표로 잡는다. 처분 SQL은 `docs/runbooks/outbox-dead-letter.md`·`outbox-publish-failed.md` | `34565130`, `1400dc15`, `bbe944bd` | +| outbox append | 읽기 전용 트랜잭션 안의 `append`도 거부(`CallerTransaction.requireReadWrite`). 전에는 트랜잭션 밖만 거부했고 읽기 전용에서는 이벤트가 조용히 사라졌다 | `inRead` 안에서 이벤트를 쓰던 코드가 이제 예외로 드러난다 | `5786126c` · `JpaOutboxStore.java` | +| 순서 번호 | aggregate 순서 번호를 DB counter가 매긴다(`OutboxAggregateSequencePort.nextSequence`). 한 aggregate에 이벤트가 하나면 `AggregateOrder.first()`. 같은 순서 키 두 번째 append는 유일 인덱스가 거부(정확한 오류 코드 확인 못 함) | 소비자가 보는 번호가 새 aggregate에서 floor+1부터 시작해 크게 뛴다. 벽시계로 번호를 만들던 코드는 바꾼다 | `1400dc15`, `bbe944bd` | +| durable operation | operation id가 UUIDv7(`UuidV7DurableOperationIdFactory`). 제출 이벤트의 event id·aggregate id가 UUIDv7이고 tenant scope는 `global` | 전에는 이 이벤트가 messaging bridge에서 전부 DEAD가 됐다(커밋 `1400dc15` 본문). 소비자가 보는 id 모양이 바뀐다 | `1400dc15`, `bbe944bd` · `SubmitDurableOperationUseCase.java` | +| tracing | 자체 tracer를 지우고 Boot tracing·OTLP로. `OTEL_EXPORTER_OTLP_ENDPOINT`는 base 주소로 보고 `<값>/v1/traces`(OTLP/HTTP)로 보낸다. 빈 값이면 exporter 없음. `meta.traceId`가 tracer의 trace id와 같다 | span이 실제로 나가기 시작한다. gRPC 포트(4317)를 넣었다면 HTTP 수신 주소로 바꾼다 | `34565130`, `1400dc15` · `docs/registries/env-keys.yaml` | +| correlation id | `X-Correlation-Id`가 `[A-Za-z0-9._-]{1,128}`(앞뒤 공백 제거 후) 밖이면 서버가 새 값으로 바꾼다 | 규칙 밖 값을 쓰던 호출자는 로그에서 자기 값을 못 찾는다 | `1400dc15` · `docs/web/http-contract.md` §3 | +| String 응답 | `String`을 반환하는 컨트롤러에 JSON을 요청하면 Envelope(`"data": "<문자열>"`)로 나간다. 전에는 500이었다. `byte[]`는 감싸지 않는다(`/v3/api-docs`) | JSON 클라이언트가 이제 200을 받는다 | `1400dc15` · `EnvelopeBodyAdvice.java` | +| GraphQL | 크기를 선언하지 않은 list를 원소 20개로 계산, `first`·`last` 둘 다면 큰 쪽. per-parent 경고 임계 10(`APP_GRAPHQL_PER_PARENT_FETCH_WARNING_THRESHOLD`). deadline instrumentation이 `REQUEST_TIMEOUT` | 전에 통과하던 깊은 목록 쿼리가 복잡도로 거부될 수 있다. 필요한 필드에 `estimatedListSize`를 선언 | `34565130`, `1400dc15`, `bbe944bd` | +| WebSocket | 노드당 STOMP 세션 1000개(`APP_WEBSOCKET_MAX_CONNECTIONS`), 초과 시 연결 후 1013으로 닫음. 메시지 64KB, 송신 버퍼 512KB, 송신 시간 10s, 첫 메시지 60s를 명시 | 동시 연결이 많은 서비스는 상한을 올린다 | `1400dc15` · `env-keys.yaml` | +| gRPC 서버(inbound adapter) | 수신 메시지 1 MiB(io.grpc 기본 4 MiB에서 줄어듦), 메타데이터 8 KiB, 연결당 동시 호출 100, 실행 스레드 32·대기열 256, 기본 deadline 10s, keepalive 30s/10s, 최대 연결 수명 30분, drain 2s | 1 MiB를 넘는 메시지는 거부된다 | `1400dc15` · `src/adapter/inbound/grpc/.../GrpcServerSettings.java` | +| 파일 서버 | 정리 worker 기본 켜짐(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED` false→true, 끄면 기동 경고). copy·move 대상은 기본 namespace만(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 그 밖은 `ACCESS_DENIED`). namespace 쿼터 상한(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`, 비우면 무제한, 넘으면 413 `QUOTA_EXCEEDED`). move가 쿼터를 옮긴다 | 다른 namespace로 copy·move하던 서비스는 허용 목록을 설정해야 한다. 정리 worker가 물리 객체를 지운다 | `5786126c`, `bbe944bd` · `CopyFileApplicationUseCase.java`, `env-keys.yaml` | +| 알림 | SES 콜백 replay 허용 차이 5m→1h. 중복 제거 창에서 버린 제출을 `CANCELED`·`DROPPED_AS_DUPLICATE`로 저장해 같은 멱등성 키에 같은 영수증. reconciliation job은 DB lease로 소유. INGEST_ONLY도 accept 때 route 이름 기록 | 콜백·영수증 결과가 바뀐다 | `34565130`, `5786126c` | +| Redis | 캐시 조건부 쓰기가 자기 SCRIPT lane(`APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS`, 기본 4)을 쓴다. registry에서 `redis.capability.*` 지표 6개를 빼고 `redis.lane.*` 6개를 더했다 | Redis 연결이 캐시 lane만큼 늘어난다. 옛 지표 이름으로 만든 대시보드·경보는 바꾼다 | `bbe944bd` · `docs/registries/metrics.yaml` | +| 설정 바인딩 | strict 설정에서 선택 숫자·크기·기간 키의 빈 값은 "미설정". 목록 원소 아래 오타 키도 거부(`StrictSettingsBinder`) | `.env.example`의 빈 값으로 기동 가능. 목록 원소 아래 오타는 이제 기동 실패 | `5786126c` · `StrictSettingsBinder.java` | +| 권한 매핑 | `app.authz.role-permissions` 기본 항목이 app-bootstrap `config/security.yml`에서 각 capability의 module-defaults(notification·fileserver·durable-operation)로 옮겨짐. 여러 출처의 항목이 합쳐진다 | 모듈을 빼면 그 권한 매핑도 빠진다 | `1400dc15` · `src/app-bootstrap/src/main/resources/config/security.yml` | +| 로그 설정 | logback이 `APP_LOG_*` 대신 `app.logging.*`을 읽는다(환경 변수 이름은 그대로 매핑) | 프로필 yml의 `app.logging.*`이 이제 먹힌다 | `1400dc15` · `logback-spring.xml` | +| local 프로필 | `server.port`가 `${APP_SERVER_PORT:8080}`을 읽는다. Flyway·`ddl-auto validate`·PostgreSQL vendor를 module-defaults에서 받는다 | local에서 `APP_SERVER_PORT`가 다른 값이면 포트가 바뀐다 | `1400dc15`, `5786126c` · `application-local.yml` | +| deprecated | `APP_CACHE_REDIS_TTL_JITTER`는 아무것도 바인딩하지 않음(`removal_deadline: 2027-02-28`) | 값이 아무 효과 없다 | `1400dc15` · `env-keys.yaml` | +| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` | + +## 6. 따라오는 순서 + +모든 명령은 `src/`에서 `--console=plain`으로 돌린다. 한 단계가 빨개지면 다음으로 가지 않는다. + +| 단계 | 할 일 | 게이트 | +|---|---|---| +| 0. 준비 | 운영·스테이징 DB 백업. 작업 브랜치를 따로 만든다. 자기 마이그레이션 번호가 4.1절 번호와 겹치는지 본다. 운영 DB 사본에 4.3절 Step 1 쿼리(필요하면 V8_1 중복 제목 확인)를 돌려 둔다 | — | +| 1. merge·의존성 | `git fetch upstream` 후 merge. 충돌 예상 파일: `config/architecture/modules.json`, `app-bootstrap/build.gradle`, `docs/registries/env-keys.yaml`, `.env.example`, `application*.yml`, API surface 스냅샷, `gradle.lockfile`. 자기 의존성을 바꿨으면 `./gradlew ::resolveAndLockAll --write-locks` | `./gradlew verifyDependencyLocks` | +| 2. 컴파일·아키텍처 | 3.1절(B-01~B-11) 고치기. 3.4절 규칙 위반 고치기 | `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, 고친 leaf마다 `./gradlew :check` | +| 3. PR 게이트 전체 | 자기 strict lane을 단계에 건다. SpotBugs MEDIUM 발견 처리 | `./gradlew ci`, `./gradlew verifyStrictLaneStages --dry-run` | +| 4. 설정 | 2절 체크리스트 1~4·10·13. 3.2절(B-12~B-27) 확인 | `./gradlew :app-bootstrap:verifyEnvKeys`, `./gradlew configContractCheck` | +| 5. DB | 이전 V21을 적용한 개발 DB 재생성(4.2절). 스테이징에 4.3절 절차 후 마이그레이션 | `./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck`(Docker 필요), 알림을 쓰면 `./gradlew integrationCheck` | +| 6. 기동 | prod와 같은 프로필·환경으로 스테이징 기동. exit 코드 70·71·72·78이면 3.2절·4절 해당 줄로 | `./gradlew :app-bootstrap:systemTest`, `./gradlew mainCheck` | +| 7. 계약 | HTTP 응답 모양·코드(3.3절)를 클라이언트와 맞춘다. 공개 경로가 바뀌었는지 확인 | `./gradlew verifyPublicPathSnapshot`, `./gradlew mainCheck`(문서 계약 lane 포함), 짝 프론트 계약 테스트 | + +## 7. 짝 프론트 + +프론트가 맞출 계약의 정본은 `docs/web/http-contract.md`다. 요약: + +**Envelope** + +| 응답 | 있는 키 | 없는 키 | +|---|---|---| +| 성공 | `success`(true), `data`, `meta` | `error` | +| 실패 | `success`(false), `error`, `meta` | `data` | +| bulk 전체 성공 | `success`(true), `results`, `meta` | `error` | +| bulk 부분 실패 | `success`(false), `error`(`BATCH_PARTIAL_FAILURE`, `details`), `meta` | `results` | + +- `success`로 가른다. 키 존재로 판단하지 않는다. `null`이면 키가 없고, 빈 목록은 `[]`로 온다. +- `error`는 `code`·`category`·`message`·`retryable`이 항상 있고 `details`는 있을 때만. +- `meta`의 모르는 키는 무시한다. 요청 id 필터 전에 끊긴 응답은 id 키가 빠질 수 있다. + +**멱등성** (같은 `Idempotency-Key` 재전송에 대한 서버 판정) + +| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 | +|---|---|---|---|---|---| +| 재생 | 첫 요청의 성공 status | — | — | — | 첫 결과로 받는다 | +| 처리 중 | 409 | `IDEMPOTENT_IN_FLIGHT` | true | 2 | 같은 키로 `Retry-After` 뒤 재전송. 새 키 금지 | +| 본문 불일치 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | false | — | 다시 보내지 않는다 | +| 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID`(`details.reason`) | false | — | 보이는 ASCII 1~256자 키로 다시 | +| 실행 전 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | true | — | 실행 안 됨. 같은 키로 나중에 | +| 실행 뒤 기록 실패(결과 불명) | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | true | — | 같은 키로 나중에. 새 키 금지 | +| 이전 효과 증명 불가 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | false | — | 업무 데이터로 확인 | + +- CORS가 켜져 있으면 `Retry-After`·`X-Request-Id`·`X-Correlation-Id`·`traceparent` 등이 `Access-Control-Expose-Headers`에 있다(§3). +- 새 코드: `REQUEST_TIMEOUT`(503, retryable), web-advanced를 쓰는 서비스는 10종(3.3절 B-32). +- 프론트 계약 문서(`clean-architecture-frontend-template` `docs/architecture/backend-api-and-server-state-contract.md` §4.1·§6)는 + `docs/web/http-contract.md`를 가리켜야 한다. +- 프론트 세션에 넘긴 인계 문서(세션 scratchpad라 지워질 수 있음): + `/tmp/claude-1000/-home-donghyeon-workspace-desktop-server-git-clean-architecture-frontend-template/4cfb2000-88f4-4501-87c2-64e07e1575a5/scratchpad/backend-contract-handoff.md` + +## 8. 소유자 확인이 남은 결정 + +재리뷰 README 8절은 아래를 "소유자 확인이 필요한 결정"으로 남겼다. main에 합쳐지기 전에 바뀔 수 있다. + +- 서블릿 오류 디스패치 허용(B-31), 데모 계정 허용 목록(B-27), V21을 V22 없이 직접 수정(4.2절), 발행·저장소 포트 시그니처 변경 + (B-01·B-02), `IDEMPOTENCY_COMPLETION_UNKNOWN` 신설(B-30), prod `fixture-` 값 거부(B-14). + +## 9. 확인 못 한 것 + +- 실제 파생 서비스(예: `tech-log-backend`) 코드에 이 안내를 적용해 보지 않았다. 각 줄이 그 서비스에 해당하는지는 서비스 쪽에서 확인한다. +- `APP_SECURITY_JWT_AUDIENCE` 누락·`app.security` 오타의 정확한 exit 코드와 메시지 전문(바인딩 예외로 감싸지는 경로). +- H2를 `bootRunH2` 밖에서 쓸 때의 정확한 오류(B-23). +- 같은 순서 키를 두 번 append할 때 나가는 오류 코드(5절 "순서 번호"). +- 옛 버전 앱이 V20~V22가 적용된 DB에서 기동하는지(4.4절). +- gRPC ledger stream의 history 표 이름과 누가 적용하는지. +- 실제 CI runner에서의 workflow 실행(재리뷰 README 8절과 같음).