- 결정 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>
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. `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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
check the idempotency record -> check the business row -> check the outbox
|
|
-> still undetermined? escalate
|
|
```
|