Files
clean-architecture-backend-…/src/adapter/outbound/notification
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00
..

adapter:outbound:notification — R0 legacy truth

현재 구현 전체는 교체 전 호환성 기준선인 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 truth table

축 현재 사실 증거와 한계
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 처리한다.

Removed R1 outbound experiment

The old top-level catalog/, provider/, and template/ graph was never assembled by production and has been removed. Do not recreate it to reach the canonical platform. The application R1 public contract remains governed separately by NOTIF-ADR-005; new runtime code belongs under ..notification.platform...

The context-aware HTML safety that was stronger in LocalEmailRenderer was carried forward before removal: platform.template.TemplateSlotPolicy now validates operator-authored HTML against the reviewed tag/attribute subset after rendering.

Wave G deletion inventory

다음 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로 자동 재전송하지 않는다.