Files
clean-architecture-backend-…/docs/jpa/repository-adaptation.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

16 KiB

JPA 관계형 영속성 플랫폼 — 저장소 대응 계약

설계 출처: docs/design/2026-08-11-jpa-persistence-platform-design.md Stable 계획 출처: docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md Experimental 계획 출처: docs/history/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md

설계 패키지는 자기 대응 규칙을 스스로 밝힌다(§3.2). 가정한 패키지 경로와 Gradle 구조는 실제 Backend Skeleton 저장소를 받지 못해서 둔 명시적 구현 가정이다. 구현 전에 공개 계약과 정책 의미는 지키면서 경로를 저장소의 기존 관례와 root 패키지에 맞춘다.

이 파일은 그 대응을 어떻게 했는지 적는 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트 소유뿐이다. 공개 계약, 정책 순서, 재시도 의미, 오류 의미는 명세대로 구현했다.

1. 모듈 배치가 다른 이유

계획은 modules/jpa/ 아래 Stable Gradle 프로젝트 18개와 modules/jpa-experimental/ 아래 Experimental 프로젝트 7개를 둔 새 라이브러리를 가정한다. 이 저장소는 fail-closed registry(gradle/modules.json)를 가진 Clean Architecture 템플릿이다. settings.gradle은 registry를 읽고 검증한 뒤 등록된 프로젝트만 들이고, verifyCleanArchitectureDependencies가 그 밖의 edge를 막는다. leaf 목록은 registry가 정한다. 계획의 Gradle 프로젝트를 새로 만들면 AGENTS.md의 HARD-STOP #5를 어긴다.

그래서 계획의 라이브러리 모듈은 등록 leaf :adapter:outbound:persistence-jpa 안의 패키지 경계가 된다. 예외는 이 저장소 자신의 규칙에서 나온 둘이다. HTTP 클라이언트 플랫폼에 이미 한 것과 같은 대응이다(docs/httpclient/repository-adaptation.md).

계획 모듈 저장소 위치 이유
jpa-spring-boot-starter :adapter:outbound:persistence-jpa (…persistence.autoconfigure, …persistence.startup) 관계형 영속성은 빌드 한 줄로 고르는 capability 모듈이다(AGENTS.md capability 규칙). leaf가 자기 auto-configuration, 기동 검증, actuator view, 내보내는 설정을 등록하고, 기본 조립은 그것을 싣지 않는다. 그 port 위의 use case 조립(outbox relay)은 composition:outbox-relay에 있다.
jpa-testkit, jpa-testkit-postgresql, jpa-testkit-migration, jpa-testkit-queryplan :adapter:outbound:persistence-jpa src/testFixtures/java/**/testkit 계획은 운영 모듈이 testkit에 의존하는 것을 막는다. 의존을 test 설정에만 선언한 source set이 새 Gradle 프로젝트 없이 같은 보장을 주고, 여러 lane이 그것을 쓴다.

패키지 경계는 JpaModuleBoundaryTest가 강제한다. 운영 root의 바로 아래 자식 패키지를 닫힌 목록으로 들고, 그 목록을 트리와 정확히 같은지 비교하고, 관찰한 최상위 edge를 모두 선언한 것과 대조하고, cycle을 거부한다.

이력: 전에는 문서의 주장이 테스트보다 강했다. 목록은 패키지 13개였는데 트리에는 22개가 있어서, 아홉 개(audit, config, failure, fileserver, h2, idempotency, lock, notification, outbox)를 아무것도 다스리지 않았고 transaction → postgresql / postgresql → transaction cycle이 통과했다. 둘 다 닫았다. 새 패키지가 빠져서 초록이 되지 않게 막는 것은 목록의 정확히-같음 검사다.

알려진 빈틈. 목록은 최상위 패키지를 다스린다. 한 최상위 패키지 안의 하위 패키지 edge는 확인하지 않는다. 리뷰 JPA-023의 목표 트리(capability/* 배치)는 구현하지 않았다. 알림 설정 facade가 그쪽으로 가는 첫걸음이다.

2. 패키지 대응

root 패키지: io.backend.skeleton.jpa → dev.caskeleton.adapter.outbound.persistence.

계획 모듈 계획 패키지 저장소 패키지
jpa-core-api …jpa.api (+ .capability, .error, .query, .transaction) dev.caskeleton.adapter.outbound.persistence.api (+ 같은 하위 패키지)
jpa-transaction …jpa.transaction …persistence.transaction
jpa-spring-data …jpa.springdata …persistence.springdata
jpa-querydsl …jpa.querydsl …persistence.querydsl
jpa-hibernate …jpa.hibernate (+ .batch, .bulk, .stateless) …persistence.hibernate (+ 같은 하위 패키지)
jpa-postgresql …jpa.postgresql (+ .error, .lock, .constraint, .json, .array, .range, .write) …persistence.postgresql (+ .write를 뺀 같은 하위 패키지. .write는 2026-09-25에 지움)
jpa-postgresql-copy …jpa.postgresql.copy …persistence.postgresql.copy
jpa-migration-flyway …jpa.migration …persistence.migration
jpa-auditing …jpa.auditing 없음 — 지웠다. …persistence.audit.AuditableEntity가 유일한 감사 방식이다
jpa-envers …jpa.envers …persistence.envers
jpa-cache-hibernate …jpa.cache …persistence.cache
jpa-observability …jpa.observation …persistence.observation
jpa-security …jpa.security …persistence.security
jpa-spring-boot-starter …jpa.autoconfigure …persistence.autoconfigure, …persistence.startup
jpa-testkit* …jpa.testkit (+ .id, .mapping, .lifecycle, .query, .fetch, .postgresql, .migration, .queryplan, .failure, .pool, .release) …persistence.testkit (+ 같은 하위 패키지), testFixtures source set
jpa-experimental/* …jpa.experimental (+ .tenant, .rls, .schema, .database, .replica, .next) …persistence.experimental (+ .next를 뺀 같은 하위 패키지. .next는 2026-09-25에 지움)

이미 있던 …persistence.transaction과 …persistence.postgresql 패키지는 이 leaf의 TransactionPort 구현과 PostgreSQL vendor 조립을 이미 가지고 있다. 플랫폼 타입은 더하기만 했다. 이름을 바꾸거나 옮기거나 대신한 기존 타입은 없고, 기존 이름과 부딪치는 계획 타입도 없다.

3. 테스트 suite 대응

계획은 JVM 테스트 suite 일곱을 선언한다(test, integrationTest, contractTest, migrationTest, failureTest, performanceTest, compatibilityTest). 이 leaf는 이미 Docker를 쓰는 postgresqlIntegrationTest source set을 가지고, 그 readiness Gradle 태스크는 이 leaf의 build.gradle에 strict lane으로 등록돼 있다. JpaReadinessRegistryTest가 readiness card를 그 lane과 대조한다(build-tools의 verifyJpaReadinessRegistry를 대신했다).

계획 suite 저장소 lane
test src/test — 밀폐된 unit lane, ./gradlew :adapter:outbound:persistence-jpa:test
contractTest, integrationTest, migrationTest, failureTest, compatibilityTest src/postgresqlIntegrationTest — 실제 PostgreSQL 컨테이너. jpaPlatform* Gradle 태스크가 고른다
performanceTest src/jpaPlatformPerformanceTest — 풀과 REQUIRES_NEW 연결 동작. jpaPlatformPoolContractTest가 돌리고, check에는 절대 들어가지 않는다. source set은 계획의 이름을 그대로 쓴다. 이 lane은 측정하지 않고 동작을 단언하며, 그로부터 어떤 성능 수치도 주장하지 않는다.

Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 leaf의 기존 관례 PostgreSqlReadinessSupport.assertDockerAvailable()과 같다.

4. 그 밖에 일부러 바꾼 것

계획의 가정 저장소의 실제 대응
Gradle Kotlin DSL, build-logic convention plugin, jpa-library-conventions.gradle.kts Groovy DSL, build-logic의 convention plugin(Java로 씀: spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, -Werror, 파일 하나에 타입 하나), LockMode.STRICT 의존성 잠금 source set과 의존성은 src/adapter/outbound/persistence-jpa/build.gradle에 선언했다. gradle.lockfile은 resolveAndLockAll --write-locks로 다시 만들었다.
Spring Boot 4.1 의존성 관리, Spring Data JPA 4.1 저장소 기준선은 gradle/libs.versions.toml의 Spring Boot 버전이다 버전은 저장소 BOM에서 물려받고 모듈마다 고정하지 않는다. 계획이 요구하는 그대로다("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM").
Hibernate ORM 7.4가 Stable provider 저장소 BOM이 org.hibernate.orm:hibernate-core:7.1.8.Final을 푼다(release registry의 stable-tested-baseline) 설계의 선언 Stable provider 기준선은 HibernateProviderPolicy에서 7.4로 남는다. 런타임 provider 버전은 Hibernate 자신에게서 읽어 보고한다. collection-fetch-pagination gate는 BOM이 푸는 provider에서 돌고, HibernateProviderPolicy.driftsFromDeclaredBaseline()이 차이를 초록 검사 뒤에 숨기지 않고 드러낸다.
PostgreSQL 16·17·18 Stable matrix 컨테이너 이미지는 gradle/container-images.properties에 digest로 고정한다 PostgreSqlVersion이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 -Pjpa.matrix.versions=<major>로 고른다. 계약 suite(JpaPlatformContractSupport.start())는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 StablePostgreSqlMatrixContractTest뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다.
settings.gradle.kts 모듈 등록 fail-closed registry registry는 바꾸지 않았다. leaf 신원, Gradle path, 허용 의존은 그대로다.
infra/jpa/{postgres,roles,toxiproxy} 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 docs/jpa/security.md로 옮겼다.
docs/jpa/**, docs/adr/ADR-JPA-*, JPA workflow 저장소가 이미 docs/와 workflow 폴더를 가진다 같은 저장소 상대 경로에 만들었다. JPA 전용 workflow 파일은 2026-11-08 단계 파일 셋(.gitea/workflows)의 job으로 접었다.
릴리스를 막는 집계 persistence-jpa/release/release-registry.json 위의 jpaReleaseQualification(persistence-jpa build.gradle). .gitea/workflows/release.yml의 jpa-release-gate job이 PostgreSQL major마다 돌린다 registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다.
task마다 git add + git commit AGENTS.md: 커밋 정책은 human-only다. 에이전트는 stage, commit, amend, push를 하지 않는다 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다.
Querydsl을 선택 모듈 의존성으로 Querydsl은 이 저장소의 의존성 묶음에 없다 querydsl은 계획의 계약대로 구현하되 Querydsl 타입을 compileOnly 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다.
Hibernate Envers를 모듈 의존성으로 Envers는 이 저장소의 의존성 묶음에 없다 Querydsl과 같다. compileOnly + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다.
계획의 build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt build-logic은 있지만 Kotlin source set은 없다 패키지 경계는 이 leaf의 JpaModuleBoundaryTest(§1)가, leaf 경계는 verifyCleanArchitectureDependencies와 :app-bootstrap:architectureTest가 gradle/modules.json을 정본으로 강제한다.
PostgreSqlRuntimeRoleVerifierIntegrationTest (Task 45) 보안 lane은 모듈마다의 integrationTest가 아니라 이 leaf의 suite 하나다 PostgreSqlSecurityContractTest(tag jpa-security)가 실제 서버의 실제 제한 역할에 대고 PostgreSqlRuntimeRoleVerifier.verify와 .requireSafe를 돌린다.
JpaSafetyProperties, JpaDataSourceProperties NamingConventionTest는 모든 @ConfigurationProperties 타입 이름이 Settings나 Policy로 끝나기를 요구한다 JpaSafetySettings로 이름을 바꿨다. 묶는 속성 prefix와 모든 칸은 그대로이고 클래스 이름만 이 저장소 관례로 옮겼다. JpaDataSourceProperties에 해당하는 설정 클래스는 지금 없다. datasource 검사는 JpaDataSourceProfileValidator가 한다.

의존 방향을 지키려고 옮긴 타입

계획의 모듈 지도는 jpa-core-api가 다른 플랫폼 모듈에 의존하는 것을 막는다. 설계가 하위 모듈에 둔 값 타입 셋을 core 계약이 쓰므로, 여기서는 core에 둔다. 셋 다 framework 의존이 없는 순수 값이라 옮기는 비용이 없다. 대안인, core 계약이 어댑터 패키지를 import하는 것은 모듈 지도가 지키려는 경계를 깬다.

타입 계획 모듈 저장소 패키지 쓰는 곳
TransactionCompletionEvidence jpa-transaction …persistence.api.transaction TransactionCompletionUnknownException(설계서 §17.3이 칸의 타입을 정한다)
ConstraintCode jpa-postgresql …persistence.api.error ConstraintViolationDetails(설계서 §22.4)
SqlExceptionSqlStateResolver jpa-transaction …persistence.api.error PostgreSQL translator들

ArchUnit 규칙 묶음(JpaArchitectureRules, EntityMappingCondition, EntityExposureCondition)은 …persistence.security 운영 코드가 아니라 testFixtures source set에 둔다. ArchUnit은 테스트 라이브러리다. 규칙 묶음을 main에 두면 테스트에서만 도는 코드를 위해 모든 배포의 런타임 classpath에 그것을 끌고 간다.

실제 서버에서 계약이 찾은 것

설계의 규칙 둘이 조금 틀리게 적혀 있었고, 그것을 보여 준 것은 컨테이너 lane이다. 설계서 본문은 여전히 옛 내용이라 여기에 기록한다.

  • §17.2 커밋 모호함은 SQLSTATE class 08만이 아니다. 커밋이 진행 중인 backend에 pg_terminate_backend를 하면 연결 class 상태가 아니라 57P01(admin_shutdown)을 보고하고, 그것이 도착할 때 커밋 기록은 이미 WAL에 있을 수 있다. 이것을 담았던 classifier(CommitFailureClassifier)는 2026-09-25에 두 번째 트랜잭션 엔진과 함께 지웠다. PostgreSqlConcurrencyFailureContractTest가 여전히 주입 지점을 고정한다.
  • schema-per-tenant 상태는 실행 결과로 짐작하지 말고 다시 읽어야 한다. MigrateResult의 대상 버전은 이미 최신이던 tenant에서 비어 있어서, 그것을 기록하면 부분 rollout 중 마이그레이션한 tenant를 안 한 것으로 보고했다. SchemaTenantMigrationOrchestrator가 이제 tenant의 schema history에서 적용된 버전을 읽는다.

5. 설계에서 바뀌지 않은 것

  • 도메인이 Entity, Embeddable, Repository, Query, 인덱스 요구, lock·soft-delete·감사 정책을 가진다. GenericRepository<T, ID>도, Spring Data CRUD를 다시 구현한 것도 없다.
  • Application Service가 트랜잭션 경계를 가진다. OSIV는 모든 런타임 profile에서 false다.
  • TransactionCompletionUnknownException은 늘 completionUnknown=true, retryable=false를 보고하고, 자동으로 다시 시도하지 않는다. 맞추기가 처리한다.
  • 재시도는 use case 전체를 새 트랜잭션과 새 Persistence Context에서 다시 돌린다.
  • SQLSTATE 분류는 구조적이다(40001, 40003, 40P01, 23505, 23503, 23514, 55P03). 지역화된 메시지 문장을 파싱하지 않는다.
  • 운영 스키마 변경의 정본은 Flyway다. Hibernate는 검증만 하고, ddl-auto는 배포된 스키마를 바꾸지 않는다.
  • CREATE INDEX CONCURRENTLY에는 명시적인 비트랜잭션 마이그레이션 표시가 필요하다.
  • 메트릭 label과 보통 로그에는 SQL 파라미터, entity ID, tenant ID, PII를 싣지 않는다.
  • Experimental 기능(multi-tenancy, RLS, schema·database tenancy, read replica)은 배포가 직접 만드는 라이브러리 코드이고 Stable 조립에 들어가지 않는다. JPA 4, Hibernate 8, PostgreSQL 19는 기능이 아니라 NOT_EXECUTABLE probe다. backend.jpa.experimental.* 스위치는 아무것도 읽지 않아서 2026-09-25에 지웠다.