설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
182 KiB
src/ 유지보수성·구조 리뷰 (2차) — 2026-09-24
개요
| 항목 | 내용 |
|---|---|
| 목적 | 1차 리뷰(2026-09-24-src-module-code-review.md, 결함 중심)에서 빠진 관점 — 유지보수, 단일 책임, 공통 계약 추출, 디자인 패턴, 테스트 가독성(given/when/then), 빌드 인프라 비례성 |
| 기준 | main @ 208077fd 작업 트리 |
| 방법 | 읽기 전용 리뷰 에이전트 11개 병렬: 모듈 그룹별 구조 리뷰 7개(S1–S7), 모듈 간 기능 중복(X1), 공통 유틸·전송 경계(X2), 빌드 비례성(BUILD), 테스트 구조(TEST). 건수 제한 없이, 비슷한 사례는 한 건으로 묶음 |
| 규칙 | 패턴은 코드를 줄이는 경우에만 권고. 반대로 구현 1개짜리 인터페이스·전달만 하는 계층은 삭제 권고 |
질문별 답
1. 유지보수·SRP·공통 계약 — 핵심은 "나쁜 코드"보다 "여러 세대와 미조립 코드의 공존"
모듈 경계(HARD-STOP 1·2·3·5)는 지켜지고 있다. 문제는 한 기능에 2~3세대 구현이 함께 있고, 그중 상당수가 실제 앱에 조립되지 않는다는 점이다. adopter는 어느 것이 정본인지 알 수 없고, 수정이 한쪽에만 들어가 이미 갈라진 곳이 여러 군데다.
조립되지 않은(도달 불가) 코드 추정치 — 그룹마다 측정 방법이 달라 겹침·오차가 있다. 일부는 의도적으로 제공하는 라이브러리 코드다.
| 영역 | 추정 | 근거 |
|---|---|---|
| redis-sdk + redis-runtime의 SDK 전용 부분 | 약 25.7k | S3 #3, 1차 G-6 |
| graphql | 약 14.7k | 1차 J-10, S5 |
| web (2세대 platform, WebFlux) | 약 13.3k | S5 #2·#4 |
| persistence-mongo | 약 13.1k | S2 #2 |
| messaging:* | ≥12.7k | S7 |
| grpc:* / grpc-advanced | 약 12.4k | S7 |
| persistence-jpa (플랫폼 라이브러리·V2·중복 엔진) | 약 10.1k | S2 #3·#4·#7 |
| websocket 플랫폼 라이브러리 | 약 9.7k | S6 #1 |
| fileserver 어댑터 루트(R1/R2 publication) | 약 8.7k | S4 #1 |
| notification (R1 4.5k + platform 0.9k + provider 5종 3.0k) | 약 8.4k | S1 #14, S4 #3 |
| application-core | 약 4.9k | S1 #1–#3 |
| objectstorage (direct/multipart, legacy adoption) | 약 4.0k | 1차 D-7, S4 #10 |
| messaging 어댑터 R1 | 약 3.5k | S4 #2 |
| 합계 | 약 15만 줄 (main 32만 줄의 약 절반) |
여러 벌로 갈라진 기능과 권고(X1·X2 요약)
| 기능 | 현재 | 권고 |
|---|---|---|
| Outbox | 세대 3개. 실제 조립된 v1에만 fencing이 없음(중복 발행 위험). 고친 두 구현(V2, messaging)은 미조립 | 앱 쪽 1벌. v1 테이블 + V2/V1002 fencing 이식 후 V2 삭제(또는 반대). messaging outbox는 vendored라 유지 |
| 멱등성 | v1/V2 계약 2개, store 3개, executor 조립 3곳, inbound 전용 ledger 3개 | V2를 정본, v1 삭제, 조립 1곳 |
| 에러 어휘 | HTTP 응답 형식 3개(Envelope, WebProblem, Fileserver problem), 코드 체계 4개. 같은 코드의 status·retryable이 전송마다 다름 | ApiErrorCode 하나 + Envelope. shared 예외 5종에 ApiErrorCarrier 구현, GraphQL retryable은 코드별 값 |
| caller 트랜잭션 guard | 9벌 복사, 빠진 곳에서 dual-write 결함 | persistence-jpa CallerTransaction.require 하나 |
| 테스트 fake | 같은 포트 fake가 모듈마다 따로(TransactionPort 21~26개), 실제 adapter와 대조하는 kit는 1개 |
포트 소유 모듈 testFixtures에 추상 contract 클래스 |
| 시크릿·prod 판정·tenant·MDC | 시크릿 경로 4갈래, prod 판정 재구현, TenantContext 2개(문법 다름), MdcKeys가 web에 갇힘 |
기존 정본(SecretSourcePort, RuntimeEnvironment)에 bridge 1줄씩, tenant 값 타입 1개, MdcKeys는 shared-contract로 |
| capability 활성화 규칙 | 6곳에 흩어지고 기본값이 이미 3가지로 갈림 | 표 하나(키·기본값·필요 조건·prod secret)에서 validator·endpoint 파생 |
| readiness/evidence/API-surface | 카드 스키마 3개, API-surface gate 3개, moduleboundary 3벌 | build-logic 구현 하나 |
| 작은 유틸 | SHA-256 헬퍼 53개, JSON escape 3가지 동작, backoff "full jitter" 뜻 3가지, HMAC cursor codec 7개 | shared-contract Sha256, Backoff, 서명 헬퍼(삭제 후 남으면) |
디자인 패턴 — 코드가 줄어드는 곳에만 권고했다.
- Template Method: httpclient blocking/reactive 공통 코어(약 600~700줄 감소, S3 #1).
- 상태 전이표(State):
ProviderRuntime,FileState,LocalPersistentControlPlane의 전이 규칙(S4 #5·#14, S1 #13). - Strategy /
EnumMap표: GraphQL 에러 category switch 3개, Redis 스크립트 status switch 5개(S5 #6, S3 #5). - 정적 factory / Value Object:
PublishResult7-인자 생성 28회, fileserver 원시 String 검증 73곳(S7 #6, S4 #8). - Rule 목록: startup validator 19개 →
StartupRule목록 + runner 1개(S6 #3). - 반대 방향(삭제): 구현 1개짜리 인터페이스·레지스트리·facade 다수 — httpclient 4개, application-fileserver 6개, notification 레지스트리 2개,
PolicyTransactionPort계열,SelectedObjectStorageProviderFactory, fileserver R2 routing 계층 등.
2. 테스트 given/when/then
// given // when // then을 모두 갖춘 파일: 1,500개 중 0개(일부만 5개). 다만 6줄 이상 테스트의 71%는 빈 줄로 단계를 나누고, 이름은 전부 camelCase 행동 문장이라 흐름 자체는 대체로 보인다.- 더 급한 문제 두 가지: (a) fake가 실제 adapter와 같은 계약 테스트를 통과하지 않는다 — 1차 리뷰의 "fake가 숨긴 결함" 6건 중 5건이 여기에 해당. (b) 이름이 약속한 성질을 단언하지 않는 테스트가 약 1,050개(12%).
- adopter가 복사하는
sample-portfolio가 가장 약하다(DisplayName 0%, 단계 분리 54%, 115줄 테스트). - 제안: GWT 주석을 규칙으로(본문 3문장 이상이면 필수,
// when은 정확히 하나), 이름에 적은 성질은 반드시 단언, 포트별 추상 contract 테스트, Mockito는 프레임워크 경계에만. 새로 쓰거나 고치는 테스트에만 적용하고 sample부터 모범 사례로 재작성. 주석 게이트(자동 강제)는 만들지 않음 — 이유는 TEST 절.
3. 빌드 인프라 — 목적 대비 과하다. 목적에 필요한 부분은 약 13%
- build-logic + build-tools 16,768줄 중 아키텍처 강제(A)는 2,242줄(13%), 핵심만 따지면 1,301줄(8%). 기능별 증거 검사(E)가 7,760줄(46%)로 가장 크다.
- Gradle 방향 게이트와 ArchUnit 규칙 105개는 필요한 크기다. 줄일 대상이 아니다.
- 최근 "gradle 얇게" 리팩터에서 빌드 코드가 늘었다:
ace8aaae(09-17) →208077fd(09-24) 사이 build-logic/build-tools/script plugin 합계 약 4.7k → 17.1k줄(직접 측정). leaf 스크립트는 215줄만 줄었다. - 권고: O3 — build-logic에는 아키텍처 코어(registry, 방향·순수성 task)·컨벤션·레인 하나만 두고, 기능별 검사는 소유 leaf의 테스트로 옮긴다(목표 약 3.5–4k줄, build-tools 0). 그 전에 어느 안을 고르든 안전한 정리 11개로 약 3.4k줄 감소, 잃는 보호 없음. 09-16 단계 분리 계획의 미이행분(PR에 남은 2단계 게이트 11개)은 삭제가 아니라 단계만 옮긴다.
- 빈틈 하나: 빌드 단계 순수성 검사가
application-*만 본다. domain-core에 외부 의존을 추가해도 빌드는 통과한다(필터 3줄 추가로 해결).
결정 필요 (승인자: 저장소 소유자)
| # | 결정 | 권고 |
|---|---|---|
| D1 | 미조립 대형 코드 처리 — redis-sdk, Mongo advanced/reactive, graphql advanced/compat, websocket 플랫폼, web 2세대·WebFlux, notification provider 5종, fileserver R2 publication, messaging experimental/rabbit/avro 등, grpc-advanced | family별로 "삭제 / optional-platforms 같은 별도 build로 이동 / 유지" 중 선택. 기본값은 이동(공개 약속 유지, 기본 빌드에서 제외) |
| D2 | Outbox 정본 | v1 테이블 유지 + fencing 이식, V2 삭제 (반대도 가능. 목표는 1벌) |
| D3 | 멱등성 정본 | V2 (Redis·소유자 fencing이 V2에만 있음) |
| D4 | WebFlux 지원 | 현재 어떤 조합으로도 켜지지 않음. 삭제 권고. 유지하려면 starter-web을 leaf에서 빼고 composition이 선택 |
| D5 | 빌드 목표안 | O3 (순서: 단계 재배치 → 안전한 정리 → O3) |
| D6 | 테스트 컨벤션 | 제안안 채택 여부, @DisplayName 언어(기본 영어) |
권고 순서
- 1차 Critical 수정과 함께 contract 테스트 추가. fake가 결함을 숨긴 6개 포트의 추상 contract를 수정 PR에 같이 넣는다. contract가 현재 코드에서 먼저 실패하면 그것이 회귀 테스트다.
- 빌드 안전 정리 1–11 + 단계 재배치(BUILD 절 "바로 할 것"). 서로 독립적이고 보호 손실 없음.
- D1–D4 결정 후 삭제/이동. 가장 큰 LOC 감소. 그 뒤 outbox·멱등성·에러 어휘를 하나로 합친다.
- 테스트 컨벤션 문서화 + sample-portfolio를 모범 사례로 재작성. 나머지는 손대는 테스트부터.
1차 리뷰 보정
- 1차 B-2(SNS 서명 우회): 영향 서술 중 "위조 callback이
SesSuppressionUpdater로 suppression을 만든다"는 과장이다. 이 클래스는 참조가 0이다(S4 #3). 서명 검증 우회 자체는 유효하다. - 1차 A-2(websocket prod 판정): 수정이 더 간단하다. bridge 없이
RuntimeEnvironment.isProductionActive(...)정적 호출 한 줄이면 된다(X2 P1-2). - 1차 O-2 이후 측정: build 코드 증가 수치는 이 문서의 직접 측정값(약 4.7k → 17.1k)을 기준으로 한다(BUILD 에이전트는 6.3k → 17.0k로 셈, 포함 범위 차이).
검증 기록
| 항목 | 결과 |
|---|---|
| 방식 | 전부 읽기 전용(grep·git·스크립트). Gradle과 테스트는 실행하지 않음 |
| 직접 재확인 | build-logic+build-tools 합계 16,768줄 일치; 09-17→09-24 증가 약 4.7k→17.1k; GWT 주석 완비 파일 0개; web·web-fileserver 둘 다 implementation spring-boot-starter-web(WebFlux 비활성 근거); application-core에 domain-core 의존 없음; 순수성 task가 application-*만 순회; persistence-mongo는 app-bootstrap runtimeOnly이고 다른 main 소스의 Mongo 타입 참조 없음 |
| 추정치 | 도달 불가 LOC, 약한 단언 수, 중복률은 이름 참조·regex 기반 추정. 리플렉션·문자열 bean 참조는 반영 안 됨 |
그룹별 상세
아래는 각 에이전트 결과 원문이다. BUILD → TEST → X1 → X2 → S1–S7 순서.
BUILD — 빌드 인프라가 목적에 비해 과한가
결론
- 대부분 과하다. 목적("빌드 시점에 아키텍처 위반을 막는 것", 카테고리 A)은 build-logic+build-tools 16,768줄 중 2,242줄(13%). 꼭 필요한 registry·의존 방향·순수성 검사만 따지면 1,301줄(8%).
- 가장 큰 덩어리는 기능(capability)별 증거 검사. jpa·notification·messaging·mongo 전용 검사(E) 7,760줄(46%), 테스트 레인 검증(C) 2,559줄, 릴리스·스냅샷류(D) 2,714줄.
- 아키텍처 게이트 자체는 적정. Gradle 방향 게이트와 ArchUnit 규칙 105개는 필요한 크기. 문제는 그 주변의 증거 검사 플랫폼.
- "gradle을 얇게" 리팩터에서 코드가 두 배. 09-17(
ace8aaae) → 09-24(208077fd) 사이 included build 코드 6,276 → 17,010줄, 같은 기간 leaf·root 스크립트는 3,947 → 3,732줄(215줄 감소). 줄어든 스크립트 로직이 Java 플러그인으로 옮겨 가면서 두 배 이상 커짐. - 09-16 단계 분리 계획은 절반만 이행. 2단계(main)로 내려야 할 env 키·공개 경로 스냅샷·전체 system 테스트·API surface·기능 검사가 지금도 PR 게이트에서 돈다.
인벤토리
카테고리: A 아키텍처, B 품질 도구, C 테스트 레인·증거, D 릴리스·스냅샷, E 기능별, F 개발 편의. 단계: PR = 1단계(머지 차단), main = 2단계, tag = 3단계. ✗ = 계획(docs/superpowers/plans/2026-09-16-ci-stage-separation.md)과 현재 위치 불일치.
| # | 구성요소 | LOC (main+test) | 쓰는 곳 / 호출 경로 | 막는 것 | 카테고리 | 판정 | 단계 현재→목표 |
|---|---|---|---|---|---|---|---|
| 1 | ca.architecture-registry, ca.optional-architecture-registry (ModuleRegistry, ModuleRegistrySettingsInstaller) |
353+162 | src/settings.gradle:13, optional-platforms/settings.gradle:6 |
registry 모듈만 include, 디렉터리 매핑, registry 형식 | A | KEEP | 설정 단계 ✓ |
| 2 | ca.architecture: verifyModuleDependencyDirection, verifyCleanArchitectureDependencies, verifyModuleDependencyPurity (+ResolvedComponents) |
619+167 | build.gradle:21, optional-platforms/build.gradle:2 → architectureCheck → ci |
HS5, application-* 프레임워크 순수성 | A | KEEP, 순수성 필터에 domain-core·shared-contract 추가 | PR ✓ |
| 3 | verifyNoIgnoredSourcePackages |
128+0 | architectureCheck |
Git 무시 패키지의 소스 | A 인접 | KEEP (1차 O-3 수정) | PR→main |
| 4 | ca.runtime-membership |
194+124 | build.gradle:20, ArchitecturePlugin.java:216-225 |
조립 루트 런타임 모듈 ⊆ registry | A | DELETE (#2와 중복) | PR→없음 |
| 5 | ca.dependency-policy |
400+95 | app-bootstrap/build.gradle:376-390, notification/build.gradle:63, messaging/build.gradle:44 → check |
fileserver 미포함, yaml/jackson 부재 | A/E | REPLACE-WITH-NATIVE | PR ✓ |
| 6 | ArchUnit (app-bootstrap/src/architectureTest) |
7,786 (규칙·지원 6,342 + fixture 1,444), 그 밖에 leaf ArchUnit 26파일 3,052 | architectureTestLaneCheck → architectureCheck |
HS1-4 import 규칙 (@ArchTest 105, @Test 109) |
A | KEEP | PR ✓ |
| 7 | ca.java-conventions (+verifyDependencyLocks, resolveAndLockAll) |
206+0 | 모든 Java leaf | toolchain, -Werror, STRICT lock, BOM |
B | SIMPLIFY (quarantineTest 삭제, leaf 버전 고정) |
PR ✓ |
| 8 | ca.quality-conventions (+qualityCheck, auxiliaryStyleCheck) |
209+0 | 모든 Java leaf | Spotless, Checkstyle, Error Prone, SpotBugs | B | KEEP | PR ✓ (5분 넘으면 SpotBugs만 main) |
| 9 | ca.java-library, ca.spring-library, ca.spring-config, ca.platform-module, ca.grpc-platform-module |
83+105 | leaf 6/22/21/38/4 | leaf 종류별 조합 | B | KEEP | — |
| 10 | ca.test-jvm-agents |
90+0 | 모든 Java leaf | Mockito agent | B | SIMPLIFY → java-conventions 약 5줄 | — |
| 11 | ca.auxiliary-source-set |
151+145 | 15 leaf | 추가 source set | B | REPLACE-WITH-NATIVE (jvm-test-suite, ADR-BUILD-001 선례) |
— |
| 12 | ca.strict-test-lane |
573+424 | 모든 Java leaf, 선언 레인 47개, root 집계(build.gradle:109-130) |
레인이 0개 실행·skip·필수 클래스 누락 시 실패 | C | KEEP, "필수 테스트 실행 + skip 금지"의 유일한 구현으로 SIMPLIFY | 레인별 |
| 13 | ca.strict-qualification |
393+273 | 9 leaf, 13회 등록 | #12와 같은 검사 3중(*RequiredClasses + listener + XML 재읽기) |
C | MERGE → #12 | PR/main |
| 14 | ca.evidence + JUnitEvidence + RequiredTestExecution |
239+116 | build.gradle:18, #15, graphql |
JUnit XML 기준 skip 금지 | C | MERGE 후 DELETE | — |
| 15 | ca.conditional-transport-qualification |
91+236 | build.gradle:19, ci-quality-gates.yml:71 |
선택 transport 테스트 skip 금지 | C/E | MERGE → app-bootstrap 레인 1개 | PR→main ✗ |
| 16 | build-tools junit (JUnitEvidenceReader) |
138+76 | messaging, jpa | XML 재읽기 | C | MERGE | — |
| 17 | ca.api-surface (+ApiSurfacePolicy, JavaPublicTypes) |
549+172 | mongo·jpa·graphql check |
공개 타입 목록 변경 | D | SIMPLIFY: 유일 구현으로, #27·jpa-adopter 흡수 | PR→main ✗ |
| 18 | ca.public-path-snapshot |
288+37 (+#19와 공유 contract test 265) | build.gradle:23, ci-quality-gates.yml:62, releaseCheck, notification-platform.yml:89 |
permitAll 경로 기준선 | D (보안) | SIMPLIFY → app-bootstrap approval test (approvaltests 이미 의존성, app-bootstrap/build.gradle:255) |
PR→main ✗ |
| 19 | ca.archive-hygiene |
216+46 | build.gradle:22 → releaseCheck |
SHA가 붙은 오래된 jar | D | DELETE (leaf 버전 고정 시 원인 소멸; 이미지는 stageDockerJar rename 경유 app-bootstrap/build.gradle:306-311) |
tag→없음 |
| 20 | ca.release-provenance |
138+71 | root, optional-platforms; 모든 leaf jar 버전(JavaConventionsPlugin.java:45-48) |
버전·SHA 추적 | D | SIMPLIFY → app-bootstrap springBoot { buildInfo() } (런타임에서 Build-Revision 읽는 곳 0) |
tag ✓ |
| 21 | ca.jmh-benchmarks |
166+79 | 4 leaf, workflow 호출 0 | — | D | REPLACE-WITH-NATIVE (me.champeau.jmh) 또는 DELETE |
없음 |
| 22 | ca.config-contract / verifyEnvKeys |
476+211 | configContractCheck → ci, notification-platform.yml:89 |
env-keys.yaml(5,869줄) ↔ 설정 바인딩 |
D | SIMPLIFY → app-bootstrap JUnit (선례 OperationalErrorRegistryContractTest, build.gradle:103-106) |
PR→main ✗ |
| 23 | ca.graphql-platform |
188+0 | graphqlStableTest(ci-quality-gates.yml:68), verifyGraphQlProductionJar(check) |
stable 레인, jar 내용 | E | SIMPLIFY: 레인은 #12로, jar 검사만 | PR→main ✗ (레인) |
| 24 | ca.jpa-test-lanes |
159+118 | persistence-jpa | PostgreSQL 레인 목록 | E | SIMPLIFY → leaf strictTestLanes |
main |
| 25 | ca.redis-topology-lane |
242+133 | cache-redis, redis-sdk-topology.yml |
topology 레인 + 자체 tracker | E | SIMPLIFY → #12 레인 | PR(경로 필터) ✓ |
| 26 | ca.jpa-evidence + ca.jpa-qualification |
2,838+744 | jpa check(build.gradle:184-185), ci-quality-gates.yml:188-207, jpa-release.yml, jpa-r2-evidence.yml |
readiness card, evidence manifest | E | 플랫폼 DELETE, registry 검사만 leaf 테스트로 | PR→main/tag ✗ |
| 27 | ca.notification-api-surface + ca.notification-evidence |
851+250 | build.gradle:24-25, notification check(:84-87) |
API 목록, evidence | E | MERGE(API → #17) / DELETE(evidence) | PR→main ✗ |
| 28 | ca.notification-configuration |
222+140 | build.gradle:26, notification check |
설정 계약 | E | SIMPLIFY → leaf 테스트 | PR→main ✗ |
| 29 | ca.messaging-qualification + ca.messaging-certification |
819+253 | build.gradle:28, leaf 4, integration-main.yml:209, messaging-certification.yml:44 |
계약 evidence, 해시 | E | SIMPLIFY → leaf 테스트 | main ✓ / PR(경로) ✓ |
| 30 | ca.mongo-verification |
544+223 | mongo check(build.gradle:226-228) |
레인 태그 분리, 자체 XML reader | E | DELETE/SIMPLIFY | PR→main ✗ |
| 31 | ca.developer-bootstrap + ca.bootrun-dotenv |
320+184 | build.gradle:29 (1차 O-1 Critical 원인), README.md:42 |
로컬 기동 순서 | F | SIMPLIFY (app-bootstrap에만 또는 scripts/) |
없음 |
| 32 | architectureCheck / verifyDependencyLocks |
— | ci-quality-gates.yml:62 |
A, B | A/B | KEEP | PR ✓ |
| 33 | ci (build.gradle:138-147) |
— | PR | PR 게이트 | — | SIMPLIFY (#34-36 빼기) | PR |
| 34 | qualificationCheck / systemTestCheck |
— | ci |
전체 앱 기동 테스트 | C | KEEP | PR→main ✗ |
| 35 | sampleWebContractCheck, configContractCheck |
— | ci |
실서버 sample, env 키 | D | KEEP | PR→main ✗ |
| 36 | quarantineTest (build.gradle:88) |
— | ci-quality-gates.yml:212-216 |
@Tag("quarantine") 0개 |
C | DELETE | PR(참고)→없음 |
| 37 | integrationCheck, releaseCheck |
— | integration-main.yml, release.yml:60 |
컨테이너 레인 / 릴리스 | C/D | KEEP (releaseCheck는 ci를 다시 돌림) |
main ✓ / tag ✓ |
| 38 | .github/workflows 18개 |
2,767 | PR 1,358 · main 339 · tag 709 · 야간 298 · reusable 63 | — | 혼합 | SIMPLIFY | — |
카테고리별 LOC
| 카테고리 | build-logic | build-tools | 합계 | 비율 |
|---|---|---|---|---|
| A 아키텍처 | 2,242 | 0 | 2,242 | 13.4% |
| B 품질 도구 | 989 | 0 | 989 | 5.9% |
| C 레인·증거 | 2,345 | 214 | 2,559 | 15.3% |
| D 릴리스·스냅샷 | 2,027 | 687 | 2,714 | 16.2% |
| E 기능별 | 840 | 6,920 | 7,760 | 46.3% |
| F 개발 편의 | 504 | 0 | 504 | 3.0% |
| 합계 | 8,947 | 7,821 | 16,768 |
표 밖: leaf build.gradle 74개 3,531줄 = 의존성 857, plugins 295, 주석·빈 줄 1,400, 그 외 로직 979(그중 약 660줄이 레인 DSL: strictTestLanes 413, auxiliarySourceSets 122, strictQualification 약 125). leaf 파일 안의 아키텍처 검사 로직은 0줄. 요약: 목적(A)에 쓰이는 빌드 코드 약 1.3–2.2k줄, 나머지 14.5k줄은 다른 목적.
중복
- 의존 방향을 4번 검사. 컴파일러(registry에 없는 모듈은 classpath에 없어 import 실패) /
verifyModuleDependencyDirection(73개 leaf 전부, 선언 edge와 컴파일 가시 edge) /verifyCompositionRuntimeMembership("미등록"이 될 수 있는 건:sample-portfolio뿐 → 방향 게이트가 이미 차단) / ArchUnit adapter 패키지 규칙 약 7개(AdapterBoundaryArchitectureTest.java:76-392). 09-16 계획이 runtime-membership 삭제를 "runtimeClasspathManifest를RuntimeMembershipClasspathAgreementTest가 읽는다"며 기각했으나 지금 두 이름 모두 grep 0 → 근거 소멸. ArchUnit 쪽 중복은 비용이 작고modules.json이 느슨해져도 잡아내므로 유지. - "필수 테스트 실행 + skip 금지" 구현 6개(1차 O-8의 5개 +
MongoJUnitXml,RedisTopologyExecutionTracker): listener 방식StrictLaneExecutionTracker,RejectSkippedTestsListener,RedisTopologyExecutionTracker; JUnit XML 파서JUnitEvidence.java(128),JUnitEvidenceReader.java(114),MongoJUnitXml.java(79). #12가 이미 필수 클래스별 실행과 skip 금지를 모두 하므로(StrictTestLanePlugin.java후반) #13·#14·#15·#16은 부분집합. - API surface 검사 3개:
ca.api-surface(javac 파싱),NotificationApiSurfaceVerifier(정규식),JpaAdopterApiSurfaceVerifier(import 정규식). - fileserver 제외 규칙이 두 곳에서 모순:
modules.json은 app-bootstrap →application-fileserver,adapter-outbound-fileserver허용,dependencyPolicy는 같은 모듈을absent로 금지. app-bootstrap 외에 fileserver edge를 허용받은 모듈 없음 → registry에서 두 항목을 빼면 방향 게이트가 전이 의존까지 차단. - HS1은 빌드 단계에서 뚫려 있음. 순수성 task는
application-*만 검사(ArchitecturePlugin.java:147) → domain-core에 외부 의존성을 추가해도 빌드 통과(ArchUnitDOMAIN_IS_PURE는 실제 import한 경우만). - CI가 아키텍처 게이트를 반복 실행:
notification-platform.yml:84-85,fileserver-certification.yml:50,jpa-release.yml:123-125,releaseCheck는ci전체 재실행. - 기능 전용 플러그인 5개가 root에(
build.gradle:24-28) →:domain-core:check한 번에도 notification·jpa·messaging 플러그인 설정 실행. - ArchUnit이 모든 leaf를 보지 않음. 대상은 app-bootstrap architectureTest 런타임 classpath; websocket·grpc 어댑터는
conditionalTransportBuildContractTest쪽에만(app-bootstrap/build.gradle:261-263), optional-platforms 18 leaf와 sample도 빠짐. 전 leaf를 보는 HS5 게이트는 Gradle 방향 task뿐.
2026-09-16 계획 이행 상태
- Track A: 완료(커밋 기록 기준).
- B1 공통화: 부분 — composite action은 널리 쓰임;
_reusable-gradle.yml은 job 2개만 쓰고 그중 하나는 항상 실패(1차 O-2). - B2 release 1개로: 미완 — tag
v*트리거 workflow 3개(release.yml,jpa-release.yml,fileserver-certification.yml). - B3 PR은 변경 모듈만: 부분 — 경로 필터는 pr-adapters, notification, fileserver-pr, redis, messaging;
ci-quality-gates는 PR마다 55개 leaf:ci전체;object-storage-qualification은 경로 필터 없이 PR마다 MinIO 컨테이너. - B4 게이트 재배치: 미이행 — 표의 ✗ 11개가 여전히 PR.
- B5 gate matrix: 방향 변경(매트릭스 파일 삭제,
ci-quality-gates.yml:5-10). - B6 도달 불가 task: 잔존(jmh 4 leaf, 테스트 0개 quarantine).
- Track C: 대부분 완료 — 이미지 build·push, CycloneDX SBOM, Trivy 스캔 있음, 서명 없음(cosign 0).
목표안 비교
| 안 | build-logic+tools LOC | leaf build | workflows | HS1 | HS2/HS3 | HS5 | 잃는 것 | 작업 규모 | 위험 |
|---|---|---|---|---|---|---|---|---|---|
| O1 중복만 정리 | 약 12,500–13,000 | 약 3,450 | 약 2,700 | ArchUnit + 컴파일러 | registry + ArchUnit | Gradle 게이트 | 없음 | 파일 약 25개 삭제, leaf 약 12개 | 낮음 |
| O2 단계 재배치만 | 16,768 | 약 3,520 | 약 2,720 | 동일 | 동일 | 동일 | 없음(유지비 그대로) | root 약 20줄, leaf 3, workflow 3 | 낮음 |
| O3 아키텍처 코어 + 컨벤션만 build-logic, 기능 검사는 소유 leaf 테스트로 | 약 3,500–4,000 (build-tools 0) + leaf 테스트 +2,000–3,000 | 약 3,200 | 약 2,400 | ArchUnit + 순수성 task(domain-core 포함) | 동일 | Gradle 게이트 | 빌드 산출물로서의 evidence manifest, 삭제 플러그인의 TestKit | 파일 약 120개 삭제, 테스트 30–40개 신설, leaf 약 20, workflow 약 8 | 중간 |
| O4 ArchUnit 중심 (Gradle 방향 task 제거) | 약 2,000–2,500 | 약 3,200 | 약 2,400 | 동일 | 동일 | ArchUnit만 | 선언만 된 edge, runtimeOnly edge, app-bootstrap classpath 밖 leaf 전부 | 중간 | HS5 약화, 높음 |
| O5 Gradle 기본 기능만 (Groovy 스크립트 플러그인, TestKit 없음) | 약 800–1,200 | 약 3,200 | 약 2,400 | 동일 | 동일 | 약 100줄 Groovy | 게이트 자체 테스트, configuration cache·parallel 안전성 재증명(ArchitecturePlugin.java:91-95) |
큼(09-18 Groovy→Java 전환 되돌림) | 높음 |
권고: O3 (순서: O2 → 바로 할 것 → O3)
- 이유: 목적에 필요한 빌드 코드는 registry, 방향·순수성 task, 컨벤션, 레인 하나로 충분(HS1-4는 ArchUnit이 이미 담당). 이미 내려진 결정과 같은 방향(
13-build-dependency-ci.md§0 "build-tools evidence/readiness/qualification 플랫폼은 축소", "특수 plugin은 opt-in", §0-A 기능 계약은 "owner module test가 소유"). 선례 두 개(ADR-BUILD-001,OperationalErrorRegistryContractTest). - 틀리면 반박되는 가정: (1) evidence manifest를 build-tools 밖에서 읽는 곳 없음(grep: build-tools, CI artifact 업로드
ci-quality-gates.yml:195-201, 문서뿐) — 감사·릴리스 소비자가 있으면 JPA manifest만 tag 단계에. (2) build-tools 로직 대부분 Gradle 무관(98파일 중 68파일, 3,416/5,888줄이org.gradle미import) → 테스트로 이전은 기계적. (3) 73개 leaf + 빌드 2개 전부를 보는 HS5 게이트는 Gradle 방향 task뿐. (4) leaf 테스트로 옮기는 검사는 읽는 파일을inputs로 선언(안 하면 1차 O-4처럼 UP-TO-DATE 거짓 통과). - 가장 강한 반론: 09-16 기록상 감사가 삭제하자던 17건이 실행으로 반박됐고 "작동하게 만드는 데는 코드가 든다"; Gradle task는
@Disabled로 조용히 꺼질 수 없지만 테스트는 가능. 답: 옮긴 테스트는rejectSkipped레인에서; 소유자 원칙상 이 검사들은 어차피 2단계 항목. - 솔직한 평가: A 자체(TestKit 포함 약 1.3k줄)와 ArchUnit은 규모가 정당 — 줄일 대상 아님.
바로 할 것 (어느 안을 고르든 안전)
ca.runtime-membership과 연결 코드 삭제(−318줄, 방향 게이트가 대신).quarantineTest삭제:JavaConventionsPlugin.java:149-165,build.gradle:88-92, CI job(약 −30줄).redis-sdkjob 삭제(1차 O-2, 약 −12줄).ca.strict-qualification13건을strictTestLanes의requires+rejectSkipped로(−666줄); messaging evidence reader가 읽는 XML 경로만 레인 기본 경로로.ca.evidence삭제, conditional-transport를 app-bootstrap 레인으로(−682줄).- XML reader 통합:
JUnitEvidenceReader,MongoJUnitXml(−293줄). - API surface 구현 하나로(약 −550줄).
dependency-policy를 Gradle 기본 기능으로(−495줄): fileserver는 app-bootstrapallowed_dependencies에서 두 항목 제거; yaml/jackson은constraints { … version { rejectAll() } }(rejectAll이 모듈 유입 시 해석을 실패시키는지 leaf 1개로 먼저 확인 — 미검증).- 순수성 task 필터에 domain-core·shared-contract 추가(+약 3줄) → HS1 빌드 단계 공백 해소.
- CI 아키텍처 게이트 중복 실행 제거(약 −10줄).
ca.test-jvm-agents를 java-conventions에 합침(−80줄), jmh는me.champeau.jmh또는 삭제(−245줄).- 단계만 옮기기(삭제 없음):
ci에서configContractCheck,qualificationCheck,sampleWebContractCheck제거;ci-quality-gates.yml:62에서:verifyPublicPathSnapshot제거; graphqlStable·conditionalTransport, jpa-candidate job, configuration-cache job을 integration-main으로; notification·jpa·mongo·api-surface 검사를 leafcheck에서 떼어mainCheck로; build-logic·build-tools job에 경로 필터.
1–11 합계 약 3,400줄 감소, 잃는 보호 없음.
조사 범위
전체: root build·settings, build-logic build.gradle·README, ArchitecturePlugin과 task 3개, ModuleRegistry·installer, RuntimeMembership, Java·Quality·레인 컨벤션, StrictTestLanePlugin, StrictQualificationExtension, EvidenceExtension, ci-quality-gates.yml, 09-16 계획, 1차 Group O, 13-build §0. 훑음: build-tools(구조, task 등록, Gradle API 비중, API surface verifier 2개), 나머지 workflow(트리거·job·gradle 호출), leaf build(스크립트 분류 + 3개 정독), ArchUnit(규칙 이름 + 2개 파일). 추정: rejectAll 동작, 각 안의 LOC, PR 소요 시간. git 이력상 build-logic·build-tools는 60b6a319에서 새로 추가된 것으로만 보여 09-18 이전 구성요소별 도입 이유는 추적 불가.
TEST — 테스트 가독성과 구조
결론
given/when/then 흐름은 이미 상당 부분 보인다. 6줄 이상 테스트의 71%(5,313/7,463)는 빈 줄로 단계를 나누고, 이름은 8,743개 전부 camelCase 행동 문장이다. 필요한 일은 스타일 신규 도입이 아니라 지금 스타일을 규칙으로 적고 // given // when // then 주석을 명시하는 것이다(주석을 모두 갖춘 파일은 현재 0개).
가독성보다 급한 문제 두 가지:
- fake가 실제 adapter와 같은 계약 테스트를 통과하지 않는다. 1차 리뷰의 "fake가 결함을 숨긴 6건" 중 5건은 공유 contract 테스트나 실제 구현을 거치는 테스트가 있었으면 잡혔을 것으로 판단. 나머지 tus 1건은 "테스트 하나에 행동 하나" 규칙으로 잡혔을 것.
- 이름이 약속한 것을 단언하지 않는 테스트가 많다. 존재·타입·예외 없음만 확인하는 테스트 약 1,050개(12%).
adopter가 복사하는 sample-portfolio가 가장 약하다(DisplayName 0%, 단계 분리 54%, 115줄 테스트 1개) → migration은 sample부터. 8,764개 전체 재작성은 권하지 않는다.
계층별 평가
blank% = 6줄 이상 테스트 중 빈 줄로 단계를 나눈 비율, DN% = @DisplayName 메서드 비율, weak% = 존재·타입·no-throw 단언만 있는 비율.
| 계층 / 모듈 그룹 | 샘플 파일 | GWT가 보이나? | 이름 | 단언 품질 | 주요 문제 |
|---|---|---|---|---|---|
domain (domain-core 2 + sample domain) |
DomainCoreContractTest, WorkLogTest, PosterTest |
짧아서 대체로 보임, WorkLogTest는 빈 줄 없음 |
camelCase, DN 0% | 값과 reason 코드까지 | WorkLogTest.java:35 NPE 타입만; WorkLogTest.java:65, PosterTest.java:46 한 테스트에 행동 2개. 좋은 예 PosterTest.java:73 |
| shared-contract (242) | TraceParentTest, OperationalErrorTest |
대부분 한 줄(blank 27%) | DN 2% | 구체적 값 | 표 형태인데 파라미터화 안 됨(30개·32개가 거의 같음) |
| application-* (667) | SubmitDurableOperationUseCaseTest, CacheAsideExecutorTest, DispatchOutcomeRecorderTest |
좋음(78%) | 영어 문장, DN 14% | weak 16% | fake 중복(TransactionPort 15개), DispatchOutcomeRecorderTest.java:169 no-op fake. 좋은 예 SubmitDurableOperationUseCaseTest.java:92 |
| persistence (1,497) | OutboxStoreAdapterTest, DurableOperationStoreContractTest, PostgreSqlWorkClaimContractTest, MongoChangeStreamRunnerTest, sample WorkLogRepositoryAdapter(Integration)Test |
좋음(81%) | DN 52% | weak 15%, 필드 10개 한 줄씩 단언 | "contract" 테스트가 adapter가 아니라 raw SQL 검증; OutboxStoreAdapterTest.java:140 행동 5개. 좋은 예 MongoChangeStreamRunnerTest.java:28 |
| outbound 기타 (1,804) | RedisHashOperationsContractTest, LiveRedisGuardrailTest, RoutingNotifierTest, FailOpenDependencyLoggerTest, DefaultGenericHttpGatewayTest, LocalPersistentControlPlaneTest |
74% | DN 33% | weak 12%, 30줄 넘는 테스트 143개 | Redis *ContractTest 16클래스(160 tests)가 in-memory에서만; PII 부재 단언이 항상 통과 |
| inbound (2,139) | TusProtocolContractTest, NotificationCallbackMvcControllerTest, RateLimitKeyResolverTest, GlobalExceptionHandlerTest, GraphQlMutationIdempotencyContextTest, HandshakeAdmissionPipelineTest |
65% | DN 47% | weak 11%, envelope 필드 줄마다 단언 | 수락+거부를 한 테스트에(#11을 숨김), 컨트롤러 직접 호출로 HTTP 경로 우회. 좋은 예 HandshakeAdmissionPipelineTest.java:103 |
| grpc:* (588) | GrpcIdempotencyInterceptorTest, GrpcOperationLedgerRepositoryTest, InMemoryOperationLedger |
68% | DN 98% | weak 3%, 최고 | fake가 FAILED→COMMITTED 허용(#15), 공유 ledger contract 없음 |
| messaging:* (829) | MessagingAdapterContract, InMemoryHarnessContractTest, OutboxRelayTest |
80% | DN 18% | weak 15%(대부분 validator 예외 타입) | 공유 contract 모범 사례가 이미 있음. 단 relay 테스트 fake가 인코딩을 안 해 #7을 숨김. 좋은 예 OutboxRelayTest.java:46 |
| bootstrap (757) | ArchitectureViolationFixtureTest, CapabilityDependencyValidatorTest, TracingActivationContextTest, MetricsContractConfigTest |
57% | DN 26% | weak 6% | 복붙 테스트 55개, assertThat(context).isNotNull() |
| sample-portfolio (218) | 파일 9개 | 54% | DN 0% | weak 11% | 115줄 테스트, 동작이 다른 FakeRepo 2개, 인자 7개 생성자 호출 7번 반복, TransactionPort fake 10개 |
Findings (영향 큰 순)
-
[Required] fake가 실제 adapter와 같은 계약으로 묶여 있지 않다. 일부 fake는 Javadoc에 "adapter와 같은 의미"라고 적었지만(
InMemoryDurableOperationStore.java:12-19,InMemoryOperationLedger.java:15-19) 확인하는 테스트가 없다. 반대 계약 검증도 있다:GrpcOperationLedgerRepositoryTest.java:191은 JPA 쪽에서 "FAILED는 종료 상태"를 검증, fake는 그 상태에서 COMMITTED 허용.DurableOperationStoreContractTest.java:183은 adapter를 거치지 않고 raw SQL로 충돌만 확인(예외 타입만). -
[Required] 이름이 약속한 성질을 단언하지 않는다.
PostgreSqlWorkClaimContractTest.java:78claimsAreDeterministicallyOrdered: 순서는 안 보고isNotEmpty()만.WorkLogUseCasesTest.java:281batchCreatePersistsEveryItemAtomically: 트랜잭션 fake가 그냥 통과시켜 원자성 증명 불가, 개수 2개만.RoutingNotifierTest.java:174: 예외 메시지가"provider-failure"라 원래 PII가 없어doesNotContain("secret@gmail.com")은 절대 실패 안 함(FailOpenDependencyLoggerTest.java:71동일).NotificationCallbackMvcControllerTest.java:118"…BeforeIngress": 미리 만든byte[]를 컨트롤러에 직접 넘겨 converter 경로 우회.MetricsContractConfigTest.java:57: SLO 버킷 대신isNotEmpty().SampleApplicationContextTest.java:45,TracingActivationContextTest.java:79:assertThat(context).isNotNull().- 규모 추정: presence만 133, 예외 타입만 672, no-throw만 123, 섞임 124 → 약 1,050개(12%). 단언 없는 93개는 대부분 ArchUnit
.check()라 정상. presence만 7개를 직접 봤더니 5개는 실제로 약함. 예외 타입만은 대부분 validator 테스트라 "틀린 이유로도 통과"(예:WorkLogTest.java:35는 어느 인자가 null이어도 NPE).
-
[Required] 한 테스트에 행동이 여러 개. 약 646개(7.4%): 예외 단언 블록 2개 이상 484개 ∪ 단언 뒤 다시 행동 181개. 결함을 숨긴 사례:
TusProtocolContractTest.java:149는 수락과 거부를 한 테스트에 묶고 chunk 2에는 틀린 checksum만 보내 누적 digest 버그(1차 C-1)가 안 보임. 규칙 "// when은 정확히 하나"로 GWT 요청과 이 문제가 같이 풀림. -
[Required] 복사 원본인 sample이 가장 약하다.
PosterImagePublicationWorkflowTest.java:73: 115줄, mock 3개,thenAnswer안에서 assert, inline FQCN, 인자 16개 생성자, 행동 4개. FakeRepo 두 벌이 다르게 동작:WorkLogUseCasesTest.java:45는 upsert + 필터,CreateWorkLogOutboxTest.java:48은 append +findPage빈 결과; 둘 다 실제 adapter와 달리 정렬 무시(WorkLogRepositoryAdapter.java:71-74).WorkLogRepositoryAdapterTest.java:70"maps to entity and back": id만 확인. -
[Consider] fake 중복. 테스트 구현 3개 이상인 포트 42개, 구현 합계 198개(lambda fake 미포함 → 하한).
TransactionPort26개/25파일/4모듈(application-notification은 공유PlatformFakes.java:54가 있는데도 10개 파일이 따로),MessagePublisher15,ObjectControlStore7(한 모듈 안, 이름만 다른 InMemory/Map/Recording/Noop),RedisRuntimeClient7(BrokenClient4),Clock직접 상속한 가변 시계 10. -
[Consider] 표 형태 테스트가 파라미터화 안 됨.
@ParameterizedTest는 45개 파일뿐. 대상:TraceParentTest(30),OperationalErrorTest(32),ArchitectureViolationFixtureTest(55),OutboxStoreAdapterTest.java:140. -
[Consider] 예외 단언이 when과 then을 한 식에 묶음.
assertThatThrownBy계열 2,400개(27%),catchThrowable26개. 캐스팅 관용구extracting(ex -> ((X) ex).reason())9개 파일 18줄. -
[Consider] 내부 구현을 직접 다루는 테스트 약 170개(2%, 상한). reflection 42, 컨트롤러 직접 호출 9,
verify만 있는 테스트 31, 타입 모양 확인 89(architectureTest lane 밖). -
[Nit]
assertThat(x.contains(y)).isTrue()14개 파일 29줄; DisplayName 3,430개 영어, 한국어 1개(MetricsAlertingContractTest.java:205), 상당수는 메서드 이름을 띄어 쓴 것뿐.
Fakes와 contract 테스트
| port | fakes (개수, 위치) | 실제 adapter | 공유 contract? | 발견된 차이 |
|---|---|---|---|---|
DurableOperationStorePort |
2 — application-core/.../InMemoryDurableOperationStore.java, web testFixtures TestDurableOperationStore.java |
DurableOperationStoreAdapter |
없음, PG 테스트는 raw SQL | 1차 #4 재제출 25P02, fake는 통과 |
GrpcOperationLedger |
1 — grpc-policy/.../InMemoryOperationLedger.java |
JpaGrpcOperationLedger |
없음 | 1차 #15 FAILED→COMMITTED |
RedisCommandGateway |
1 (2.4k줄) — InMemoryRedisCommandGateway |
LettuceRedisCommandGateway |
부분적: LiveRedisOperationsFixture는 있으나 contract 16클래스(160 tests)가 new RedisOperationsFixture()에 고정, live는 20 tests |
HDEL/PEXPIRE 미재현 |
UploadApplicationService (tus) |
1 — InMemoryUploadApplicationService.java:117 |
DefaultUploadApplicationService |
없음 | fake가 버그와 같은 누적 digest. contract만으로 부족, chunk 2 정상 케이스 필요 |
DeliveryProjectionStorePort |
3 — DispatchOutcomeRecorderTest.java:169(no-op), NotificationPlatformNoops, ProviderEventLateMatchTest.java:211 |
JpaDeliveryAttemptStore |
없음 | projection 덮어쓰기(1차 B-5) |
MessagePublisher |
15 / 10파일 | DefaultMessagePublisher |
없음, relay는 RecordingOutboxPublisher(OutboxRelayTest.java:416) |
1차 #7 재인코딩 실패 |
WorkLogRepository (sample) |
2, 서로 다른 동작 | WorkLogRepositoryAdapter |
없음 | 정렬 무시, save 의미 불일치 |
IdempotencyStorePort |
4 (app-core, web ×2, sample) | IdempotencyStoreAdapter, RedisIdempotencyStoreAdapter |
없음 | 미평가 |
ObjectControlStore |
7 (objectstorage 한 모듈) | LocalDevObjectControlStore, S3ConditionalObjectControlStore |
없음 | 미평가 |
권장 패턴: 저장소 안에 이미 있는 MessagingAdapterContract(messaging-testkit/.../MessagingAdapterContract.java:19, 사용처 InMemoryHarnessContractTest.java:14)를 표준으로.
포트 소유 모듈의 testFixtures:
abstract class XxxContract { protected abstract Xxx subject(); @Test ... }
fake 쪽 unit lane: InMemoryXxxContractTest → @Nested class Contract extends XxxContract
adapter 쪽 PG/live lane: JpaXxxContractTest → 같은 @Nested 구조
static kit 방식(LegacyOutboxAppendContract)은 쓰지 않는다 — 새 검증을 추가해도 사용하는 쪽이 호출하기 전까지 어디서도 실행되지 않음. 추상 클래스 방식은 케이스를 추가하는 순간 모든 구현에서 돈다. application-core/src/testFixtures는 이미 있지만 지금은 persistence-jpa PG lane만 소비(persistence-jpa/build.gradle:88) → 다른 모듈은 testImplementation(testFixtures(project(':application-core'))) 추가. Object Mother는 이미 쓰는 OutboxFixtures.pending(), ContractMessage.orderCreated() 형태가 기본; builder는 인자 6개 이상이고 테스트마다 필드 2개 이상 바꿀 때만(CreateWorkLogCommand 9, PublishPosterImageCommand 10, UpdateWorkLogCommand 6).
제안 컨벤션 (새로 쓰거나 고치는 테스트에만)
- 이름: lowerCamelCase 행동 문장
<상황/주체><결과>(지금 방식 유지;test/should접두어·snake_case 도입 안 함). 이름에 적은 성질은 반드시 단언한다. - @DisplayName: 선택. 메서드 이름으로 못 쓰는 내용(숫자, 기호, "왜")이 있을 때만. 언어는 저장소 단위로 하나 — 기본 영어(현재 3,430개). 한국어 전환은 소유자 결정, 바꾸더라도 새 테스트부터. (반론: 한국어 팀은 IDE 리포트에서 한국어가 잘 읽힘 — 파일마다 섞이는 비용이 더 큼.)
- GWT 주석: 본문 statement 3개 이상이면
// given// when// then필수 + 구역 사이 빈 줄. 준비할 게 없으면// given생략. 한 줄 테스트(순수 함수 입력 → 단언 1개)와 ArchUnit.check()는 주석 없이.// when은 정확히 하나 — 두 번 필요하면 테스트를 둘로. 예외 테스트는catchThrowable로 when 분리; 기존assertThatThrownBy는 손댈 때// when & then표시까지 허용. - @Nested: 테스트 10개 이상이고 대상 연산 2개 이상인 클래스에서만, 연산 단위 한 단계. contract 테스트에도 사용.
- 단언: then은 when의 결과 하나에 대해서만. 여러 필드는
usingRecursiveComparison().isEqualTo(expected)또는extracting(..).containsExactly(..).isNotNull/isNotEmpty/isPresent/doesNotThrowAnyException만으로 끝내지 않음(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입 + reason/message(isInstanceOfSatisfying).assertThat(x).contains(y)형태. 표 형태 입력은@ParameterizedTest. - fake vs mock: 포트는 hand-rolled fake, 포트당 하나, 포트 소유 모듈 testFixtures에. adapter가 있는 포트면 fake와 adapter가 같은
XxxContract통과. Mockito는 프레임워크 경계(Spring Data repo, SDK client)와 장애 주입에만,thenAnswer안에서 assert 금지. no-op fake는 결과를 단언하지 않는 협력자에만.
Before — src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java:232-264
@Test
void updateRejectsRevertingStatusToOpen() {
FakeRepo repo = new FakeRepo();
WorkLog created =
new CreateWorkLogUseCase(
repo, IDS, STUB_EVENT_IDS, NO_OP_OUTBOX, NO_CORRELATION, UTC_CLOCK, TX)
.handle(createCmd("status revert"));
WorkLog inProgress =
new UpdateWorkLogUseCase(repo, TX)
.handle(
new UpdateWorkLogCommand(
created.id(),
Patch.absent(),
Patch.absent(),
Patch.absent(),
Patch.absent(),
Patch.of(WorkLogStatus.IN_PROGRESS)));
assertThatThrownBy(
() ->
new UpdateWorkLogUseCase(repo, TX)
.handle(
new UpdateWorkLogCommand(
inProgress.id(),
Patch.absent(),
Patch.absent(),
Patch.absent(),
Patch.absent(),
Patch.of(WorkLogStatus.OPEN))))
.isInstanceOf(WorkLogInvariantException.class)
.extracting(ex -> ((WorkLogInvariantException) ex).reason())
.isEqualTo(WorkLogInvariantException.Reason.INVALID_STATUS_TRANSITION);
}
After — 같은 동작 검증(필드는 JUnit 기본 수명이라 테스트마다 새 인스턴스)
private final FakeRepo repo = new FakeRepo(); // sample testFixtures 공유 fake로 이동 예정
private final CreateWorkLogUseCase create =
new CreateWorkLogUseCase(repo, IDS, STUB_EVENT_IDS, NO_OP_OUTBOX, NO_CORRELATION, UTC_CLOCK, TX);
private final UpdateWorkLogUseCase update = new UpdateWorkLogUseCase(repo, TX);
@Nested
class Update {
@Test
void rejectsMovingAnInProgressWorkLogBackToOpen() {
// given
WorkLog inProgress = update.handle(statusChange(aCreatedWorkLog().id(), IN_PROGRESS));
// when
Throwable thrown = catchThrowable(() -> update.handle(statusChange(inProgress.id(), OPEN)));
// then
assertThat(thrown)
.isInstanceOfSatisfying(
WorkLogInvariantException.class,
e -> assertThat(e.reason()).isEqualTo(Reason.INVALID_STATUS_TRANSITION));
}
}
private WorkLog aCreatedWorkLog() {
return create.handle(createCmd("any title"));
}
private static UpdateWorkLogCommand statusChange(WorkLogId id, WorkLogStatus status) {
return new UpdateWorkLogCommand(
id, Patch.absent(), Patch.absent(), Patch.absent(), Patch.absent(), Patch.of(status));
}
Migration과 enforcement 계획
- 규칙 문서화 (PR 1개). 위 6개 규칙을 canonical
AGENTS.md"테스트 전략"에 약 25줄,CLAUDE.mdTesting에는 포인터 한 줄. 이후 적용 범위는 새로 쓰거나 고친 테스트. sample-portfolio전체 (62 files / 218 tests).WorkLogRepositoryContract를 만들어 fake와WorkLogRepositoryAdapter(integrationTest lane) 양쪽에서; TransactionPort fake 하나로;PosterImagePublicationWorkflowTest행동별 분리.- divergence가 확인된 6개 포트의 contract를 1차 Wave 1 수정과 같은 PR에서. contract가 현재 코드에서 먼저 실패하면 그 자체가 회귀 테스트. Redis는 contract 16클래스를 fixture 타입으로 추상화하고 live lane subclass 추가. 공용
RecordingTransactionPort는application-coretestFixtures. - 계층별 모범 모듈 하나씩(수정 때문에 어차피 손대는 곳): application-core
operation/idempotency, persistence-jpaoperation/outbox, weberror, cache-redissdk/lettuce/operations. - 약한 단언 정리(목록, 게이트 아님). presence만 133 + no-throw만 123은 모듈별로; 예외 타입만 672는 이름이 reason을 약속하는 경우만; 나머지는 손댈 때(boy-scout).
Enforcement 판단
- GWT 주석 게이트는 만들지 않는다: 주석은 bytecode에 없어 ArchUnit이 못 봄; Checkstyle로 "statement 3개 이상 메서드"만 골라 검사하기 어려움; 이 저장소는 텍스트 파서 게이트를 이미 지웠음(
verifyDocumentedLeafCount삭제);// when이 있다고 행동 하나가 증명되지도 않음. - Consider: Checkstyle
MethodLength(max 50)를 test에 — 설정 파일을 main/test가 공유(QualityConventionsPlugin.java:60), 현재 50줄 초과 테스트 68개를 baseline 억제 필요, integrationTest/systemTest lane은 Checkstyle 대상 아님 → 비용 작지만 효과 중간 이하, 지금은 보류 권고. - 실질적 강제 수단은 구조: fake와 adapter가 같은 추상 contract를 상속하면 한쪽만 약해지는 일이 없다.
Coverage note
범위: 등록 leaf 73개의 main·testFixtures 제외 모든 source set; @Test/... 파일 1,483, 메서드 8,743(호출 측 1,500/8,764와 차이는 regex 차이). 스크립트: scratchpad {stats,methods,weak2,fakes,tgrep}.py. 약 40개 파일을 메서드 단위로 읽고 약한 단언 분류 14개는 본문 직접 판정. 한계: 분류는 AST 아닌 regex 추정; lambda fake 미포함; graphql·websocket systemTest 깊게 안 읽음; "5/6건을 잡았을 것"은 판단(tus·notification 건은 누락 케이스 추가 가정); 단언 강도를 정확히 재려면 한두 모듈에 PIT mutation 테스트.
X1 — 모듈 간 기능 중복
기능 지도 (현재 → 권고)
| 기능 | 현재 구현 | 공유 계약? | 갈라짐? | 권고 | 크기 |
|---|---|---|---|---|---|
| Outbox | 저장 모델 3개(outbox_event, *_v2 테이블 5개, messaging_outbox), append 포트 4개, claim SQL 4개, relay 3개(+Debezium CDC), retry 정책 3개, 정리 작업 2개. 기본 조립은 v1만 |
app-core에 세대 3개 공존, messaging은 별도 | 예 | 앱 쪽 1개(v1 테이블 + fencing claim), V2 삭제; messaging outbox는 유지 | L |
| 요청 멱등성 | 계약 2개(v1/V2), store 3개, executor 조립 위치 3곳, inbound 전용 ledger 3개(websocket SPI, graphql context, grpc ledger) | app-core v1+V2 | 예 | V2를 정본, v1 삭제, 조립 1곳, inbound는 V2 사용 | M |
| 자연키 생성-또는-반환 | durable operation(예외 catch), notification request(ON CONFLICT), 미사용 upsert executor |
없음 | 예 (Critical #4) | durable operation을 notification 방식으로, upsert executor 삭제 | S |
| Inbox / 소비자 dedup | app-core inbox(소비자 0), messaging inbox(미조립), mongo 변경 dedup, notification provider ledger | 포트 2개 | 복붙 흔적 33% | app-core inbox 삭제, 나머지 유지 | M |
| lock / lease / fencing | app-core 포트 4개(lock, lease, cache refresh, operation lease), row lease 약 9개, 범용 claim executor(참조 0) | owner·attempt record 중복 | 예 | 미사용분 삭제, fencing은 contract kit로 검증 | M |
| caller 트랜잭션 guard | 9벌 복사 | 없음 | 예 (E-3) | persistence-jpa 안 helper 1개 | S |
| Backoff 계산식 | 10개 | 없음 | "full jitter" 뜻 3가지 | 앱 쪽 5곳에 shared-contract Backoff |
S |
| Rate limit | shared-contract 포트 + Redis 구현(조립됨), web 전용 병렬 타입 세트(구현체 0) | 있음 | 예 (FAIL_OPEN 허용 여부) | web 병렬 타입 삭제 | S |
| Admission / in-flight | 약 11개 | 없음 | 예 (gRPC M1 수정이 1곳만) | 유지, Semaphore 사용 |
S |
| Kafka producer | 2개(legacy seam, platform) | messaging bridge | 둘 다 TLS/SASL 없음 | outbox 정리에 포함 | M |
| 파일 control plane / canonical JSON | 직접 짠 JSON parser 3개, 파일 CAS store 3개, FilePublicationPort 소비자 0 |
없음 | 예 | 결정 필요(삭제 권고) | L |
| readiness / evidence / API-surface / moduleboundary | 카드 스키마 3개, 검증기 3개, family별 evidence plugin 5개, API-surface gate 3개, moduleboundary 3벌(main 1.7k줄) | build-logic에 범용 plugin 있음 | 예 | build-logic으로 통합 | L |
| 테스트 fake / contract kit | TransactionPort fake 21개 등; 실제 adapter에 도는 kit는 1개 |
ADR-BUILD-001 (testFixtures) |
first-pass fake 결함 6건 | 포트별 kit를 testFixtures에 |
M |
발견 (효과 큰 순)
1. [Required] Outbox: 세대 3개 공존, 실제 조립된 v1이 가장 약함
- 구현: 조립(v1)
LegacyOutboxAppendPort→OutboxStoreAdapter→PostgreSqlOutboxClaimRepository/H2OutboxClaimRepository→PublishPendingOutboxEventsUseCase+OutboxRelayScheduler→OutboxReaper(ca-skeleton.outbox.enabled=true일 때만). canonical 추가분OutboxAppendPort→CanonicalOutboxAppendAdapter(같은outbox_event). V2(미조립)OutboxAppendPortV2,OutboxPollingDeliveryPortV2,PostgreSqlImmutableOutboxAppendAdapter(376),PostgreSqlPollingDeliveryAdapter(549),PublishNextOutboxDeliveryUseCase,OutboxV2RetryPolicy, migrationjpa/outbox-storage,jpa/outbox-polling. messagingJdbcOutboxRepository(721),OutboxRelay,OutboxRelayWorker,OutboxRetryScheduler,OutboxCleanupJob,messaging_outbox. - 조립 상태: V2 adapter는 stereotype 없음(
PostgreSqlPollingDeliveryAdapter.java:29-43), main 참조 0, migration location 미설정(grepoutbox-storage|outbox-polling→ 테스트만). messaging relay는@ConditionalOnBean(OutboxRepository)(MessagingReliabilityAutoConfiguration.java:81)인데 앱에 bean 없음; app-bootstrap·adapter main의messaging.reliabilityimport 0. "새 코드는 이것을 쓰라"는OutboxAppendPort(LegacyOutboxAppendPort.java:6) 소비자 0, 소비자 7곳 모두LegacyOutboxAppendPort. - 갈라진 증거: v1은 fencing 없음 — claim이
IN_FLIGHT행 재획득(PostgreSqlOutboxClaimRepository.java:15-29),markPublished/markFailed가eventId만으로 씀(OutboxStoreAdapter.java:93,106), claim·발행·결과 기록이 별도 트랜잭션(PublishPendingOutboxEventsUseCase.java:91,142,160). messagingV1002__messaging_outbox_lease_fencing.sql:1-14주석이 바로 이 시나리오("A 멈춤 → B 재claim·발행 → A가 FAILED로 덮어씀 → 중복 발행")를 버그로 설명하고lease_owner/lease_token으로 고침; V2도 owner CAS로 고침. 고친 두 구현은 미조립, 조립된 v1은 미수정. 추가:CanonicalOutboxAppendAdapter만 트랜잭션 guard 없음(1차 E-3); canonical 이벤트가 v1 claim을 타며 aggregate 순서 깨짐(1차 E-5);OutboxBackoffPolicy·OutboxV2RetryPolicy역할 중복(1차 A-3); legacy producer(KafkaSenderAutoConfiguration.java:61-81)도 TLS/SASL 없음(Critical #8과 같은 문제). - 권고: 앱 outbox 1벌 — 저장소는 소비자와 V13/V14 canonical 컬럼이 있는
outbox_event; claim에 V2/V1002의 owner+token CAS 이식 후 V2(app-coreoutbox/v2약 800줄, persistence-jpa 1,055줄, migration 2종) 삭제; append 포트는OutboxAppendPort하나(legacy는 cutover 후 삭제). 계약 위치 application-coreoutbox, contract kit는 기존application-core/src/testFixtures/.../LegacyOutboxAppendContract확장 + fencing 시나리오. messaging outbox는 vendored라 유지하되src/messaging/CLAUDE.md에 "앱은messaging_outbox를 쓰지 않는다" 명시. - adopter가 몰라도 되는 것: 어느 append 포트/테이블이 정본인지, 어느 relay가 도는지.
- 가정/반론: V2 cutover 설계(
2026-09-18-outbox-v2-*spec)를 계속 추진할 계획 없음 / V2가 더 안전 → 그렇다면 V2를 조립하고 v1 삭제. 어느 쪽이든 목표는 1벌. 승인자: 소유자.
2. [Required] 멱등성: 계약 2개, store 3개, 조립 3곳, inbound 전용 ledger 3개
- 구현: v1
IdempotencyStorePort/IdempotencyExecutor/IdempotencyStoreAdapter(+H2·PG claim repo); V2IdempotencyStorePortV2/IdempotencyExecutorV2,PostgreSqlOwnerSafeIdempotencyStore(662),RedisIdempotencyStoreAdapter(534) — v1과 같은idempotency_record테이블을 상태 어휘만 바꿔 사용(jpa/idempotency/V1__expand_owner_safe_v2.sql:107). inbound 전용: websocketCommittedResultLedger(inbound가 정의한 저장 SPI, main 구현 0), graphqlGraphQlMutationIdempotencyInterceptor(요청 경로 밖), grpcGrpcOperationLedger+JpaGrpcOperationLedger(optional build, 별도 테이블). - 소비자: v1 executor는 sample
PublishPosterImageUseCase.java:121만;IdempotencyExecutorV2는 조립 클래스(RedisIdempotencyConfig,PostgreSqlIdempotencyProviderConfig,IdempotencyProviderSelectionConfig) 외 호출자 0. - 갈라진 증거: V2 executor 두 곳에서 다르게 조립 — Redis는
getProcessingLease()읽음(RedisIdempotencyConfig.java:71-73), PostgreSQL은Duration.ofMinutes(2)·"json.v1"하드코딩(PostgreSqlIdempotencyProviderConfig.java:36,39). v1 완료 기록 실패 시 action 재실행 결함(1차 A-8). 자연키 dedup 두 방식:JpaNotificationRequestStore.java:47-77ON CONFLICT DO NOTHING후 승자 읽기(주석에 25P02 이유) vsDurableOperationStoreAdapter.java:60catch 후 같은 트랜잭션 재조회(Critical #4); 범용RegisteredPostgreSqlUpsertExecutor참조 0. - 권고: V2를 정본으로 하고 이름에서
v2제거(application-coreidempotency); sample을 V2로 옮기고 v1 전부 삭제; executor는IdempotencyProviderSelectionConfig한 곳에서IdempotencySettings로, provider는 store bean만; websocketCommittedResultLedger삭제(inbound가 저장 SPI를 갖는 건 방향이 틀림); graphql은 V2에 연결하거나idempotencyKeyallowlist 제거;DurableOperationStoreAdapter는 notification 방식으로, upsert executor 삭제; grpc ledger는 유지(vendored, ADR-GRPC-004). - 반론: v1이 더 단순 — 하지만 Redis는 V2만 구현하고 소유자 fencing은 V2에만 있음.
3. [Required] 테스트 fake: 같은 포트를 모듈마다 따로 흉내, 실제 adapter와 대조하는 kit 거의 없음
- 구현(테스트 source set):
TransactionPortfake 21개(application-notification 11, sample 6, app-core 4),ObjectControlStorefake 7개(한 leaf 안),IdempotencyStorePort4 + V2 3,DurableOperationStorePort2(app-coreInMemoryDurableOperationStore, webtestFixtures/TestDurableOperationStore),OutboxRepository3,InboxRepository2. - 갈라진 증거: 1차 공통 패턴 4(grpc ledger fake, tus fake digest, Redis fake HDEL/PEXPIRE, notification recorder, durable operation, messaging fake publisher); PG contract test가 adapter를 거치지 않고 raw SQL만 실행; app-core
DistributedLockPortContractTest.java:46은 테스트 안에 정의한FakeDistributedLockPort를 검증(fake를 테스트); 실제 adapter에 도는 kit는LegacyOutboxAppendContract하나뿐. - 권고: 포트 소유 leaf의
src/testFixtures(ADR-BUILD-001)에 포트별 contract kit를 두고 fake와 실제 adapter 양쪽에서 실행. 우선순위:DurableOperationStorePort,IdempotencyStorePortV2,GrpcOperationLedger(grpc-testkit),RecipientLeaseStorePort, tus upload, Redis gateway.DirectTransactionPort는 application-core testFixtures에 1개.ObjectControlStorefake는@TempDir위LocalDevObjectControlStore로 대체. - 반론: 실DB lane이 느림 — kit는 fake에서도 돌아 최소한 fake 의미 = 실제 adapter 의미를 보장.
4. [Required] caller 트랜잭션 guard 9벌 복사, 빠진 곳에서 결함
- 구현: persistence-jpa 7곳(
OutboxStoreAdapter:130,DurableOperationStoreAdapter:178,JpaLiveEventReplayAdapter:163,PostgreSqlImmutableOutboxAppendAdapter:337,PostgreSqlSameStoreInboxAdapter:502,PostgreSqlPollingDeliveryAdapter:488,IdempotencyCapabilityGuard:93), messaging 2곳(JdbcOutboxRepository:229,JdbcInboxRepository:102). - 갈라짐:
CanonicalOutboxAppendAdapter0건(E-3, 조용한 dual-write); notification JPA store 11개도 0건. - 권고: persistence-jpa
transaction패키지CallerTransaction.require(op)하나(messaging은 vendored라 자기 것 유지).@Transactional(MANDATORY)는 V2 adapter가 bean이 아니라 proxy가 안 붙어 불가. Size S.
5. [Required] Rate limit: 공유 계약이 있는데 web에 같은 이름의 병렬 세트
- 조립된 경로
RateLimitInterceptor→dev.caskeleton.shared.ratelimit.EdgeRateLimitPort→RedisEdgeRateLimitAdapter(이 저장소에서 공유 계약을 올바르게 만든 유일한 사례). 병렬 세트 webratelimit/WebRateLimiter,RateLimitDecision,RateLimitFailurePolicy—WebMvcThrottleFilter:10-11,41,WebFluxThrottleFilter:10-11,44가 쓰고 main 구현 0(testFixturesCountingRateLimiter뿐). - 갈라짐: web enum은
FAIL_OPEN허용, shared enum은FAIL_CLOSED만; 단순 클래스 이름이 같아 import 오선택 쉬움. - 권고: web 병렬 타입·throttle filter 삭제 또는
EdgeRateLimitPort로 재연결(1차 I-8과 같은 결정). Size S.
6. [Required] lock / lease / claim: 소비자가 있는 포트와 구현체가 있는 포트가 어긋남
- app-core:
DistributedLockPort(JDBC 구현, 비즈니스 소비자 0);DistributedLeasePort+LeaseWatchdog(Redis 구현, 소비자 0,LeaseGuarantee에EFFICIENCY_ONLY하나뿐);CacheRefreshCoordinationPort(소비자CacheAsideExecutor있음, main 구현은Disabled뿐). - 중복 value type:
IdempotencyOwner·InboxOwner필드 동일(scope, ownerToken, attempt, stateRevision, claimOperationId);IdempotencyClaimAttempt,InboxClaimAttempt,LeaseAttempt같은 구조. - 미사용 범용:
postgresql/lock/PostgreSqlWorkClaimExecutor·WorkQueue*참조 0 — 그 사이 outbox, durable operation, notification, fileserver가 claim SQL을 각자 작성. - 갈라짐: fencing 있음(messaging outbox, V2, fileserver
LeaseFence) vs 없음(v1 outbox, notificationrecipients.save— 1차 B-5). - 권고: claim executor 삭제(테이블마다 순서 요구가 달라 SQL 공유 이득 없음); lock과 lease 중 하나만(멱등성처럼 "포트 1 + provider 2" 또는 Redis lease adapter가
CacheRefreshCoordinationPort구현) — 결정 필요; app-core inbox 삭제로 중복 record 해소; 공유할 것은 규칙 하나("종결 쓰기는 owner+token을 명시하고 밀려난 쪽의 쓰기는 아무것도 매칭하지 않는다") →ClaimFencingContractkit를 application-core testFixtures에 두고 각 row lease store에서 실행.
7. [Required] readiness / evidence / API-surface / moduleboundary: 같은 일을 하는 자체 프레임워크 여러 벌
- readiness 카드 스키마 3개:
config/jpa/readiness-cards.yaml:2(kebab-case,state: selected, build-toolsJpaReadinessRegistryValidator),config/messaging/readiness-cards.yaml:1(camelCase,maturity:, app-bootstrapMessagingCapabilityRegistryContractTest:128),docs/registries/object-storage-readiness.yaml:5(snake_case,claimed_level: R1,ContractRegistrySchemaGovernanceTest:32+ objectstorage test). - evidence plugin family별: jpa 2,838줄, messaging 819, notification 851, mongo 544 — 범용
ca.strict-qualification은 leaf 9개에 이미 적용. - API-surface gate 3개:
ca.api-surface(build-logic),ca.notification-api-surface(156줄 verifier), jpaverifyJpaAdopterApiSurface(JpaQualificationPlugin.java:57-62) — persistence-jpa는ca.api-surface(build.gradle:8,167)와 이것을 둘 다 적용. - moduleboundary:
*StableModule,*ModuleBoundary,*ModulePurity가 web/graphql/websocket main에 3벌(1,723줄), 테스트*BuildModel/*SourceGraph도 3벌. - 갈라짐: jpa 카드가 messaging에 없는
messaging-cdc-dispatch.v1을 가리키고 성숙도 어휘 불일치(1차 E-11). - 권고: build-logic에 카드 스키마 1개 + 검증기 1개(id, R0–R3, family 간 prerequisite, 필수 task, 증거 selector, 한계), family plugin에는 증거 실행기만; API-surface는
ca.api-surface하나로; moduleboundary는 production jar에서 빼서ca.architecture/ArchUnit 규칙 1개로. Size L. 반론: 빌드 시점 코드라 런타임 위험 없음 — 단 family 간 참조가 이미 깨짐.
8. [Consider] 파일 publication: control plane·canonical JSON codec 중복 (결정 필요)
- 구현: app-core
filepublication(399) → fileserver 최상위 패키지(publication plane 8,567줄,FileserverControlRecordCodec855 포함),FilePublicationPortmain 소비자 0; deprecatedFileExportPort→FilesystemCsvExportAdapter; objectstorageCanonicalJsonObjectControlRecordCodec(898),CanonicalJsonReader/Writer,ObjectControlStore(sample만 사용, app-bootstrap edge 없음). - 갈라짐: UTF-8 처리 —
FileserverControlRecordCodec.java:842strict(REPORT) vsLocalPublicationJournalCodec.java:156,CanonicalJsonReader.java:16느슨한new String; 원자적 쓰기 —LocalPublicationJournal.java:104-118temp +ATOMIC_MOVEvsLocalDevObjectControlStore.java:54-57제자리CREATE_NEW(1차 D-5). - 권고: fileserver HTTP 플랫폼과 objectstorage는 유지(
docs/storage-capability-boundary.md에 결정 문서화). 소비자 0인FilePublicationPortplane은 삭제 권고 — CSV가 필요하면StreamingCsvEncoder를StagedObjectPublicationPort앞에; parser 3개 → 1개. 둘 다 유지해야 하면 canonical JSON을 shared-contract로(두 leaf 모두 edge 있음). 반론: R2의 표 형식 정책(수식 무력화 등)은 인코더 계층 문제. 승인자: 소유자.
9. [Consider] Backoff 계산식 10개, "full jitter" 뜻 3가지
OutboxBackoffPolicy.java:63-65:base·2ⁿ + U(0,base)(이름과 달리 더하기 jitter, 상한 없음); httpclient:78, jpa:60:U(0,capped]; messaging:56:capped·U[0,1); notificationRetryBackoff.java:43: base 하한. jpa 한 leaf에BackoffCalculator·TransactionRetryBackoff두 벌; grpcGrpcRetryCoordinator소비자 0.- 권고: shared-contract
Backoff(base, max, multiplier, Jitter)(stdlib만) — app-core outbox, httpclient, jpa 2곳(notification은 registry edge 추가 필요); mongo(edge 없음), messaging, grpc는 자기 것 유지. 반론: 공식은 20줄 — 가치는 "같은 이름 = 같은 의미" 보장.
10. [FYI] 받아들일 수 있는 중복
- admission 제한 약 11개: transport별 거부 처리가 달라 합치지 않음. 단
GrpcAdmissionController.java:53-59check-then-increment는Semaphore.tryAcquire로(M1 수정이GrpcStreamAdmission에만 적용). - gRPC 스택 2개: 기본
adapter:inbound:grpc(623줄)와 optional buildgrpc:*(약 2만 줄) — 별도 build는 의도된 결정. - SHA-256 hex 헬퍼 65벌: app-core
Sha256record가 이미 있음; notificationMessageDigestPort는 과한 추상화 → 정리 시 흡수.
조사 범위와 한계
읽기 전용 grep/find/wc/sed; 기능마다 구현체·포트·main/test 참조 수·조립 조건(@Conditional*, stereotype)·migration 대조. "소비자 0" = 클래스명 grep -w로 main source set 확인(리플렉션·SPI 미확인). 실행 미확인: v1 outbox 이중 발행 경합, V2·v1 idempotency_record 공존 문제; 33% 복붙 비율은 정규화 줄 비교(84/253). 깊게 안 봄: fileserver platform/**, objectstorage direct/multipart, messaging 내부 중복.
X2 — 공통 유틸리티와 전송 경계 계약
Part 1: 작은 유틸리티
| utility | implementations (count) | canonical exists? | diverged? | recommendation | where it lives |
|---|---|---|---|---|---|
| 시크릿 조회 경로 | 앱 쪽 5개: SecretSourcePort, S3ProviderBinding.SecretResolver, RedisSdkAutoConfiguration.RedisSecretSource, MongoCredentialResolver, notification SecretMaterialProvider; 벤더 쪽 2개: messaging CredentialProvider, grpc GrpcCallCredentialProvider |
있음: application/outbound/SecretSourcePort + support EnvironmentSecretSource |
있음(Spring Environment / 프로세스 env / 무조건 거부로 갈림) | Required: 새 타입 없이 cache-redis 같은 1줄 bridge bean | 경로 유지, bridge는 각 capability config |
| prod 판정 | 정본 1개 + 다른 구현 5종(websocket, messaging(벤더), grpc 설정값(벤더), 같은 이름의 httpclient enum, sample 3곳) | 있음: shared.runtime.RuntimeEnvironment |
있음(websocket은 trim·소문자 안 함, production도 prod) |
Required: 1줄 교체 | shared-contract(기존) |
| Settings 바인딩·검증 | @ConfigurationProperties 파일 64개, 방식 3가지, 오타 키 거부는 4곳 |
일부: StrictSettingsBinder(support), 규칙 문서 없음 |
있음 | Required(문서화) | 규칙은 root CLAUDE.md, 코드는 support |
| 서명된 불투명 토큰(cursor/resume) | HMAC codec 7개 | 없음 | 있음(TTL, kid, version 지원 제각각) | Consider: 먼저 삭제, 서명 계층 하나로 정한 뒤 공용 헬퍼 | shared-contract (grpc는 자체 사본) |
| SHA-256·hex | MessageDigest.getInstance 파일 66개, private helper 53개(47파일) |
없음 | 없음 | Consider | shared-contract Sha256 (예외 아래) |
| JSON 문자열 escape | 직접 구현 8개(앱 7, 벤더 1) | 없음 | 있음(동작 3가지) | Consider | shared-contract 또는 기존 Jackson |
| Clock | Clock bean 3개, 주입 Clock 우회 약 20곳 | 있음: BootstrapClockAutoConfiguration:21-24 |
있음(한 클래스 안에서 두 시간 소스 혼용) | Consider: 기존 bean 주입 | — |
| 상수 시간 비교 | MessageDigest.isEqual 19파일, 이것 없이 HMAC 검증하는 곳 0 |
stdlib | 없음 | FYI | — |
| Base64url | 18파일, stdlib 한 줄 | stdlib | 없음 | FYI | — |
마스킹 toString |
약 45개, 표기 4종(REDACTED, redacted, <redacted>, ***), 로그 마스크 **** |
로그는 LogMaskingPatterns |
표기만 | FYI (타입별 필요, 줄일 것 없음) | — |
requireNonBlank/requirePositive |
inline 검사 448곳(342파일), 이름 붙은 helper 14, requirePositive(Duration) 12 |
없음 | 메시지만 | FYI (관용구) | — |
| Size/Duration 파싱 | 직접 파서 0 (Spring 바인딩 + env-keys.yaml 규칙 30s, 10MB) |
Spring | 없음 | FYI | — |
P1-1 [Required] 시크릿 조회 경로 4갈래, bridge는 Redis 하나에만
- 정본
SecretSourcePort(application-core), bootstrapSecretSourceFactory가 strategy 선택. - S3는
System::getenv고정(adapter/outbound/objectstorage/.../s3/S3ObjectStorageProviderContribution.java:41) → Spring property source·정본 strategy 둘 다 미적용. - Redis 기본값도
System.getenv(RedisSdkAutoConfiguration.java:212-216)지만 cache-redis가RedisCapabilityConfig.java:68에서SecretSourcePort로 연결 → 결과적으로 정본 사용. 따라 할 모범 사례. - Mongo는 기본값
MongoCredentialResolver.unconfigured(), bridge 없음 → adopter가 Vault strategy를 설정해도 Mongo 연결만 실패. - 수정: S3와 Mongo에 Redis 같은 bridge bean(
secretSource::resolve), 새 추상화 없음.
P1-2 [Required] websocket prod 판정이 아직 직접 구현(BOOT-002 미해결)
adapter/inbound/websocket/.../config/WebSocketPlatformSafetyConfiguration.java:78-85:"prod".equals(profile) || "production".equals(profile)→Prod·앞뒤 공백 미인식(fail-open). 정본RuntimeEnvironment.fromProfile은 trim + 소문자.- websocket은 shared-contract에 의존 가능 → fileserver처럼
RuntimeEnvironment.isProductionActive(List.of(environment.getActiveProfiles()))한 줄(FileserverSecurityConfiguration.java:81참고). 1차는 "bridge가 outbound leaf에 있어 못 쓴다"고 봤지만 정적 메서드 직접 호출이면 bridge 불필요. - 규칙상 허용되는 별도 구현:
MessagingAdminDurabilityValidator.java:25Set.of("prod","production"), grpcGrpcTlsProfile.Environment(기본값LOCAL,GrpcPlatformProperties:26) — 벤더 영역이라 자체 어휘 허용(RuntimeEnvironmentJavadoc). 단 grpc bridge를 붙일 때RuntimeEnvironment→GrpcTlsProfile.Environment매핑 필요; GraphQL이 좋은 예(CapabilityDependencyValidator.java:29-30,163-185가 deployment mode를 runtime 환경과 대조). - httpclient
profile/RuntimeEnvironment는 정본에서 값을 만들어 동작은 문제없으나(HttpClientProfileAutoConfiguration:154-159) 이름이 같아 혼동 → Nit:HttpClientHardening등으로 개명.
P1-3 [Required(문서)] Settings 검증 방식 3가지, 새 capability가 따를 규칙 없음
@ConfigurationProperties파일 64개 기준: Bean Validation annotation 5, compact constructor throw 19, 별도*StartupValidator/*SettingsValidator34(중복 집계 있음).- 오타 키 거부는 4곳:
StrictSettingsBinder의 fileserver·httpclient,ignoreUnknownFields=false의GrpcServerProperties:17·GrpcPlatformProperties:19. 나머지 약 60개는 오타 키를 조용히 무시. - root
CLAUDE.md·AGENTS.md에 규칙 없음(web/CLAUDE.md:65B4는 request DTO 전용). - 잠재 충돌(런타임 미검증):
ca-skeleton.grpc는 strict이고platform필드가 없음(GrpcServerProperties.java:22-40)인데 벤더 prefix가ca-skeleton.grpc.platform→ 두 gRPC stack을 같이 올리면 adapter 바인딩에서 "unbound"로 기동 실패 가능성 높음. - 수정: root 문서에 한 줄 — "capability settings는 master-gated auto-config 안에서
StrictSettingsBinder로 바인딩, 값 검증은 compact constructor"(StrictSettingsBinderJavadoc에 근거 있음); gRPC adapter prefix 분리.
P1-4 [Consider] HMAC 서명 cursor·resume token codec 7개, 모두 production에서 생성 안 됨
| codec | 위치 | 상태 |
|---|---|---|
cursor/CursorCodec |
web | TTL 24h, kid 없음, test 전용, dev key 하드코딩("ca-skeleton-dev-cursor-key-0001", CursorCodec.java:38-40) |
HmacWebCursorCodec |
web pagination | keyring 지원 |
HmacGraphQlCursorCodec |
graphql | kid 있음, 만료 없음 |
SignedJsonCursorCodec |
persistence-jpa | version 있음, kid 없음 |
MongoKeysetCursorCodec |
persistence-mongo | kid·만료 없음 |
ResumeTokenCodec |
websocket | kid·만료 있음 |
GrpcResumeTokenCodec |
grpc(벤더) | kid·만료 있음 |
- 이름 grep 기준 7개 모두 production에서
new없음. inbound·outbound 양쪽에 서명 codec → adopter가 어느 계층에서 서명할지 모름; 같은 이름CursorCodec2개(web 클래스, persistence-jpa 인터페이스). - 권고: (1) web
cursor/CursorCodec삭제 (2) 서명 계층 하나 — inbound에서 서명, persistence는 typed keyset만 (3) 남은 코드가 2개를 넘으면 stdlib sign/verify 헬퍼(약 80 LOC, kid + 선택적 만료)를 shared-contract에.
P1-5 [Consider] SHA-256 보일러플레이트 — 예외 래핑 65곳 중 64곳 IllegalStateException, 호출부마다 6~8줄; 결과 바이트는 모든 곳 동일(UTF-8, 소문자 HexFormat.of(), charset 없는 getBytes() 0곳) → V1 fingerprint(EnvelopeHashV1, PartitionKeyV1)를 교체해도 바이트 불변. shared-contract Sha256.digest(byte[])/Sha256.hex(String)로 약 51개 파일에서 약 350줄 감소(objectstorage 14, fileserver 12, messaging adapter 6). 자체 사본 유지: shared-contract에 의존할 수 없는 persistence-mongo(4), application-notification(3), application-objectstorage(2)(application-core가 shared-contract를 implementation으로 선언해 전달 안 됨, application-core/build.gradle:11); messaging(2)·grpc(2)는 벤더 규칙.
P1-6 [Consider] JSON 문자열 escape 3가지로 갈림 — RFC 8259 제어문자까지(5개: OutboxEnvelopeJson.java:44, redis-sdk JsonEnvelopeFraming.java:166, LocalPublicationJournalCodec.java:121, sample PosterEventPublisher.java:89, WorkLogReservedIntegrationEventMapper.java:56); ASCII만 허용·나머지 거부(CanonicalJsonWriter.java:82, digest 입력용 → 유지); \와 "만(sample PosterImagePublicationEventPublisher.java:76-78 — 제어문자가 들어오면 잘못된 JSON, 지금 값은 ID·media type이라 위험 낮지만 sample은 adopter가 복사). 수정: sample 3곳은 Jackson, outbox adapter·fileserver 2곳은 공용 JsonStrings.quote(약 25 LOC), redis-sdk·messaging은 자체 사본.
P1-7 [Consider] Clock 우회 — RoutingObjectMutationAdapter는 clock 필드가 있는데(:60,70) Instant.now() 14번(:128-349), 게다가 설정 코드가 Clock.systemUTC()로 생성; objectstorage 설정 5곳 직접 Clock.systemUTC()(ObjectStorageCapabilityConfig.java:78, ObjectStorageScanMaintenanceConfig.java:19, ObjectStorageBindingCompiler.java:40, S3ObjectStorageProviderContribution.java:33,35); 그 밖에 MvcStreamWriter ×5, WebFluxPlatformAutoConfiguration.java:54, LocalFilePublicationAdapter.java:184,229, FileserverR2Config.java:65, LiveEventStompBroadcaster.java:99, MongoTenantClientRegistry.java:70, KeyOperationRequests.java:139. 수정: 기존 Clock bean 주입(adopter가 Clock을 바꾸면 테스트 시간이 이 코드에도 적용).
Part 2: 전송 경계 관심사
| concern | implementations | shared contract? | diverged? | recommendation |
|---|---|---|---|---|
| 에러 어휘·wire 매핑 | 경로 9개 이상(아래) | 있음: ApiErrorCode, ApiErrorCarrier, Category, OperationalError, error-codes.yaml |
있음 | Required: 계약 적용 범위 확대, 병행 어휘 정리 |
| Carrier 적용 범위 | web만 타입별 handler로 매핑 | ApiErrorCarrier |
있음 | Required: 1줄 변경 5개 |
| Request·trace·correlation id | web 필터 3, GraphQL은 Spring id, websocket 자체 id, gRPC 없음 | 일부: TraceParent(3곳), MdcKeys는 web에만 |
있음 | 파서 정리 Required, 키 이동 Consider |
| 인증 컨텍스트·tenant | 전송마다 principal/tenant 타입 따로 | AuthorizationPrincipal(web만) |
있음(tenant 문법) | tenant Required, principal Consider |
| Rate limit | MVC RateLimitInterceptor + 연결 안 된 병행 stack |
EdgeRateLimitPort |
병행 구현 | Required(삭제) |
| Body/message 크기 제한 | 전송별 knob | 불필요 | 에러 코드만 다름 | FYI |
| CORS/origin | 검증기 3, env key 3 | 없음 | 기본값 다름 | Consider: websocket 안의 2개만 합침 |
| 응답 envelope | 같은 servlet 앱에서 Envelope·problem+json 혼재 | Envelope |
있음 | Required |
에러 매핑 구현(module · class · LOC): web — GlobalExceptionHandler 417, ErrorResponseFactory 35, ClientSafeErrorMessages/ProblemCode 81, ProblemCatalog 183, problem-catalog.yaml, WebMvcProblemExceptionHandler 174, WebFluxProblemExceptionHandler 164, BudgetProblemMapper 76, ThrottleProblemWriter 78; web-fileserver — FileserverExceptionHandler 46, FileserverProblemFactory 45; graphql — GraphQlWireErrorMapper 124, GraphQlPlatformRejectionMapper 136, GraphQlErrorCategory 40, GraphQlErrorCode 113, GraphQlRequestErrorMapper 57(참조 0); websocket — SafeStompSubProtocolErrorHandler 32, WebSocketCloseCode 95; grpc adapter — GrpcStatusMapper 57, GrpcExceptionHandlingInterceptor 131; grpc 벤더 — GrpcErrorMapper 182(규칙상 유지).
P2-1 [Required] 같은 코드 이름이 status나 retryable이 다르게 나감
VALIDATION_FAILED:OperationalError.java:15·error-codes.yaml:756-758400,problem-catalog.yaml422.- budget 경로 크기 초과:
URI_TOO_LONG(원래 414,OperationalError:41)이REQUEST_TOO_LARGE(413)로(BudgetProblemMapper.java:34), JSON 깊이 초과는VALIDATION_FAILED(422)로(:37).WebMvcBudgetExceptionHandler는backend.web.budgets.enabled=true면 켜져(:40) Envelope servlet 앱 안에서 budget 초과만 problem+json. ProblemCode는 이름이 다른 동의어 병행 어휘(error-codes.yaml에서 0건):RATE_LIMITED/RATE_LIMIT_EXCEEDED,REQUEST_TOO_LARGE/PAYLOAD_TOO_LARGE,IDEMPOTENCY_KEY_REUSED/IDEMPOTENT_REQUEST_MISMATCH,AUTHENTICATION_REQUIRED/UNAUTHENTICATED,ACCESS_DENIED/FORBIDDEN.- GraphQL은
retryable을 코드별이 아니라 category에서 계산(GraphQlWireError.java:73,GraphQlErrorCategory:13-28,GraphQlWireErrorMapper.java:104-106) — shared README는 "retryable은 코드별 값":RATE_LIMIT_EXCEEDEDREST true(OperationalError:46) vs GraphQL false;DB_DEADLOCK/DB_SERIALIZATION_FAILURE/LOCK_ACQUISITION_TIMEOUTtrue vs false;DB_QUERY_CANCELEDfalse(:61) vs true. - 사용자 메시지: web 코드별 영어(
ClientSafeErrorMessages.java:14), GraphQL category별 한국어(GraphQlWireErrorMapper.java:114). gRPC trailer에는retryable없음(GrpcStatusMapper.trailersFor). - 수정: (a) GraphQL
fromApiError에서retryable = code.retryable(), 플랫폼 자체 코드만 category 기본값 (b)ProblemCode·ProblemCatalog제거, problem document는ApiErrorCode의httpStatus()·code()에서(약 260 LOC + yaml 감소) (c) Envelope 계약이 켜져 있으면 budget handler도 Envelope (d) client-safe 메시지 표 하나로.
P2-2 [Required] shared 예외가 ApiErrorCarrier를 구현하지 않아 web에서만 제대로 매핑
MappingException(shared/error/MappingException.java:11),AdapterDisabledException(:13), application-coreIdempotency{InFlight,RequestMismatch,ScopeMissing}Exception은 평범한RuntimeException. web은 타입별 handler(GlobalExceptionHandler.java:79,91,193,205,218); GraphQL(GraphQlWireErrorMapper.mapCommon)·gRPC(GrpcExceptionHandlingInterceptor.java:105,121)는instanceof ApiErrorCarrier만 봐서INTERNAL_ERROR.IllegalArgumentException: web 400BAD_PARAMETER(:103-109), GraphQL·gRPCINTERNAL_ERROR→ 같은 검증 실패가 REST에선 클라이언트 잘못, 다른 전송에선 서버 장애.- 수정: 위 5종이
ApiErrorCarrier구현(errorCode()1줄씩) → 모든 전송의 기존 carrier 분기가 처리, web 타입별 handler 5개 삭제 가능. IAE → 400은 정책 결정(전송 전체에 한 번에 적용 또는 web에서도 제거).
P2-3 [Required] HTTP 에러 응답 모양이 기능마다 다름 — shared README는 Envelope가 RFC 7807을 대체(D5); 같은 servlet 앱에서 fileserver는 항상 problem+json(FileserverExceptionHandler.java:35-40), budget 초과 problem+json, 나머지 Envelope; WebFlux엔 Envelope advice 없음(flag off면 Spring 기본 형식). FileserverErrorCode는 이미 ApiErrorCode 구현 → Envelope 전환 거의 무비용; UNAUTHENTICATED, PRECONDITION_FAILED, UNSUPPORTED_MEDIA_TYPE은 OperationalError와 이름이 같음(status 같으나 코드 문자열이 enum 두 곳에 정의). 허용: GraphQL·gRPC(프로토콜이 형식 결정), STOMP close code, notification callback(외부 provider용 본문 없는 204/400/413, NotificationCallbackMvcController.java:87-98).
P2-4 [Required] 한 요청 안에서 traceparent를 두 번, 다른 규칙으로 파싱 — WebMvcRequestIdFilter.java:49-50·WebFluxRequestContextFilter.java:46-47은 정규식 사본(version 무시, 전부 0인 trace-id 허용) vs RequestLoggingFilter.java:57-69는 엄격한 TraceParent.parse(version 00만, 전부 0 거부); 두 필터 기본 동시 활성(WebMvcPlatformAutoConfiguration.java:50-54,146-150) → request attribute WebTraceId와 MDC trace_id(Envelope meta.traceId)가 다른 값이 될 수 있음; request id도 두 필터가 각각 생성 가능(RequestLoggingFilter:60). 수정: 정규식 2개 삭제, TraceParent.parse 사용. (1차 I-4와 같은 영역)
P2-5 [Consider] correlation이 HTTP 밖으로 이어지지 않음 — MdcKeys(13 LOC)가 adapter/inbound/web/observability에 있어 다른 inbound가 못 씀; MDC.put 1파일(RequestLoggingFilter); CorrelationIdPort 구현은 web MDC adapter 하나 → STOMP·gRPC 호출에서 outbox 등의 correlation 단절; GraphQL executionId는 Spring GraphQL request id(GraphQlPlatformWebInterceptor.java:156-159), X-Request-Id·로그와 무관. 수정: MdcKeys를 shared-contract로(원본 docs/registries/mdc-keys.yaml), 전송마다 MDC 채우는 얇은 코드, GraphQL은 platform request id.
P2-6 [Required(tenant) / Consider(principal)] 인증 컨텍스트
- 같은 이름
TenantContext두 개, 허용 값 다름: web[A-Za-z0-9][A-Za-z0-9_.-]{0,63}(web/core/TenantContext.java:20) vs graphql 비어 있지 않고 128자 이하면 무엇이든(graphql/context/TenantContext.java:17,30) → 같은 tenant가 한 전송은 통과, 다른 전송은 거부. 수정: application-core tenant id 값 타입 하나 + 두 context가 감쌈. - principal 전송마다: web
AuthenticatedPrincipal(19) +ActorContext(52) +SecurityIdentity(22); graphqlGraphQlPrincipalResolver(기본 anonymous → web 필터 체인이 검증한 JWT를 안 씀); websocketrequest.getPrincipal(); gRPCGrpcAuthenticationPolicy는boolean만(principal·tenant 없음). - 가명 처리도 전송마다:
UserPrincipalPseudonymizerPort(APP_PRIVACY_PSEUDONYMIZATION_SALT), GraphQLGraphQlIdentityFingerprinter(150, 자체 key), 키 없는ActorRef.sha256Prefix, websocket salt SHA-256 → 같은 사용자가 전송마다 다른 가명으로 로그. - 권고: application
AuthorizationPrincipal에 tenant 추가, 모든 전송이 이것을 생성; bootstrap에 Spring Security → GraphQL 기본 bridge resolver.
P2-7 [Required] 연결되지 않은 두 번째 rate-limit stack — WebRateLimiter(25), WebMvcThrottleFilter(136), WebFluxThrottleFilter(142), ThrottleProblemWriter(78) 모두 Spring 어노테이션 없음, production 생성 0, 테스트 0; 동작하는 것은 RateLimitInterceptor(EdgeRateLimitPort, :75)뿐 → 삭제. WebFlux·websocket·gRPC엔 rate limit 없음; GraphQL-over-HTTP가 MVC interceptor에 걸리는지 미확인(걸려도 모든 요청이 POST /graphql 하나). client IP 신뢰 규칙도 모듈 안에서 두 갈래: ForwardedHeaderClientIpResolver.java:11-16(trusted-proxy 없이 XFF 첫 hop) vs ExternalRequestUrlResolver.java:31(trusted proxy 요청만) — 1차 I-5.
P2-8 [Consider] Origin 검증기 3개 — web WebCorsPolicyValidator.java:59, websocket WebSocketOriginPolicy.java:95, WebSocketProperties @AssertTrue가 각자 "wildcard 없이 정확 일치" 구현; env key 3개 기본값 다름(APP_SECURITY_CORS_ORIGINS 빈 값, APP_WEBSOCKET_ALLOWED_ORIGINS http://localhost:3000, APP_WEBSOCKET_PLATFORM_ALLOWED_ORIGINS 빈 값). websocket 안의 두 사본만 합침(모듈 간 공유는 약 40 LOC라 가치 없음).
P2-9 [FYI] 크기 제한 — knob은 전송마다 맞음(web budgets, graphql maxBodyBytes/maxDocumentBytes, websocket maxMessageBytes, grpc maxInboundMessageBytes); 위반 코드는 다름(PAYLOAD_TOO_LARGE, REQUEST_TOO_LARGE, GRAPHQL_DOCUMENT_SHAPE_REJECTED, close 1009, RESOURCE_EXHAUSTED) → P2-1 정리 때 이름만 통일. websocket STOMP는 모든 실패를 WEBSOCKET_REQUEST_REJECTED 하나로(SafeStompSubProtocolErrorHandler.java:12, carrier 코드 소실). gRPC adapter GrpcStatusMapper와 벤더 GrpcErrorMapper는 bridge 미연결이며 그 사실이 grpc/CLAUDE.md:88-93에 기재 → 공존 가능.
Coverage note
대상: src/*/src/main/java 73개 source set(grpc-codegen fixture, build/, bin/ 제외); 개수는 ERE grep(이름 기준 helper 수는 최소치); 벤더 영역은 규칙상 자체 사본이라 권고 제외. 미확인: MVC rate-limit interceptor가 GraphQL route에 걸리는지, ca-skeleton.grpc prefix 충돌의 실제 기동 실패 여부, Spring GraphQL request.getId() 값. capability 단위 중복은 X1 담당, grpc-advanced edge·notification callback 서명 검증은 상수 시간 비교 여부만 확인.
S1 — Core and application leaves
Path abbreviations: AC/ = src/application-core/src/main/java/dev/caskeleton/application/, AN/ = src/application-notification/src/main/java/dev/caskeleton/application/notification/, AF/ = src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/, AO/ = src/application-objectstorage/src/main/java/dev/caskeleton/application/, SC/ = src/shared-contract/src/main/java/dev/caskeleton/shared/
Per-leaf maintainability verdict
| leaf | main LOC | verdict | one-line reason |
|---|---|---|---|
| domain-core | 110 | HEALTHY | 마커 3개 + ID 인터페이스 2개. 단, application-core가 이 leaf에 의존하지 않아 production에서 안 쓰임(#16) |
| shared-contract | 2.8k | NEEDS_WORK | 한 leaf만 쓰는 타입 약 550줄; CLAUDE.md 책임 목록은 13개 패키지 중 6개만 설명 |
| application-core | 9.1k | OVERBUILT | 약 4.9k줄(54%)이 production 호출 경로 밖; idempotency 2세대·outbox 3세대 공존 |
| application-notification | 17.0k | OVERBUILT | R1 4.5k(1차) + platform 미사용 약 0.9k; 생성자 15개짜리 dispatch 서비스; 같은 전략만 담은 레지스트리 |
| application-fileserver | 6.8k | NEEDS_WORK | use-case 계약 밖 *Service/Default* 쌍 10개; retire 로직 3곳 복사, 이미 다름; 에러 코드마다 예외 클래스 |
| application-objectstorage | 2.7k | NEEDS_WORK | 포트만 담은 단순 구조. 거의 같은 식별자 클래스 6개, 복사된 가드, deprecated legacy 네임스페이스 |
Findings (highest leverage first)
-
[Required][duplication] idempotency 엔진 2세대 공존, V2는 bean만 있고 호출자 0 —
AC/idempotency/IdempotencyExecutor.java:19,AC/idempotency/v2/IdempotencyExecutorV2.java:33,94- Evidence: V1 = executor +
IdempotencyStorePort+IdempotencyScope; V2 = executor +IdempotencyStorePortV2+IdempotencyScopeDigest+ outcome 타입 13종(767줄). V2 executor는PostgreSqlIdempotencyProviderConfig.java:51,RedisIdempotencyConfig.java:68에서 생성만, mainexecute호출 0; 실제 호출은 sample V1(PublishPosterImageUseCase.java:61)뿐; bootstrap에 두 세대 bean 수를 세는 배타성 가드(IdempotencyProviderSelectionConfig.java:42-57,IdempotencyComposition.java, 112줄); 실패 처리 이미 다름(1차 A-8). - Remedy: 한 세대로 — V2 정본(web·sample scope 생성 이전, V1·가드 삭제) 또는 소비자 생길 때까지 V2 삭제. Size L · 약 300줄 + 가드 112줄(또는 반대로 V2 767줄 + 어댑터 2개).
- Evidence: V1 = executor +
-
[Required][duplication] outbox 포트 3세대, 실제 사용은 legacy 하나 —
AC/outbox/LegacyOutboxAppendPort.java:11,AC/outbox/OutboxAppendPort.java:13,AC/outbox/v2/OutboxAppendPortV2.java:9(append 포트 3개 중 main 호출자는 sample이 쓰는 legacy뿐; 폴링 포트 둘OutboxStorePort.java:14·OutboxPollingDeliveryPortV2.java:7; retry 정책 둘OutboxBackoffPolicy.java:15·OutboxV2RetryPolicy.java:16;ClaimedOutboxEvent.java:11이 legacy·canonical을 sealed로 묶음). Remedy: 한 세대만(append 1, 폴링 1, retry 1), 1차 A-3의 V2 publish 466줄 포함. Size L · 약 0.7–1.0k줄, 포트 4개. 반론: 세대 전환 중 — 템플릿 adopter에겐 옮겨올 세대 이력이 없음. -
[Required][reachability] application-core 호출자 없는 코드 약 2.8k줄(#1·#2 제외) — 호출자 자체 없음: cache executor 계열 20파일 1,488줄(
AC/cache/CacheAsideExecutor.java:19,@Deprecated, "shipped runtime does not compose"),LeaseWatchdog(AC/lease/LeaseWatchdog.java:28) 228줄,TransactionCompletionResolver/CompletionResolution50줄. 어댑터 구현은 있으나 use case가 안 부름:lease/*399,inbox/*213(InboxOwner·InboxClaimAttempt는idempotency/v2같은 역할 타입과 필드 동일),filepublication/*399,EphemeralFanoutPort58. Remedy: use case가 생길 때 추가, 유지하면 별도 library leaf/testFixtures. Size L. 반론: H5 결정이 "검증된 reference"로 유지 — 코드 스스로@Deprecated. -
[Required][SRP|readability]
NotificationDispatchService한 클래스가 흐름 제어·record 복사·실패 분류 —AN/platform/dispatch/NotificationDispatchService.java:72-87,202-231,253-288,483-508(생성자 15개; 22필드 record를 필드별로 재조립하는 곳이 이 파일 2곳 +DispatchOutcomeRecorder.java:66-90,108-1322곳 →record()105줄; catch 분기:253-288은 provider 결과 분류 정책; 종료 상태 계산:473-475·:510-514두 번; FQN 11줄; record 전체 재작성 방식이 1차 B-5(stale snapshot 덮어쓰기)의 구조적 원인). Remedy: record 전이 메서드(DeliveryAttemptRecord.completed(result, at)/leaseLost(at),RecipientDeliveryRecord.advancedRoute(now)), catch 분기는ProviderOutcomeClassifier정적 메서드. Size M · 약 150줄. -
[Required][duplication] fileserver retire 절차 3곳 복사, 이미 다름 —
AF/lifecycle/DefaultFileLifecycleService.java:84-104,AF/admin/DefaultFileserverAdminService.java:159-181,AF/upload/DefaultUploadApplicationService.java:250-270(셋 다markDeleting후cleanupQueue.enqueue; lifecycle은 content 키 없으면 DELETING→DELETED, adminforceDelete엔 이 분기 없음 → content 없는 레코드가 DELETING에 남음(바로 위 주석 "must not ... leave a file unreachable"과 모순); cancel 쪽은 1차 C-4). Remedy:retire(FileRecord)하나. Size S. -
[Required][structure] fileserver 인바운드가 use-case 계약 밖 —
AF/upload/UploadApplicationService.java외 9개 (이 leaf의@UseCaseCapability/CommandUseCase/QueryUseCase0건(notification은 17/18) → capability fitness gate 미적용; 인터페이스 6개CleanupService,WriterLeaseCoordinator,FileLifecycleService,TransferAdmissionController,FileReconciliationService,FileStateMachine은 두 번째 구현·fake 없음). Remedy: 최소안은 6개 인터페이스 삭제; 템플릿 정합은 transport가 부르는 연산을*UseCase+ capability 선언으로. Size M/L. -
[Consider][duplication|pattern] 에러 코드마다 예외 서브클래스 약 45개, 타입 분기는 5개 —
AF/api/error/*Exception.java(23파일, 571줄),AN/platform/api/error/*Exception.java(25파일, 323줄) (transport는 code/context로 매핑(FileserverExceptionHandler.java:35); 타입 catch는 fileserver 3(AmbiguousCompletion,UploadOffsetMismatch,FileNotFound) + notification 2; notification 예외 12개는 throw 0;FileTooLargeException.java:8생성자가 아무 context나 받아 타입≠code 가능;FileNotFoundException,FileAlreadyExistsException,InvalidPathException은 JDK 이름과 같아 어댑터가 FQN으로 구분(LocalPersistentRootAttestor.java:283)). Remedy: base를 구체 클래스 +of(code, …), 서브클래스는 타입 분기 5개만. Size M · 약 700줄. -
[Consider][over-abstraction]
PolicyTransactionPort계열이 호출 1곳을 위해 존재 —AC/transaction/PolicyTransactionPort.java:9,AF/upload/FileserverCompensationTransaction.java:20-59(maininTransaction호출 1곳, 정책 7개 중MAINTENANCE_NEW만; 결과 5종을 전부 예외로 되돌려 결국inNew와 같음; 딸린 타입 7개 약 290줄). Remedy:TransactionPort.inNew사용, persistence-jpaSpringPolicyTransactionPort까지 삭제. Size M. -
[Consider][over-abstraction] 같은 전략만 담은 레지스트리 2개 —
AN/platform/callback/ProviderEventProjectorRegistry.java:7(구현은StandardDeliveryProjector하나; Twilio/Ses 서브클래스는 providerId만 넘기고 "No provider-specific transitions are needed"),AN/platform/dispatch/TemplateRendererRegistry.java:10(모든 channel에 같은 클래스 등록,NotificationPlatformProviderConfig.java:55-77). Remedy: 구현체 직접 주입. Size S · 타입 7개, 약 140줄. -
[Consider][duplication] 알림 제출 진입점 두 벌 —
AN/platform/dispatch/NotificationSubmissionService.java:38,81-90,186-191vsSubmit/ScheduleNotificationApplicationUseCase.java(prepare → inWrite(commit) → recordAccepted흐름·주석까지 복사;NotificationOrchestrator의 유일한 소비자는 호출자 없는ReactorNotificationOrchestrator(1차 B-8)). Remedy: Reactor facade와 함께NotificationOrchestrator·서비스 public 진입 메서드 삭제. Size S. -
[Consider][duplication] SHA-256 헬퍼 분산,
RequestFingerprint이름 충돌 —AN/platform/dispatch/MessageDigestPort.java(stdlib 해시를 outbound 포트+어댑터로 감쌈; 다른 7곳은MessageDigest.getInstance("SHA-256")직접, 예AO/objectstorage/model/ObjectDigest.java:35),AN/platform/dispatch/RequestFingerprint.java:15vsAC/idempotency/RequestFingerprint.java:13(grep 결과가 섞임 — 이 리뷰의 도달성 스캔도 한 번 잘못 셈). Remedy: application-coreSha256.hex(byte[])하나, 포트·어댑터 삭제, notification 쪽은PlanFingerprint로 개명. Size S. -
[Consider][over-abstraction] fileserver content SPI를 application이 안 씀 —
AF/api/content/{BlockingContentStore,AsyncContentStore,CopyCapableContentStore,CapacityAwareContentStore,DelegatedDownloadStore}.java(application은 좁은 gateway 8개만;BlockingContentStore는 어댑터만 참조; 나머지 4개 + record 3개는 구현·호출 0, 143줄). Remedy: 확장 4개 삭제,BlockingContentStore는 어댑터 내부로. Size S · 약 190줄. -
[Consider][pattern]
FileStateMachine인터페이스 → enum 메서드 —AF/api/FileStateMachine.java:9,AF/api/DefaultFileStateMachine.java(전이표 Map 하나를 인터페이스·구현·bean으로 감쌈; 반대로 notificationRecipientDeliveryState는 전이표 없이 여러 파일에서 제각각 전이 결정). Remedy:FileState.canTransitionTo(target). Size S. -
[Consider][reachability] notification platform에서 R1 외 약 920줄(40파일) 미사용 —
AN/platform/api/error/(throw 0 예외 12),AN/platform/security/{NotificationRedactor,SafeDiagnosticContext,SensitiveValueClassifier}.java(157),AN/platform/sms/*(218),push/,email/,webpush/. Remedy: 삭제. Size S. -
[Consider][structure] shared-contract가 한 leaf만 쓰는 타입 보관소 —
SC/activation/*(207, app-bootstrap만),SC/opstore/*(128, graphqladvanced/**만, 구현 0),SC/ratelimit/{RateLimitPolicy,RateLimitAlgorithm,RateLimitEvaluationDedupPolicy}.java(216, cache-redis만;RateLimitEvaluationDedupPolicy.java:9-10은 "Redis program" 전제 — 어댑터 구현 설정);src/shared-contract/CLAUDE.md책임 목록은 13개 패키지 중 6개만. Remedy: 유일한 소비자 leaf로 이동, opstore 삭제. Size M. -
[Consider][structure] 문서가 말하는
application-core → domain-core의존이 빌드에 없음 —src/application-core/build.gradle:11(registry는 허용,CLAUDE.md:54·AGENTS.md 작업 순서도 전제; 실제 의존은b3add016(2026-07-28)에서 빠짐; application-* 전체dev.caskeleton.domainimport 0; 그 결과 domain-coreIdFactory대신NotificationIdGeneratorPort,UploadIdentifierFactory가 따로 생김). Remedy: 의존 한 줄 복원, 또는 domain-core를 "fork에서만 쓰는 leaf"로 문서화. Size S. -
[Consider][duplication] objectstorage 식별자·가드 복사, legacy 네임스페이스 공존 —
AO/objectstorage/identity/{ObjectId,ObjectReference,ObjectStageHandle,ObjectVersionToken,PartReceiptToken,DirectTransferSessionId}.java(40줄 클래스 6개, 이름·검증 호출만 다름),AO/objectstorage/model/ObjectModelSupport.java:11vsAO/objectstorage/request/ObjectRequestSupport.java:18(본문 같고 인자 순서만 반대),AO/storage/ObjectStoragePort.java:6,28(legacyapplication.storage284줄은 sample만; Javadoc이 "the only dependency"와 "Legacy compatibility only"를 동시에). Remedy: 식별자 record +toString만 재정의, 가드 하나, legacy 네임스페이스는 sample로 옮길지 결정. Size S/M · 약 160줄. -
[Consider][structure] 포트·서비스 이름 규칙이 leaf마다 다름 —
AF/api/metadata/FileQuotaService.java(outbound인데 Service); CLAUDE.md는 outbound =*Port; fileserver outbound 이름: Store 7, Gateway 8, Port 5, 그 외 Probe/Queue/Ledger/Locator/Service/Factory/Verifier; notification outbound: Port 34, StorePort 15, Registry/Ledger/Inbox/Protector; 인바운드*UseCase/*ApplicationUseCase/*Service+Default*혼재;V2접미사 타입 5개; 파일 관련 어휘 4곳(filepublication, deprecatedfileexport, fileserver, objectstorage). Remedy: outbound*Port, inbound*UseCase로 기계적 개명, #1·#2 정리 뒤V2제거. Size M. -
[Nit][readability] 이력 주석 약 50곳("used to", "Replaces an injected", "There were two V2 store contracts" — 예
NotificationDispatchService.java:57-62,187-189,264-267,334-339,IdempotencyExecutorV2.java:17-31); inline FQN notification 82줄, application-core 7줄. -
[Nit][structure] notification
dispatch/패키지에 여러 기능 —AN/platform/dispatch/(46파일, 3.8k줄)에 제출, 템플릿 게시, 조회,ContactPoint*(contact/패키지가 따로 있는데도), reconciliation, worker. Remedy:submission/,dispatch/,reconciliation/. Size M(이동만).
Cross-module leads (not investigated)
messaging:*자체 outbox/inbox(messaging-outbox-jdbc-postgresql,messaging-inbox-jdbc-postgresql/IdempotentConsumer.java)와 application-coreoutbox/inbox같은 패턴 3~4벌.- UUIDv7 생성: notification
UuidV7Generator, fileserverRandomUploadIdentifierFactory, sampleUuid*IdFactory. - outbound 어댑터(
RedisIdempotencyConfig.java:68)가 application executor 조립. - 어댑터
Local*Gateway7개(383줄)는LocalBlockingContentStore를 넘기기만. - persistence-jpa
SpringPolicyTransactionPort는 #8과 함께 정리. - fileserver 전이 규칙이
DefaultFileStateMachine과 persistenceFileTransitionRepositorySQL 두 곳.
Coverage note
정독: dispatch/submission 서비스·제출 use case, 두 idempotency executor, outbox/transaction 포트, fileserver upload/lifecycle/admin/error/content, objectstorage identity/support, shared-contract ratelimit/opstore. 도달성은 클래스 이름 grep으로 이 leaf들 밖 main에서의 전이 참조(리플렉션·문자열 bean 미포착; 이름 충돌로 한 번 잘못 셈 → 수동 교정). 훑음: notification policy/observation/provider, fileserver finalize/cleanup.
S2 — Persistence leaves
Path prefixes: JPA/ = src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/, MONGO/ = src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/, FS/ = src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/
Per-leaf maintainability verdict
| leaf | main LOC | verdict | one-line reason |
|---|---|---|---|
| persistence-jpa | 26,317 | OVERBUILT | Three things in one: a JPA platform library (~13.6k), skeleton-wide stores (~5.7k), the notification feature (~7.1k). Only 16.2k statically reachable from wiring; supported adopter surface is 20 types. |
| persistence-mongo | 23,188 | OVERBUILT | allowed_dependencies is [] → implements no application port, no production consumer; 13.1k lines not referenced even by its own auto-config. |
| persistence-fileserver | 2,538 | HEALTHY | One self-contained feature; its tests/docs were left in another leaf; same gate repeated on root config and 9 classes. |
Q1 (is persistence-jpa one leaf?): No — three things. Skeleton-wide stores (outbox, idempotency, inbox, operation, liveevent, lock) implement application-core ports and belong here; notification is the same case fileserver was and should come out the same way (#1).
Q2 (how much Mongo is "advanced"?): advanced = 3.4k; reactive + change streams ~2.7–4k (excluded from the shipped jar). What an adopter needs: ~1–1.5k (opt-in gate, client profile, health, startup validator).
Findings (highest leverage first)
-
[Required][structure] persistence-jpa carries notification persistence (27% of the leaf) —
JPA/notification/**(7,066 lines),db/migration/jpa/notification-platform(841 SQL lines)- Evidence: notification imports only
application.notification(184) and itself; 0 imports from otherpersistence.*; only reverse edgeJPA/autoconfigure/PersistenceJpaAutoConfiguration.java:6,24→ forcespersistence-jpa→application-notification(modules.json:68), so every JPA deployment resolves notification. Three things exist only to exclude it:JPA/config/PersistenceJpaConfig.java:87(OPT_IN_NOTIFICATION_PACKAGE), a 19-package list repeated in@EntityScanand@EnableJpaRepositories(only 5 packages hold entities),PersistenceEntityScanCoverageTest.JPA/notification/crypto(505 lines) is test-only, a parallel copy of the wiredadapter/outbound/notification/.../AesGcmNotificationPayloadProtection. - Remedy: new module using the
persistence-fileserver/build.gradle:3-14recipe; deletecrypto. Size L · Removes the jpa→application-notification edge, both 19×2 lists, the constant, the coverage test, 505 dead lines. - Assumption/Counter: notification ITs need jpa's container fixture (reuse via
testFixtures) / one more registry leaf.
- Evidence: notification imports only
-
[Required][reachability] persistence-mongo: a 23k-line platform with no consumer —
modules.json:84,src/app-bootstrap/build.gradle:129- Evidence:
runtimeOnly, no main source names a Mongo type; reachability from its 3 auto-config entry points 10.1k/23.2k; unreferenced by any wiring: transaction 1.6k, schema 1.9k, migration 1.2k, query 1.5k, security.admin 0.6k,advanced3.4k. Nothing importsMONGO/advanced/autoconfigure/MongoAdvancedConfiguration.java→ everyca-skeleton.persistence-mongo.advanced.*.enabledflag is bound by nobody. 10 interfaces without implementation:MongoSearchOperations,MongoVectorSearchOperations,MongoTimeSeriesOperations,MongoGridFsCompatibilityReader,MongoIntegrationEventPublisher,MongoChangeToIntegrationEventMapper,MongoDataKeyResolver,MongoTenantDatabaseResolver,MongoTenantMigrationCheckpointStore,TenantScopedMongoOperations. Carrying cost: 16k test lines, 261-line build.gradle, 2 release scripts. - Remedy: keep a "Stable core" ~1.5k (
MongoOptInAutoConfigurationImportFilter,MongoRootAutoConfiguration,MongoPersistenceSettings,client/*,MongoProfileProperties, health/startup/topology); delete the rest (git keeps it) or move to a separately versioned library. Size L · Removes ~20k main + ~14k test. - Assumption/Counter: tech-log-backend does not use platform types (to check) / leaf CLAUDE.md declares an intentional platform with an API snapshot.
- Evidence:
-
[Required][duplication/reachability] Two transaction/retry engines, one used —
JPA/transaction/,JPA/autoconfigure/PersistenceJpaRuntimeConfig.java:54-78- Evidence: live:
SpringTransactionPort.java:29→SpringPolicyTransactionPort+TransactionRetryBackoff+TransactionRetryClassifier(40001/40P01 hard-coded:8-9). Second:SpringJpaTransactionExecutor,FullTransactionRetryCoordinator,DefaultJpaRetryPolicy,BackoffCalculator,RetryBudget,PersistenceFailureTranslatorChain,EvidenceAwareJpaTransactionManager,CompletionUnknownRecorder,TransactionProfileRegistry— beans created,JpaTransactionExecutor0 consumers, last three referenced only from Javadoc/tests.JpaTransactionAutoConfiguration.java:37claims "the retry coordinator implements PolicyTransactionPort" — false. SQLSTATE tables duplicated:failure.SqlStateErrorMapping(Standard/PostgreSql/H2) andpostgresql.error.PostgreSqlState+h2/H2FailureTranslator.java:48-52; 40001 in 4 places. - Remedy: keep the port-backed engine, delete the second; one SQLSTATE enum per vendor for mapping and retry. Size L · Removes ~1.2k lines, 2 of 4 tables.
- Assumption/Counter: CLAUDE.md invariant "CompletionUnknown is not retried" is enforced only by the unused engine — move it into the live one if it matters.
- Evidence: live:
-
[Required][duplication] Three outbox generations and two idempotency generations side by side —
JPA/outbox/OutboxStoreAdapter.java:43,JPA/outbox/CanonicalOutboxAppendAdapter.java:28,JPA/postgresql/outbox/*(1,055),JPA/postgresql/inbox/*(596),JPA/idempotency/IdempotencyStoreAdapter.java:30vsJPA/postgresql/idempotency/PostgreSqlOwnerSafeIdempotencyStore.java:61- Evidence: V2 outbox, V2 polling, inbox adapters constructed by no production code (only
CandidateAdapterCompositionTest+ ITs);outbox/entity/OutboxEventEntity.javahas 57 public methods (legacy + canonical columns); outbox migrations across 3 streams (postgresql/V3,V13,V14,jpa/outbox-storage,jpa/outbox-polling). - Remedy: finish the migration, one generation per capability; keep possibly-applied migrations, delete code only. Size L · Removes ~1.7k (unwired V2) or ~1k (legacy) + matching port versions.
- Assumption/Counter: adopters start from an empty DB / README treats "implemented-candidate" as deliberate staging.
- Evidence: V2 outbox, V2 polling, inbox adapters constructed by no production code (only
-
[Required][duplication] Mongo reactive twin stack — excluded from the jar, already diverged once —
MONGO/reactive/**,MONGO/transaction/*Reactive*,MONGO/transaction/session/ReactiveMongoCausalSessionExecutor.java,MONGO/changestream/**- Evidence: executor, consistency binder, scoped operations, collection access, transaction executor, session factory, causal session each exist twice; ~2.7k lines / 30 files touch reactor;
app-bootstrap/build.gradle:129-135excludes the reactive starter ("kept for a future promotion");ReactiveMongoConsistencyBinderJavadoc: "The imperative binder was given this contract and the reactive one was not." - Remedy: delete the reactive half and change streams (first-pass change-stream defects go with it). Size L · Removes ~4k lines, reactor-test, reactive starter.
- Evidence: executor, consistency binder, scoped operations, collection access, transaction executor, session factory, causal session each exist twice; ~2.7k lines / 30 files touch reactor;
-
[Required][duplication] Owner-lease claim mechanics copy-pasted across PostgreSQL stores —
JPA/postgresql/inbox/PostgreSqlSameStoreInboxAdapter.java:223-277vsPostgreSqlOwnerSafeIdempotencyStore.java:120-170- Evidence: same claim decision sequence;
digestFieldsidentical twice (inbox:559,PostgreSqlPollingDeliveryAdapter.java:523); write-tx guard 4× (inbox:501,polling:487,PostgreSqlImmutableOutboxAppendAdapter.java:336,IdempotencyCapabilityGuard.java:93);capability_schema_registrycheck 6× (4 stores +NotificationSchemaActivation+FS/FileserverSchemaActivation.java) — copies disagree (= 2vs>= 2; only 2 of 6 handle an unreadable registry); only idempotency was split into collaborators. - Remedy: package-private
PostgreSqlStoreSupport(write-tx guard, capability check, db now, owner token, digest) +CapabilitySchemaRequirementrecord; fold in first-pass E-3 guard for outbox/operation/liveevent. Size M · Removes ~200 lines, 5 SQL copies.
- Evidence: same claim decision sequence;
-
[Required][reachability] JPA platform library outside the supported surface —
docs/architecture/jpa-adopter-api-surface.txt(20 types) vsjpa-api-surface.txt(311)- Evidence: types referenced by composition/sample match the 20-type list exactly. Outside it and unused beyond the leaf:
springdata(1.0k),hibernate.batch/bulk/stateless(0.8k),postgresql.{copy,json,range,write,array,lock}(1.8k),api.query(0.4k),envers/querydsl/cache(0.6k),experimental(1.5k). 8 single-impl interfaces without test/outside reference:JpaBatchExecutor,BulkDmlExecutor,StatelessSessionRunner,PostgreSqlCopyLoader,PostgreSqlUpsertExecutor,WorkClaimExecutor,EnversHistoryReader,JpaTransactionExecutor.postgresql/lock/PostgreSqlWorkClaimExecutor(generic SKIP LOCKED claimer) has 0 callers while 6 places hand-write SKIP LOCKED (PostgreSqlOutboxClaimRepository,PostgreSqlPollingDeliveryAdapter,RecipientClaimSql,JpaRecipientLeaseStore,JdbcReconciliationJobStore,DurableOperationJpaRepository). - Remedy: shrink to supported surface + what stores use. Size L · Removes ~6–7k lines.
- Counter: design doc describes "18 Stable modules" — but the leaf's own surface file says public implementation types are not compatibility promises.
- Evidence: types referenced by composition/sample match the 20-type list exactly. Outside it and unused beyond the leaf:
-
[Consider][structure] Three wiring styles, stale rationale —
JPA/config/JpaAdapterComponentsConfig.java,JPA/notification/configuration/NotificationJpaPersistenceFacade.java,FS/FileserverJpaPersistenceConfig.java(scanned stereotypes with per-class conditions / explicit facades / "deliberately no stereotype" classes nothing constructs; the paragraph "Both composition roots component-scan dev.caskeleton.adapter" in 4 classes +CandidateAdapterCompositionTest.java:18is false —CaSkeletonApplication.java:106excludesadapter.outbound.persistence..*; fileserver repeats its gate 10×; Mongo repeatsenabled8×). Remedy: explicit@Beanwiring per feature config only; drop per-class stereotypes/conditions, stale paragraphs, candidate test. Size M. -
[Consider][structure] Features scattered by vendor; two unrelated "inbox" packages — outbox over 5 Java locations (
outbox/,outbox/entity/,postgresql/PostgreSqlOutboxClaimRepository.java,postgresql/outbox/,h2/H2OutboxClaimRepository.java) and 3 migration dirs; idempotency over 6 locations;postgresql/inbox(message dedupe,application.inbox) vsnotification/platform/inbox(user inbox). Remedy: package by feature (outbox/{jpa,postgresql,h2}), rename the first tomessageinbox. Size M (moves). -
[Consider][over-abstraction] Promotion/benchmark gates on the production classpath — JPA
experimental/next/*(186); Mongoadvanced/MongoAdvancedPromotionGate.java(incl.addsStarterDependency() { return false; }:41-46),MongoAdvancedPromotionEvidence,MongoVectorSearchBenchmarkGate,MongoSearchReadinessGate— test-only, parallel designs; Mongo CLAUDE.md already moved release gating to the testkit. Remedy: testkit or delete. Size S · ~450 lines. -
[Consider][structure] Fileserver extraction left its tests behind —
persistence-jpa/build.gradle:86-87(4 fileserver ITs in jpa'spostgresqlIntegrationTest;FS/JpaFileQuotaService.reservedBytes/committedBytespublic only for them; leaf has no CLAUDE.md/README; removing fileserver means editing jpa). Remedy: own IT source set viatestFixtures(project(':adapter:outbound:persistence-jpa'))+ short CLAUDE.md. Size M. -
[Consider][readability] Javadoc tells history — comment lines 21% of JPA main, 28% of Mongo main; ~90 files with "used to", "until now", "nothing registered", "documented as registered and never was"; worst:
JpaAdapterComponentsConfig.java(52 comment vs 13 code lines),MongoPlatformAutoConfiguration.java:140-145,176-180,322-325,410-412,431-434,MongoRootAutoConfiguration,PostgreSqlPersistenceConfig.java,PersistenceJpaConfig.java:90,MongoAdvancedPromotionGate.java:28-30(MNG-008). Remedy: 1–2 lines of invariant, history to git/ADR. Size M. -
[Nit][readability]
JpaTransactionAutoConfiguration.java:40is a plain factory instantiated twice (PersistenceJpaRuntimeConfig.java:58,70);new JpaTransactionSettings(null ×9)atSpringTransactionPort.java:42,53despitedefaultSettings()at:221; 36 port implementations use 7 naming conventions (*StoreAdapter,*Adapter,Jpa*Store,Jdbc*,PostgreSql*Store, port-likeSpringTransactionPort/DomainContextAuditContextPort,JpaFileQuotaService). Remedy: inline factory,JpaTransactionSettings.defaults(),<Tech><Port>naming. -
[Nit][docs] jpa CLAUDE.md "NoSQL extension rule" (
:306-316) says create a Mongo leaf (exists); MapStruct section (:281-304) for an unused tool;jpa-adopter-api-surface.txt:11lists movedFileserverSchemaActivation; Mongo CLAUDE.md:157MongoAdvancedProperties(class isMongoAdvancedSettings);JpaAdapterComponentsConfig{@link}into a leaf not on its classpath.
Cross-module leads (not investigated)
- application-core port versions
IdempotencyStorePort/V2,OutboxAppendPort/LegacyOutboxAppendPort/OutboxAppendPortV2,OutboxStorePort/OutboxPollingDeliveryPortV2are the root cause of #4. - Idempotency claim decision table duplicated in cache-redis
RedisIdempotencyStoreAdapterandPostgreSqlOwnerSafeIdempotencyStore.claim→ one pure function in application-core. - Signed cursor codecs ×4: jpa
SignedJsonCursorCodec, mongoMongoKeysetCursorCodec, webCursorCodec/WebCursorKeyRing, graphqlHmacGraphQlCursorCodec. - Failure hierarchies ×3: jpa
api/error(23 types), mongoapi/error(25), shared-contractPersistenceFailureException. sample-portfolio/.../SamplePostgreSqlPersistenceConfig.java:71-78redeclares claim-repository beans ofPostgreSqlPersistenceConfig.- JPA wiring split between the leaf's
PersistenceJpaRuntimeConfigand bootstrap'sJpaPlatformAutoConfiguration/JpaPlatformRuntimeAutoConfiguration.
Coverage note
Reachability computed from auto-config entry points, scanned stereotypes and types referenced by composition/sample main code (imports, same-package names, FQNs; strings/reflection not tracked → approximate). Read in full: wiring/config of all three leaves, claim/helper paths of the 4 PostgreSQL stores, transaction wiring, each CLAUDE.md. Not in depth: notification store internals, Mongo schema/migration/query internals.
S3 — Redis와 outbound HTTP client
Leaf별 유지보수성 판정
| leaf | main LOC | 판정 | 한 줄 사유 |
|---|---|---|---|
redis-runtime |
7,306 | OVERBUILT | 약 절반이 redis-sdk 전용: gateway 118개 메서드 중 약 110개, lane 6개 중 4개, raw/admin/pubsub 역할, SDK 설정 섹션 |
redis-sdk |
21,724 | OVERBUILT | 내부는 정돈(sync/reactive가 *OperationRequests 3.3k 공유)되어 있으나 명령 하나 추가에 leaf 3개·약 10개 파일 수정, 소비자 없음 |
cache-redis |
4,574 | NEEDS_WORK | capability별 패키지는 좋음. "lease 빌림 → 대기 → 실패 분류" 틀이 15곳에 복사되어 이미 달라짐 |
httpclient |
16,828 | NEEDS_WORK | autoconfig·패키지 분리는 좋음. blocking/reactive가 사실상 두 벌(동일 코드 약 675줄), 진입점 6개가 호출 파이프라인을 각자 조립 |
Findings (영향 큰 순)
-
[Required][duplication] httpclient blocking/reactive 병렬 스택이 이미 갈라짐 —
src/adapter/outbound/httpclient/.../restclient/DefaultGenericHttpGateway.java↔.../webclient/DefaultReactiveHttpGateway.java외 14쌍- 근거: 짝 15개(약 3.1k줄 대 약 3.0k줄), 이름만 바꾸면 같은 줄 약 675줄.
BlockingClientRuntime↔ReactiveClientRuntime86%,RestClientRuntimeFactory↔WebClientRuntimeFactory80%,DefaultHttpServiceRegistry↔DefaultReactiveHttpServiceRegistry80%,KernelHttpExchangeAdapter↔ReactiveKernelHttpExchangeAdapter102줄 동일. 이미 갈라진 곳(1차categoryOf외): 401 credential refresh가 blocking에만 있음(DefaultGenericHttpGateway.java:213-225vs reactive:314false고정);AttemptBudgetCalculator생성 방식 상이(:194vs:275); reactivefirstByteDeliveredfalse고정(ReactiveAttemptExecutor.java:157,164,172);withCredentialQuery수정이 한쪽 먼저(주석ReactiveAttemptExecutor.java:206); reactive runtime이BlockingExecutionSupport반환(ReactiveClientRuntime.java:117). - Remedy: Template Method —
AbstractLogicalCall(context/finish/ambiguous/retryExhausted/onRetryGranted/credentialRequest + attempt guard;RetryContext17-arg 생성 한 곳),AttemptCore(observation,mapResponse,mapFailure, credential 병합), 공통 필드는ClientRuntime으로, permit 획득을Permits acquire()하나로(AttemptResiliencePipeline.java:69-86=ReactiveAttemptResiliencePipeline.java:50-70), registry·kernel adapter는 요청 매핑 static helper 공유. Size L · Removes 약 600~700줄, "두 번 고치기" 제거. - 가정/반론: Mono와 동기 흐름을 한 추상화에 억지로 넣으면 읽기 어려움 → 합치는 범위는 순수 함수(매핑, 컨텍스트 생성)와 permit 획득까지, 재시도 루프(sleep vs
Mono.delay)는 두 벌 유지.
- 근거: 짝 15개(약 3.1k줄 대 약 3.0k줄), 이름만 바꾸면 같은 줄 약 675줄.
-
[Required][duplication/structure] 진입점 6개가 호출 파이프라인을 각자 조립, 적용 단계가 제각각
- 근거: lease → metadata → prepare → admission → deadline → credential → observation을 각자 손으로 조립. Generic/Reactive와
BlockingStreamingGateway는 admission·deadline·credential 모두 O;DefaultReactiveSseGateway는 credential만;DefaultDynamicTargetGateway는 자체 binding;ReactiveStreamingGateway.java:50-107은 셋 다 X.BlockingStreamingGateway.java:63-68주석은 이 누락을 버그로 적고 고쳤는데 reactive streaming은 그대로 → 인증 profile에서 streaming 요청이 credential 없이 나갈 수 있음(동작 테스트로 확인 필요, correctness backlog). - Remedy:
CallSetup.prepare(lease, operation)이 metadata/prepared/deadline/admission/credentials 반환, 진입점은 전송 방식만 다르게 + 명시적 opt-out. Size M · Removes 약 150줄, 공통 단계 추가 시 1곳 수정. - 가정/반론: streaming에서 retry 없음은 의도 → 공통 범위는 retry 이전 단계까지.
- 근거: lease → metadata → prepare → admission → deadline → credential → observation을 각자 손으로 조립. Generic/Reactive와
-
[Required][over-abstraction] 118개 메서드
RedisCommandGateway는 template에 불필요 —src/adapter/outbound/redis-runtime/.../lettuce/operations/RedisCommandGateway.java(1227),LettuceRedisCommandGateway.java(1282)- 근거: 배선된 semantic adapter·health가 쓰는 메서드 8개(
get, set, getAndDelete, incrementBy, loadScript, evaluateRegisteredForList, evaluateRegisteredForLong, ping), 죽은 realtime이 11개, 나머지 약 99개는 redis-sdk 전용. production lane은REGULAR/SCRIPT뿐(BLOCKING/TRANSACTION/PUBSUB/ADMIN은RedisSdkAutoConfiguration.java:277-282한도 설정에만). runtime이 SDK 개념에 역의존:RedisConnectionKind.forCommand(RedisCommandDescriptor)(호출자 SDKCommandPolicyGuard.java:104),sendApprovedRaw/sendAdminDiagnostic/sendExtension(:1107-1134).RedisSdkSettings의 Limits/Blocking/Transaction/PubSub/Advanced/Raw/Admin 섹션 약 350줄도 SDK용. production 클래스가Sdk이름·...redis.sdk패키지를 쓰고 redis-sdk와 split package 9개 공유. - Remedy: 8개 메서드
SemanticRedisCommands(fake용 인터페이스는 유지), lane 2개, 역할 APPLICATION/ADVANCED만,RedisRuntimeSettings로 개명,...redis.runtime.*패키지. Size L(대부분 삭제) · Removes 약 4k/7.3k줄 + 2,481줄 test fake 축소. - 가정/반론: redis-sdk 유지 결정 시 잘라낸 메서드는 redis-sdk 확장 인터페이스로 이동. runtime 계약은 어느 경우든 8개로.
- 근거: 배선된 semantic adapter·health가 쓰는 메서드 8개(
-
[Required][duplication] cache-redis "lease 빌림 →
.get(timeout)→ 예외 처리" 틀 15곳 복사, 이미 달라짐 — idempotency 6, lease 4, cache 4, rate-limit 1 (+probe 1, realtime 5)- 근거:
try (borrow) {...get(..NANOSECONDS)} catch Interrupted catch Exception반복.RedisOperationException.metadata().ambiguousExecution()로 "안 보냄/보냈는지 모름" 구분하는 곳은 rate-limit뿐(RedisEdgeRateLimitAdapter.java:123-131); 나머지 셋은 lane 거절도Indeterminate(1차 #1 부수 증상과 같은 원인). Lua 응답 디코더 3벌:IdempotencyScripts.java:286-300,RateLimitScripts.java:275-285,LeaseScripts.java:169-185. - Remedy:
SemanticRedisCall.run(kind, capability, op, gw -> stage, onReply, onFailure(NOT_SENT|AMBIGUOUS|INTERRUPTED))+ 1차 #8의RegisteredLuaScript에 reply 디코딩까지. Size M · Removes 약 180줄. - 가정/반론: capability마다 fallback이 다름 → fallback은 호출자, 분류만 공통.
- 근거:
-
[Consider][pattern]
RedisIdempotencyStoreAdapter.transition파라미터 15개(outcome enum 7개),complete/markFailed/releaseBeforeExecution은 이를 안 쓰고 재구현 —:420-481,:212-252,:270-306,:311-338(같은 status 문자열 위switch5개). Remedy:IdempotencyScripts.Reply에서enum ScriptStatus로 한 번 파싱, 호출부는Map<ScriptStatus,O>. Size M · Removes 약 120줄(#4와 합치면 534 → 약 300줄). 반론: 명시적 switch가 리뷰 쉬움 — 단 5벌이 이미 서로 다른 default. -
[Consider][over-abstraction] 대체 불가능한 확장 지점 —
HttpClientObservationAutoConfiguration.java:23-35(@ConditionalOnMissingBean HttpClientTagPolicy소비처 없음;BlockingExecutionSupport.standard()가HttpClientTagPolicy.standard()를 다시 만들어(BlockingExecutionSupport.java:77) override 무효;BlockingExecutionSupport는 구성요소 19개 묶음, 11개가 상태 없는new X()). Remedy: bean 삭제 또는 support에 주입,ExecutionSupport로 개명. Size S. -
[Consider][over-abstraction] 구현 1개짜리 인터페이스(테스트 대역 없음) —
RetryCoordinator(참조 0),RetryEligibilityEngine/Default…,ExecutionEvidenceClassifier/Default…,BackoffStrategy/ExponentialFullJitterBackoff(테스트도Default*직접 생성). Remedy: 인터페이스 삭제·구현체 개명. Size S · 개념 4개 제거. 반론: design 문서가 SPI로 기재 — 교체 소비자 없음. -
[Consider][reachability] httpclient에서
HttpClientPlatformAutoConfiguration으로 도달 불가 약 820줄 —BoundedErrorBody(54줄, main·test 참조 0 → 즉시 삭제),MultipartReplayability,SafeHttpLogEvent,spring7/*(107),migration/*(164)는 테스트만 참조,http3/*(392, Experimental, compileOnly Jetty + 별도 lane). Remedy: http3만 유지, 나머지 삭제 또는 docs로. Size S~M. -
[Consider][SRP]
RedisTopologyClientFactory(662줄) 역할 과다 — URI/TLS/ClientOptions factory +RuntimeClient구현 3개(:427Standalone,:475Cluster,:551RoleRouting) + 참조 카운트(SharedClientResources:382) +ShutdownBudget. Remedy: 구현 3개를 package-private top-level로 이동(이동만). Size M · 파일 약 350줄로. -
[Consider][duplication] settings → profile 필드 단위 복사 —
HttpClientProfileFactory.java:40-153(Pool11,Timeout9,Tls8 필드…;valueOf(x.toUpperCase())8번). Remedy: settings 필드를 enum 타입으로(binder가 대소문자 무시 변환). Size S. 반론:@DefaultValue가 Spring 타입이라 profile 레코드 직접 바인딩 불가 — 복사 구조 자체는 정당. -
[Nit][readability] 이력 서술 주석 — httpclient "used to/no longer" 27곳(
ProtocolEvidenceReader.java:8,HttpClientTransportAutoConfiguration.java:66,BlockingStreamingGateway.java:63),RedisCapabilityConfig.java:30-33"376 lines … (BOOT-007)",CapabilityKeyspace.java:11, redis leaf 23곳; 인라인 FQN 약 160줄(HttpMethod/HttpStatus충돌만 정당;RedisKeys.java:37-80javax.crypto,RedisIdempotencyStoreAdapter.java:435,ReactiveAttemptExecutor.java:208-213). Remedy: 불변 조건만 남기고 이력은 git/ADR로. -
[Nit][structure] cache-redis 세부 —
CacheKeys가 가변 generation 상태 보유(RedisCacheRegionAdapter.java:421-450) →RegionGeneration분리; HMACKeyDigest가 설정 패키지(capability/RedisKeys.java)에 있고RedisNamespace.prefix()대신 env:service:domain 재조립;cache-redis/CLAUDE.md의 "legacy cache router" 존재하지 않음. -
[Nit] 기타 — Jackson 2 사용 main 파일은
RemoteProblemDecoder하나(build.gradle:58-66주석은 "two files") → Jackson 3로 옮기면 의존성 1개 감소; "runtime draining"·"retry budget exhausted"를HttpRateLimitRejectedException으로 던짐(DefaultGenericHttpGateway.java:182,280, reactive:265,351) → 텔레메트리 카테고리 오기;RedisSdkAutoConfiguration.java:297-338health indicator 둘은 DOWN 값만 달라 하나로.
Cross-module leads (조사 안 함)
RedisSdkAutoConfiguration.RedisSecretSource+System.getenvfallback(:213-217,375) vsSecretSourcePort(RedisCapabilityConfig.java:68); httpclient는 port 직접.HttpClientEnvironmentKeys(179줄, 리플렉션 env 이름 파생) vs supportStrictSettingsBinder.- TLS material 로딩:
RedisTopologyClientFactory.java:327-380,RedisSdkAutoConfiguration.java:253vshttpclient/security/TlsMaterialProvider.java. ca-skeleton.capabilities.*selector 문자열이 bootstrap/persistence-jpa/redis main 16개 파일에 흩어짐(RedisCorrectnessRoles.java포함).secret://<source>/<name>파싱(RedisKeys.java)의 다른 leaf 존재 여부.
Coverage note
깊게: httpclient gateway·executor·resilience·runtime·support·autoconfig, cache-redis main 전체, redis-runtime gateway 사용처·lane·settings·autoconfig·topology. 훑음: redis-sdk(구조·크기), httpclient profile/security/dynamic. 수치는 grep·정규화 diff 추정. #2 reactive streaming credential 누락은 동작 테스트로 확인 필요.
S4 — 그 밖의 outbound capability adapter
Leaf별 유지보수성 판정
| leaf | main LOC | 판정 | 한 줄 이유 |
|---|---|---|---|
adapter/outbound/notification |
13,512 | OVERBUILT | provider 7종 중 조립되는 건 SES·SMTP 2종. 나머지 5종 약 2.75k줄은 테스트에서만 생성 |
adapter/outbound/fileserver |
14,230 | OVERBUILT | 루트 패키지 8.7k줄(R1/R2 publication)의 port 호출처 0. platform/**와 코드 공유 없는 별도 제품 |
adapter/outbound/objectstorage |
14,478 | OVERBUILT | legacy/신규 두 세대 공존. legacy adoption은 SPI 구현체가 없어 켜면 기동 실패. direct/multipart는 1차 D#7 |
adapter/outbound/messaging |
4,249 | OVERBUILT | 79%(3.36k줄)가 연결되지 않은 R1 compiler/encoder |
adapter/outbound/messaging-kafka |
367 | HEALTHY | 작은 R0 seam |
adapter/outbound/support |
279 | HEALTHY | 결함은 1차에서 다룸 |
adapter/outbound/identifier |
83 | HEALTHY | UuidCodec은 1차에서 다룸 |
Findings (영향 큰 순)
-
[Required][reachability/structure] fileserver 루트 패키지 publication 제품군(R1+R2) 호출처 없음 —
src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/*.java(31파일, 8,659줄)- 근거: main에서
FilePublicationPort/FileExportPort를 쓰는 곳은 이 leaf와 application-core뿐(sample·composition·bootstrap 0).FileserverR2Config.java:20-23은 component scan으로,FileExportConfig.java:23,49는 bean 등록. 루트 패키지와platform/**는 서로 import 0. leaf 안에 FilePublicationPort 계열 구현 3개(FilesystemCsvExportAdapter,LocalFilePublicationAdapter, R2 provider). - Remedy: 삭제. 유지 결정이면 별도 optional leaf로 추출. Size L · Removes 약 8.7k줄, 설정 네임스페이스 2개(
app.fileserver.*,app.file-export.*),FileserverActivationValidator. - 가정/반론: 어떤 fork도 R2 publication을 안 씀 / CLAUDE.md가 "first qualified R2 provider"로 공개 API 취급.
- 근거: main에서
-
[Required][reachability] messaging R1 compiler/encoder 체인 미연결 —
src/adapter/outbound/messaging/.../envelope(1,573) +contract(628) +destination(723) +config(439)- 근거: 진입점
JsonSchemaIntegrationEventEncoder가 main에 나오는 곳은app-bootstrap/.../OutboxCanonicalTransportRequirementValidator.java:55의 에러 메시지 문자열뿐;CompiledMessagingDescriptormain 참조 0; CLAUDE.md "R1 compiler is intentionally not wired". 그런데 NetworkNT validator가 runtime 의존성(implementation(libs.json.schema.validator)), schema 리소스 9개·YAML 배제 정책 유지.realtime/MessagingDurableFanoutAdapter(+RealtimeFanoutEnvelopeJson, 138줄)는 생성처·테스트 0. leaf에 R0 legacy(MessageBroker)·R1(미연결)·canonical bridge 세 세대 공존. - Remedy: R1 체인·realtime fanout 삭제(evidence 생성에 필요하면 qualification source set으로). Size L · Removes 약 3.5k줄 + runtime 의존성 1개.
- 가정/반론: R1 encoder는 canonical bridge(vendored
messaging-schema-*)로 대체됨 / R2 qualification evidence가 사용 — 그래도 test 전용이면 충분.
- 근거: 진입점
-
[Required][reachability] notification provider 5종 미조립, 확장 슬롯도 비어 있음 —
.../platform/provider/{apns,fcm,twilio,webpush,webhook}(2,750줄)- 근거:
ProviderRuntimeAssembler구현은SesProviderRuntimeAssembler.java:28,SmtpProviderRuntimeAssembler.java:482개;ProviderCallbackAssembler는 SES 1개; 둘 다AssembledProvider.dispatchOnly반환(:98,:112) → projector/reconciliation 슬롯·MapProviderEventProjectorRegistry·CapabilityReconciliationGateway에 production 입력 없음. 참조 0:SesDeliveryProjector,TwilioDeliveryProjector,SesSuppressionUpdater,FcmContactPointUpdater,TwilioReconciliationCapability. 자격증명 회전 경로(ProviderRuntimeRotator,RuntimeDrainCoordinator,CredentialProbe구현 0) 미연결. 설정 문서는 7종 모두 유효값으로 기재(docs/notification/configuration-reference.md:64);Provider.validate는 APNs topic·VAPID·Twilio secret까지 검사 후NotificationProviderAssembly.java:141-143에서 "missing assembler"로 실패. - 1차 B#2 보정: B#2는 위조 callback이
SesSuppressionUpdater로 suppression을 만든다고 적었으나 이 클래스는 참조 0 → 그 영향 서술은 과장(서명 우회 자체는 유효). - Remedy: 5종을 extension source set/sample로 이동 또는 삭제;
ProviderType을 SES/SMTP로; 빈 projector/reconciliation 슬롯 제거. Size L · Removes 약 3.0k줄, 개념 6개. - 가정/반론: support-matrix가 "contract implemented / unqualified"로 광고 — 계약 보존이 목적이면 이동이 맞음.
- 근거:
-
[Required][duplication(어긋남)] SMTP capability 두 곳에 서로 다른 값 —
SmtpProviderRuntimeAssembler.java:138-152vsSmtpNotificationProviderAdapter.java:75-76(maxPayload 26,214,400 vs 25,000,000; TTL 24h vs 1d; assembler는 자기 사본(:126), SES assembler는adapter.capabilities()(SesProviderRuntimeAssembler.java:95); 11개 위치 인자new ProviderCapabilities(false,false,…)8곳). Remedy: 사본 삭제·adapter.capabilities()사용, named factory(application-notification record라 cross-leaf). Size S. -
[Required][SRP]
LocalPersistentControlPlane7가지 일 —.../fileserver/LocalPersistentControlPlane.java(1,470줄; #1에서 유지할 때만)- ① 레코드 repository(
:176-352,:728-790) ② 상태 전이표(validateOperationTransition,isAllowedAdjacentTransition:499-592) ③ 2단 lock manager(static stripe,FileLock,ThreadLocal재진입, staticPOISONED_OPERATION_LOCK_ROOTS:40-46,:205-268,:1377-1449) ④ durable write 프로토콜(temp→force→replace→read-back→repair:352-497) ⑤ 보안 디렉터리 syscall facadeSystemSecureRecordOperations(:1036-1272) ⑥ fault-injection 타입 7개 + test 생성자·factory 6개(:62-147,:1273-1376) ⑦ R1 호환 decode(:1318). - Remedy: 전이표 →
DurablePublicationRecord.State.canAdvanceTo()(objectstorage는 이미ObjectOperationStateMachine으로 분리); 나머지OperationLockManager,DurableRecordFile, 얇은 repository로. Size L · 한 번 수정 시 읽을 범위 1.4k → 약 300줄.
- ① 레코드 repository(
-
[Required][duplication(어긋남)] "attested root 아래 private shard" 구현 3벌 —
LocalPersistentControlPlane.java:668-715/LocalPersistentPayloadOperations.java:356-406,607-700,780-1064/LocalPersistentRootAttestor.java:662-773(각자FaultCallback,IdentityVerifier,FailureKind, 예외,SecureShard/ShardAttributes, System* facade 약 550줄; 검증도 다름 — control은 symlink·Files.getFileStore, payload는 fileKey 공백·store 이름;forceDirectory3곳(:808,LocalPublicationJournal.java:209,LocalFilePublicationAdapter.java:338),MessageDigest.getInstance7개 파일). Remedy: package-privateAttestedDirectory하나 + System 구현 1 + fault test double 1. Size M · Removes 약 400줄, seam 인터페이스 9개. 반론: crash qualification 테스트가 FaultPoint에 묶여 이전 비용 큼. -
[Required][duplication(어긋남)] 손으로 만든 flat JSON parser 2개 —
FileserverControlRecordCodec.java:655-855vsLocalPublicationJournalCodec.java:110-266(control은 엄격한decodeUtf8, journal은new String(bytes, UTF_8)로 잘못된 byte를 대체 문자로 조용히 변환; 빈 객체·쉼표 루프 상이). Remedy:FlatCanonicalJson하나. Size S · 약 120줄. 반론: R1 journal은 읽기 전용 호환이라 관대 decode 의도 — 그렇다면 한 줄 명시. -
[Consider][Value Object] 원시 String 검증 73곳 —
FileserverControlRecordCodec.java:463-558(codec이 validator 13개 겸함),FileserverR2Validation.java:36-125(requireText22,requireDigest12,requireFileId8;requireDigest(value, field)와requireSha256(label, value)는 인자 순서만 다른 중복). Remedy:Sha256Hex,FileId,RouteToken,SafeSegmentrecord. Size M. -
[Consider][pattern] notification provider 공통 템플릿은 절반만 있음 — 공유:
ProviderResults,NotificationHttpGateway. HTTP adapter 5개가 각자 재구현:completedFuture(send), nanoTime,protector.reveal(AccessContext.dispatch), request map, exchange, 2xx→accepted 아니면rejected(classifier.classify), transport catch(ApnsNotificationProviderAdapter.java:74-100,SesNotificationProviderAdapter.java:105,TwilioSmsProviderAdapter.java:76-126,WebPushNotificationProviderAdapter.java:80,WebhookNotificationProviderAdapter.java:107); classifier가new ProviderFailure(…5인자)18회. callback SPI는 있고 구현은 SES·Twilio(미연결). Remedy: #3 적용 시 HTTP provider는 SES 하나라 불필요; 3개 이상 유지 시HttpProviderSend.run(...)helper +ProviderResults.failure(code, category, reason)factory(success mapper 인자). Size M · 약 150줄. -
[Consider][reachability] objectstorage legacy adoption은 켜면 기동 실패 —
.../maintenance/*(609줄),config/ObjectStorageLegacyMigrationConfig.java,LegacyObjectAdoptionSettings(LegacyObjectInspector,LegacyAdoptionApprovalReplayStore구현체 없음;Ed25519LegacyAdoptionApprovalVerifiermain 참조 0; readinessObjectStorageCapabilityEvidence/Card(112줄) 테스트 전용;control/ObjectControlRecordEnvelope참조 0). Remedy: 삭제 또는 별도 migration 도구. Size M · 약 800줄. 반론: fork가 구현을 공급하는 SPI일 수 있음 → 그렇다면 README에 필수 bean 명시. -
[Consider][structure] objectstorage 세대 구분·패키지 위치 불명확 — 루트
ObjectStorageConfig.java,config/RoutingObjectMutationAdapter.java:52-57,96-170,273-406(legacy(ObjectStoragePort, 동기S3Client)와 신규(S3AsyncClient+netty)가 코드 공유 없이 공존; port 구현 4개가config/; managed publish(약 230줄)는 router inline, staged는kernel/→ 비대칭). Remedy: legacy →legacy/,Routing*Adapter→routing/,kernel/ManagedObjectPublicationKernel추출. Size M. sample이 legacy 기본 사용 → legacy 삭제는 sample 이전 후. -
[Consider][over-abstraction]
SelectedObjectStorageProviderFactory는 factory가 아님 — telescoping 생성자 4개,Object슬롯 3개를Class<T>cast로 꺼내는 type-unsafe service locator(슬롯은 미연결 direct/multipart 전용). Remedy:record ProviderInstance(ObjectStorageProvider, ObjectControlStore, Runnable close). Size S · 약 70줄. -
[Consider][over-abstraction] provider 1개인데 fileserver R2 routing 계층 —
RoutingFilePublicationAdapter,FilePublicationProvider(구현 1),LocalPersistentPublicationProvider.java:60-86(destination마다 넘긴 뒤 "전부 같은 인스턴스인지" 재검증). Remedy: provider가(controlPlane, payload, Map<id, CompiledFileDestination>)를 받게 하고 router·interface 삭제. Size S. -
[Consider][State 전이표]
ProviderRuntime상태 전이가 7개 메서드에 흩어짐 —ProviderRuntime.java:127-241,RegistryProviderRuntimeControl.java:30-45(markAuthenticationFailed만 무조건set→ DISABLED·DRAINING도 덮어씀). Remedy:EnumMap<State, Set<State>>+transition(target, reason). Size S · 약 70줄. -
[Consider][readability] Settings가 모든 provider 필드를 한 record에 —
NotificationPlatformSettings.java:209-256,280(switch (resolved.name())문자열 분기, 테스트 호환용 11-인자 오버로드). Remedy: enum switch, #3과 함께 미조립 provider 필드 제거. Size S. -
[Nit][readability] 이력 서술 주석 notification 56건·fileserver 18건(예:
ProviderType.java:10-19, 예외 메시지:85"used to bind successfully…",MapProviderCallbackAdapterRegistry.java:10-15,AesGcmCallbackPayloadProtection.java:11-15); objectstorage main inline FQN 84줄(RoutingObjectMutationAdapter.java:74,80,ObjectStorageConfig.java@Conditional) — objectstorage CLAUDE에 금지 규칙 없음. -
[Nit][structure] 용어 혼재 — fileserver 한 leaf 안에서 루트는
*Config, platform은*Configuration; notification*ProviderProperties7개는@ConfigurationProperties가 아닌 파생 값 →*ProviderProfile; 클래스 이름의 버전 라벨(FileserverR2Config,R2PublishedReferenceCodec).
Cross-module leads (조사 안 함)
- 손으로 만든 canonical JSON codec이 3개 leaf에: fileserver 2벌, objectstorage
control/CanonicalJsonReader/Writer, messagingDeterministicEnvelopeWriter. - 로컬 보안 파일시스템 primitive 중복: fileserver
LocalPersistent*·platform/local/SafeFileChannelFactory·SecureDirectoryWalkvs objectstorageLocalObjectPathGuard·LocalDev*Store. - notification
JdkNotificationHttpGateway·AwsSignatureV4Signervsadapter:outbound:httpclient+ objectstorage의 AWS SDK. - adapter
LocalJsonSchemaRegistryvs vendoredmessaging-schema-json;adapter:outbound:messaging-kafkavs vendoredmessaging/messaging-kafka. ProviderCapabilities(application-notification) 11개 위치 인자 → named factory.
Coverage note
구조: fileserver 루트 대형 파일 5개 outline·핵심 구간, notification provider/assembly/runtime, objectstorage config/kernel/maintenance/readiness, 네 leaf 전체 타입의 main 참조 grep(.imports/spring.factories 확인, 문자열·reflection wiring은 grep 한계). 얕게: notification template/security/observation, fileserver platform/local, objectstorage s3/*.
S5 — Inbound HTTP / GraphQL
Leaf별 유지보수성 판정
| leaf | main LOC | 판정 | 이유 |
|---|---|---|---|
src/adapter/inbound/web |
23,095 (340 파일) | OVERBUILT | servlet 진입점에서 닿는 코드 155/340 파일, 9.8k/23.1k LOC. 관심사마다 구현 두 벌. WebFlux 쪽은 어떤 조합으로도 안 켜짐 |
src/adapter/inbound/web-fileserver |
3,976 (62 파일) | NEEDS_WORK | 전부 도달하나 reactive 907줄은 안 켜짐; 별도 problem+json 형식; 업로드 정책이 4개 transport에 복사; leaf 문서 없음 |
src/adapter/inbound/graphql |
25,984 (400 파일) | OVERBUILT | 도달 136/400(1차와 같음). 배선된 코어는 정리됐으나 에러 진입점 우회, autoconfig 706줄, 부팅마다 reflection 아키텍처 검사 |
발견 (효과 큰 순)
-
[Required][duplication] HTTP 에러 어휘가 web+fileserver 안에 3개, 이미 갈라짐 —
web/.../error/ClientSafeValidationDetails.java:18-43외- 응답 형식 3개·코드 체계 4개: Envelope(
GlobalExceptionHandler,AuthErrorResponseWriter,RateLimitInterceptor; 코드OperationalError,RateLimitTransportError);WebProblem(ProblemCodeenum,ProblemCatalog.standard()ProblemCatalog.java:51-162,problem-catalog.yaml이 같은 목록 세 벌; MVC/WebFlux problem handler,ThrottleProblemWriter,BudgetProblemMapper,WebMvcBudgetExceptionHandler);FileserverProblem(필드 15개 problem+json,FileserverExceptionHandler.java:24-40). - 갈라짐 1 — 검증 규칙표 두 벌:
ClientSafeValidationDetails(NotNull→NOT_NULL, 고정 문구, 점 경로) vsvalidation/WebValidationIssueMapper.java:56-86(must-not-be-null, 치환된 메시지를 그대로 노출(${만 거름), RFC 6901 pointer) → README "치환 메시지 미노출" 규칙을 한쪽만 지킴. - 갈라짐 2 — 운영은
spring.mvc.problemdetails.enabled=false(app-bootstrap/.../application.yml:17-22)라 WebProblem은 fixture(ContractFixtureApplication.java:35-40)에서만; 반대로 fileserver는 D5(ProblemDetail 거부)와 달리 운영에서 problem+json을 보내는데FileserverErrorCode는 이미ApiErrorCode구현. - 조치: HTTP 에러 형식을 Envelope 하나로; WebProblem 어휘(yaml, 핸들러 2, writer 3 포함) 삭제 또는 testFixtures로; fileserver는
ErrorResponseFactory.envelope(code,…, details)(프로토콜이 요구하는Draft12OffsetProblem만 유지); 검증 규칙표 하나로. 규모 L · 약 1.3k LOC, 응답 형식 2개, 코드 체계 1개 제거. - 가정/반론: fileserver 클라이언트가 problem+json 의존 가능 / 템플릿이라 외부 소비자가 없는 지금이 가장 쌈.
- 응답 형식 3개·코드 체계 4개: Envelope(
-
[Required][reachability/duplication] WebFlux 쌍둥이 코드는 어떤 조합에서도 안 켜짐 —
web/build.gradle:26,web-fileserver/build.gradle:27- 근거: 두 leaf 모두
implementation spring-boot-starter-web→ 소비자 classpath에 DispatcherServlet → Boot는 항상 SERVLET →@ConditionalOnWebApplication(REACTIVE)모두 false.FileserverReactiveConfiguration.java:24-30Javadoc도 "inert in the shipped composition". - 규모: web main 약 1.8k(
webflux/*1,010,advanced/webflux525,callback/reactive221), fileserver reactive 907, test 약 2k, strict lane 2개(webFluxContractTest,webFluxPerformanceTest). - 중복 정도: 주석·import 제외 쌍마다 40–69% 동일(problem handler 0.69, budget 0.49, throttle 0.44, request-id 0.40). transport 중립 코어(
core/,budget/,operation/,ProblemCatalog,WebValidationExceptionMapper)는 이미 있음 → 중립 코어를 더 뽑아도 줄어드는 양은 300줄 미만. - 갈라짐:
NoResourceFoundException→404는 MVC에만(WebMvcProblemExceptionHandler.java:150); reactive fileserver에는 tus/draft12/lifecycle/describe 없음.WebFluxPlatformAutoConfiguration.java:34-37의 중복 정당화("공유 설정을 쓰면 servlet 타입이 딸려 온다")는 사실이 아님(중복 bean 7개 — 주석은 6개 — 모두 stdlib/Jackson만 import). - 조치: reactive 껍데기 삭제. 꼭 지원해야 하면 graphql처럼 leaf에서 starter-web을 빼서 서버 선택을 composition으로, 공통 bean 7개는
WebPlatformCommonConfiguration으로. 규모 L · main 약 2.7k + test 약 2k, lane 2개 제거. - 반론: 설계서가 WebFlux를 Stable로 약속 — 실행할 composition이 repo에 없음.
- 근거: 두 leaf 모두
-
[Required][over-abstraction]
WebMvcPlatformAutoConfiguration: bean 14개 중 9개는 운영에서 읽는 곳 없음, startup check는 실패 불가 —mvc/autoconfigure/WebMvcPlatformAutoConfiguration.java:56-178- 읽는 곳 없는 bean:
webOperationCatalog(읽는FunctionalRouteRegistry,WebRouteInventory둘 다 도달 불가),webBudgetCatalog,webProblemCatalog,webProblemFactory,webValidationExceptionMapper,webValidationIssueMapper,webWireTypeManifest,webUriPolicy,webMethodPolicy.WebMvcEvidenceFilter.java:52-57은 매 요청 tracker 생성하지만 main의markApplication*/snapshot()/requireTracker호출 0.WebMvcPlatformStartupCheck.java:33-53은 같은 클래스가 무조건 만드는 bean 3개의 존재만 확인 → 실패 불가.WebPlatformSnapshot필드 7개 중 4개는 항상 빔. - 조치: bean 9개, evidence filter 배선, startup check,
admin/platform삭제. 규모 M · 약 600 LOC, 개념 약 12개.
- 읽는 곳 없는 bean:
-
[Required][structure] web 안에 같은 관심사가 "1세대(운영·sample 사용)"와 "2세대 platform(읽는 곳 0)" 두 벌 (1차 I-8 확장)
- 조건부 요청:
ETags/PreconditionFailedException(sample 사용, handler 있음) vsEntityTag*/ConditionalReadEvaluator/MutationPreconditionEvaluator/WebPreconditionFailedException(test만, handler 없어 실제로 쓰면 500;WebPreconditionFailedException.java:13이 스스로 인정). - 페이지네이션:
PageParams/SortParamvsWebCollectionRequestParser+ catalog 5종(약 1.1k). cursor codec은 web 2벌(cursor/CursorCodec,pagination/HmacWebCursorCodec) + graphql 1벌(HmacGraphQlCursorCodec), 셋 다 운영 경로 밖. - 헤더 상수: 같은 패키지
http/ApiHeaders와http/WebHeaderName11개 겹침(표준 헤더는 SpringHttpHeaders에 이미 있음). - rate limit:
RateLimitInterceptor(운영) vsWebRateLimiter+Web{Mvc,Flux}ThrottleFilter+admission/*+advanced/ratelimit(fixture 전용). - 로깅:
RequestLoggingFiltervsWebAccessLog*/WebAudit*(381). 동시 실행 제한 semaphore 3벌:SemaphoreAdmissionController,VirtualThreadAdmissionGuard,BlockingBridgeBudget. - 조치: 관심사마다 하나만(기본은 2세대 삭제 — 1세대가 문서·sample·handler와 연결). 규모 L · 약 5k LOC, 병렬 개념 약 8개.
- 반론: 2세대가 설계 목표일 수 있음 → 그렇다면 1세대를 옮기고 삭제. 둘 다 두는 것이 최악.
- 조건부 요청:
-
[Required][duplication] Retry-After 초 계산 3벌, 결과 다름 — 운영
ratelimit/RateLimitInterceptor.java:107-111은"0"가능;error/ThrottleProblemWriter.java:72-76은 최소 1("0은 즉시 재시도" 주석);mvc/operation/OperationHttpController.java:81,ReactiveOperationHttpController.java:100은toSeconds()버림. 조치:RetryAfter.seconds(Duration)하나. 규모 S. -
[Required][duplication/pattern] GraphQL 에러 "단일 진입점"이 우회되고 Category switch 3개 —
runtime/GraphQlWireErrorMapper.java:23,57-72- Javadoc "Everything routes through here"인데 요청 단계 경로 2곳(
GraphQlPlatformWebInterceptor.java:165,GraphQlPlatformInstrumentation.java:88)은GraphQlPlatformRejectionMapper.map을 직접 호출;mapRequestRejection호출처 0, 본문이mapFieldFailure와 동일. 결과: adopterGraphQlPrincipalResolver가ApiErrorCarrier를 던지면 요청 단계는INTERNAL_ERROR, 필드 단계는 제 코드. - Category switch 3개(
category:102,clientMessage:112,GraphQlWireErrors.classificationOf:54);mapKnowninstanceof 분기 9개(GraphQlPlatformRejectionMapper.java:54-121); "요청한 리소스를 찾을 수 없습니다." 3곳 중복. 실제 매퍼는runtime/, 참조 0인 것(GraphQlRequestErrorMapper,GraphQlSubscriptionExceptionResolver,GraphQlNullabilityContract, 186줄)은error/. - 조치: 세 호출부가 하나의
map(Throwable, ctx);EnumMap<Category, Rendering>표로 switch 3개 대체; platform 예외가 code/category/message 인터페이스를 구현해 instanceof 사슬 제거; 실제 쓰는 에러 클래스는error/로, 참조 0 삭제. 규모 M · 약 250 LOC.
- Javadoc "Everything routes through here"인데 요청 단계 경로 2곳(
-
[Consider][SRP]
GraphQlPlatformAutoConfiguration706줄 + 부팅마다 reflection 아키텍처 검사 —autoconfigure/GraphQlPlatformAutoConfiguration.java:83,151(bean 약 40개가 10가지 기능: startup 검증, runtime 감지, body limit, chain, auth, cost, 에러, 관측 7, preparsed cache, DataLoader;graphQlControllerBoundaryCheck가architecture/(969 LOC)를 매 부팅 실행 — 같은 경계를app-bootstrapArchUnitAdapterBoundaryArchitectureTest.java:50,345가 빌드 때 이미 검사; Javadoc(:76) "A real @AutoConfiguration"인데 실제는 FQN@Configuration, :626-660 FQN 투성이). 조치: 기능별@Configuration으로 나누고 root에서 import,architecture/는 ArchUnit test로. 규모 L. -
[Consider][over-abstraction] web이 하위 leaf 패키지 구조를 앎 —
web/.../moduleboundary/WebStableModule.java:119-172(web main이 web-fileserver 패키지 12개 선언 — 방향이 거꾸로 된 지식; testWebBuildModel.java:190-207은 형제 leaf 디렉터리를 경로로 스캔; main 669줄은 test에서만; graphql도 같은 구조(main 535); 자체 import 스캐너 285/293줄은 ArchUnitlayeredArchitecture()/slices()로 대체 가능). 조치: leaf마다 ArchUnit 규칙 하나, enum·스캐너 삭제. 규모 M · 약 2.1k LOC. -
[Consider][structure] notification HTTP는 일반 web leaf 소속이 아님 —
web/.../notification/platform/**(18 파일, 1,168줄; web에서application-notification을 import하는 유일한 패키지(17곳); web 쪽은core·observability만 사용; web-fileserver 분리 이유(web-fileserver/build.gradle:8-20)와 같은 모양; 이 패키지 때문에 모든 HTTP 앱이application-notification을 classpath에 둠(web/build.gradle:18); webCLAUDE.mdAllowed 목록에 이 의존 없음). 조치:adapter:inbound:web-notificationleaf. 규모 M. -
[Consider][SRP] fileserver 업로드 세션 정책(namespace, 만료 시각)이 4개 transport에 복사 —
FileUploadController.java:180-187,TusController.java:105-110,Draft12UploadController.java:86-93,reactive/FileUploadHandler.java:116-123(TTL 설정 3개·검증 복사:FileserverWebProperties.java:24-26,TusProperties.java:22,Draft12Properties.java:16-21; 만료 계산은 세션 정책이라 HARD-STOP 4에 가까움). 조치: application-fileserver가UploadMode별로 계산. 규모 S-M. -
[Consider][pattern]
compat/GraphQlSchemaComparator.java(791줄, S5 최대 파일) +GraphQlChangeKind.java(285줄)는 graphql-java 기능 재구현 — graphql-java 25에graphql.schema.diff.SchemaDiff/DiffCategory있음; compat 패키지는 도달 불가. 조치: 삭제(1,562 LOC), 필요하면SchemaDiff빌드 태스크. 가정: 세부 분류가SchemaDiff와 같게 나오는지 미확인. -
[Nit][pattern] profile-name record 5개 복사본, 1개는 이미 다름 —
operation/{Admission,Authorization,Response}ProfileName,CachePolicyName,budget/WebBudgetProfileName=[a-z][a-z0-9.-]{2,63};ratelimit/RateLimitProfileName만[a-z][a-z0-9-]{0,63}. 조치:ProfileName하나 또는 #3과 함께 삭제. 약 140줄. -
[Nit][over-abstraction] GraphQL
Unsupported플래그 6개는 "켜면 부팅 실패"만 —GraphQlPlatformSettings.java:151-176,GraphQlPlatformStartupValidator.java:54-72, 문자열with(String,…). 미구현 기능에는 설정 키를 두지 않음. -
[Nit][readability] web README
:3패키지 루트dev.caskeleton.adapter.web틀림; web 문서에 WebFlux·notification·problem catalog·advanced·operationasync 전혀 없음(LOC 절반 이상); web-fileserver CLAUDE.md/README 없음; 주석 비율 web 30%, graphql 33%; 이력 서술 web 34, graphql 74; graphql "design §" 92회, "Task N" 17회; inline FQN web 58, graphql 92;GraphQlPlatformWebInterceptor.java:66생성자 인자 9개(anonymous 관련 3값 parameter object).
다른 모듈로 이어지는 단서 (조사 안 함)
- Category→status/message switch가 grpc
GrpcStatusMapper.java:40에도; web 영어 문구, graphql 한국어 문구로 이미 다름 → shared-contract 표 하나 후보. - moduleboundary 세 번째 사본: websocket
WebSocketStableModule.java(394),WebSocketBuildModel(264). - request context 타입 3종: web
core/WebRequestContext, graphqlGraphQlRequestContext, sharedTenantContext. - release/promotion gate(web
advanced/release, graphqlrelease)가 websocket/grpc에도 반복되는지. - bulkhead: graphql
GraphQlBlockingBridge, fileserverBlockingTransferExecutor, httpclient 겹침 여부.
검토 범위
자세히: leaf 문서, 두 web autoconfig, error/validation/ratelimit/conditional, graphql autoconfig/error/runtime, fileserver 컨트롤러·problem·reactive 설정. 도달성은 servlet 진입점(autoconfig, 스캔 대상 stereotype, 다른 main leaf import, sample 제외) 스크립트. 대충: advanced/*, pagination 내부, compat 내부. 1차 결함은 재보고 안 함.
S6 — Realtime/gRPC inbound adapters, composition roots, sample
Per-leaf maintainability verdict
| leaf | main LOC | verdict | one-line reason |
|---|---|---|---|
| adapter-inbound-websocket | 12,954 | OVERBUILT | 문서상 기능은 stomp/ 8클래스(479줄)뿐. 나머지 약 9.7k줄은 leaf 자체 @Configuration에서도 닿지 않고, 두 composition root 어디에도 조립 안 됨 |
| adapter-inbound-grpc | 623 | HEALTHY | 9파일, config 1, runner 1. 다른 곳에 gRPC 스택이 하나 더 있다는 것만 문제(lead) |
| app-bootstrap | 6,366 | NEEDS_WORK | 활성화 규칙 6곳 이상에 흩어지고 기본값이 이미 다름; validator 19개가 5패키지·3 lifecycle; scan 제외 regex가 약 12개 leaf 내부 패키지를 앎 |
| sample-portfolio | 9,496 | NEEDS_WORK | WorkLog slice는 복사할 만함. 그러나 main의 48%가 poster-image; bootstrap 코드 약 540줄 복사; bootstrap이 결함으로 규정한 scan 방식 사용; yml 1/3 미사용 |
| composition-fileserver-platform | 868 | HEALTHY | root 1개 + @Import로 얇게 조립. 오래된 주석, 쓰지 않는 registry edge 1개 |
그룹 질문에 대한 답
- 활성화 지도가 한눈에 읽히는가: 아니다. 스위치↔capability 대응이
MasterSwitch(shared-contract, 9개), auto-config 9개의@ConditionalOnProperty문자열,CapabilityDependencyValidator·DataSourceRequirement·RedisActivationValidator·SecretSourceValidator·OutboxRelayBrokerRequirementValidator,AdapterActivationEndpoint,build.gradledependencyPolicy,docs/capability-status.md에 나뉘고 이미 서로 어긋남(#2, #5). bean 등록 경로도 3가지(component scan,AutoConfiguration.imports,spring.factoriesEPP 6개). - sample이 복사할 만한가: WorkLog는 그렇다(얇은 컨트롤러, 순수 Java use case +
@Bean명시 wiring, 직접 만든 fake 테스트). 모듈 전체로는 아니다(#7–#11). - capability 하나 켜려면: Outbox+relay = 스위치 5개(
APP_OUTBOX_ENABLED,APP_OUTBOX_RELAY_ENABLED,APP_PERSISTENCE_JPA_ENABLED,APP_MESSAGING_ENABLED,APP_MESSAGING_BROKER) + broker starter 의존성 +APP_MESSAGING_KAFKA_BROKERS, yml 3개와 build.gradle, 검증 클래스 4개. Redis cache =redis.yml·capabilities.yml스위치 1개씩, 연결 env(APP_REDIS_MODE/NODES)는 어느 yml에도 없음, prod HMAC secret, 검증 클래스 2개. 전체 표면: bootstrap yml 19개(1,388줄, 52% 주석), env placeholder 273개,.env.example401줄.
Findings (highest leverage first)
-
[Required][reachability] websocket leaf가 안 쓰는 플랫폼 라이브러리를 보유 —
src/adapter/inbound/websocket/src/main/java/.../websocket/- Evidence: 7개 Spring config에서 닿는 코드는 48클래스 3,230줄; 닿지 않음:
advanced/4,041,outbound689,moduleboundary519,handler467,evidence407,release311.release/WebSocketStableReleaseGate,advanced/release/AdvancedPromotionGate는 테스트만 호출;moduleboundary/WebSocketStableModule(394줄 enum)은 leaf 안의 두 번째 모듈 registry;WebSocketAdvancedCapability.java:71"Read by the startup validator"는 거짓(호출처ResumeTokenTest:184-186뿐); STOMP 스택 2개(stomp/WebSocketConfigvsadvanced/stomp/**1,491줄),StompBrokerExclusivity는 둘의 충돌 방지용으로만 존재. - Remedy:
stomp/+ safety config만 남기고 gate·moduleboundary·evidence는 test source로; 플랫폼 라이브러리는optional-platforms같은 별도 build로 빼거나 삭제; STOMP 스택 하나로. Size L · 기본 빌드에서 약 9–12k줄 제거. - 가정/반론: 향후 채택용 vendored 라이브러리 → 그렇다면
messaging:*처럼 별도 family로, inbound adapter leaf 안에 둘 이유 없음.
- Evidence: 7개 Spring config에서 닿는 코드는 48클래스 3,230줄; 닿지 않음:
-
[Required][duplication] capability 의존 규칙 6곳, 기본값 이미 갈라짐 (1차 L-6보다 넓음)
- Evidence:
ca-skeleton.outbox.relay-enabled없을 때 해석 셋:CapabilityDependencyValidator.java:54,196-198false,OutboxConfig.java:66matchIfMissing = true,OutboxRelayBrokerRequirementValidator.java:50Boolean.TRUE→ ORBRV는 "키 없을 때"만 실패, 명시적 true면 CDV가 EPP 단계에서 먼저 거부.capabilities.idempotency.provider기본값이 CDV:89·DSR:37·RAV:69는 "disabled",SecretSourceValidator.java:137은 "jdbc". Redis role 표 두 벌(RedisActivationValidator.java:27-33맵 vsSecretSourceValidatorprefix 분기);SecretSourceValidator.java:31REDIS_ENABLED_PROPERTY는MasterSwitch.REDIS중복. 같은 키 문자열 반복:idempotency.provider9회/6파일,relay-enabled7회/3파일,multi-instance-enabled5회/3파일. - Remedy: 규칙을 표 하나로(
RuntimeNumericBoundsValidator.BOUNDS모양): 키·기본값·필요한 것(JPA/MESSAGING/REDIS)·prod secret. CDV, DSR, Redis 모순 검사, 필요 secret 목록, endpoint를 표에서 파생. Size M · 약 350줄, 클래스 4개 제거. - 가정/반론: 표가 작은 DSL로 커질 수 있음 / 소비처 이미 5곳, 기본값 drift 실재.
- Evidence:
-
[Required][SRP|duplication] startup validator 19개가 3 lifecycle·5 패키지에 흩어짐
- Evidence: EPP 3,
InitializingBean4,SmartInitializingSingleton12; 12개는Environment만 받음; 합계 약 1.5k줄(main의 24%). OSIV 검사 두 벌:OpenInViewSafetyValidator.java:26-27(모든 profile 거부) vsJpaDangerousConfigurationGuard.java:51(local-convenience 허용) — 앞의 것이 무조건 등록(RuntimeSafetyConfig.java:28-30)이라 뒤의 예외는 죽은 코드. ddl-auto 검사 두 벌(JpaSchemaSafetyValidator,JpaDangerousConfigurationGuard:62-65).isProdActive()5곳 복사(JpaSchemaSafetyValidator:51,FlywayProdSafetyValidator:55,PersistenceVendorProdSafetyValidator:81,PostgreSqlTransportSecurityValidator:86,SecretSourceValidator:161).runtime/startup/(CLAUDE.md상 vocabulary 패키지)에 guard 3개. CDV는 EPP와CapabilityDependencyStartupCheck에서 두 번 실행. - Remedy:
StartupRule { List<String> violations(Environment) }목록 + EPP runner 하나; bean 필요한 검사 3개만 bean; OSIV/DDL 하나로. Size M · 약 500줄, 클래스 약 10개 제거.
- Evidence: EPP 3,
-
[Required][structure] root가 넓게 scan한 뒤 다른 leaf 패키지를 blacklist —
app-bootstrap/.../CaSkeletonApplication.java:42,58,96-117- Evidence:
AUTO_CONFIGURED_PACKAGES에 약 12개 leaf 내부 패키지를 가리키는 alternative 18개;bootstrap.notification(:98)은 존재하지 않는 패키지. scan이 실제로 잡는 stereotype 38개(web 27, bootstrap 8), regex가 빼는 것 70개.@ConfigurationPropertiesScan에 별도 whitelist 11개. - Remedy: scan을
dev.caskeleton.bootstrap(autoconfigure 제외)로 좁히고,adapter:inbound:web은 persistence/httpclient처럼 자기AutoConfiguration.importspublish. Size M · regex, whitelist, parity 테스트, "새 패키지를 root에도 등록" 규칙 제거. - 반론: web advice·controller 순서를 auto-config로 옮길 때 추가 작업.
- Evidence:
-
[Required][structure] Fileserver는 build에서 빠졌는데 스위치·설정은 남음
- Evidence:
app-bootstrap/build.gradle:376-390dependencyPolicy가 4개 모듈을 runtime에서 제외; 그런데application.yml:244가config/fileserver.yml(116줄) import;MasterSwitch.FILESERVER*가 endpoint에 보고되고DataSourceRequirement.java:54-59는 이 capability 때문에 pool을 열며,CaSkeletonApplicationregex에 3개 항목;docs/capability-status.md:27-28WIRED=yes. 결과(코드상 추론, 미실행): shipped jar에서APP_FILESERVER_PLATFORM_ENABLED=true→ fileserver bean 없음, 에러 없음, DB pool만 열림. - Remedy: fileserver 설정을 composition 모듈 채택 문서/테스트 resource로; "스위치 켜졌는데 capability auto-config 클래스가 없으면 실패" 검사(
ClassUtils.isPresent). Size S–M · root에서 약 130줄.
- Evidence:
-
[Required][duplication] idempotency 설정이 binder 3개·yml 2개, 서로 불일치
- Evidence:
IdempotencySettings(ca-skeleton.idempotency,config/idempotency.yml:9),IdempotencyProviderSettings(provider만), cache-redisRedisCapabilitySettings.APP_IDEMPOTENCY_TTL이 두 키에 바인딩(capabilities.yml:34).PostgreSqlIdempotencyProviderConfig.java:36,39는 lease 2분·codecjson.v1하드코딩,capabilities.yml:33,38은 30s·json-v2광고(PostgreSQL provider는 안 읽음). 같은 패턴:APP_RATE_LIMIT_DEFAULT_POLICY_ID가ratelimit.yml:10·capabilities.yml:55둘 다. - Remedy:
ca-skeleton.capabilities.idempotencysettings record 하나를 모든 provider가 사용;config/idempotency.yml·하드코딩 상수 삭제. Size M.
- Evidence:
-
[Required][duplication] sample이 bootstrap 인프라 약 540줄 복사, 이미 갈라짐 —
sample-portfolio/.../bootstrap/{tracing,idempotency,settings,logging,metrics,context,management}(difflib 유사도 0.22–0.89;SampleIdempotencyConfigJavadoc "Sample-local copy";SampleTracingSampleRateResolver의"staging" -> 0.10자체 profile 어휘 — bootstrap CLAUDE.md는RuntimeEnvironment밖 profile 판정 금지; 원인: app-bootstrap이 라이브러리가 아니라 두 번째 root는 복사할 수밖에 없음). Remedy: root 무관 부분을 두 root가 쓰는 library leaf로(composition:fileserver-platform모양, registry edge 추가). Size M · 약 500줄. -
[Required][structure] sample root가 bootstrap이 결함이라 적은 scan 방식을 가르침 —
SamplePortfolioApplication.java(@ComponentScan("dev.caskeleton")+@ConfigurationPropertiesScan("dev.caskeleton"), 타입 3개만 제외;CaSkeletonApplicationJavadoc은 이를 "꺼진 capability의 settings가 바인딩되는 원인"으로 설명). Remedy: sample 패키지만 scan, leaf는 auto-config(#4 이후). Size S–M. -
[Required][reachability] sample
application.yml327줄 중 109줄을 읽는 코드 없음 —ca-skeleton.capabilities.cache(30),app.cache.redis(25),app.outbound.http(20),ca-skeleton.logging(17),app.notification(5),app.messaging(4),ca-skeleton.bootstrap(2) (1차의 rate-limit 6줄 제외; sample classpath에 binder 없음). Remedy: 삭제. Size S. -
[Consider][structure] sample 대표 예제가 poster-image에 묻힘 — poster-image 약 4.6k줄 vs WorkLog 2.2k;
application/에 종류별(command/,query/,event/,port/,exception/)과 기능별(poster/,posterimage/,worklog/) 패키지 혼재; 상태 머신PosterImageUploadIntent(333줄, 필드 24)가 application 계층(WorkLog는 domain);PublishPosterImageUseCase생성자 14개; legacy API 모드 약 420줄;WorkLogSortField(domain)가 HTTP 이름(fromRequest)과 persistence property 이름을 둘 다 앎;sample-portfolio/CLAUDE.md:15-21은 WorkLog만, 경로 틀림. Remedy: 기능별 패키지, poster-image는 별도 sample 모듈/objectstorage 검증 consumer로 이동, legacy 모드 삭제. Size L. 반론: object-storage publication·idempotency V2를 끝까지 쓰는 유일한 consumer → 삭제가 아니라 이동. -
[Consider][duplication] sample 컨트롤러·테스트 반복 —
toId()4벌(WorkLogController:239,PosterController:161,LegacyPosterImageController:49,PosterImagePublicationController:110); sort 파싱 2벌(WorkLogController:99-113,PosterController:91-105);WorkLogController.requireIfMatch:209가 update 전에 get use case를 추가 호출(컨트롤러가 use case 2개 조율, 읽기-비교가 트랜잭션 밖); 테스트 9개 파일이TransactionPortfake를 각자 작성, testFixtures에 공용 fake 없음. Remedy:UpdateWorkLogCommand에expectedVersion, id/sort helper 하나,InlineTransactionPort를 testFixtures로. Size S. -
[Consider][over-abstraction] JPA 정책 클래스 —
JpaPlatformAutoConfiguration은 auto-config가 아니라 factory·report·16개 항목 정적 catalog 겸용;jpaDataSourceProfileValidatorbean(JpaPlatformRuntimeAutoConfiguration:59-64) 주입처 없음(PersistenceJpaRootAutoConfiguration:43이 따로new);app.jpa-platform.addons-enabled(:30) 테스트만 설정. Remedy: 개명/inline, 미사용 bean·플래그 삭제. Size S. -
[Consider][over-abstraction] 역할 없는 startup 예외 subclass 4개 —
runtime/startup/{MigrationFailed,ProfileMismatch,RequiredAdapterDisabled,StartupValidation}Exception(각자StartupErrorCode를 부모에 넘기기만; 타입 구분 55곳 모두 테스트). Remedy: 구체 클래스 하나 +errorCode()단언. Size S. -
[Consider][structure] 스위치 prefix·"capability" 뜻 제각각 — prefix 셋:
ca-skeleton.*(jpa, mongo, notification, outbox, tracing, grpc),app.*(messaging, redis, fileserver, httpclient, websocket, rate-limit),backend.graphql; "capability" 4가지 뜻(@UseCaseCapability, master switch,capabilities.*provider selector,JpaCapability/WebSocketAdvancedCapability); outbox·tracing·lock 스위치는MasterSwitch에 없어 endpoint에 미보고. Remedy:MasterSwitch.legacyProperties()이관 장치로 prefix 통일. Size M. 반론: property 이름 변경은 fork breaking. -
[Consider][structure] bootstrap
:test에 저장소 governance 테스트 약 7.6k줄 —src/test/.../contract/(47파일 중 33개가 docs/registry/yml을 직접 읽음). Remedy:architectureTest처럼 별도 lane. Size M. -
[Nit][readability] 이력/리뷰 ID 주석: bootstrap 105줄(주석 비율 25%), websocket 35%;
CapabilityDependencyEnvironmentValidator.java30줄 Javadoc이 3줄짜리 클래스 설명; hikariconnection-timeout주석 "It shipped as 5s…"; config yml 15개가 같은 3줄 헤더 반복;OpenInViewSafetyValidator예외 메시지에 "D2";FileserverPlatformAutoConfiguration의 "identifier generator" 설명 틀림(identifier 의존성 없음 → registry edgeadapter-outbound-identifier도 미사용). -
[Nit]
TracingSettings.sampleRate가 String이라 3곳에서 파싱(클래스 5개, 377줄;TracingSampleRateResolverinline FQN) → 범위 검증 붙은Double.
Cross-module leads (not investigated)
- gRPC 서버 스택 2개:
adapter/inbound/grpc(GrpcServerRunner,GrpcStatusMapper) vsgrpc/grpc-server+grpc-spring-boot-starter(GrpcErrorMapper), 둘 다 조립 안 됨. - inline
TransactionPortfake가 저장소 전체 테스트 19곳 이상 → application-core testFixtures로 하나. - 복사용 예제
CreateWorkLogUseCase가LegacyOutboxAppendPort사용(MSG-015 cutover 관련). docs/capability-status.md:27-28WIRED=yes vsdependencyPolicy모순;MasterSwitch(shared-contract)가 shipped build에 없는 capability 나열.DefaultUploadApplicationService생성자 14개(application-fileserver),FileserverUploadServiceConfiguration.java:74에서 조립.
Coverage note
깊게: bootstrap activation/, autoconfigure/{idempotency,jpa,outbox,redis}, CaSkeletonApplication, validator 목록·핵심 본문, yml; sample entry, bootstrap/*, 컨트롤러, 대표 use case·테스트, yml; gRPC main 전체. websocket 도달 가능성은 단순 이름 참조 그래프(Spring config root, reflection 미반영).
S7 — Vendored platforms (messaging:*, grpc:*, grpc-advanced:*)
Per-family / per-leaf maintainability verdict
| leaf or family | main LOC | verdict | one-line reason |
|---|---|---|---|
| messaging-core-api | 3,948 | NEEDS_WORK | 예외 서브클래스 12개 미사용, MessageHandler 연결 없음, boolean 12개 capability |
| messaging-schema-api / schema-json | 654 / 226 | HEALTHY | 조립되는 코덱은 json 하나; schema-api는 core-api와 합칠 후보 |
| schema-avro / schema-protobuf / cloudevents / claim-check | 1,190 | OVERBUILT | 쓰는 곳 없음(100% 도달 불가); starter가 cloudevents·claim-check edge를 쓰지 않으면서 달고 있음 |
| policy / transport-spi / runtime-core / security / observability | 5,140 | HEALTHY | 발행 경로, 도달 불가 0–38% |
| messaging-kafka | 3,454 | NEEDS_WORK | 71% 도달 불가(consume 쪽 전체), 645줄 registrar |
| rabbit + starter-rabbit | 2,625 | OVERBUILT | 기동 시 선택하면 거부; 운영 코드에 RabbitChannelPublisher 구현 없음 |
| pulsar / nats / kafka-share / stream-bridge | 2,082 | OVERBUILT | vendor SDK 의존성 없음, 쓰는 곳 없음 |
| reliability-api / outbox-jdbc / inbox-jdbc | 3,599 | NEEDS_WORK | leaf 하나가 서로 다른 일 4가지; 호출자 없는 port 메서드 |
| admin-api + admin-runtime | 2,858 | NEEDS_WORK | 진입점 없음, leaf 2개로 나눈 이유 없음 |
| messaging-spring-boot-starter | 3,328 | NEEDS_WORK | 550줄 god config, 20필드 union settings, 쓰는 곳 없는 facade 3개 |
| starter-kafka / testkit | 197 / 1,145 | HEALTHY | capability artifact / 테스트 지원 |
| grpc-core-api | 1,897 | NEEDS_WORK | registry 내용을 코드로 재기술(GrpcStableModuleCatalog) |
| grpc policy+server+client+discovery+admin | 8,197 | NEEDS_WORK | 의존성 경계 1개를 leaf 5개로 쪼갬; io.grpc import는 운영 파일 5개뿐 |
| grpc-proto-contract + codegen | 1,297 | OVERBUILT | protoc/Buf를 regex로 재구현 |
| grpc-observability | 354 | NEEDS_WORK | 쓰는 곳 0 |
| grpc-operation-ledger-jpa / starter / testkit | 336 / 494 / 2,323 | HEALTHY | JPA·Spring·netty라는 실제 의존성 경계 |
| advanced bootstrap/edition/streaming/resilience/diagnostics | 3,021 | OVERBUILT | stdlib뿐인 leaf 5개, 런타임 진입점 0 |
| grpc-advanced-compat | 962 | NEEDS_WORK | reactor·spring-integration 실제 의존성 있음, gate 클래스 섞임 |
도달성(starter/adapter/app-bootstrap main에서 클래스 이름 참조 전이 폐포, 과대 추정 → 도달 불가 수치는 하한): messaging testkit 제외 ≥12.7k/29.3k LOC(43%), grpc starter 기준 12.4k/16.6k(75%) 도달 불가.
Findings (highest leverage first)
-
[Required][granularity|reachability] 선택 불가하거나 쓰는 곳 없는 messaging leaf 10개가 기본 빌드에 —
messaging-pulsar-experimental,-nats-experimental,-kafka-share-experimental,-spring-cloud-stream-bridge(build.gradle에 SCSt 의존성 없음),-rabbit+-starter-rabbit(MessagingProviderSelection.java:69기동 거부),-schema-avro,-schema-protobuf,-cloudevents,-claim-check- Evidence: 운영 5,897 + 테스트 4,016 LOC; pulsar/nats/kafka-share/stream-bridge는 vendor 의존성 없이 자체
*SendOperationseam만(PulsarMessagingTransport.java:264); starter가 cloudevents·claim-check를implementation으로 달지만 main 참조 0(messaging-spring-boot-starter/build.gradle:36,43);MessagingSettings.Experimental/Bridge(:150,:212)는 바인딩만. - Remedy: grpc처럼
optional-platformsbuild로 이동; experimental 4개와 Debezium은 삭제 권고; starter edge 2개·설정 클래스 2개 삭제. Size M · 기본 빌드 leaf 10개, 약 5.9k LOC. - Assumption/Counter: 기본 adopter는 Kafka 발행만 /
docs/messaging/support-matrix.md공개 약속 — 이동은 삭제가 아님.
- Evidence: 운영 5,897 + 테스트 4,016 LOC; pulsar/nats/kafka-share/stream-bridge는 vendor 의존성 없이 자체
-
[Required][structure|over-abstraction] consume 계약 3개, 조립 0 —
messaging-core-api/.../delivery/MessageHandler.java:15(참조 0),DefaultDeliveryProcessor.java:40(Function<MessageEnvelope<EncodedMessage>,HandleResult>),reliability-api/.../IdempotentMessageHandler.java:21- Evidence:
MessagingTransport.register()main 호출 0; 자동 조립 transport는 발행 전용 생성자(KafkaMessagingTransport.java:80-91→KAFKA_CONSUMER_NOT_CONFIGURED);KafkaConsumerRegistrar(645),KafkaBatchConsumerRegistrar, delivery/retry mapper 합쳐 약 2.4k LOC 도달 불가. - Remedy:
MessageHandler<T>하나로;DefaultDeliveryProcessor가 codec registry로 decode; starter-kafka가consumerFactory로 registrar 조립(@ConditionalOnBean(MessageHandler.class)). consume을 범위에서 빼면 handler 3종·registrar를 #1처럼 이동. Size M. - Counter: README(
messaging-spring-boot-starter/README.md:34) "직접 조립" — 예제 없고 계약 3개라 따라갈 수 없음.
- Evidence:
-
[Required][granularity] grpc 18 leaf → 9 leaf — io.grpc import 운영 파일 5개뿐(
grpc-policy4,GrpcServerInterceptorChain)- Evidence:
grpc-client는api "io.grpc:grpc-api"(build.gradle:12) 선언하나 io.grpc import 0;grpc-codegen의 proto-contract 의존(:13),grpc-advanced-edition의 project 의존 3개(:9-11)는 미사용. 실제 의존성 경계는 core-api(0), ledger-jpa(JPA), observability(Micrometer), compat(reactor/SI), starter, testkit. 설계서 §2(2026-08-30-grpc-platform-adaptation-design.md:78-81)도 advanced는 "합쳐도 불변 조건 유지". - Remedy: policy+server+client+discovery+admin →
grpc-runtime; proto-contract+codegen →grpc-contract; advanced 5개 →grpc-advanced, compat 유지. "grpc:* → grpc-advanced:* 금지"는 prefix 두 개로 표현. Size L(이동만) · leaf 9개, phantom edge 5개. - Counter: 원본 31-모듈 계획과의 1:1 대응 — Gradle이 강제하는 규칙은 없음.
- Evidence:
-
[Required][over-abstraction] governance를 운영 코드로 구현 — grpc/advanced main의 gate/guard/matrix/promotion/catalog 약 1,690줄
- Evidence: 인자 없이 상수를 반환하는 메서드 11개 —
GrpcStableBuildInvariant.java:26,GrpcKotlinCompatibilityGate.java:67,GrpcWebCompatibilityGate.java:54,GrpcServletStartupValidator.java:49,GrpcEdition2026Guard.java:18,46,GrpcEdition2024Gate.java:50,59,GrpcResolverSafetyPolicy.java:77,82,GrpcXdsStartupGuard.java:98.GrpcStableModuleCatalog.java는 leaf 목록을 core-api 안에 재기술(registry SSOT 규칙 위반).GrpcRawApiImportRule/GrpcApplicationBoundaryRules(200줄)는 문자열로 ArchUnit 흉내, 자기 테스트에서만. - Remedy: 상수 gate, catalog, invariant,
GrpcAdvancedInfrastructureTestkit삭제; import rule은 ArchUnit으로. Size M · 약 700–1,000 LOC. 1차 N-9(validateAdvancedIsolation)와 겹침. - Counter: 테스트가 "결정을 붙든다" —
return false를 검증하는 테스트는 오타만 막음.
- Evidence: 인자 없이 상수를 반환하는 메서드 11개 —
-
[Required][SRP]
messaging-outbox-jdbc-postgresql이 서로 다른 일 4가지 — vendor 중립 relay 7클래스(약 877), PostgreSQL repository(721), Debezium 4개(약 351, SDK 없음, 참조 0),JdbcAdminOperationJournal(326, 오류 메시지 문자열에서만 언급). leaf 19클래스 중 Spring JDBC import는 3개(Jdbc*); inbox도 6개 중 5개가 stdlib.- Remedy:
messaging-reliability(reliability-api + relay/inbox 로직, stdlib) +messaging-reliability-jdbc-postgresql(Jdbc 3종), Debezium 삭제. Size M · leaf 3→2, 약 350 LOC.
- Remedy:
-
[Required][duplication|pattern]
PublishResult7-인자 생성 11개 파일 28회 — 실제 모양은 rejected/ambiguous/confirmed 3가지.PublishEvidence.ambiguous()가 있는데 7곳이new PublishEvidence(true, MAY_HAVE_BEEN_TRANSMITTED, false, NONE)직접 사용(PublishResults.java:43-67);rejectedLocally4곳 복사(KafkaMessagingTransport.java:200,RabbitMessagingTransport.java:271,PulsarMessagingTransport.java:246,NatsJetStreamTransport.java:263);PulsarPreSendRejection·NatsPreSendRejectionJavadoc만 다름. Remedy:PublishResult.rejected/ambiguous/confirmed정적 factory,PreSendRejection은 transport-spi 하나. Size S–M · 약 200 LOC. -
[Required][duplication] envelope ↔ canonical header 변환 3번 작성 —
KafkaHeaderMapper.java:32-100+KafkaDeliveryMapper.java:66-125,RabbitHeaderMapper.java:31+RabbitDeliveryMapper.java:65-94,DebeziumOutboxEventRouter.java:35(ReservedHeaders 참조 31개). Remedy: core-apiCanonicalEnvelopeHeaders에write(envelope, BiConsumer<String,String>)·read(Function<String,String>); broker mapper는 연결 코드만,RESERVED_HEADER_FORGED규칙 한 곳. Size M · 약 300 LOC. -
[Consider][over-abstraction] outbox port·repository 죽은 표면 —
OutboxRepository.java:36leaseBatch(deprecated, main 0), 4-인자claimBatch·3-인자markAmbiguous오버로드(main 0),JdbcOutboxRepository.java:426-455*Unfenced4개(main 0),:600-721손 JSON 직렬화 약 115줄. Remedy: 메서드 7개 삭제, JSON은 Jackson(starter 런타임에 있음) 또는jsonb_each_text. Size M · 약 250 LOC(purge 오버로드는 1차 M-6). -
[Consider][SRP] starter 조립 구조 —
MessagingCoreAutoConfiguration.java550줄·@Bean28·inline FQN 46줄;BrokerSettings.java:42는 Kafka·Rabbit 20필드 union record인데 broker 중립 core starter에; Blocking/Reactive/Batch facade(약 566 LOC)는 외부 사용 0인데 Reactive 때문에api 'io.projectreactor:reactor-core'(build.gradle:54)가 모든 앱에 노출. Remedy: config/validation, publish pipeline, observability 세 configuration; broker별 필드는 broker starter가Binder로; facade 삭제 또는 reactorcompileOnly. Size M. -
[Consider][over-abstraction] 미사용 API 타입(1차 M-9 목록 외) —
MessagingException서브클래스 23개 중 12개 main 참조 0(Authentication, BrokerUnavailable, Consumer, DeadLetter, HandlerTimeout, HeaderRejected, PublishAmbiguous, PublishRejected, Redrive, RetryExhausted, Routing, SettlementUnknown; 각 약 50줄, (category, retryable)만 다름; 서브클래스별 catch는 1곳);MessageHandler,KafkaTopologyInspector,RabbitRequestReply,ReliableMessagePublisher,InboxRecord구현·참조 0. Remedy: 삭제. Size M · 약 750 LOC. Counter: public surface breaking — 구현·사용처 없음. -
[Consider][pattern]
MessagingCapabilities위치 boolean 12개 —KafkaMessagingTransport.java:62-63new MessagingCapabilities(true, true, …, true), 생성 11곳, main에서 읽는 flag는 12개 중 3개. Remedy:EnumSet<Capability>, 안 읽는 flag 삭제. Size S. -
[Consider][granularity] messaging API leaf 병합 — core-api + schema-api → 1개; admin-api + admin-runtime → 1개. #1·#5와 합치면 기본 빌드 messaging leaf 27 → 14. transport-spi·runtime-core는 bridge 격리 규칙 때문에 유지. Size M.
-
[Consider][reinvention]
GrpcProtoContractValidator(447줄 regex .proto 파서)와grpc-codegen(Buf lint/breaking 재구현, Java import regex) — 근거 "Buf CLI가 없다"(grpc-codegen/build.gradle:8-9); protoc은 Maven artifact, Buf도 Gradle로 받을 수 있음; 실제 stub 생성 0건. Remedy:com.google.protobuf플러그인 + buf를 CI에서, 두 leaf 삭제. Size L · 약 1.1k LOC. 반론: 설계 결정 D5/D6. -
[Consider][structure] 패키지·leaf 이름 불일치, 용어 혼재 —
dev.caskeleton.grpc.resilience/streaming은grpc-policy의 패키지인데grpc-advanced-resilience/-streaming은 leaf 이름;discovery는 반대;grpc-policy에 interceptor·writer·rotation manager 같은 런타임 코드; 지원 등급 이름 4개(CapabilityTier{M1..M3},CompatibilityMatrix.Tier,GrpcCapabilityGrade,GrpcEvidenceGrade). Remedy: #3으로 대부분 해소, 용어 하나로. Size S. -
[Consider][readability] messaging main 주석 30%(9,234/30,446), grpc 17%; "used to / no longer" 78줄(
KafkaConsumerRegistrar6줄), 리뷰 IDMSG-*9곳(MessagingCoreAutoConfiguration.java:370,442,480등); inline FQN 190줄(KafkaConsumerRegistrar31,DefaultBatchMessagePublisher20). Remedy: 이력은 git/ADR, OpenRewriteShortenFullyQualifiedTypeReferences. Size M(기계적). -
[Nit][structure]
dev.caskeleton.messaging.autoconfigure패키지가 leaf 3개에 걸침(package-privateStartupProfileValidation때문); registry의 starter-kafkaallowed_dependencies10개인데 build.gradle은 2개만 사용;KafkaConsumerRegistrar.dispatch75줄(:264).
Cross-module leads (not investigated)
- outbox relay 3개:
application-core/.../PublishPendingOutboxEventsUseCase,.../outbox/v2/PublishNextOutboxDeliveryUseCase, messagingOutboxRelay. - 멱등성 저장소 3개: application idempotency,
grpc-operation-ledger-jpa,messaging-inbox-jdbc. - Kafka producer 경로 2개:
adapter/outbound/messaging-kafkaLegacyKafkaMessagingRootAutoConfiguration(R0) vsKafkaMessagingTransport. - lease/claimBatch:
JpaRecipientLeaseStore.claimBatchvsOutboxRepository.claimBatch. - messaging 기본 off 처리 두 곳:
DisabledMessagingSentinelAutoConfiguration(app-bootstrap) vs starter master switch.
Coverage note
leaf 45개 전부 LOC/파일, 의존성 선언, import, 도달성 계산. 자세히: starter 3종·조립 클래스, transport 4종 publish/classify, outbox/inbox, core-api publish·error·capabilities, grpc starter·core-api·advanced gate, 설계서 §2. rabbit/kafka consumer 내부, grpc-policy streaming 개별 클래스는 이름·크기만.