Files
clean-architecture-backend-…/docs/jpa/transaction-guide.md
T
DongHyeonka 34565130e0 fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다
문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를
모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중
끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을
DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와
wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이
기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를
한 번도 돌리지 않았다.

방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택:
- 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은
  쓰기가 하나 늘어 버림).
- 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를
  트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림).
- 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가).
- 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는
  web Jackson mixin으로 생략(shared-contract는 stdlib only).
- 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로.
- strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다.
발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다.

위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지
않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다.
이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다
(다음 커밋에서 대체 이미지로 해결).

검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지
pull 거부). -p optional-platforms ci integrationCheck, performanceCheck,
releaseCheck(-PgitRevision) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절
BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은
audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true,
Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
2026-11-03 19:52: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#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried).

Recovery is reconciliation, not retry:

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