문제: 구조 정리와 문서 체계를 합친 트리에서 `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.
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. |
Types relocated to keep the dependency direction legal
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_backendon a backend with a commit in flight reports57P01(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;PostgreSqlConcurrencyFailureContractTeststill 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.SchemaTenantMigrationOrchestratornow 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.
TransactionCompletionUnknownExceptionalways reportscompletionUnknown=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-autonever mutates a deployed schema. CREATE INDEX CONCURRENTLYrequires 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_EXECUTABLEprobes, not features. Thebackend.jpa.experimental.*flags were removed on 2026-09-25: nothing read them.