Files
clean-architecture-backend-…/docs/notification/migration-guide.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

2.5 KiB

Migration guide

From the R0 routing seam

The pre-existing dev.caskeleton.adapter.outbound.notification router (RoutingNotifier, FailOpenNotificationProvider, the Google email and Slack webhook seams) stays untouched. The delivery platform lives beside it under …notification.platform and does not modify or delete any R0 class.

Migration order per capability:

  1. Register the contact points behind ContactPointStorePort so the platform owns protected values.
  2. Publish the template version, and pin the template id, version and locale at every call site.
  3. Move the call site from the router to the N1 typed facade for the channel.
  4. Verify evidence in the snapshot rather than in the caller's return value: submit() is durable acceptance and nothing more.
  5. Remove the R0 route only after the platform route has produced provider evidence in the target environment.

Return-value semantics change

The R0 seam returned a send-shaped result. NotificationReceipt returns notificationId, a request status and an acceptance time. Callers that treated the old return value as proof of delivery must be changed; there is no compatibility shim, because a shim would have to invent the delivery claim this platform exists to avoid.

FCM target migration

Registration tokens keep working through LegacyFcmRegistrationToken. New registrations should use FcmInstallationId. The two are distinct types, so a migration is a compile-time task rather than a runtime guess.

R1의 처분 (NOTIF-ADR-005)

이 문서는 R0 router → platform 이행만 설명해 왔고, dev.caskeleton.application.notification 직속의 R1 public type 100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지 문서 어디에도 답이 없었다.

  • canonical은 ..notification.platform..이다. NOTIF-ADR-005가 근거와 함께 정한다.
  • application R1 public type은 2026-09-25에 삭제했다. production consumer가 0건이었다. 남은 것은 단순 알림 포트 NotificationPort·Notification·NotificationChannel뿐이다.
  • R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의 catalog/, provider/, template/ 실험 구현도 제거했다. 실제 runtime은 dev.caskeleton.adapter.outbound.notification.platform..만 사용한다.
  • 삭제 목록과 마지막 커밋은 docs/capability-status.md의 「제거된 코드」 표에 있다.