pr / done (pull_request) Canceled after 0s
시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기, 알림 claim·발송·lease 회복·맞추기·provider event replay는 capability도 트랜잭션 선언도 없는 서비스를 worker가 바로 부르고, 그 worker와 조립은 outbound adapter 안에 있다. 알림 운영자 연산 넷은 permission 없이 서비스 하나에 모여 있고 재시도 시각은 상수다. web stream bridge는 outbound가 구현한 replay 포트를 바로 읽는다. fileserver 관리 HTTP 기본값은 controller가 정한다. 고른 방법: 시스템 쓰기는 @SystemInvoked 유스케이스로 나누고 composition worker 설정이 new로 만든다(bean 아님). 알림 worker와 fileserver 정리 조립은 composition으로 옮기고, 맞추기의 재시도·포기 시점은 유스케이스가 정한다. 운영자 연산은 platform.admin의 유스케이스 클래스 넷과 notification-admin:* permission이다(port.in 인터페이스는 port.in과 admin의 cycle을 만들어 두지 않는다). replay 읽기는 조회 유스케이스 둘을 거치고 포트는 LiveEventReplayQueryPort로 이름을 바꾼다. 아키텍처 규칙 둘: 사용자 전송은 저장·id 포트를 쥐지 못하고, inbound는 application 서비스·coordinator를 interface로도 쥐지 못한다. 재시도 시각은 설정, 관리 기본값은 command 팩터리다. 재시도 시각의 규칙은 policy의 값 RetryTiming 하나가 갖고 설정은 그 값을 만든다. retry·routing 값들은 서버가 만드는 값이라 잘못된 값을 IllegalStateException으로 거절한다(manual 06). 모듈 기본값이 role notification-admin에 운영자 permission 넷을 준다(fileserver의 ROLE_FILE_ADMIN과 같다). 버린 대안: 서비스에 @UseCaseCapability만 달기(사용자와 시스템이 같은 진입점을 나눠 써서 권한 규칙이 막지 못한다), 운영자 서비스 삭제, 설정에서 policy를 만들어 버리며 검증하기(규칙이 바뀐 policy bean과 상관없이 남는다). 위험·한계: 공개 타입·생성자·bean 이름·아키텍처 규칙이 바뀐다. 파생 서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1~3·5·6행이다. claim·fence 커밋 위에 쌓았다. 검증: PR 본문의 desktop 결과. Refs: RR9-05-06, RR9-05-07, RR9-05-08, RR9-05-10, RR9-05-19 BREAKING CHANGE: NotificationAdminService·NotificationAdminApplicationService가 없어지고 운영자 연산은 platform.admin의 RedriveDeliveryUseCase 등이다(permission notification-admin:*). 알림 worker가 composition:notification-platform으로 옮기고 ReconciliationJobWorker·ProviderEventReplayWorker는 유스케이스가 됐다. MessagingReplayBridge 생성자가 조회 유스케이스를 받고 LiveEventReplayPort는 LiveEventReplayQueryPort다. 사용자 전송이 저장·id 포트나 application 서비스 interface를 쥐면 architectureTest가 실패한다. 운영자 요청 record 이름이 *Request로 바뀌고 DefaultNotificationRetryPolicy 생성자가 RetryTiming을 받는다. RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult가 잘못된 값에 IllegalStateException을 던진다.
8.5 KiB
8.5 KiB
업그레이드 안내 — 2026-11 application 구조와 작은 정리
- 범위: 시스템이 부르는 쓰기를
@SystemInvoked유스케이스로 나누고, 알림 worker와 fileserver 정리 서비스 조립을 composition으로 옮기고, 알림 운영자 연산을 유스케이스 넷으로 나누고, replay 읽기와 durable operation 제출을 유스케이스로 거치게 한 변경. 쓰지 않던 공개 타입 일곱을 지웠다. 공개 타입과 생성자가 바뀐 곳이 있다. 아래 표가 그 목록이다. - 근거: 2026-11-12 전체 리뷰(
docs/reviews/2026-11-12-round9-review/)의 application 구조(B15a)와 작은 것(B15b) 발견
1. 누가 읽나
이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 알림 운영자 연산이나 알림 worker bean을
직접 쓴 서비스, MessagingReplayBridge로 stream을 다시 보내는 서비스, durable operation을 직접 제출하는 서비스,
사용자 전송(web·GraphQL·gRPC·WebSocket) 클래스에서 저장 포트를 직접 쥐는 서비스다.
2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
|---|---|---|---|
| 1 | NotificationAdminService·NotificationAdminApplicationService가 없어졌다. 운영자 연산은 platform.admin의 유스케이스 클래스 RedriveDeliveryUseCase·ReconcileDeliveriesUseCase·ChangeSuppressionUseCase·ChangeProviderStateUseCase를 주입받아 handle(new …Command(request, actor))로 부른다(command도 platform.admin). 운영자 요청 record의 이름이 바뀌었다: RedriveCommand→RedriveRequest, ReconcileCommand→ReconcileRequest, SuppressCommand→SuppressionRequest, SetProviderStateCommand→ProviderStateRequest. adminAuthorizationGuard·duplicateRiskGuard bean은 없어졌다(유스케이스 설정이 new로 만든다). 모듈 기본값이 role notification-admin에 permission 넷(notification-admin:redrive·notification-admin:reconcile·notification-admin:suppress·notification-admin:provider-control)을 준다. 운영자 role 이름이 다르면 app.authz.role-permissions에 직접 대응시킨다 |
컴파일이 실패한다. 두 guard bean을 주입받던 정의는 기동이 실패한다(NoSuchBeanDefinitionException). 운영자가 notification-admin role도 대응시킨 role도 없으면 운영자 호출이 403이다 |
알림 운영자 연산을 쓴 서비스 |
| 2 | 알림 worker가 adapter:outbound:notification에서 composition:notification-platform으로 옮겼다. NotificationBackgroundWorkers는 dev.caskeleton.composition.notification의 공개 타입이고, 생성자는 서비스 대신 유스케이스를 받는다(lease 회복·replay·맞추기). 발송 scheduler(NotificationSchedulerWorker)는 그 패키지 안의 타입이 됐다. claim·발송·backlog 측정 유스케이스로 돌고, 바꿔 끼우는 bean이 아니다. ReconciliationJobWorker·ProviderEventReplayWorker는 application의 @SystemInvoked 유스케이스(ReconcileOutstandingAttemptsUseCase(jobs, reconciler, tx, clock, deliveryLease, batchSize, maxAdditionalAttempts)·ReplayProviderEventsUseCase(projection, batchSize))가 됐다. reconciliationJobWorker·notificationProviderEventReplayWorker bean을 덮어쓰던 서비스는 notificationBackgroundWorkers bean을 덮어쓴다 |
옛 import와 생성자가 컴파일되지 않는다. 옛 bean 이름으로 덮어쓴 정의는 더는 쓰이지 않는다 | 알림 worker를 직접 조립하거나 덮어쓴 서비스 |
| 3 | MessagingReplayBridge는 생성자에서 조회 유스케이스 둘을 받는다: new MessagingReplayBridge<>(window, replay, decoder). 두 유스케이스는 서비스의 조립 설정(자기 composition 설정이나 bootstrap 설정, web 설정이 아니다)에서 bean으로 만든다: @Bean GetReplayWindowUseCase(LiveEventReplayQueryPort port, TransactionPort tx), @Bean ReplayLiveEventsUseCase(...). 템플릿은 bridge를 조립하지 않으므로 이 bean도 만들지 않는다. LiveEventReplayPort는 LiveEventReplayQueryPort로, testFixtures의 LiveEventReplayContract는 LiveEventReplayQueryContract로 이름이 바뀌었다 |
컴파일이 실패한다. web 설정에서 port를 쥐고 유스케이스를 만들면 5행 규칙에 걸린다 | stream replay를 쓰는 서비스 |
| 4 | OperationCommand에서 operation id 인자를 지우고, tenant를 Optional<TenantId>(application.tenant.TenantId)로 넘긴다. GetDurableOperationQuery·CancelDurableOperationCommand의 tenant도 같다. SubmitDurableOperationUseCase는 생성자에 DurableOperationIdFactory를 받아 id를 직접 만든다. DurableOperationController는 id factory를 받지 않는다 |
컴파일이 실패한다 | durable operation을 직접 제출·조회하거나 그 use case를 조립한 서비스 |
| 5 | 사용자 전송 패키지(시스템이 부르는 ..adapter.inbound.messaging..·..adapter.inbound.scheduler..를 뺀 모든 ..adapter.inbound..)의 클래스가 *Repository·*StorePort·*QueryPort·*IdFactory·*IdGeneratorPort·*IdentifierPort를 직접 쥐면 새 아키텍처 규칙 USER_TRANSPORTS_DO_NOT_HOLD_PERSISTENCE_OR_ID_PORTS가 빌드를 실패시킨다. 또 inbound 클래스가 application의 *Service·*Orchestrator·*Coordinator를 interface로 쥐어도 INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES가 실패시킨다(전에는 구체 클래스만 봤다). 읽기·쓰기는 유스케이스를 거친다 |
architectureTest가 실패한다 |
사용자 전송에서 포트나 서비스를 직접 쓴 서비스 |
| 6 | DefaultNotificationRetryPolicy를 직접 만들던 코드는 new DefaultNotificationRetryPolicy(timing, jitter)로 바꾼다. timing은 새 값 RetryTiming(backoff, reconcileDelay)이고 배포 설정의 값은 NotificationPlatformSettings.retry().timing()이다(기본값은 RetryTiming.DEFAULT). RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult의 생성자와 RetryBackoff.delay(attempt 번호 1 미만)는 잘못된 값에 IllegalStateException을 던진다(전에는 IllegalArgumentException). 새 값 RetryTiming도 같다 |
컴파일이 실패한다. IAE를 잡던 코드는 그 예외를 놓친다 | 알림 retry policy를 직접 만들거나, route planner·plan codec·eligibility policy를 직접 구현하거나, RoutingDecision을 직접 만드는 서비스 |
| 7 | 쓰는 곳이 없던 공개 타입 일곱을 지웠다: application.transaction.ReadConsistency, FileserverSpans, 알림의 ProviderEventId·NotificationExpiredException·BatchNotificationProviderAdapter·CollapseCapability·ProviderCollapseMapping |
그 타입을 쓴 코드는 컴파일이 실패한다. 템플릿 안에는 쓰는 곳이 없었다 | 그 타입을 쓴 서비스 |
3. 바뀐 동작 (따라 할 일 없음)
- 알림 재시도 시각이 설정이다:
app.notification.platform.retry.backoff-base(1s)·backoff-max(5m)·reconcile-delay(1m). 기본값은 전의 상수와 같고 코드(RetryTiming.DEFAULT)에만 있다. module-defaults에는 주석 예시만 있다. 값이 틀리면 (backoff-base0 이하,backoff-max가 base보다 짧음,reconcile-delay음수) 기동이 실패한다. - fileserver cleanup worker와 알림 worker는
@SystemInvoked유스케이스를 거쳐 쓴다(manual 07 「시스템이 부르는 쓰기」). 알림 worker의 lease claim과 reconciliation job 기록은 이제 쓰기 트랜잭션 안에서, scheduler의 backlog 측정과 replay의 ledger 읽기는 읽기 트랜잭션 안에서 돈다. provider에는 여전히 트랜잭션 없이 묻는다. - 운영자 redrive는 대상 attempt를 claim·쓰기와 같은 쓰기 트랜잭션에서 읽는다(dry run은 읽기 트랜잭션). 운영자 reconcile의 tenant 확인은 읽기 트랜잭션에서 한다. 전에는 트랜잭션 밖에서 읽었다.
- fileserver 정리·맞추기 서비스(
CleanupService·FileReconciliationService)는composition:fileserver-platform이 조립한다. bean 이름과 타입은 그대로다. - fileserver 관리 HTTP의 기본값(orphan 정리 dry run과 1 GiB·
ORPHAN_APPLY, cleanup 100개·1 GiB, 목록 100개)은 application command의requested(...)가 채운다. 응답은 같다. GetDurableOperationUseCase·PublishPendingOutboxEventsUseCase가 final이 아니다.- 알림 받기의
idempotencyKey가IdempotencyExecutor와 다른 이유는 manual 05 「executor를 쓰지 않는 중복 판정 둘」에 있다.