- 결정 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>
3.7 KiB
JPA Platform Runbooks
Operator procedures for the failures this platform is designed to surface rather than hide.
A transaction reported completion unknown
Signal: a write use case failed with a commit-phase error (connection lost, 57P01, class
08) from TransactionPort.
What it means: the commit may or may not have happened. It is not a rollback.
Do not re-run the use case. That is what the platform refused to do automatically, for the same reason.
Procedure:
- Take the idempotency key or operation id of the failed request.
- Check the idempotency record for that key.
- Check the business row the use case would have written.
- Check the outbox for a corresponding event.
- If all three agree the write happened, stop — the request succeeded.
- If all three agree it did not, the use case may be re-run.
- If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome; guessing is not.
Deadlock or serialization rate rising
Signal: DB_DEADLOCK / serialization failures rising in the persistence error codes.
SpringTransaction does not retry, so each one reaches the caller.
- Group the failures by operation. A single operation dominating means a hot row or an inconsistent lock order.
- For deadlocks, check whether two operations take the same rows in opposite orders — that is a code fix, not a tuning one.
- For serialization failures under
SERIALIZABLE, confirm the isolation is actually required.
Pool exhaustion
Signal: connection acquisition timeouts; PoolMeasurement.pending non-zero.
- Check
REQUIRES_NEWusage. It takes a second connection while pinning the first, so the pool must satisfy(threads x (1 + depth)) + 1. - Check for streaming outside a bounded scope — a
Streamreturned past the transaction holds its connection until the pool notices. - Check for external calls inside a DB transaction. The design forbids them precisely because an HTTP timeout then holds a connection for its whole duration.
Flyway validation failed at startup
The deployment is running against a schema it was not built for. It failed closed, which is correct.
- Read the reported error codes (the messages are deliberately not propagated).
CHECKSUM_MISMATCH— an applied migration was edited afterwards. Find which change is missing from this database. Do not runrepair: it rewrites history to match the scripts, which resolves the symptom by deleting the evidence.MISSING_SCRIPT— a migration applied here is not in this build. Usually a rollback to an older artifact.
An invalid index exists
Signal: this query returns rows.
select n.nspname || '.' || i.relname as invalid_index
from pg_index x
join pg_class i on i.oid = x.indexrelid
join pg_namespace n on n.oid = i.relnamespace
where not x.indisvalid;
A concurrent build failed. The index is ignored by the planner and maintained by every write.
- Confirm no build is currently running. An in-progress build looks identical in the catalog.
- Run
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;outside a migration. - Re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to drop an index another instance was about to finish building.
The runtime role failed verification
Startup refused because the runtime credential holds CREATE, or search_path contains an
unapproved schema.
This is not a false positive to be worked around. Re-provision from
infra/jpa/roles/runtime-roles.sql; the application's credential having DDL is the condition that
makes every other schema guarantee unenforceable.