refactor(application)!: durable operation 타입을 맞추고 안 쓰는 타입을 지운다

durable operation은 core 공통 타입을 따르지 않는다. tenant·principal이
문자열이고 operation id는 controller가 만들며, UUIDv7 파생은 유스케이스가
한다. operation id 문법이 셋인데 이유가 없고, 멱등 판정 셋 중 둘이
executor를 쓰지 않는 이유도 없다. 쓰는 곳 없는 공개 타입이 일곱이고,
final 유스케이스가 둘이며, 포트 둘은 실패 결과를 적지 않았고, 소스
문자열에 NUL 바이트가 있다.

고른 방법: OperationCommand·query·command가 Optional<TenantId>를 받고
SubmitDurableOperationUseCase가 DurableOperationIdFactory로 id를 만든다.
UUIDv7 파생은 IntegrationIdentity로 옮긴다. id 문법 셋은 다니는 곳(URL
경로, header·Redis key, 비교만)이 달라 합치지 않고 OperationId Javadoc에
비교를 적는다. executor를 쓰지 않는 중복 판정 둘은 manual 05에 결정으로
적는다. 안 쓰는 타입은 지우고, final을 떼고, 실패 결과 Javadoc을 쓰고,
NUL은 \u0000으로 쓴다. final을 뗀 유스케이스는 SpotBugs
CT_CONSTRUCTOR_THROW에 걸려, config/spotbugs/exclude.xml의 CGLIB 그룹을
@UseCaseCapability가 붙은 *UseCase class까지 넓힌다(유스케이스 계약이 final을
금한다). 버린 대안: operation id 값 타입 하나로 통일(path
segment가 '/'를 실을 수 있게 되거나 지금 유효한 caller id를 거절한다).

위험·한계: 공개 생성자와 타입이 바뀐다. 파생 서비스가 할 일은
docs/upgrade/2026-11-round9-application.md 1·2행이다(최종 안내에서는 4·7행).

검증: PR 본문의 desktop 결과.

Refs: RR9-05-11, RR9-05-12, RR9-05-13, RR9-05-14, RR9-05-15, RR9-05-16, RR9-05-17, RR9-05-18
BREAKING CHANGE: OperationCommand·GetDurableOperationQuery·CancelDurableOperationCommand의 tenant가 Optional<TenantId>이고 OperationCommand에 operation id 인자가 없다. SubmitDurableOperationUseCase 생성자가 DurableOperationIdFactory를 받는다. ReadConsistency, FileserverSpans, ProviderEventId, NotificationExpiredException, BatchNotificationProviderAdapter, CollapseCapability, ProviderCollapseMapping을 지웠다.
This commit is contained in:
DongHyeonka
2026-11-13 16:37:03 +09:00
parent 141c2a4f6d
commit e60408e931
45 changed files with 324 additions and 278 deletions
+21
View File
@@ -44,6 +44,27 @@ DB 커밋 중 연결 끊김 ─────────────────
executor 조립과 실제 PostgreSQL 저장소 왕복은 `PostgreSqlIdempotencyProviderIntegrationTest`(app-bootstrap
`integrationTest`)다. KEYED 유스케이스를 HTTP부터 끝까지 이은 업무 기능 예는 템플릿에 없다.
### executor를 쓰지 않는 중복 판정 둘 (2026-11-13 결정)
템플릿에는 `IdempotencyExecutor` 말고 중복을 판정하는 곳이 둘 더 있다. 둘 다 일부러 executor로 옮기지 않는다.
executor는 **응답을 다시 돌려주는 기록**이다: HTTP `Idempotency-Key` 헤더로 들어오고, 원본 키 대신 scope digest만
저장하고, 기록은 TTL이 지나면 지운다. 아래 둘은 **업무 행 자체의 정체성**이라 수명과 판정 대상이 다르다.
| 어디 | 키 | 같은 키·같은 요청 | 같은 키·다른 요청 | 수명 |
| --- | --- | --- | --- | --- |
| executor(KEYED 유스케이스) | `Idempotency-Key` 헤더의 scope digest | 저장된 응답 재생 | 422 `IDEMPOTENT_REQUEST_MISMATCH` | TTL |
| 알림 받기(`AcceptNotificationApplicationUseCase`) | 본문의 `idempotencyKey`. 없으면 알림 plan 지문 | 처음 만든 알림의 receipt | `IDEMPOTENCY_CONFLICT`(요청 지문 비교) | 알림 행과 같다 |
| durable operation 제출(`SubmitDurableOperationUseCase`) | 제출 scope(tenant·principal·operation 이름)와 payload 지문 | 처음 받은 operation | 지문이 키에 들어 있어 다른 키다. 새 operation | operation 보존 기간 |
- 알림: 키는 tenant 안에서 같은 알림을 한 번만 만드는 업무 키다. 저장소의 유일 제약이 동시 제출을 막고, 진 쪽은 이긴 행을
읽어 같은 receipt로 수렴한다. 키를 주지 않은 호출자도 중복을 막도록 plan 지문으로 키를 만든다. executor로 옮기면 TTL
뒤 같은 알림을 다시 만들고, 키 없는 호출은 중복을 막지 못한다. 저장한 키 값을 어떻게 다룰지(원본 저장)는 보안 검토
항목이다.
- durable operation: 결정 15·26(서버가 id를 만들고 payload 지문으로 재제출을 판정)이 정한다. capability의 `KEYED`는
"같은 scope·같은 payload로 다시 보내면 같은 작업"이라는 뜻이고, 그 판정은 operation 저장소의 scope 유일성이 한다.
- 새 기능이 이 둘을 따라 할 일은 거의 없다. 클라이언트가 응답을 못 받아 다시 보내는 쓰기는 위 순서대로 executor를 쓴다.
업무 행 자체가 영구히 하나여야 하면(04장 유일 제약) 그 행의 키로 판정한다.
## 클라이언트에게 무엇을 약속하나
| 응답 | 의미 | 클라이언트 행동 |
+1 -6
View File
@@ -2,7 +2,7 @@
# Every top-level public type under the platform packages. Growth is a reviewed change.
# Update only after review with:
# ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange
# types: 364
# types: 359
dev.caskeleton.adapter.outbound.notification.NotificationConfig
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider
@@ -136,7 +136,6 @@ dev.caskeleton.application.notification.platform.api.NotificationPlan
dev.caskeleton.application.notification.platform.api.NotificationReceipt
dev.caskeleton.application.notification.platform.api.NotificationSnapshot
dev.caskeleton.application.notification.platform.api.NotificationVariable
dev.caskeleton.application.notification.platform.api.ProviderEventId
dev.caskeleton.application.notification.platform.api.ProviderId
dev.caskeleton.application.notification.platform.api.ProviderProfileId
dev.caskeleton.application.notification.platform.api.RecipientDeliveryId
@@ -168,7 +167,6 @@ dev.caskeleton.application.notification.platform.api.error.CallbackValidationExc
dev.caskeleton.application.notification.platform.api.error.FailureCategory
dev.caskeleton.application.notification.platform.api.error.IdempotencyConflictException
dev.caskeleton.application.notification.platform.api.error.NotificationException
dev.caskeleton.application.notification.platform.api.error.NotificationExpiredException
dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode
dev.caskeleton.application.notification.platform.api.error.NotificationFailureDescriptor
dev.caskeleton.application.notification.platform.api.error.NotificationValidationException
@@ -329,14 +327,11 @@ dev.caskeleton.application.notification.platform.port.in.SubmitNotificationComma
dev.caskeleton.application.notification.platform.port.in.SubmitNotificationUseCase
dev.caskeleton.application.notification.platform.provider.AttachmentAccessContext
dev.caskeleton.application.notification.platform.provider.AttachmentResolver
dev.caskeleton.application.notification.platform.provider.BatchNotificationProviderAdapter
dev.caskeleton.application.notification.platform.provider.CollapseCapability
dev.caskeleton.application.notification.platform.provider.EvidenceCertainty
dev.caskeleton.application.notification.platform.provider.EvidenceFact
dev.caskeleton.application.notification.platform.provider.NotificationProviderAdapter
dev.caskeleton.application.notification.platform.provider.ProviderCallNotStartedException
dev.caskeleton.application.notification.platform.provider.ProviderCapabilities
dev.caskeleton.application.notification.platform.provider.ProviderCollapseMapping
dev.caskeleton.application.notification.platform.provider.ProviderExecutionEvidence
dev.caskeleton.application.notification.platform.provider.ProviderFailure
dev.caskeleton.application.notification.platform.provider.ProviderProfileSnapshot
@@ -0,0 +1,22 @@
# 업그레이드 안내 — 2026-11 application 구조와 작은 정리
- 범위: durable operation 제출이 id를 유스케이스에서 만들고 tenant를 타입으로 받게 한 변경, 쓰지 않던 공개 타입 일곱의
삭제, 그 밖의 작은 정리. 공개 타입과 생성자가 바뀐 곳이 있다. 아래 표가 그 목록이다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 application 작은 것(B15b) 발견
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 durable operation을 직접 제출·조회하는
서비스와 아래 표의 지운 타입을 쓴 서비스다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | `OperationCommand`에서 operation id 인자를 지우고, tenant를 `Optional<TenantId>`(`application.tenant.TenantId`)로 넘긴다. `GetDurableOperationQuery`·`CancelDurableOperationCommand`의 tenant도 같다. `SubmitDurableOperationUseCase`는 생성자에 `DurableOperationIdFactory`를 받아 id를 직접 만든다. `DurableOperationController`는 id factory를 받지 않는다 | 컴파일이 실패한다 | durable operation을 직접 제출·조회하거나 그 use case를 조립한 서비스 |
| 2 | 쓰는 곳이 없던 공개 타입 일곱을 지웠다: `application.transaction.ReadConsistency`, `FileserverSpans`, 알림의 `ProviderEventId`·`NotificationExpiredException`·`BatchNotificationProviderAdapter`·`CollapseCapability`·`ProviderCollapseMapping` | 그 타입을 쓴 코드는 컴파일이 실패한다. 템플릿 안에는 쓰는 곳이 없었다 | 그 타입을 쓴 서비스 |
## 3. 바뀐 동작 (따라 할 일 없음)
- `GetDurableOperationUseCase`·`PublishPendingOutboxEventsUseCase`가 final이 아니다.
- 알림 받기의 `idempotencyKey`가 `IdempotencyExecutor`와 다른 이유는 manual 05 「executor를 쓰지 않는 중복 판정 둘」에 있다.