review-followup Wave 3 라운드 2(P18): outbox canonical 통일, composition 모듈, legacy Kafka seam 삭제
- 결정 7: `LegacyOutboxAppendPort`·legacy 저장 모델·relay·Kafka R0 seam 삭제, 템플릿 JSON encoder(`JsonIntegrationEventEncoder`),
durable operation·sample 이벤트가 `OutboxAppendPort` + encoder로, persistence-jpa V19(pre-canonical 미발행 row 거부)
- 결정 3: outbox relay·멱등성 executor 조립을 `composition:outbox-relay`·`composition:idempotency`로,
sample이 복사한 bootstrap 인프라를 `composition:service-runtime`으로(sample `SampleIdempotencyConfig` 복사본 삭제)
- persistence-jpa outbox·멱등성 패키지 feature 기준 이동, messaging outbox·inbox leaf를 reliability / reliability-jdbc-postgresql로
- messaging outbox header를 jsonb로(P18-new-1 — `\`로 끝나는 값이 다음 header를 삼키던 결함)
- 통합(충돌 22건): P25 A-10c(전략 선택 설정 삭제)를 service-runtime `DomainContextConfig`에 적용, P25 startup 예외 통합을
composition 설정 테스트에, P25 `CommandUseCase.handle` 이름을 PG 통합 테스트에, P15 `EventJson`은 호출자 0이 되어 삭제
- root CLAUDE.md의 legacy seam 문장 수정(P18-new-2)
검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,OutboxAppendTransactional,OutboxConcurrentRelay,OutboxRowLifecycle}IntegrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest --continue 통과(700 task)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
25de288ab4
commit
423a29c46f
@@ -33,8 +33,10 @@ Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구
|
||||
보유한다. tenant가 없는 모드도 null 대신 canonical system tenant scope를
|
||||
`AggregateIdentity`에 넣어 dedupe/order identity가 PostgreSQL nullable uniqueness에 기대지
|
||||
않게 한다.
|
||||
- `IntegrationEventEncoderPort` 뒤의 adapter가 deterministic encoding과 schema validation을
|
||||
수행하고 `ValidatedIntegrationEvent`를 돌려준다. 결과는 logical destination, exact US-ASCII
|
||||
- `IntegrationEventEncoderPort` 뒤의 adapter가 deterministic encoding을 수행하고
|
||||
`ValidatedIntegrationEvent`를 돌려준다. 템플릿의 구현은 `adapter:outbound:support`의
|
||||
`JsonIntegrationEventEncoder`다(envelope v1 + payload record의 결정적 JSON, 선언한 schema hash를
|
||||
classpath 파일과 대조). 결과는 logical destination, exact US-ASCII
|
||||
partition key, exact encoded envelope bytes, schema/envelope hash와 catalog/binding revision을
|
||||
defensive copy로 보존한다.
|
||||
- `ContractDescriptor`는 owner module, logical destination, serializer ID, ordering requirement,
|
||||
@@ -372,7 +374,7 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||||
못한다.
|
||||
- **안전한 allowlist report**: `OutboxRelayFailureReport`는
|
||||
`code/eventId/eventType/aggregateId/correlationId/attemptCount/nextAttemptAt/cause`만 가진다.
|
||||
payload, idempotency key, whole `OutboxEvent`, severity/template, arbitrary map은 타입 수준에서
|
||||
payload, envelope bytes, whole `ClaimedOutboxEvent`, severity/template, arbitrary map은 타입 수준에서
|
||||
전달할 수 없다. retry factory는 `OUTBOX_PUBLISH_FAILED`와 필수 `nextAttemptAt`, dead factory는
|
||||
`OUTBOX_DEAD_LETTER`와 null retry time을 고정한다.
|
||||
- **상태 갱신 실패는 시끄럽게 전파한다**: 발행 성공 후의 `markPublished` 실패는 store/인프라
|
||||
@@ -406,17 +408,18 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||||
업데이트와 **함께만** 바꾼다.
|
||||
- 지수 계산은 overflow 방지를 위해 `2^30` 에서 cap 한다(`2^30 × 30s > 30년` 이라 안전).
|
||||
|
||||
### outbox 값/상태 타입 (Status · Event · NewOutboxEvent · RelayResult · Command)
|
||||
### outbox 값/상태 타입 (Status · ClaimedOutboxEvent · RelayResult · Command)
|
||||
|
||||
- `OutboxEventStatus` — 행 상태 머신(D5). `PENDING → IN_FLIGHT → {PUBLISHED | FAILED | DEAD}`,
|
||||
`FAILED → IN_FLIGHT`(재claim), `IN_FLIGHT 고아 → IN_FLIGHT`(I6). `DEAD` 는 FIFO 형제를 막는다 —
|
||||
같은 aggregate 의 뒤 행 claim 을 차단하므로 runbook 개입이 필요하다.
|
||||
- `OutboxEvent` — `claimBatch` 가 반환하는 claim-result 읽기 모델. `NewOutboxEvent` 필드 + 현재
|
||||
`status` + `attemptCount`. relay 가 `attemptCount` 로 다음 실패 시 dead-letter 여부를 결정한다.
|
||||
- `NewOutboxEvent` — caller 의 write 트랜잭션 안에서 append 할 새 이벤트 값 객체. 모든 필드가
|
||||
필수이고 null/blank 면 생성 시점에 거부한다(D12). caller 가 `eventId`·`idempotencyKey` 를
|
||||
공급한다(I12 — outbox core 는 ID 생성에 비의존). 권장 기본값은 `idempotencyKey = eventId`
|
||||
(per-event dedup, CloudEvents-C2).
|
||||
- append 는 `OutboxAppendPort.append(ValidatedIntegrationEvent)` 하나다(2026-09-28, 소유자 결정 7).
|
||||
use case 가 `IntegrationEventDraft` 를 만들고 `IntegrationEventEncoderPort` 로 encode 한 뒤 같은
|
||||
write 트랜잭션 안에서 append 한다. consumer 의 중복 제거 키는 event id 다.
|
||||
- `ClaimedOutboxEvent` — `claimBatch` 가 반환하는 claim-result 읽기 모델. append 된 validated event
|
||||
(저장된 exact envelope bytes 에서 복원) + 현재 `status` + `attemptCount`. relay 가 `attemptCount` 로
|
||||
다음 실패 시 dead-letter 여부를 결정한다. 옛 `OutboxEvent`/`NewOutboxEvent`/`LegacyOutboxAppendPort`
|
||||
(free-text payload 모델)는 삭제됐다.
|
||||
- `OutboxRelayResult` — relay 한 사이클의 결과. `claimedCount` + per-event outcome 목록. 내부
|
||||
`Outcome` enum 이 `OutboxEventStatus` 의 5값을 재사용하지 않고 4값(PUBLISHED/FAILED/DEAD/
|
||||
STALE — 마지막은 lease 를 잃어 결과를 쓰지 못한 경우)을
|
||||
|
||||
Reference in New Issue
Block a user