Files
clean-architecture-backend-…/docs/notification/migration-guide.md
DongHyeonka 5a860e1e6b docs(notification): 알림 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.

고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
  그대로다.
- 코드에 맞춘 주장:
  - configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
    (`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
    (`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
    적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
  - at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
    지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
    `NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
    결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
    문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
    대로 짧은 교체 순서를 더했다.
  - module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
    「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
    provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
  옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
  있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
  거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
  표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.

버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.

위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:notification:check` rc=0(375개 건너뜀 1 실패 0. `NotificationReleaseGateTest` 3,
  `NotificationEvidenceVerifierTest` 7, `NotificationModeSsotTest` 3, `NotificationPayloadAtRestContractTest` 5),
  `:mainCheck` rc=0(`notificationDocumentContractTest`의 저장소 문서 대조 통과), `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `NotificationReleaseGateTest` 2개와 저장소 문서 대조가 실패한다
  ("support-matrix.md has no table that assigns a grade (a '등급' column …)").
2026-11-07 17:56:34 +09:00

2.5 KiB

이행 안내

R0 routing seam에서

이미 있던 dev.caskeleton.adapter.outbound.notification router(RoutingNotifier, FailOpenNotificationProvider, Google email과 Slack webhook seam)는 건드리지 않는다. 전달 플랫폼은 그 옆 …notification.platform 아래에 있고, R0 클래스를 고치거나 지우지 않는다.

capability마다 이행 순서:

  1. 플랫폼이 보호된 값을 가지도록 연락처를 ContactPointStorePort 뒤에 등록한다.
  2. 템플릿 버전을 게시하고, 모든 호출 지점에서 템플릿 id, 버전, locale을 고정한다.
  3. 호출 지점을 router에서 그 채널의 N1 typed facade로 옮긴다.
  4. 증거는 호출자의 반환값이 아니라 snapshot에서 확인한다. submit()은 durable 수락일 뿐이다.
  5. 대상 환경에서 플랫폼 route가 provider 증거를 낸 뒤에만 R0 route를 지운다.

반환값의 뜻이 바뀐다

R0 seam은 보낸 결과 모양을 돌려줬다. NotificationReceipt는 notificationId, 요청 상태, 수락 시각을 돌려준다. 옛 반환값을 전달 증거로 다룬 호출자는 고쳐야 한다. 호환 shim은 없다. shim은 이 플랫폼이 피하려고 있는 전달 주장을 지어내야 하기 때문이다.

FCM 대상 이행

registration token은 LegacyFcmRegistrationToken으로 계속 쓸 수 있다. 새 등록은 FcmInstallationId를 쓴다. 둘은 서로 다른 타입이라 이행은 런타임 짐작이 아니라 컴파일 시점의 일이다.

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의 「제거된 코드」 표에 있다.