Files
clean-architecture-backend-…/docs/jpa/repository-adaptation.md
T
DongHyeonka 8251616767 fix(docs): 지우고 옮긴 경로에 문서 검사 예외와 참조를 맞춘다
문제: 구조 정리와 문서 체계를 합친 트리에서 `python3 scripts/check-docs.py`가
23건으로 실패한다. 문서 검사는 구조 정리 전 트리를 기준선으로 만들어졌다.
- 예외 목록이 지운 파일(infra 아래 README 6개, 샘플 CLAUDE.md의 언어·숫자
  두 줄)을 가리킨다.
- 옮긴 문서 넷(infra/keycloak, infra/redis-sdk, infra/redis-sdk/acl,
  src/optional-platforms의 README)은 옛 예외 줄이 낡고 새 경로가 영어 문서로
  걸린다.
- `docs/jpa/security.md`는 구조 정리가 한국어 절(운영 DB 조건)을 더해 더는
  영어 문서로 판정되지 않는다.
- 살아 있는 문서 넷이 지운 `infra/`, `src/sample-portfolio`,
  `src/Dockerfile.sample`을 인라인 코드로 가리킨다.

고친 방법: 문서 체계 인계 노트의 「구조 정리와 합칠 때」를 따른다.
- 지운 파일과 더는 걸리지 않는 줄 아홉은 예외 목록에서 지운다.
- 옮긴 문서 넷은 예외 줄의 경로를 새 경로로 바꾸고, FROZEN에서 옛 줄의
  지문을 새 줄의 지문으로 바꾼다. FROZEN에 새로 더한 지문은 없다.
- 결정 색인의 두 행은 지운 경로 대신 지운 목록이 있는 업그레이드 안내
  B-49·B-50을 가리킨다(docs/README.md 「지운 경로는 upgrade/에 쓴다」).
- JPA 적응 표의 「저장소 현실」 칸과 리뷰 기준 18행에서 지운 경로를 뺀다.
- docs/README.md의 검사 설명은 지운 infra 폴더를 인라인 코드 밖에서 적는다.
  검사는 지운 infra/ 아래 경로를 계속 본다(다시 나타나면 낡은 참조다).

버린 대안: 결정 색인을 참조 검사 제외 목록(HISTORY_HOLDERS)에 넣기. 색인은
지금 결정을 찾는 곳이라 낡은 경로를 걸러야 한다.

위험·한계: `docs/jpa/security.md`는 영어 본문이 그대로 남아 있지만 판정에서
빠졌다. 번역 단계의 대상 목록에서 빠지지 않게 인계 노트에 적는다.

검증(노트북, 이 트리): check-docs.py rc=0(언어 걸림 173·예외 173, 참조 걸림 7·
예외 7, 숫자 걸림 28·예외 28), `python3 -m unittest discover -s scripts/tests`
42개 통과, check-work-docs.py rc=0.
2026-11-07 15:03:56 +09:00

15 KiB

JPA Relational Persistence Platform — Repository Adaptation Contract

Design source: docs/design/2026-08-11-jpa-persistence-platform-design.md Stable plan source: docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md Experimental plan source: docs/history/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md

The design package states its own adaptation rule (§3.2): the assumed package paths and Gradle structure are explicit implementation assumptions made because the real Backend Skeleton repository was not supplied. Before implementing, paths are adjusted to the repository's existing conventions and root package while the public contracts and policy semantics are preserved.

This file is the single record of how that mapping was performed. Only paths, build DSL, and composition-root ownership changed. Public contracts, policy order, retry semantics, and error semantics are implemented as specified.

1. Why the module layout differs

The plan assumes a greenfield library with 18 Stable Gradle projects under modules/jpa/ plus 7 Experimental projects under modules/jpa-experimental/. This repository is a Clean Architecture template whose fail-closed registry (src/config/architecture/modules.json, enforced by src/settings.gradle and verifyCleanArchitectureDependencies) declares exactly 19 leaf identities, and src/settings.gradle throws when the registry does not contain exactly 19 modules. Creating 25 more Gradle projects would violate HARD-STOP #5 in AGENTS.md.

Therefore the plan's library modules become package boundaries inside the registered leaf :adapter:outbound:persistence-jpa, with two exceptions driven by this repository's own rules. This is the same adaptation already applied to the HTTP client platform (docs/httpclient/repository-adaptation.md).

Plan module Repository home Reason
jpa-spring-boot-starter :adapter:outbound:persistence-jpa (…persistence.autoconfigure, …persistence.startup) Relational persistence is a capability module selected by one build line (AGENTS.md capability rules): the leaf registers its own auto-configuration, startup validation, actuator view and shipped settings, and the default composition does not carry it. Use-case assembly over its ports (the outbox relay) stays in app-bootstrap.
jpa-testkit, jpa-testkit-postgresql, jpa-testkit-migration, jpa-testkit-queryplan :adapter:outbound:persistence-jpa src/testkit/java/**/testkit The plan forbids production modules depending on the testkit. A source set whose dependencies are declared only on test configurations gives the same guarantee without a new Gradle project, and more than one lane consumes it.

The package boundary is enforced by JpaModuleBoundaryTest. It holds a closed catalog of the production root's direct child packages, compares that catalog against the tree for exact equality, checks every observed top-level edge against the declared ones, and rejects cycles.

This used to be a stronger claim than the test. The catalog listed thirteen packages while the tree held twenty-two, so nine — audit, config, failure, fileserver, h2, idempotency, lock, notification, outbox — were governed by nothing, and a transaction → postgresql / postgresql → transaction cycle passed. Both are closed now, and the catalog's exact-equality check is what keeps a new package from being green by omission.

Known gap. The catalog governs top-level packages. Sub-package edges inside one top-level package are not checked, and the target tree in the review's JPA-023 (a capability/* layout) is not implemented — the notification configuration facade is the first step toward it.

2. Package mapping

Root package: io.backend.skeleton.jpa → dev.caskeleton.adapter.outbound.persistence.

Plan module Plan package Repository package
jpa-core-api …jpa.api (+ .capability, .error, .query, .transaction) dev.caskeleton.adapter.outbound.persistence.api (+ same subpackages)
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 (+ same subpackages)
jpa-postgresql …jpa.postgresql (+ .error, .lock, .constraint, .json, .array, .range, .write) …persistence.postgresql (+ same subpackages except .write, removed 2026-09-25)
jpa-postgresql-copy …jpa.postgresql.copy …persistence.postgresql.copy
jpa-migration-flyway …jpa.migration …persistence.migration
jpa-auditing …jpa.auditing none — removed; …persistence.audit.AuditableEntity is the one audit mechanism
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 (+ same subpackages), testkit source set
jpa-experimental/* …jpa.experimental (+ .tenant, .rls, .schema, .database, .replica, .next) …persistence.experimental (+ same subpackages except .next, removed 2026-09-25)

The existing …persistence.transaction and …persistence.postgresql packages already hold this leaf's TransactionPort implementation and PostgreSQL vendor composition. The platform types are additive: no existing type was renamed, moved, or replaced, and no plan type collides with an existing name.

3. Test-suite mapping

The plan declares seven JVM test suites (test, integrationTest, contractTest, migrationTest, failureTest, performanceTest, compatibilityTest). This leaf already owns a Docker-backed postgresqlIntegrationTest source set and its readiness Gradle tasks are registered as strict lanes in this leaf's build.gradle; JpaReadinessRegistryTest holds the readiness cards to those lanes (it replaced the build-tools verifyJpaReadinessRegistry).

Plan suite Repository lane
test src/test — hermetic unit lane, ./gradlew :adapter:outbound:persistence-jpa:test
contractTest, integrationTest, migrationTest, failureTest, compatibilityTest src/postgresqlIntegrationTest — real PostgreSQL containers; selected by the jpaPlatform* Gradle tasks
performanceTest src/jpaPlatformPerformanceTest — pool and REQUIRES_NEW connection behaviour, run by jpaPlatformPoolContractTest; never part of check. The source set keeps the plan's name; the lane asserts behaviour rather than measuring, and no numeric performance bound is claimed anywhere from it.

Docker-dependent lanes fail closed rather than skipping, matching the existing PostgreSqlReadinessSupport.assertDockerAvailable() convention in this leaf.

4. Other deliberate substitutions

Plan assumption Repository reality Adaptation
Gradle Kotlin DSL, build-logic convention plugin, jpa-library-conventions.gradle.kts Groovy DSL, root src/build.gradle conventions (spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, -Werror, one-type-per-file), LockMode.STRICT dependency locking Source sets and dependencies declared in src/adapter/outbound/persistence-jpa/build.gradle; gradle.lockfile regenerated with resolveAndLockAll --write-locks.
Spring Boot 4.1 dependency management, Spring Data JPA 4.1 Repository baseline is Spring Boot 4.0.8 Versions are inherited from the repository BOM and never pinned per module, exactly as the plan requires ("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM").
Hibernate ORM 7.4 is the Stable provider Boot 4.0.0 resolves org.hibernate.orm:hibernate-core:7.1.8.Final The declared Stable provider baseline of the design stays 7.4 in HibernateProviderPolicy; the runtime provider version is read from Hibernate itself and reported. The collection-fetch-pagination gate runs against whatever provider the BOM resolves, and HibernateProviderPolicy.driftsFromDeclaredBaseline() makes the difference visible instead of hiding it behind a green check.
PostgreSQL 16·17·18 Stable matrix This leaf's existing evidence image is postgres:16-alpine PostgreSqlVersion declares exactly PG 16, 17, 18. The default lane runs the repository's existing 16 image; 17 and 18 are selected by -Pjpa.matrix.versions=16,17,18, and an unknown or empty selection is an error rather than a skip.
settings.gradle.kts module registration Fail-closed 19-leaf registry No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged.
infra/jpa/{postgres,roles,toxiproxy} 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 docs/jpa/security.md로 옮겼다.
docs/jpa/**, docs/adr/ADR-JPA-*, .github/workflows/jpa-*.yml Repository already owns docs/ and .github/workflows/ Created at the same repository-relative paths.
release blocking aggregate jpaReleaseQualification (persistence-jpa build.gradle) over persistence-jpa/release/release-registry.json, run per PostgreSQL major by the jpa-release-gate job in .github/workflows/release.yml The registry names the blocking lanes; Gradle defines how each lane runs; CI only schedules the matrix.
Per-task git add + git commit AGENTS.md: commit policy is human-only; agents do not stage, commit, amend, or push Implementation is delivered unstaged. This is the only plan step intentionally not executed, and it is recorded here.
Querydsl as an optional module dependency Querydsl is not part of this repository's dependency set querydsl is implemented against the plan's contracts with the Querydsl types kept behind compileOnly, so the Stable runtime classpath never carries Querydsl and a deployment opting in adds the artifact itself.
Hibernate Envers as a module dependency Envers is not part of this repository's dependency set Same treatment as Querydsl: compileOnly + explicit opt-in, matching the plan's "Envers is opt-in and never enabled by a global base class".
build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt There is no build-logic project and no Kotlin source set; module boundaries are enforced by the registry itself verifyCleanArchitectureDependencies plus :app-bootstrap:architectureTest assert the same property against src/config/architecture/modules.json, which is the authority the plan's test would have had to duplicate.
PostgreSqlRuntimeRoleVerifierIntegrationTest (Task 45) The security lane is one suite in this leaf rather than a per-module integrationTest PostgreSqlSecurityContractTest (tag jpa-security) exercises PostgreSqlRuntimeRoleVerifier.verify and .requireSafe against a real restricted role on a real server.
JpaSafetyProperties, JpaDataSourceProperties NamingConventionTest requires every @ConfigurationProperties type to end in Settings or Policy Renamed to JpaSafetySettings and JpaDataSourceSettings. The bound property prefixes and every field are unchanged; only the class names move to this repository's convention.

The plan's module map forbids jpa-core-api from depending on any other platform module. Three value-only types the design places in a downstream module are consumed by a core contract, so they live in the core here instead. Each is a pure value with no framework dependency, so the relocation costs nothing and the alternative — a core contract importing an adapter package — would break the boundary the module map exists to hold.

Type Plan module Repository package Consumed by
TransactionCompletionEvidence jpa-transaction …persistence.api.transaction TransactionCompletionUnknownException (design §17.3 types the field)
ConstraintCode jpa-postgresql …persistence.api.error ConstraintViolationDetails (design §22.4)
SqlExceptionSqlStateResolver jpa-transaction …persistence.api.error the PostgreSQL translators

The ArchUnit rule pack (JpaArchitectureRules, EntityMappingCondition, EntityExposureCondition) is placed in the testkit source set rather than in …persistence.security production code. ArchUnit is a test library; putting the rule pack in main would drag it onto every deployment's runtime classpath to serve code that only ever runs in a test.

Findings the contracts produced against a real server

Two of the design's rules turned out to be stated slightly wrong, and the container lanes are what showed it. Both are recorded here because the design text still reads the old way.

  • §17.2 commit ambiguity is not only SQLSTATE class 08. pg_terminate_backend on a backend with a commit in flight reports 57P01 (admin_shutdown), not a connection-class state — and the commit record may already be in the WAL when it arrives. The classifier that encoded this (CommitFailureClassifier) was removed with the second transaction engine on 2026-09-25; PostgreSqlConcurrencyFailureContractTest still pins the injection points.
  • Schema-per-tenant status must be read back, not inferred from the run. MigrateResult's target version is empty for a tenant that was already current, so recording it reported migrated tenants as unmigrated during a partial rollout. SchemaTenantMigrationOrchestrator now reads the applied version from the tenant's schema history.

5. What is unchanged from the design

  • Domain owns Entity, Embeddable, Repository, Query, index requirements, lock/soft-delete/audit policy. No GenericRepository<T, ID> and no Spring Data CRUD re-implementation exists.
  • Application Service owns the transaction boundary; OSIV is false in every runtime profile.
  • TransactionCompletionUnknownException always reports completionUnknown=true, retryable=false, and is never automatically retried — reconciliation handles it.
  • Retry re-executes the whole use case in a new transaction and a new Persistence Context.
  • SQLSTATE classification is structural (40001, 40003, 40P01, 23505, 23503, 23514, 55P03) and never parses localized message text.
  • Flyway is the source of truth for production schema change; Hibernate only validates; ddl-auto never mutates a deployed schema.
  • CREATE INDEX CONCURRENTLY requires an explicit non-transactional migration marker.
  • Metric labels and ordinary logs never carry SQL parameters, entity IDs, tenant IDs, or PII.
  • Experimental features (multi-tenancy, RLS, schema/database tenancy, read replica) are library code a deployment constructs itself and never enter the Stable composition. JPA 4, Hibernate 8 and PostgreSQL 19 are NOT_EXECUTABLE probes, not features. The backend.jpa.experimental.* flags were removed on 2026-09-25: nothing read them.