Files
clean-architecture-backend-…/docs/adr/ADR-JPA-003-completion-unknown.md
T
DongHyeonka 74be416f93 docs(adr): 아키텍처 결정 기록 본문을 한국어로 옮긴다
문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이
영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로
정했다(design-docs `repo-structure/README.md` 3.2절).

방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약·
현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위
줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드·
명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한
영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을
괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본
지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은
`scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에
남긴다.

위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤
문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다.

검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움,
head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조,
check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:33:54 +09:00

3.7 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택(보완)
  • 작성일: 2026-08-11
  • 요약: commit 결과를 모르는 실패는 재시도하지 않는다는 결정이다. 2026-09-25 보완이 있다.
  • 현재 정본: docs/jpa/transaction-guide.md

ADR-JPA-003 — 완료를 모름은 절대 재시도하지 않는다

  • 상태: 채택. 2026-09-25 보완 — TransactionCompletionResolver, CommitFailureClassifier, 재시도 엔진을 지웠다. 유일한 트랜잭션 엔진인 SpringTransactionPort가 아무것도 재시도하지 않으므로 불변식이 지켜진다. 아래 강제 절도 그에 맞게 고쳤다.
  • 날짜: 2026-08-11
  • 설계: §17

배경

커밋이 진행 중일 때 연결이 끊길 수 있다. 서버가 커밋했을 수도 있고, 확인 응답만 잃었을 수도 있다. driver는 둘을 구별하지 못한다.

결정

TransactionCompletionUnknownException은 자동이든 아니든 절대 재시도하지 않는다. 트랜잭션 단계가 COMMITTING인 동안 본 실패에서만, 그리고 SQLSTATE 40003, 연결 class(08*) 상태, 전송 끊김에 대해서만 만든다. 회복은 도메인별 맞춰 보기다.

결과

커밋됐을지 모르는 쓰기를 재시도하는 것이 이 플랫폼이 할 수 있는 가장 해로운 일이다: 중복 결제, 중복 주문, 두 번 깎기. 실패가 일시적인 것이 아니라 알 수 없는 것이라서, 그것을 안전하게 만드는 예산이나 backoff는 없다.

불변식은 정책만이 아니라 타입 수준에서 강제한다. JpaFailureContext는 재시도할 수 있는 completion-unknown 문맥을 만들기를 거절하고, 예외는 무엇을 받든 안전한 factory로 자기 문맥을 다시 만든다. 그래서 나중의 정책 결함이 안전하지 않은 재시도를 낳을 수 없다 — 그것에 필요한 값이 존재하지 않는다.

규칙은 반대 방향으로도 일부러 좁다. 모든 연결 실패를 completion-unknown으로 분류하면 보통의 pool 고갈과 서버 재시작이 맞춰 보기 queue로 밀려 들어가고, 그것은 운영자에게 그 queue를 읽지 않고 비우도록 길들인다 — 그러면 중요했던 항목 하나가 나머지와 함께 지워진다.

비용은 도메인이 resolver를 줘야 한다는 것이다. 플랫폼은 할 수 없다: 어떤 멱등성 레코드, 업무 행, outbox 항목이 쓰기가 일어났음을 증명하는지는 도메인만 안다.

강제

운영 경로: SpringTransaction은 자기가 시작한 쓰기 트랜잭션에서 action이 돌아온 때를 기록한다. 그 뒤의 실패는 PersistenceExceptionTranslator#translateCommitFailure를 거치고, 그것이 08*, 40003, vendor 종료 상태 (SqlStateErrorMapping#commitOutcomeUnknownStates, PostgreSQL 57P01/57P02), 전송 끊김에 대해 이 예외를 만든다. 커밋 안의 Hibernate flush는 COMMIT 자체와 나뉘지 않으므로, 그 flush 중에 잃은 연결도 모름으로 알린다 — 안전한 쪽이다. review 04-01(2026-11-01) 전까지는 아무것도 이 예외를 만들지 않았고, 커밋 단계의 08*가 재시도할 수 있는 DB_UNAVAILABLE로 호출자에게 닿았다.

JpaFailureContextTest, SpringTransactionTest, PersistenceExceptionTranslatorTest, PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried (DB_COMPLETION_UNKNOWN을 단언한다. jpa-failure lane, 곧 릴리스 gate completion-unknown-no-retry이기도 하다).