Files
clean-architecture-backend-…/docs/notification/module-mapping.md
T
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

8.1 KiB

알림 전달 플랫폼 — 모듈 대응표

출처 설계서: docs/design/2026-08-10-notification-platform-design.md

출처 계획서: docs/history/plans/2026-08-10-notification-platform-implementation-plan.md

대응표가 있는 이유

계획은 가상의 저장소(modules/notification/**, root 패키지 io.backend.skeleton.notification, Gradle 프로젝트 31개)를 두고 쓰였다. 이 저장소는 fail-closed Clean Architecture 템플릿이다. src/settings.gradle은 registry (src/config/architecture/modules.json)를 읽고 검증한 뒤 등록된 프로젝트만 들이고, verifyCleanArchitectureDependencies는 allowed_dependencies 밖의 프로젝트 edge를 거부한다.

Gradle 프로젝트 31개를 새로 만들면 AGENTS.md의 HARD-STOP #5를 어긴다. 패키지 README도 이것을 내다보고, 공개 계약과 신뢰성 의미를 지키면서 의존성 카탈로그와 패키지·파일 경로를 받는 저장소의 규칙에 맞추라고 구현자에게 지시한다.

그래서 계획의 논리 모듈마다 그 책임을 가진 등록 leaf 안의 패키지로 구현했다. 공개 계약, 증거 규칙, 신뢰성 의미는 하나도 빠지지 않았다.

논리 모듈 → 등록 leaf

계획 모듈 등록 leaf 패키지
notification-core-api application-notification dev.caskeleton.application.notification.platform.api
notification-content-api application-notification …platform.api.content
notification-contact-api application-notification …platform.contact
notification-template-api application-notification …platform.template
notification-policy application-notification …platform.policy
notification-provider-spi application-notification …platform.provider
notification-callback-api application-notification …platform.callback
notification-inbox-api application-notification …platform.inbox
notification-admin-api application-notification …platform.admin
notification-security (ports) application-notification …platform.security
notification-observability (ports) application-notification …platform.observation
notification-dispatch-runtime adapter:outbound:notification dev.caskeleton.adapter.outbound.notification.platform.dispatch
notification-security (AES-GCM/HMAC impl) adapter:outbound:notification …platform.security
notification-template-thymeleaf (reference renderer) adapter:outbound:notification …platform.template
notification-email-smtp adapter:outbound:notification …platform.provider.smtp
notification-email-ses adapter:outbound:notification …platform.provider.ses
notification-observability (Micrometer impl) adapter:outbound:notification …platform.observation
notification-admin-runtime adapter:outbound:notification …platform.admin
notification-spring-boot-starter adapter:outbound:notification …platform.autoconfigure
notification-persistence-jpa adapter:outbound:persistence-notification dev.caskeleton.adapter.outbound.persistence.notification.platform(저장소 어댑터), ….platform.entity(JPA 행), ….platform.repository(Spring Data interface와 SQL 문)
notification-inbox-jpa adapter:outbound:persistence-notification …persistence.notification.platform(JpaNotificationInbox, InboxCommitEventPublisher, InboxOutboxRecordFactory). 행과 repository는 ….platform.entity / ….platform.repository
notification-callback-mvc adapter:inbound:web-notification dev.caskeleton.adapter.inbound.web.notification.platform.callback
notification-submission-mvc adapter:inbound:web-notification dev.caskeleton.adapter.inbound.web.notification.platform.submission
애플리케이션 조립(use case, 콜백 bridge, config/module-defaults/notification.yml) composition:notification-platform dev.caskeleton.composition.notification
notification-testkit 소유 leaf의 test source set …platform.testkit

의존 방향의 결과

계획의 모듈 DAG(*-api → provider-spi/policy → runtime/adapters → starter)는 registry가 이미 강제하는 leaf DAG로 지켜진다.

application-notification (all *-api, provider SPI, policy, callback contracts; → application-core)
        ↑                        ↑                      ↑
adapter:outbound:notification    adapter:outbound:persistence-notification    adapter:inbound:web-notification
        ↑                                    ↑ (runtimeOnly, with persistence-jpa)    ↑ (→ adapter:inbound:web)
        └──────────── composition:notification-platform ───────────────────────┘
                                   ↑
                             app-bootstrap (one line)

계획의 edge 둘은 이 저장소에서 프로젝트 edge로 표현할 수 없어서 port로 바꿨다.

  1. notification-email-ses → httpclient platform. (이 edge를 함께 쓰던 Twilio, FCM, APNs, Web Push, Webhook 어댑터는 assembler가 없어서 지웠다.) adapter-outbound-notification은 adapter-outbound-httpclient에 의존할 수 없고, SES는 이제 그것이 필요 없다. SES 어댑터는 스스로 요청에 서명하는 AWS SDK v2 sesv2 클라이언트로 보낸다(소유자 결정 17). 어댑터 안의 JDK HTTP gateway와 SigV4 signer는 그 변경과 함께 지웠다. 클라이언트는 profile마다 SDK 재시도를 끄고, 기본 credential chain 없이(요청마다 자기 profile의 자격 증명을 싣는다), profile의 endpoint로 만든다. 그 endpoint는 여전히 알림 routability guard를 통과한다.
  2. notification-inbox-jpa → optional messaging outbox integration. adapter-outbound-persistence-notification은 adapter-outbound-messaging에 의존할 수 없다. inbox는 이미 있는 persistence outbox 테이블과 애플리케이션 port NotificationInboxSignalPort로 내보내고, outbox relay는 composition:outbox-relay가 조립한다.

커밋 정책

AGENTS.md는 커밋 정책을 human-only로 고정한다. 그래서 계획의 모든 task에 있는 Step 5(git add / git commit)는 에이전트가 일부러 하지 않았다. 작업 트리가 변경을 싣고, 사람 소유자가 커밋한다.

R1 어댑터 정리 뒤 런타임 도달 범위

NOTIF-ADR-005가 다루는 애플리케이션 R1 계약은, 그것을 둘러싸고 만들었다가 버린 outbound 구현과는 다른 문제다. 뒤의 것은 없어졌다. 알림 leaf에는 최상위 catalog/, provider/, template/ R1 어댑터 패키지가 더는 없다. 그것들은 운영 조립의 consumer가 없었고 자기 fake로만 증명됐다.

그 실험의 쓸모 있던 렌더링 불변식은 버리지 않았다. R2 platform.template.TemplateSlotPolicy가 이제 치환한 값을 escape하는 것에 더해, 최종 HTML을 검토한 태그·속성 부분집합과 대조한다. 실행되는 script markup, event handler 속성, HTTPS가 아닌 HTML 링크는 거부한다.

R2 provider 프로토콜 패키지는 canonical 플랫폼 SPI를 구현하고 계약 테스트가 있어서 남아 있다. 남은 것은 ses와 smtp이고, 둘 다 내보내는 조립이 발송에 쓴다(SES는 콜백 받기에도 쓴다). 다른 family는 조립이 그 family에 필요한 설정·secret 출처와 함께 ProviderRuntimeAssembler를 보탤 때 생긴다. 표는 support-matrix.md에 있다.

R1 public type (NOTIF-ADR-005)

NOTIF-ADR-005가 ..notification.platform..을 canonical로 정했다. dev.caskeleton.application.notification 바로 아래의 R1 타입은 운영 consumer가 없어서, 두 namespace를 떼어 놓던 ArchUnit 규칙과 함께 2026-09-25에 지웠다. 거기 남은 것은 어댑터 core가 구현하는 단순 알림 port NotificationPort, Notification, NotificationChannel이다. 지운 타입과 마지막 커밋은 docs/capability-status.md 「제거된 코드」에 있다.