fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
This commit is contained in:
@@ -32,7 +32,16 @@ Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구
|
||||
- `IntegrationEventDraft`는 canonical event/aggregate/order/correlation identity와 typed payload를
|
||||
보유한다. tenant가 없는 모드도 null 대신 canonical system tenant scope를
|
||||
`AggregateIdentity`에 넣어 dedupe/order identity가 PostgreSQL nullable uniqueness에 기대지
|
||||
않게 한다.
|
||||
않게 한다. 새 event의 event id와 causation id는 정규 소문자 UUIDv7이어야 한다
|
||||
(`IntegrationIdentity.isCanonicalUuidV7`). messaging platform의 `MessageId`가 그것만 바꾸지 않고
|
||||
싣기 때문이다. draft가 거부하므로 그런 id는 업무 트랜잭션 안에서 실패하고, 커밋된 뒤 relay에서
|
||||
DEAD가 되지 않는다(리뷰 2026-11-01 06-06, 재리뷰 2026-11-03 RR-05-04). 저장 문법 `EventId`는
|
||||
이 규칙 전에 쓰인 행을 읽으려고 넓게 남아 있다.
|
||||
- draft는 `IntegrationEventDrafts.draft(...)`로만 만든다. 계약 id·버전·목적지, correlation
|
||||
fallback(요청 값이 `IntegrationIdentity` 문법에 맞지 않으면 event id), tenant 없는 기능의
|
||||
`SINGLE_TENANT_SCOPE`가 거기 한 번 있다. 운영 코드가 생성자를 직접 부르면
|
||||
`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`가 막는다. 식별자 문법·길이는
|
||||
`IntegrationIdentity`가 정본이고, 값을 미리 검사할 때는 `isCanonical(value, bound)`를 부른다.
|
||||
- `IntegrationEventEncoderPort` 뒤의 adapter가 deterministic encoding을 수행하고
|
||||
`ValidatedIntegrationEvent`를 돌려준다. 템플릿의 구현은 `adapter:outbound:support`의
|
||||
`JsonIntegrationEventEncoder`다(envelope v1 + payload record의 결정적 JSON, 선언한 schema hash를
|
||||
@@ -43,9 +52,38 @@ Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구
|
||||
payload/envelope byte limit, sensitivity classification, same-event requeue horizon만 표현한다.
|
||||
physical topic, Kafka cluster/security topology는 deployment binding의 책임이다.
|
||||
|
||||
이 단계의 완성 범위는 **framework-free semantic contract R1**이다. JSON Schema validator와
|
||||
deterministic writer, Kafka ACK producer, PostgreSQL outbox append/relay는 후속 R2 작업이며 여기서
|
||||
구현되었거나 검증됐다고 주장하지 않는다.
|
||||
이 절의 타입은 framework-free semantic contract다. 결정적 writer는 `adapter:outbound:support`의
|
||||
`JsonIntegrationEventEncoder`, outbox append·claim은 `adapter:outbound:persistence-jpa`, relay 조립은
|
||||
`composition:outbox-relay`, 발행은 `adapter:outbound:messaging`의 platform bridge가 맡는다. payload를
|
||||
JSON Schema로 매번 검증하는 validator는 템플릿에 없다(서비스가 encoder bean을 바꿔 둔다).
|
||||
|
||||
### payload version 올리기 (리뷰 2026-11-01 06-10)
|
||||
|
||||
payload schema는 version마다 `contracts/messaging/<contract>/v<N>.schema.json` 파일 하나다. 한 번
|
||||
출시한 version 파일은 고치지 않는다. 이미 그 version으로 쓰인 event가 outbox·broker·DLQ에 남아 있고,
|
||||
소비자는 그 schema로 만들어져 있다. 그래서 schema를 가진 leaf는 출시한 version의 SHA-256을
|
||||
`src/test/resources/contracts/released-payload-schemas.sha256`에 고정하고, testFixtures의
|
||||
`ReleasedPayloadSchemaContract`를 상속한 테스트가 두 가지를 막는다.
|
||||
|
||||
- 출시한 version 파일의 바이트가 바뀌면 실패한다(필드 삭제·타입 변경 같은 깨지는 변경 포함).
|
||||
- 고정되지 않은 version 파일이 있으면 실패한다. 새 version은 manifest에 한 줄을 더하는 순간 출시된다.
|
||||
|
||||
필드를 바꾸거나 지우거나 더하는 변경은 새 version으로 낸다(설계 문서 2026-07-28 §14.4 STRICT_VERSIONED).
|
||||
|
||||
1. 새 version 추가: `v<N+1>.schema.json`, 새 payload record, 새 `IntegrationEventContractContribution`.
|
||||
옛 version의 contribution은 그대로 둔다. encoder catalog는 `(contractId, payloadVersion)`마다 하나라
|
||||
두 version이 함께 등록된다.
|
||||
2. 소비자 배포: 모든 소비자가 v<N>과 v<N+1>을 둘 다 읽게 한다. outbox에 이미 쌓인 v<N> 행은 저장된
|
||||
바이트 그대로 나가므로, 생산자를 바꾼 뒤에도 한동안 두 version이 함께 도착한다.
|
||||
3. 생산자 전환: draft를 v<N+1> contract로 만든다. 이 커밋에서 manifest에 v<N+1> 줄을 더한다.
|
||||
4. 옛 version 제거: outbox·broker·DLQ·archive에 v<N>이 더 남지 않았을 때만 contribution과 파일을 지우고
|
||||
manifest 줄도 지운다. 지우는 줄은 리뷰에서 보이는 변경이다.
|
||||
|
||||
고른 방법과 버린 대안: 출시한 version 파일의 해시 고정(위). 버린 대안 — 직전 version과 새 version의
|
||||
JSON Schema diff로 호환성을 검사하는 fixture: payload schema가 닫혀 있어(`unevaluatedProperties: false`)
|
||||
필드 하나를 더해도 옛 소비자의 검증이 깨지므로, diff는 거의 모든 새 version을 "깨짐"으로 판정한다.
|
||||
설계도 diff heuristic으로 호환성을 주장하지 않기로 했다(§14.4). 외부 schema registry 도입 — 이 템플릿
|
||||
범위에 비해 운영 비용이 크다.
|
||||
|
||||
---
|
||||
|
||||
@@ -367,9 +405,14 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||||
- 발행 성공(`CONFIRMED`) → `inWrite { markPublished }` → `PUBLISHED`.
|
||||
- 확정 거부(`REJECTED_BEFORE_SEND`·`REJECTED_AFTER_BROKER`) → 시도 예산과 무관하게 바로 `markDead`.
|
||||
- 일시적 실패(`AMBIGUOUS`·`REJECTED_RETRYABLE`, 즉 `OutboxPublishOutcome.retryable()`) →
|
||||
시도 예산을 쓰지 않고 항상 `markDeferred(nextAttemptAt)`(FAILED 전이 + 미룬 시도로 기록). broker 정지·종료 중·permit 부족·
|
||||
시도 예산을 쓰지 않고 항상 `markDeferred(nextAttemptAt, failureCode)`(FAILED 전이 + 미룬 시도로 기록). broker 정지·종료 중·permit 부족·
|
||||
credential 교체는 모든 행을 같은 방식으로 실패시키고 저절로 끝나므로, 예산을 쓰게 하면 몇 분
|
||||
장애가 aggregate 머리마다 DEAD 행을 남긴다(2026-11-01 리뷰 06-01·06-03).
|
||||
장애가 aggregate 머리마다 DEAD 행을 남긴다(2026-11-01 리뷰 06-01·06-03). 대가로 끝이 없다 —
|
||||
저절로 풀리지 않는 원인(진짜 credential 오류, Kafka adapter가 이름을 모르는 broker 거부)이면
|
||||
영원히 재시도된다. 그래서 모든 실패 전이는 원인 코드를 함께 적는다(`OutboxPublishAttempt.failureCode`:
|
||||
publisher가 붙인 코드, 없으면 결과 이름, 던진 예외면 그 타입 이름 → 행 `last_failure_code`, 보고
|
||||
`failureCode`). 오래 미룬 행은 `OutboxStorePort.longRetries`로 세고, 운영자는 그 행을 `PARKED`로
|
||||
보류할 수 있다(재리뷰 2026-11-03 RR-05-03, publish-failed runbook §4.1).
|
||||
- 발행 예외(`RuntimeException`, adapter가 분류하지 못한 실패): `budgetedAttemptCount() >=
|
||||
maxAttempts` 면 `markDead`, 아니면 `markFailed(nextAttemptAt)`. 예산은 이 경우에만 쓴다 —
|
||||
payload 자체 결함일 수 있는 실패가 aggregate를 영원히 막지 않게 하는 장치다.
|
||||
@@ -411,6 +454,10 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||||
`@RequiresPermission("outbox:relay")`는 D4 규칙을 통과시키려고 붙인 장식이었다(빈이 아니라 한
|
||||
번도 검사되지 않았고, 빈이었다면 매 tick 거부됐다). ArchUnit D4는 `@SystemInvoked`를 권한 선언
|
||||
대신 받고, `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`이 둘을 함께 다는 것을 막는다.
|
||||
면제의 전제(전송 계층이 닿지 않는다)도 코드가 지킨다: `@SystemInvoked` 빈은
|
||||
`PermissionEnforcementGuard`가 기동을 실패시키고, inbound adapter가 그 클래스에 의존하면
|
||||
`INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 실패시킨다(review 2026-11-03
|
||||
RR-01-02).
|
||||
|
||||
### OutboxBackoffPolicy
|
||||
|
||||
@@ -439,7 +486,9 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||||
|
||||
- `OutboxEventStatus` — 행 상태 머신(D5). `PENDING → IN_FLIGHT → {PUBLISHED | FAILED | DEAD}`,
|
||||
`FAILED → IN_FLIGHT`(재claim), `IN_FLIGHT 고아 → IN_FLIGHT`(I6). `DEAD` 는 FIFO 형제를 막는다 —
|
||||
같은 aggregate 의 뒤 행 claim 을 차단하므로 runbook 개입이 필요하다.
|
||||
같은 aggregate 의 뒤 행 claim 을 차단하므로 runbook 개입이 필요하다. `PARKED` 는 운영자만 만든다
|
||||
(`FAILED → PARKED`, runbook SQL): claim 되지 않고 DEAD 처럼 FIFO 형제를 막는다. 재개는
|
||||
`PARKED → FAILED`, 버리기는 `PARKED → PUBLISHED`. relay 의 어떤 전이도 `PARKED` 로 가거나 나오지 않는다.
|
||||
- append 는 `OutboxAppendPort.append(ValidatedIntegrationEvent)` 하나다(2026-09-28, 소유자 결정 7).
|
||||
use case 가 `IntegrationEventDraft` 를 만들고 `IntegrationEventEncoderPort` 로 encode 한 뒤 같은
|
||||
write 트랜잭션 안에서 append 한다. consumer 의 중복 제거 키는 event id 다.
|
||||
@@ -448,11 +497,11 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||||
다음 실패 시 dead-letter 여부를 결정한다. 옛 `OutboxEvent`/`NewOutboxEvent`/`LegacyOutboxAppendPort`
|
||||
(free-text payload 모델)는 삭제됐다.
|
||||
- `OutboxRelayResult` — relay 한 사이클의 결과. `claimedCount` + per-event outcome 목록. 내부
|
||||
`Outcome` enum 이 `OutboxEventStatus` 의 5값을 재사용하지 않고 4값(PUBLISHED/FAILED/DEAD/
|
||||
STALE — 마지막은 lease 를 잃어 결과를 쓰지 못한 경우)을
|
||||
`Outcome` enum 이 `OutboxEventStatus` 를 재사용하지 않고 5값(PUBLISHED/FAILED/DEAD/STALE/RELEASED —
|
||||
STALE 은 lease 를 잃어 결과를 쓰지 못한 경우, RELEASED 는 멈추는 relay 가 쓰지 않은 claim 을 놓은 경우)을
|
||||
따로 두는 이유: relay 관점은 "이번 실행에서 무슨 일이 있었나" 이지 "행의 현재 영속 상태" 가
|
||||
아니다(후자는 store 가 5값으로 추적). 별도 enum 이 메트릭·스케줄러 로깅 consumer 에게 relay API
|
||||
를 깔끔하게 유지해 준다.
|
||||
아니다(후자는 store 가 `OutboxEventStatus` 로 추적). 이 5값이 `outbox.publisher.published.total` 의
|
||||
`outcome` label 이다(`docs/registries/metrics.yaml`, 계약 테스트가 비교).
|
||||
- `PublishPendingOutboxEventsCommand` — relay 커맨드 마커. 스케줄러 구동이라 caller 파라미터가
|
||||
없고, 모든 운영 파라미터는 생성 시점에 주입된다(IdempotencyExecutor 선례). 호출마다 새 인스턴스를
|
||||
만들 필요가 없게 `INSTANCE` 싱글톤을 제공한다.
|
||||
@@ -522,40 +571,12 @@ application 계층은 락 획득/해제 계약만 알고, 실제 구현은 adapt
|
||||
|
||||
---
|
||||
|
||||
## Notification R1
|
||||
## 알림 타입은 이 leaf에 없다 (application-notification)
|
||||
|
||||
R1 오케스트레이션 타입(`dev.caskeleton.application.notification` 직속, production consumer 0건)은
|
||||
2026-09-25에 삭제했다. canonical은 `..notification.platform..`이다(NOTIF-ADR-005). 직속 패키지에는
|
||||
단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`만 남았다.
|
||||
|
||||
## 알림 포트 (notification)
|
||||
|
||||
### NotificationPort
|
||||
|
||||
- named channel + 논리 route 로 알림을 전달하는 outbound 포트.
|
||||
- 2-인자 overload 는 관례적 `"default"` route 를 쓰는 편의 메서드다. adapter 가
|
||||
`app.notification.routes.<channel>.<route>` 에서 구체 provider 목록을 해석하므로, application
|
||||
계층은 provider 선택과 분리된다(호출부에 provider id 가 없다).
|
||||
- fan-out(route 당 여러 provider)은 adapter 관심사다. 어떤 provider 가 실패하면 adapter 가
|
||||
fail-open 정책(관측만, 전파 안 함)을 적용하고, route 자체가 unbound 면
|
||||
`AdapterDisabledException("notification", ...)` 을 던진다.
|
||||
- outbound 포트의 `*Port` 접미사 명명 규칙을 따른다(CLAUDE.md).
|
||||
|
||||
### Notification (값 객체)
|
||||
|
||||
- transport-중립 알림 값으로, routing target 과 내용만 운반한다.
|
||||
- **절대 logger(또는 dependency logger)에 넘기면 안 된다** — recipient 주소·body 가 로그 라인에
|
||||
닿을 수 없게 하기 위함(PII 계약).
|
||||
- `adapter-outbound` 에서 `application-core` 로 옮긴 이유: 유스케이스가 adapter 타입을 import 하지
|
||||
않고도 알림을 만들어 `NotificationPort` 로 전달할 수 있게 하기 위함(clean-architecture
|
||||
HARD-STOP #3).
|
||||
|
||||
### Channel
|
||||
|
||||
- 알림 채널 판별자(`EMAIL`/`SLACK`). provider 와 독립적으로 전달 매체를 식별한다.
|
||||
- caller 가 `Channel` 값(compile-safe) + 논리 route 이름을 `NotificationPort` 에 넘기면 adapter 가
|
||||
`app.notification.routes.<channel>.<route>` 로 provider 목록을 해석한다 — 도메인은 provider
|
||||
세부를 들여다보지 않는다(HARD-STOP #4).
|
||||
`NotificationPort`·`Notification`·`NotificationChannel`과 알림 플랫폼(`..notification.platform..`,
|
||||
NOTIF-ADR-005)은 leaf `application-notification`(`src/application-notification`)이 소유한다. 패키지
|
||||
이름이 `dev.caskeleton.application.notification`이라 이 leaf의 것처럼 보일 뿐이다. 설명과 규칙은 그
|
||||
leaf의 코드 Javadoc과 `docs/notification/`이 정본이다. R1 오케스트레이션 타입은 2026-09-25에 삭제했다.
|
||||
|
||||
---
|
||||
|
||||
@@ -593,9 +614,11 @@ R1 오케스트레이션 타입(`dev.caskeleton.application.notification` 직속
|
||||
벽시계(예전 샘플의 epoch 마이크로초)는 인스턴스 사이 시계 차이·NTP 되돌림·같은 마이크로초 두 건에서
|
||||
커밋 순서와 달라진다.
|
||||
- 계약(`OutboxAggregateSequenceContract`, fake `InMemoryOutboxAggregateSequences`와 JPA 구현이 공유):
|
||||
aggregate마다 1부터 하나씩 커지고 aggregate끼리 독립이다. JPA 구현(`JpaOutboxStore`, V21
|
||||
`outbox_aggregate_sequence`)은 counter row lock으로 같은 aggregate 쓰기를 직렬화하고, 기존 outbox
|
||||
row의 최대 번호 다음에서 시작하며, reaper가 row를 지워도 번호를 다시 쓰지 않는다. 같은
|
||||
aggregate마다 첫 번호부터 하나씩 커지고, 첫 쓰기 두 개가 겹쳐도 둘 다 성공하며, aggregate끼리
|
||||
독립이다. 첫 번호는 구현마다 다르다(fake는 1). JPA 구현(`JpaOutboxStore`, V21
|
||||
`outbox_aggregate_sequence`)은 counter row lock으로 같은 aggregate 쓰기를 직렬화하고, 남은 outbox
|
||||
row의 최대 번호와 V21이 기록한 floor(적용 시각의 epoch 마이크로초) 중 큰 값 다음에서 시작한다.
|
||||
그래서 reaper가 지웠거나 identity가 바뀐 aggregate도 옛 벽시계 번호보다 뒤에서 시작한다. 같은
|
||||
`(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` 두 번째 append는 V21
|
||||
유일 인덱스가 append 시점에 거부한다.
|
||||
- aggregate가 자체 version 열(낙관적 락)을 가지면 그 값을 써도 된다. 이 포트는 counter가 없는
|
||||
|
||||
Reference in New Issue
Block a user