- 결정 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>
89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# 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:**
|
|
|
|
1. Take the idempotency key or operation id of the failed request.
|
|
2. Check the idempotency record for that key.
|
|
3. Check the business row the use case would have written.
|
|
4. Check the outbox for a corresponding event.
|
|
5. If all three agree the write happened, stop — the request succeeded.
|
|
6. If all three agree it did not, the use case may be re-run.
|
|
7. 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.
|
|
|
|
1. Group the failures by operation. A single operation dominating means a hot row or an
|
|
inconsistent lock order.
|
|
2. For deadlocks, check whether two operations take the same rows in opposite orders — that is a
|
|
code fix, not a tuning one.
|
|
3. For serialization failures under `SERIALIZABLE`, confirm the isolation is actually required.
|
|
|
|
## Pool exhaustion
|
|
|
|
**Signal:** connection acquisition timeouts; `PoolMeasurement.pending` non-zero.
|
|
|
|
1. Check `REQUIRES_NEW` usage. It takes a second connection while pinning the first, so the pool
|
|
must satisfy `(threads x (1 + depth)) + 1`.
|
|
2. Check for streaming outside a bounded scope — a `Stream` returned past the transaction holds its
|
|
connection until the pool notices.
|
|
3. 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.
|
|
|
|
1. Read the reported error codes (the messages are deliberately not propagated).
|
|
2. `CHECKSUM_MISMATCH` — an applied migration was edited afterwards. Find which change is missing
|
|
from this database. **Do not run `repair`**: it rewrites history to match the scripts, which
|
|
resolves the symptom by deleting the evidence.
|
|
3. `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.
|
|
|
|
```sql
|
|
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.
|
|
|
|
1. Confirm no build is currently running. An in-progress build looks identical in the catalog.
|
|
2. Run `DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;` outside a migration.
|
|
3. 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.
|