Files
clean-architecture-backend-…/docs/jpa/transaction-guide.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +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. SpringTransactionPort 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

SpringTransactionPort 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