설계: 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>
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
check the idempotency record -> check the business row -> check the outbox
|
|
-> still undetermined? escalate
|
|
```
|