Files
clean-architecture-backend-…/src/adapter/outbound/notification
DongHyeonka 8813b02e54 docs(adapter-outbound): outbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가
영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전
(4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열·
표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을
가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다:
identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는
hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap
`IdempotencySettings`」를 실제 위치 `composition:idempotency`로,
redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로
mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는
지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다
(MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한
곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가
아직 영어라 원문 제목으로 둔다.

위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면
낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음
커밋에서 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄
10개 지움, src/** number 줄 0), check-work-docs.py rc=0,
--links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:24:33 +09:00
..

adapter:outbound:notification — R0 legacy의 사실

현재 구현 전체는 교체 전 호환성 기준선인 R0 legacy다. GoogleEmailClient와 SlackClient는 project-supplied seam일 뿐 실제 Google Mail 또는 Slack 연동이 아니며, provider/card qualification evidence도 없다.

알림(email/Slack 등) 아웃바운드 어댑터 모듈. 패키지 루트: dev.caskeleton.adapter.outbound.notification. :adapter:outbound:support 에 의존해 공유 correlation / fail-open 의존성 로깅을 재사용한다.

허용/금지 의존 정책은 src/config/architecture/modules.json의 adapter-outbound-notification row가 SSOT다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거와 canonical 구현 전 삭제 대상을 모아둔 참조용 기록이다.

Task 1 R0 사실 표

축 현재 사실 증거와 한계
application contract raw NotificationPort.notify(Channel, route, Notification) mode, transaction, receipt, attempt certainty가 없는 R0 port
routing (channel, providerId) registry + route별 provider ID list fan-out RoutingNotifierTest; route list의 모든 provider를 순서대로 호출
provider failure 모든 provider를 중앙 FailOpenNotificationProvider로 감싸고 예외를 삼킴 global fail-open이며 application kind별 정책이 아님
unbound route AdapterDisabledException fail-fast NotificationAdapterTest; disabled sentinel은 없음
email seam google-email + GoogleEmailClient interface module 안 production client/SDK/credential/protocol 구현 0
Slack seam slack-webhook + SlackClient interface module 안 production client/SDK/credential/protocol 구현 0
configuration code는 app.notification.routes.*와 provider별 *.enabled를 읽음 checked-in application.yml/env registry의 app.notification.{slack,email}.provider selector와 drift
production consumer feature/application production consumer 0 main source에는 application contract 선언, adapter 구현과 bootstrap composition만 존재
evidence grade local fake/contract baseline real provider, durability, callback, security, load evidence 0; 모든 seam R0 legacy

selector drift는 이 기준선의 일부다. Task 1에서는 고치지 않는다. canonical graph가 준비되고 cutover evidence가 생기기 전까지 기존 key를 새 의미로 재사용하거나 legacy class에 production 동작을 추가하지 않는다.

모듈 개요

application-core 포트 뒤에 두는 선택형 알림 어댑터다. @ConditionalOnProperty 로 게이팅되고 기본 비활성이다. 이 모듈이 기본 제공하는 프로바이더는 email/google(GoogleEmailProvider / GoogleEmailClient)과 slack/webhook(SlackWebhookProvider / SlackClient)이며, 실제 연동 client 는 포킹 프로젝트가 채우는 seam 이다.

(channel, providerId) 복합 키 + fan-out

RoutingNotifier 는 (channel, providerId) 복합 키로 프로바이더를 등록한다 — 채널 내 중복 providerId 는 생성 시점에 실패한다. 라우트당 providerId 목록을 주면 fan-out(모든 프로바이더 호출)이 된다. 각 프로바이더는 이미 FailOpenNotificationProvider 로 감싸져 있어 한 곳의 실패가 다른 곳을 막지 않고, 그래서 fan-out 루프에 try/catch 가 필요 없다. FailOpenNotificationProvider .send 가 throws 를 선언하지 않는 건 이 루프를 try/catch 없이 예외-free 로 증명하기 위함이다.

중앙 fail-open 합성 + 라우팅 바인딩

NotificationConfig 가 모든 프로바이더를 FailOpenNotificationProvider 로 중앙에서 감싼다(→ :adapter:outbound:support 의 FailOpenDependencyLogger 로 WARN 로깅). 라우팅은 app.notification.routes.<channel>.<route>=<providerId>[,<providerId>]. 프로바이더는 channel()+providerId() 로 키잉된 NotificationProvider 빈으로 기여한다(예: GoogleEmailProvider, SlackWebhookProvider). GoogleEmailClient/SlackClient 는 포크가 구현하는 seam 이며 실패는 데코레이터가 fail-open 처리한다.

지운 R1 outbound 실험

예전 최상위 catalog/, provider/, template/ 그래프는 운영에서 한 번도 조립되지 않았고 지웠다. 정해진 플랫폼에 닿으려고 그것을 다시 만들지 않는다. 애플리케이션 R1 공개 계약은 따로 NOTIF-ADR-005가 다룬다. 새 런타임 코드는 ..notification.platform.. 아래에 둔다.

LocalEmailRenderer에서 더 강했던 문맥 인식 HTML 안전 장치는 지우기 전에 옮겨 왔다: 이제 platform.template.TemplateSlotPolicy가 렌더링 뒤에 운영자가 쓴 HTML을 리뷰한 tag·attribute 부분집합과 대조한다.

Wave G 삭제 목록

다음 surface는 canonical-only cutover와 retained evidence 검증이 끝난 뒤 한 묶음으로 제거한다. 그 전에는 동작을 확장하지 않고 R0 회귀 기준선으로만 유지한다.

  • application R0 contract: Channel, Notification, raw NotificationPort
  • router/decorator SPI: NotificationConfig, NotificationRoutesSettings, RoutingNotifier, NotificationProvider, FailOpenNotificationProvider
  • fake-only Google email seam: GoogleEmailClient, GoogleEmailProvider, GoogleEmailNotificationAdapterConfig
  • fake-only Slack webhook seam: SlackClient, SlackWebhookProvider, SlackNotificationAdapterConfig
  • legacy configuration/tests: app.notification.routes.*, app.notification.google-email.enabled, app.notification.slack-webhook.enabled, drifted APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED/APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED, NotificationAdapterTest, RoutingNotifierTest와 bootstrap legacy gating cases

accepted 또는 indeterminate work를 inventory하지 않은 상태에서 이 목록을 삭제하거나 canonical provider로 자동 재전송하지 않는다.