Files
clean-architecture-backend-…/docs/jpa/transaction-guide.md
T
donghyeon-kaandClaude Opus 5.5 0579935746 review-followup Wave 3 라운드 3(P28·P29): fileserver use case·file:* 권한, 보안 파일 primitive 공용화, jvm-test-suite
- 결정 32: fileserver transport 연산 21개를 `port.in` use case로, 쓰기·읽기에 `file:*` 권한(소유자·tenant 정책은 유지),
  inbound 서비스 이름 `*UseCase`, port 구현 이름 `<Tech><Port>` 규칙(S2-#13b, 24개)
- 디렉터리 descriptor 파일 primitive를 `adapter:outbound:support`로(S4-lead-2 일부 — fileserver는 번역만),
  persistence-fileserver를 scan·클래스별 조건 대신 명시적 `@Bean` 설정으로(S2-#8a 일부), `FileVerifier`를 adapter로
- 호출자 0인 `poster.image-attached` 이벤트 삭제, SES SDK client를 레지스트리 종료 때 close, fileserver migration V1–V5 고정
- P29: auxiliary 레인 → Gradle `jvm-test-suite`(BUILD-O3-5, build-logic 16,768 → 5,851줄), redis-sdk가 runtime을 api로(P22-new-3)
- 통합: JPA API surface 기준선 재승인(이름 규칙 변경), migration lane에 V19 반영, messaging 통합 테스트가 jar 안 migration 목록 조회(ORCH-new-5)
- P28·P29 에이전트가 세션 재시작으로 중단 — 커밋된 것만 합치고 결과 파일은 오케스트레이터가 확정, S6-#10a는 P30으로

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck architectureCheck verifyPublicPathSnapshot
:app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest
:sample-portfolio:systemTest integrationCheck · -p build-logic test · -p optional-platforms ci · releaseCheck qualificationBootJar 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 14:54:06 +09:00

2.7 KiB

Transaction Guide

Design §15-§20. What owns a transaction, what may be retried, and what must never be.

The application service owns the boundary

Repository adapters do not open transactions. The use case does, through TransactionPort, because the unit of work is a business decision and only the use case knows where it starts and ends. SpringTransaction is the only implementation: one pre-built TransactionTemplate per mode over Spring's PlatformTransactionManager, every mode pinned to READ_COMMITTED.

Call Propagation When
inWrite REQUIRED, read-write command default
inRootWrite REQUIRED, read-write, rejects an ambient transaction before running orchestration that must prove a physical commit
inRead REQUIRED, read-only query default
inNew REQUIRES_NEW, read-write outbox / audit / compensation that must commit on its own

Open Session In View is off in every runtime profile. It is on by default in Spring Boot, which is why JpaDangerousConfigurationGuard fails startup rather than trusting configuration review.

REQUIRES_NEW acquires a second physical connection while pinning the first, so the pool must satisfy:

maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1

Nothing is retried by the port

SpringTransaction runs the action once. A failure rolls back and propagates, translated to the shared persistence error codes where the SQLSTATE is known. A caller that decides to retry must re-run the whole use case in a new transaction — never re-issue one statement — because an optimistic conflict or a serialization failure means the state the attempt computed against is no longer the committed state.

A second engine with named policies, deadline budgets, transaction-local timeouts and automatic full-transaction retry (SpringJpaTransactionExecutor, FullTransactionRetryCoordinator, PolicyTransactionPort) existed next to this one and was removed on 2026-09-25. Its last commit is recorded in docs/capability-status.md.

Completion unknown

A connection can break while a commit is in flight; the server may have committed and only the acknowledgement was lost. TransactionCompletionUnknownException is never retried, and the type system enforces it: JpaFailureContext refuses to represent a retryable completion-unknown failure. The port itself retries nothing, so such a commit surfaces to the caller as a failure exactly once (PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried).

Recovery is reconciliation, not retry:

check the idempotency record -> check the business row -> check the outbox
                             -> still undetermined? escalate