refactor(application)!: 시스템 쓰기와 운영자 연산을 유스케이스 계약 안으로 옮긴다 #38

Merged
donghyeon.kang merged 6 commits from claude/r9-b-application into main 2026-11-13 20:15:07 +00:00
Owner

무엇을, 왜

2026-11-12 전체 리뷰의 B15a(application 구조, RR9-05-19 관리 기본값 포함)와 B15b(application 작은 것) 발견 13건을 고친다. claim·fence PR(#33) 위에 쌓았다. 알림 worker와 durable operation 파일이 그 PR과 같기 때문이다. 그 PR이 먼저 병합되어야 하고, 그 전까지 이 PR의 diff에는 그 PR의 커밋이 함께 보인다. #33 다음에 main(#29~#31)을 merge 커밋 하나로 받았다(그룹 A 권한 변경과 함께 검증하려고). 이 PR의 커밋은 마지막 둘이다.

  • 시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기, 알림 claim·발송·lease 회복·맞추기·provider event replay는 @UseCaseCapability도 트랜잭션 선언도 없는 서비스를 worker가 바로 부른다. 그 worker와 조립은 outbound adapter 안에 있다.
  • 알림 운영자 연산이 계약 밖이다. 연산 넷이 유스케이스·capability·@RequiresPermission 없이 서비스 하나에 모여 있다. 재시도 시각은 상수다.
  • web이 저장 포트를 직접 읽는다. MessagingReplayBridge가 outbound가 구현한 LiveEventReplayPort를 바로 읽는다.
  • durable operation이 core 공통 타입을 따르지 않는다. tenant·principal이 문자열이고, id를 controller가 만든다.
  • 작은 것. operation id 문법이 셋인 이유가 적혀 있지 않다. 멱등 판정 셋 중 둘이 executor를 쓰지 않는 이유도 없다. UUIDv7 파생을 유스케이스가 한다. 쓰지 않는 공개 타입이 일곱이다. final 유스케이스가 둘이다. 포트 실패 결과 Javadoc이 없다. 소스 문자열에 NUL 바이트가 있다. 관리 HTTP 기본값을 controller가 정한다.

고른 방법과 버린 대안

  • 시스템 쓰기는 @SystemInvoked 유스케이스로 나눈다. fileserver RunScheduledCleanupUseCase·ReconcileRecoverableFilesUseCase, 알림 ClaimDueDeliveriesUseCase·DispatchClaimedDeliveryUseCase·RecoverAbandonedDeliveriesUseCase·ReconcileOutstandingAttemptsUseCase·ReplayProviderEventsUseCase다. composition worker 설정이 new로 만들어 넘기고 bean으로 두지 않는다. 언제 다시 묻고 포기하는지(맞추기의 재시도·claim lease = delivery lease, 최대 시도 = 추가 시도 + 1)는 유스케이스가 정한다. scheduler의 backlog 지표도 query 유스케이스(MeasureDispatchBacklogUseCase, 읽기 트랜잭션)를 거친다. 그래서 어떤 사용자 전송도 닿지 못한다(manual 07 「시스템이 부르는 쓰기」). 알림 worker와 fileserver 정리 서비스 조립은 composition으로 옮긴다. 유스케이스가 아닌 채 남은 알림 협력 서비스 여섯은 NotificationUseCaseContractDeviationTest가 목록으로 묶는다. 버린 대안: 서비스에 @UseCaseCapability만 붙이기(사용자 경로와 시스템 경로가 같은 진입점을 나눠 써서 권한 규칙이 막지 못한다).
  • 운영자 연산은 platform.admin의 유스케이스 클래스 넷이다. RedriveDeliveryUseCase·ReconcileDeliveriesUseCase·ChangeSuppressionUseCase·ChangeProviderStateUseCase와 그 옆의 command, 권한은 notification-admin:*이다. 대상 확인은 claim·쓰기와 같은 트랜잭션에서 읽는다(reconcile은 읽기 트랜잭션, provider 호출은 트랜잭션 밖). 버린 대안: 서비스 삭제(파생 서비스의 운영자 화면이 쓸 진입점이 없어진다), platform.port.in 인터페이스(command가 AdminActor를 실어 port.in과 admin이 서로를 보는 cycle이 되고, 구현 이름이 따라 하지 않는 *ApplicationUseCase가 된다).
  • replay 읽기는 조회 유스케이스 둘을 거친다. GetReplayWindowUseCase·ReplayLiveEventsUseCase이고, 포트 이름은 LiveEventReplayQueryPort로 바꾼다. 새 규칙 USER_TRANSPORTS_DO_NOT_HOLD_PERSISTENCE_OR_ID_PORTS가 시스템이 부르는 것을 뺀 모든 inbound 패키지에서 저장·id 포트를 쥐는 것을 막는다. INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES는 이제 application 서비스·coordinator를 interface로 쥐는 것도 막는다(@SystemInvoked 유스케이스가 감싸는 서비스는 권한 검사 없이 쓰는 bean이다). 위반 fixture와 통과 fixture가 규칙이 실제로 잡고 정상 코드를 막지 않는지 본다. 두 조회 유스케이스 bean은 템플릿이 bridge를 조립하지 않아 만들지 않고, 서비스의 조립 설정이 만든다(안내 3행).
  • durable operation은 Optional<TenantId>를 받고, id는 SubmitDurableOperationUseCase가 DurableOperationIdFactory로 만든다. UUIDv7 파생은 IntegrationIdentity로 옮긴다.
  • 작은 것.
    • operation id 문법 셋은 값 타입 하나로 합치지 않는다. 다니는 곳(URL 경로, header·Redis key, 비교만)이 달라서다. 그 비교를 OperationId Javadoc에 적는다.
    • 멱등 판정 둘이 executor를 쓰지 않는 이유는 manual 05 「executor를 쓰지 않는 중복 판정 둘」에 결정으로 적는다.
    • 쓰지 않는 공개 타입 일곱은 지운다. 유스케이스 둘은 final을 뗀다. 포트에 실패 결과 Javadoc을 적는다. NUL은 \u0000으로 바꾼다.
    • 관리 HTTP 기본값은 application command의 requested(...) 팩터리가 채운다.

정한 기본값

  • 알림 재시도 시각: app.notification.platform.retry.backoff-base 1s, backoff-max 5m, reconcile-delay 1m. 전의 상수와 같다. 기본값과 규칙은 policy의 값 RetryTiming(DEFAULT) 한 곳에만 있고, 설정은 그 값을 만든다. 틀린 값은 IllegalStateException으로 기동을 실패시킨다(binder가 app.notification.platform.retry 블록 이름을 붙인다).
  • policy 패키지의 서버가 만드는 값(retry·routing·eligibility 결과)은 잘못된 값에 IllegalStateException을 던진다. 이유는 policy/package-info.java 한 곳에 적었다. 요청 데이터를 싣는 record(consent·preference·수신자·suppression)는 그대로 IllegalArgumentException이다.
  • 운영자 permission 넷: notification-admin:redrive·reconcile·suppress·provider-control. 모듈 기본값이 role notification-admin에 넷을 준다(fileserver의 ROLE_FILE_ADMIN → file:admin과 같은 꼴). 다른 이름의 운영자 role은 서비스가 대응시킨다.
  • fileserver 관리 기본값(orphan dry run, 1 GiB, ORPHAN_APPLY, cleanup 100개·1 GiB, 목록 100개)은 전과 같다.

위험과 영향

공개 타입, 생성자, bean 이름, 아키텍처 규칙이 바뀐다. 파생 서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 2절 일곱 줄이다. 요약:

  • 컴파일이 깨지는 곳: 운영자 서비스 둘 삭제와 운영자 유스케이스의 platform.admin 위치, 운영자 요청 record 이름(*Request), DefaultNotificationRetryPolicy(RetryTiming, JitterSource)(안내 6행), 알림 worker 패키지 이동과 생성자, MessagingReplayBridge 생성자, LiveEventReplayPort·LiveEventReplayContract 개명, OperationCommand·query·command의 tenant 타입, 쓰지 않던 공개 타입 일곱 삭제.
  • 동작: 운영자가 notification-admin role도, 서비스가 대응시킨 role도 없으면 운영자 호출이 403이다. IdP가 notification-admin을 다른 뜻으로 쓰면 그 키를 덮어쓴다. 옛 worker bean 이름으로 덮어쓴 정의는 더는 쓰이지 않는다.
  • 빌드: 사용자 전송에서 저장·id 포트를 쥔 클래스, inbound에서 application 서비스·coordinator를 interface로 쥔 클래스가 있으면 architectureTest가 실패한다.
  • 트랜잭션: 알림 worker의 lease claim과 reconciliation job 기록이 이제 쓰기 트랜잭션 안에서 돈다. provider 호출은 여전히 트랜잭션 밖이다.
  • 쌓기: claim·fence PR(#33)이 먼저 병합되어야 한다.
  • 그룹 B 경로 밖 한 줄: config/spotbugs/exclude.xml의 CT_CONSTRUCTOR_THROW CGLIB 그룹에 「@UseCaseCapability가 붙은 *UseCase class」를 더했다. 유스케이스는 계약상 final일 수 없어서(src/application/core/AGENTS.md), @RequiresPermission이 class에 없는 @SystemInvoked·조회 유스케이스가 처음 생기면서 걸렸다.

검증

  • GREEN: desktop scripts/verify.sh pr --on here --no-cache rc=0. 트리 941ce531(이 PR head, main 3e908c02 위), 시험 6979건(실패 0, skip 35), FROM-CACHE 0. 로그 ~/r9-group-b-logs/pr3-verify-r14.log.
  • 전 모듈 컴파일(--continue, main·test·testFixtures·모든 시험 source set) rc=0.
  • lane: :adapter:outbound:persistence-jpa:jpaPlatformContractTest rc=0, 455건.
  • 중간 커밋: B15b 커밋 트리 30a77cc4만으로 application-core·notification·fileserver, adapter notification·web, composition durable-operation check, PG 시험 컴파일, :app-bootstrap:architectureTest rc=0, 2164건(skip 20).
  • 처음 desktop에서 끝까지 돌렸을 때 SpotBugs CT_CONSTRUCTOR_THROW(final을 뗀 유스케이스 12개)와 시험 컴파일 1건(DurableOperationAccessPolicyTest가 Optional<TenantId>를 따라가지 않음)이 걸려 고쳤다.
  • 노트북: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py 통과. API surface 스냅숏(docs/notification/api-surface-snapshot.txt)을 코드에서 다시 만들어 맞췄다. 알림 공개 타입은 main 364에서 375로 는다. 빠진 15개는 composition으로 옮긴 worker 넷, 운영자 서비스 둘, 이름을 바꾼 요청 record 넷, 쓰지 않던 타입 다섯이다. 더한 26개는 유스케이스와 command·query 20개, 요청 record 넷, NotificationAdminPermissions, RetryTiming이다.
  • RED: 구조 변경이 대부분이라 시험을 먼저 실패시키는 순서를 따르지 않은 것이 있다. 새 규칙은 위반 fixture 시험이, 운영자 권한은 NotificationAdminUseCasesTest가, id 생성 위치는 SubmitDurableOperationUseCaseTest.theOperationIdIsMintedByTheUseCase가 본다.

리뷰어가 볼 곳

  • composition/notification/NotificationApplicationCompositionAutoConfiguration(worker 설정 import), NotificationWorkerConfiguration·NotificationSchedulerWorker·NotificationBackgroundWorkers(옮긴 worker의 수명·mode 조건·종료).
  • 알림 platform/admin/*UseCase와 AdminOperationExecutor(권한·트랜잭션).
  • AdapterBoundaryArchitectureTest의 새 규칙·넓힌 규칙과 fixture.
  • SubmitDurableOperationUseCase·DurableOperationAccessPolicy.

관련

발견 표

ID 판정 커밋
RR9-05-06 고침 2d274a68
RR9-05-07 고침 2d274a68
RR9-05-08 고침 2d274a68
RR9-05-10 고침 2d274a68
RR9-05-19 고침 2d274a68
RR9-05-11 고침(값 타입은 합치지 않고 이유를 OperationId Javadoc에 적음) e60408e9
RR9-05-12 고침(결정 기록, manual 05) e60408e9
RR9-05-13 고침 e60408e9
RR9-05-14 고침 e60408e9
RR9-05-15 고침 e60408e9
RR9-05-16 고침 e60408e9
RR9-05-17 고침 e60408e9
RR9-05-18 고침 e60408e9
B16 넘김 DurableOperationStoreContractTest 고침(같은 파일이라 #33에서) —
## 무엇을, 왜 2026-11-12 전체 리뷰의 B15a(application 구조, RR9-05-19 관리 기본값 포함)와 B15b(application 작은 것) 발견 13건을 고친다. claim·fence PR(#33) 위에 쌓았다. 알림 worker와 durable operation 파일이 그 PR과 같기 때문이다. 그 PR이 먼저 병합되어야 하고, 그 전까지 이 PR의 diff에는 그 PR의 커밋이 함께 보인다. #33 다음에 main(#29~#31)을 merge 커밋 하나로 받았다(그룹 A 권한 변경과 함께 검증하려고). 이 PR의 커밋은 마지막 둘이다. - **시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다.** fileserver 정리·맞추기, 알림 claim·발송·lease 회복·맞추기·provider event replay는 `@UseCaseCapability`도 트랜잭션 선언도 없는 서비스를 worker가 바로 부른다. 그 worker와 조립은 outbound adapter 안에 있다. - **알림 운영자 연산이 계약 밖이다.** 연산 넷이 유스케이스·capability·`@RequiresPermission` 없이 서비스 하나에 모여 있다. 재시도 시각은 상수다. - **web이 저장 포트를 직접 읽는다.** `MessagingReplayBridge`가 outbound가 구현한 `LiveEventReplayPort`를 바로 읽는다. - **durable operation이 core 공통 타입을 따르지 않는다.** tenant·principal이 문자열이고, id를 controller가 만든다. - **작은 것.** operation id 문법이 셋인 이유가 적혀 있지 않다. 멱등 판정 셋 중 둘이 executor를 쓰지 않는 이유도 없다. UUIDv7 파생을 유스케이스가 한다. 쓰지 않는 공개 타입이 일곱이다. final 유스케이스가 둘이다. 포트 실패 결과 Javadoc이 없다. 소스 문자열에 NUL 바이트가 있다. 관리 HTTP 기본값을 controller가 정한다. ## 고른 방법과 버린 대안 - **시스템 쓰기는 `@SystemInvoked` 유스케이스로 나눈다.** fileserver `RunScheduledCleanupUseCase`·`ReconcileRecoverableFilesUseCase`, 알림 `ClaimDueDeliveriesUseCase`·`DispatchClaimedDeliveryUseCase`·`RecoverAbandonedDeliveriesUseCase`·`ReconcileOutstandingAttemptsUseCase`·`ReplayProviderEventsUseCase`다. composition worker 설정이 `new`로 만들어 넘기고 bean으로 두지 않는다. 언제 다시 묻고 포기하는지(맞추기의 재시도·claim lease = delivery lease, 최대 시도 = 추가 시도 + 1)는 유스케이스가 정한다. scheduler의 backlog 지표도 query 유스케이스(`MeasureDispatchBacklogUseCase`, 읽기 트랜잭션)를 거친다. 그래서 어떤 사용자 전송도 닿지 못한다(manual 07 「시스템이 부르는 쓰기」). 알림 worker와 fileserver 정리 서비스 조립은 composition으로 옮긴다. 유스케이스가 아닌 채 남은 알림 협력 서비스 여섯은 `NotificationUseCaseContractDeviationTest`가 목록으로 묶는다. 버린 대안: 서비스에 `@UseCaseCapability`만 붙이기(사용자 경로와 시스템 경로가 같은 진입점을 나눠 써서 권한 규칙이 막지 못한다). - **운영자 연산은 `platform.admin`의 유스케이스 클래스 넷이다.** `RedriveDeliveryUseCase`·`ReconcileDeliveriesUseCase`·`ChangeSuppressionUseCase`·`ChangeProviderStateUseCase`와 그 옆의 command, 권한은 `notification-admin:*`이다. 대상 확인은 claim·쓰기와 같은 트랜잭션에서 읽는다(reconcile은 읽기 트랜잭션, provider 호출은 트랜잭션 밖). 버린 대안: 서비스 삭제(파생 서비스의 운영자 화면이 쓸 진입점이 없어진다), `platform.port.in` 인터페이스(command가 `AdminActor`를 실어 `port.in`과 `admin`이 서로를 보는 cycle이 되고, 구현 이름이 따라 하지 않는 `*ApplicationUseCase`가 된다). - **replay 읽기는 조회 유스케이스 둘을 거친다.** `GetReplayWindowUseCase`·`ReplayLiveEventsUseCase`이고, 포트 이름은 `LiveEventReplayQueryPort`로 바꾼다. 새 규칙 `USER_TRANSPORTS_DO_NOT_HOLD_PERSISTENCE_OR_ID_PORTS`가 시스템이 부르는 것을 뺀 모든 inbound 패키지에서 저장·id 포트를 쥐는 것을 막는다. `INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES`는 이제 application 서비스·coordinator를 interface로 쥐는 것도 막는다(`@SystemInvoked` 유스케이스가 감싸는 서비스는 권한 검사 없이 쓰는 bean이다). 위반 fixture와 통과 fixture가 규칙이 실제로 잡고 정상 코드를 막지 않는지 본다. 두 조회 유스케이스 bean은 템플릿이 bridge를 조립하지 않아 만들지 않고, 서비스의 조립 설정이 만든다(안내 3행). - **durable operation은 `Optional<TenantId>`를 받고, id는 `SubmitDurableOperationUseCase`가 `DurableOperationIdFactory`로 만든다.** UUIDv7 파생은 `IntegrationIdentity`로 옮긴다. - **작은 것.** - operation id 문법 셋은 값 타입 하나로 합치지 않는다. 다니는 곳(URL 경로, header·Redis key, 비교만)이 달라서다. 그 비교를 `OperationId` Javadoc에 적는다. - 멱등 판정 둘이 executor를 쓰지 않는 이유는 manual 05 「executor를 쓰지 않는 중복 판정 둘」에 결정으로 적는다. - 쓰지 않는 공개 타입 일곱은 지운다. 유스케이스 둘은 final을 뗀다. 포트에 실패 결과 Javadoc을 적는다. NUL은 `\u0000`으로 바꾼다. - 관리 HTTP 기본값은 application command의 `requested(...)` 팩터리가 채운다. ## 정한 기본값 - 알림 재시도 시각: `app.notification.platform.retry.backoff-base` 1s, `backoff-max` 5m, `reconcile-delay` 1m. 전의 상수와 같다. 기본값과 규칙은 policy의 값 `RetryTiming`(`DEFAULT`) 한 곳에만 있고, 설정은 그 값을 만든다. 틀린 값은 `IllegalStateException`으로 기동을 실패시킨다(binder가 `app.notification.platform.retry` 블록 이름을 붙인다). - policy 패키지의 서버가 만드는 값(retry·routing·eligibility 결과)은 잘못된 값에 `IllegalStateException`을 던진다. 이유는 `policy/package-info.java` 한 곳에 적었다. 요청 데이터를 싣는 record(consent·preference·수신자·suppression)는 그대로 `IllegalArgumentException`이다. - 운영자 permission 넷: `notification-admin:redrive`·`reconcile`·`suppress`·`provider-control`. 모듈 기본값이 role `notification-admin`에 넷을 준다(fileserver의 `ROLE_FILE_ADMIN` → `file:admin`과 같은 꼴). 다른 이름의 운영자 role은 서비스가 대응시킨다. - fileserver 관리 기본값(orphan dry run, 1 GiB, `ORPHAN_APPLY`, cleanup 100개·1 GiB, 목록 100개)은 전과 같다. ## 위험과 영향 공개 타입, 생성자, bean 이름, 아키텍처 규칙이 바뀐다. 파생 서비스가 할 일은 `docs/upgrade/2026-11-round9-application.md` 2절 일곱 줄이다. 요약: - **컴파일이 깨지는 곳:** 운영자 서비스 둘 삭제와 운영자 유스케이스의 `platform.admin` 위치, 운영자 요청 record 이름(`*Request`), `DefaultNotificationRetryPolicy(RetryTiming, JitterSource)`(안내 6행), 알림 worker 패키지 이동과 생성자, `MessagingReplayBridge` 생성자, `LiveEventReplayPort`·`LiveEventReplayContract` 개명, `OperationCommand`·query·command의 tenant 타입, 쓰지 않던 공개 타입 일곱 삭제. - **동작:** 운영자가 `notification-admin` role도, 서비스가 대응시킨 role도 없으면 운영자 호출이 403이다. IdP가 `notification-admin`을 다른 뜻으로 쓰면 그 키를 덮어쓴다. 옛 worker bean 이름으로 덮어쓴 정의는 더는 쓰이지 않는다. - **빌드:** 사용자 전송에서 저장·id 포트를 쥔 클래스, inbound에서 application 서비스·coordinator를 interface로 쥔 클래스가 있으면 `architectureTest`가 실패한다. - **트랜잭션:** 알림 worker의 lease claim과 reconciliation job 기록이 이제 쓰기 트랜잭션 안에서 돈다. provider 호출은 여전히 트랜잭션 밖이다. - **쌓기:** claim·fence PR(#33)이 먼저 병합되어야 한다. - **그룹 B 경로 밖 한 줄:** `config/spotbugs/exclude.xml`의 `CT_CONSTRUCTOR_THROW` CGLIB 그룹에 「`@UseCaseCapability`가 붙은 `*UseCase` class」를 더했다. 유스케이스는 계약상 final일 수 없어서(`src/application/core/AGENTS.md`), `@RequiresPermission`이 class에 없는 `@SystemInvoked`·조회 유스케이스가 처음 생기면서 걸렸다. ## 검증 - GREEN: desktop `scripts/verify.sh pr --on here --no-cache` rc=0. 트리 `941ce531`(이 PR head, main `3e908c02` 위), 시험 6979건(실패 0, skip 35), FROM-CACHE 0. 로그 `~/r9-group-b-logs/pr3-verify-r14.log`. - 전 모듈 컴파일(`--continue`, main·test·testFixtures·모든 시험 source set) rc=0. - lane: `:adapter:outbound:persistence-jpa:jpaPlatformContractTest` rc=0, 455건. - 중간 커밋: B15b 커밋 트리 `30a77cc4`만으로 application-core·notification·fileserver, adapter notification·web, composition durable-operation `check`, PG 시험 컴파일, `:app-bootstrap:architectureTest` rc=0, 2164건(skip 20). - 처음 desktop에서 끝까지 돌렸을 때 SpotBugs `CT_CONSTRUCTOR_THROW`(final을 뗀 유스케이스 12개)와 시험 컴파일 1건(`DurableOperationAccessPolicyTest`가 `Optional<TenantId>`를 따라가지 않음)이 걸려 고쳤다. - 노트북: `python3 scripts/check-docs.py`, `python3 scripts/check-work-docs.py` 통과. API surface 스냅숏(`docs/notification/api-surface-snapshot.txt`)을 코드에서 다시 만들어 맞췄다. 알림 공개 타입은 main 364에서 375로 는다. 빠진 15개는 composition으로 옮긴 worker 넷, 운영자 서비스 둘, 이름을 바꾼 요청 record 넷, 쓰지 않던 타입 다섯이다. 더한 26개는 유스케이스와 command·query 20개, 요청 record 넷, `NotificationAdminPermissions`, `RetryTiming`이다. - RED: 구조 변경이 대부분이라 시험을 먼저 실패시키는 순서를 따르지 않은 것이 있다. 새 규칙은 위반 fixture 시험이, 운영자 권한은 `NotificationAdminUseCasesTest`가, id 생성 위치는 `SubmitDurableOperationUseCaseTest.theOperationIdIsMintedByTheUseCase`가 본다. ## 리뷰어가 볼 곳 - `composition/notification/NotificationApplicationCompositionAutoConfiguration`(worker 설정 import), `NotificationWorkerConfiguration`·`NotificationSchedulerWorker`·`NotificationBackgroundWorkers`(옮긴 worker의 수명·mode 조건·종료). - 알림 `platform/admin/*UseCase`와 `AdminOperationExecutor`(권한·트랜잭션). - `AdapterBoundaryArchitectureTest`의 새 규칙·넓힌 규칙과 fixture. - `SubmitDurableOperationUseCase`·`DurableOperationAccessPolicy`. ## 관련 - 리뷰: `docs/reviews/2026-11-12-round9-review/05-architecture-domain.md` - 안내: `docs/upgrade/2026-11-round9-application.md` - 쌓은 PR: #33 ## 발견 표 | ID | 판정 | 커밋 | | --- | --- | --- | | RR9-05-06 | 고침 | 2d274a68 | | RR9-05-07 | 고침 | 2d274a68 | | RR9-05-08 | 고침 | 2d274a68 | | RR9-05-10 | 고침 | 2d274a68 | | RR9-05-19 | 고침 | 2d274a68 | | RR9-05-11 | 고침(값 타입은 합치지 않고 이유를 `OperationId` Javadoc에 적음) | e60408e9 | | RR9-05-12 | 고침(결정 기록, manual 05) | e60408e9 | | RR9-05-13 | 고침 | e60408e9 | | RR9-05-14 | 고침 | e60408e9 | | RR9-05-15 | 고침 | e60408e9 | | RR9-05-16 | 고침 | e60408e9 | | RR9-05-17 | 고침 | e60408e9 | | RR9-05-18 | 고침 | e60408e9 | | B16 넘김 `DurableOperationStoreContractTest` | 고침(같은 파일이라 #33에서) | — |
donghyeon.kang added 5 commits 2026-11-13 07:37:13 +00:00
lease를 넘겨받는 저장소 다섯 곳이 앞 실행의 쓰기를 막지 못한다.
durable operation은 owner만 보고 써서 같은 worker id가 다시 claim하면
앞 실행의 결과가 남는다. 알림 lease 회복은 상태를 다시 읽은 뒤 조건
없이 되돌려 끝난 delivery를 다시 보낸다. 만료 sweep·전체 읽음은
기다린 행의 상태를 다시 보지 않는다. 멱등성 reaper는 앱 시계로 비교하고
한 번에 다 지우며, 같은 키 요청이 되살린 기록까지 지운다. fileserver
recovery enqueue는 동시 삽입에서 25P02로 실패하고, cleanup은 claim
lease가 끝난 뒤에도 항목을 시작한다. 저장소가 행에서 만드는 claim·lease
record는 잘못된 값을 IllegalArgumentException으로 거절해 web이 400으로
바꾼다.

고른 방법: 모든 쓰기를 owner·fence(·상태·만료) 조건을 단 한 문장으로
바꾼다. durable operation은 V23 lease_fence를 더하고 DurableOperationClaim
을 돌려준다. 알림 회복은 requeueAbandoned 한 문장이다. 만료 sweep은
subquery가 SKIP LOCKED로 쥔 행을 건너뛰고 바깥 UPDATE가 상태·만료를 다시
본다. 전체 읽음은 바깥 UPDATE가 상태를 다시 본다. reaper는 DB now()로
1000행씩, 트랜잭션마다 30초(SpringTransaction.DEFAULT_TIMEOUT_SECONDS)이고
바깥 DELETE에도 만료를 둔다. recovery는 INSERT … ON CONFLICT, cleanup은
lease 마지막 2분에 시작하지 않고 시도를 세지 않는 release로 돌려준다.
알림 provider timeout은 lease보다 짧아야 기동한다(호출이 lease를 넘으면
lease 복구가 아직 도는 호출을 맞추기로 넘긴다). 저장소가 만드는 record
일곱은 IllegalStateException으로 거절한다. 버린 대안: 읽고 비교한 뒤
쓰기(경합이 그대로 남음), 앱 쪽 락(인스턴스 사이에서 무의미).

위험·한계: 포트 시그니처가 바뀐다(DurableOperationStorePort,
RecipientLeaseStorePort.expiredDispatching, RecipientDeliveryStorePort
.requeueAbandoned, CleanupQueuePort.release). owner가 없거나 fence가
0인 V4 전 DISPATCHING 행은 회복이 고르지 않는다(안내 4행에 고치는 SQL).
provider timeout 검사는 필요조건일 뿐이고, 호출 전체를 묶는 것은 SES다.

검증: desktop RED(고치기 전 트리 + 새 시험, pr1-red3) 새 시험 13건
실패. GREEN은 PR 본문의 verify.sh pr·PostgreSQL lane 결과.

Refs: RR9-01-02, RR9-01-04, RR9-01-06, RR9-01-12, RR9-01-13, RR9-01-23, RR9-01-24, RR9-01-29, R1 넘김 DurableOperationStoreContractTest
BREAKING CHANGE: DurableOperationStorePort의 heartbeat·reportProgress·succeed·fail이 DurableOperationClaim을 받고 claimNext가 그것을 돌려준다. RecipientLeaseStorePort.expiredDispatching이 List<RecipientLease>를 돌려주고 RecipientDeliveryStorePort.requeueAbandoned, CleanupQueuePort.release가 새로 생긴다. IdempotencyReaper 생성자에서 Clock이 빠진다. 알림 provider timeout이 lease 이상이면 기동이 실패한다. 저장소가 만드는 claim·lease record가 IllegalStateException을 던진다. docs/upgrade/2026-11-round9-claim-fence.md
남은 트랜잭션·정리 결함 일곱. live event log는 지우는 곳이 없어 끝없이
자란다. app.lock.wait-time은 읽는 곳이 없다. 알림 scheduler는 poll마다
상태 쿼리 넷을 돌리고, projection 지연은 닫힌 event까지 읽는다.
stateless runner 트랜잭션에 시한이 없다. tenant pool 예산은 새 pool의
크기를 모른 채 열어 연결 합계가 상한을 넘는다. runbook SQL 설명이
lane 넷 중 셋만 말한다.

고른 방법: LiveEventReaper(1000행씩, 트랜잭션 30초)와 공용
BatchedDeletes를 더한다. app.realtime.replay.*는 LiveEventReplaySettings가
엄격하게 묶고, 조립 설정이 SchedulingConfigurer로 reaper를
reaper-interval(기본 10분)마다 등록한다. LockSettings는 lease-ttl 하나만
받는다(모르는 키로 기동 실패). scheduler는 backlogDepth() 한 문장만 읽고,
그 WHERE는 claim과 같은 SQL 조각(RecipientClaimSql.CLAIMABLE_AT_NOW)이다.
projection 지연은 V14 부분 인덱스로 읽는다(lock_timeout, V21 선례대로
CONCURRENTLY 아님). runner 기본 30초(SpringTransaction 쓰기 시한과 같음을
시험이 본다), tenant 예산은 계획된 pool 크기로 열기 전에 본다. 버린
대안: V14를 CONCURRENTLY로(Flyway 트랜잭션 안에서 못 돈다, 큰 DB는
안내대로 미리 만든다), reaper @Scheduled에 SpEL로 settings bean 이름
읽기(문자열 bean 조회는 검사가 못 본다).

위험·한계: LockSettings·TenantDataSourceRegistry·TenantPoolBudget의
공개 생성자가 바뀐다. V14는 큰 notification_provider_event에서 쓰기를
잠깐 막는다(안내 4행에 미리 만드는 법과 INVALID 인덱스 확인). backlog
수치는 창이 닫힌 delivery를 더는 세지 않는다.

검증: desktop RED(pr1-red3) 새 시험 실패 포함. GREEN은 PR 본문.

Refs: RR9-01-03, RR9-01-07, RR9-01-09, RR9-01-10, RR9-01-14, RR9-01-25, RR9-01-26
BREAKING CHANGE: JpaLiveEventReplay.sweepExpired 삭제, app.realtime.replay 아래 모르는 키와 app.lock.wait-time은 기동 실패, HibernateStatelessSessionRunner 트랜잭션 30초 상한, TenantPoolBudget·TenantDataSourceRegistry 시그니처 변경. docs/upgrade/2026-11-round9-claim-fence.md
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을 지웠다.
시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. 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을 던진다.
donghyeon.kang added 1 commit 2026-11-13 07:37:46 +00:00
Merge branch 'main' into claude/r9-b-application
pr / done (pull_request) Canceled after 0s
dedafd5de1
donghyeon.kang added 1 commit 2026-11-13 07:58:28 +00:00
Merge branch 'main' into claude/r9-b-application
pr / done (pull_request) Canceled after 0s
f9d0cf351b
donghyeon.kang added 1 commit 2026-11-13 09:43:00 +00:00
Merge branch 'main' into claude/r9-b-application
pr / done (pull_request) Successful in 11m55s
46e6a7eff5
donghyeon.kang added 1 commit 2026-11-13 18:43:53 +00:00
Merge branch 'main' into claude/r9-b-application
pr / done (pull_request) Successful in 14m31s
a9ac254373
donghyeon.kang merged commit 99cc4f59ae into main 2026-11-13 20:15:07 +00:00
donghyeon.kang deleted branch claude/r9-b-application 2026-11-13 20:15:07 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#38