Files
clean-architecture-backend-…/src/shared-contract/CLAUDE.md
T
DongHyeonka 6e992970ca fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다
문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).

방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
  만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
  금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
  늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.

위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).

검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).

Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
2026-11-05 21:26:50 +09:00

4.5 KiB

shared-contract — skeleton-wide operational contract

Registered identity

  • Module ID: shared-contract
  • Gradle path: :shared-contract
  • Focused test (derived from Gradle path): ./gradlew :shared-contract:test --console=plain
  • Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
  • Registry SSOT: src/config/architecture/modules.json.

Package root: dev.caskeleton.shared.

Design decisions previously kept as code comments (error-code classification, response envelope shape, metric cardinality bounds, tracing seam, domain-context propagation) live in README.md. This file stays the SSOT for module rules.

Responsibility

  • Response envelope (response/Envelope, response/ApiError, response/BulkEnvelope, response/BulkItemResult).
  • Error code contract (error/ApiErrorCode interface, error/OperationalError enum, error/ApiErrorCarrier) and the one client-facing wording table (error/ClientErrorMessages, Korean, one message per Category, used by every transport).
  • Cross-cutting mapper sentinel (error/MappingException).
  • Request value contract (request/Patch).
  • Tracing contract types (tracing/TraceParent, tracing/SpanErrorRecorder) — W3C traceparent value type and the span-error-recording seam (feature-distributed-tracing-contract; the OTel tracer runtime is a fork-activated seam, so these stay Java-stdlib-only).
  • Stdlib helpers every leaf used to copy (review X2-P1-5, X2-P1-4b, X1-#9): digest/Sha256 (the SHA-256 digest value and the one MessageDigest.getInstance("SHA-256")), digest/HmacSha256 (sign and constant-time verify), retry/Backoff (capped exponential ceiling; "full jitter" means U[0, ceiling] and nothing else). Vendored messaging:* and the optional gRPC build do not depend on this module and keep their own copies; each family's CLAUDE.md says why (a different product, MSG-023). Every template leaf that needs one of these has the shared-contract edge and uses them instead of copying: identifier, persistence-mongo, application-objectstorage and redis-sdk took the edge for exactly this (review 2026-11-01 01-11, decision in the review README §15), each with a test that pins its output to a vector computed outside the JVM.
  • observability/MdcKeys: the snake_case MDC key names (registry docs/registries/mdc-keys.yaml) every transport puts a request's correlation under — web, GraphQL, STOMP and gRPC alike.
  • ratelimit/: the provider-neutral edge rate-limit port (EdgeRateLimitPort) and its value types, between the web edge and the Redis adapter (README 「ratelimit」).
  • security/Permission: the resource:action permission value AuthorizationPort is asked about (README 「security」).
  • concurrency/: the domain-context propagation port and its ThreadLocal default (README 「concurrency」).
  • runtime/RuntimeEnvironment: the one runtime-profile vocabulary every leaf answers "is this production?" with.
  • metrics/ForbiddenMetricTags: the high-cardinality tag keys no metric may carry.
  • These are the module's packages and the only ones it may have: ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES refuses a class in any other package below dev.caskeleton.shared or directly in the root, which holds only its package-info. A new contract package goes into that test's SHARED_CONTRACT_PACKAGES and into this list together; SharedContractPackageRuleTest fails when SHARED_CONTRACT_PACKAGES and the module's packages differ.
  • Registry-rule mirrors read only by contract tests live in testFixtures, not main: metrics/MetricNaming, metrics/CardinalityBounds, metrics/AlertSeverity, tracing/BaggageAllowlist. Move one to main only when production code consumes it.
  • Generic messaging envelope schema resources under contracts/messaging/envelope/. They own transport-neutral envelope metadata only; feature payload schemas remain in their feature-owner modules. Resource presence is not runtime discovery or registration.

Allowed

  • Java standard library ONLY. No Spring, no Jackson, no JPA imports.

Forbidden

  • business/domain concept (domain error codes belong in the consuming module).
  • framework imports (HTTP status is expressed as transport-neutral int; the web module maps it).
  • claiming Draft 2020-12 validator compatibility before the messaging adapter's Task 6 validator qualification exists.

Test

cd src
./gradlew :shared-contract:test