문제: `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 …)").
6.6 KiB
알림 지원 매트릭스
채널마다 실제로 증명할 수 있는 것과, 플랫폼이 주장하기를 거부하는 것이다.
등급 칸은 의견이 아니다. docs/notification/evidence-manifest.json이 등급마다 필요한 claim과 claim마다 그것을 증명하는
실행 산출물을 선언하고, NotificationEvidenceVerifierTest(:adapter:outbound:notification:test)가 claim이 모두 실제
파일로 뒷받침되지 않은 등급을 거부한다. 등급을 올리려면 산출물을 먼저 더한다.
2026-08-15까지 다섯 채널이 Stable이었다. 파이프라인의 어떤 것도 provider에 요청을 보낸 적이 없었고(sandbox job의 본문
전체가 continue-on-error 뒤의 echo 두 줄이었다), 발송 도중 worker를 죽인 테스트도 없었다. 프로토콜은 구현돼 있고 그
계약은 실제 PostgreSQL에서 증명됐지만, 실제 전송과 장애 중단은 증명되지 않았다. 지금 등급이 말하는 것이 그것이다.
채널
| 채널 | 참조 구현 | 등급 | 플랫폼이 기본으로 기록하는 가장 강한 증거 |
|---|---|---|---|
| SMTP, Amazon SES API | Contract implemented / runtime unqualified | provider 수락. provider가 이벤트를 내면 수신 메일 서버 전달, bounce, complaint | |
| SMS | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(docs/capability-status.md 제거된 코드) |
Extension | 더한 provider 어댑터가 증명할 수 있는 것 |
| 모바일 push(FCM, APNs) | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(docs/capability-status.md 제거된 코드) |
Extension | 더한 provider 어댑터가 증명할 수 있는 것 |
| Web Push | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(docs/capability-status.md 제거된 코드) |
Extension | 더한 provider 어댑터가 증명할 수 있는 것 |
| 앱 안 inbox | 자체 DB | Optional stable | PERSISTED, SEEN, READ |
| Webhook | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(docs/capability-status.md 제거된 코드) |
Extension | 받는 HTTP 계약이 말하는 것 |
내보내는 provider 조립이 닿는 범위
위 등급은 프로토콜·신뢰성 증거를 말한다. 모든 참조 구현을 기본 조립에서 고를 수 있다는 뜻이 아니다. 발송이 닿는지는 따로 보는 축이다.
| provider family | 내보내는 조립의 발송 assembler | 콜백 assembler | 지금 쓰임 |
|---|---|---|---|
| SMTP | 있음 | 없음 | EMAIL 발송 참조 family |
| SES | 있음 | 있음 | EMAIL 발송 + SNS 콜백 수집. 꺼진 참조 profile이 config/module-defaults/notification.yml(composition:notification-platform)에 들어 있다 |
APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있다가 지워졌다. 이제
ProviderType에는 SES와 SMTP만 있으므로 그런 profile은 모르는 종류로 바인딩에서 실패한다. assembler가 없는 켜진 발송
profile은 profile·family 이름을 대며 기동에 실패한다. 빈 런타임으로 조용히 조립되는 일은 없다. SMTP는 relay가 설정되지
않아 내보내는 assembler가 없으면 spring.mail.host도 이름 댄다.
등급마다 필요한 것
| 등급 | 필요한 claim |
|---|---|
| Stable | durable, multi-worker-safe, callback-supported, recoverable, provider-wire-qualified |
| Contract implemented / runtime unqualified | durable, multi-worker-safe, callback-supported |
| Optional stable | durable |
| Extension | 없음. 받는 쪽 계약이 자기 보장을 가진다 |
| Experimental | 없음. 등급 자체가 경고다 |
recoverable은 테스트 둘이 뒷받침한다. WorkerCrashRecoveryContractTest는 발송이 지나는 네 단계(claim됨, attempt 기록됨,
요청 시작됨, 본문 커밋됨)를 따라가며 단계마다 죽은 worker가 남기는 행을 고정한다. 지난 lease, 그리고 attempt insert부터는
그 단계의 증거를 가진 끝나지 않은 attempt다. 그 행을 테스트가 직접 쓰므로, 복구가 아니라 복구의 입력을 확인한다.
PostgreSqlNotificationBackgroundPassIntegrationTest는 dispatcher 자신의 factory가 쓴 행에 lease 복구와 맞추기를 돌리고
결과를 단언한다. attempt 전이면 다시 큐에 넣고, attempt 뒤면 맞춘다(review 05-01, RR-03-07).
남은 미충족 claim과 그것을 채울 것:
- provider-wire-qualified — 실제 provider sandbox 호출로 correlation id가 있는 불변 산출물을 만들어 올린다. CI에서 프로세스 밖으로 요청이 나간 적이 한 번도 없다.
증거 수준
NONE → PLATFORM_QUEUED → PROVIDER_ACCEPTED → NETWORK_OR_CARRIER_ACCEPTED →
DEVICE_DELIVERED → USER_AGENT_DISPLAYED → USER_READ
| provider 신호 | 그 신호가 낼 수 있는 가장 높은 증거 |
|---|---|
| 내부 큐 커밋 | PLATFORM_QUEUED |
SES MessageId |
PROVIDER_ACCEPTED |
SES Delivery |
NETWORK_OR_CARRIER_ACCEPTED |
| 앱 안 행 커밋 | PROVIDER_ACCEPTED |
앱 안 seen 엔드포인트 |
USER_AGENT_DISPLAYED |
앱 안 read 엔드포인트, 인증된 앱 수신 확인 |
USER_READ |
플랫폼이 코드에서도 설정에서도 하지 않는 승격:
- 배포가 더한 어느 provider 어댑터에서 온 것이든 push·SMS 수락은
DEVICE_DELIVERED가 아니다. - provider의 2xx는
DELIVERED가 아니다. - SES
MessageId는DELIVERED가 아니다. - SMTP
250은 받은편지함 도착이 아니다.
제출 결과
NOT_SUBMITTED, CONFIRMED_ACCEPTED, CONFIRMED_REJECTED, AMBIGUOUS.
AMBIGUOUS는 오류 경로가 아니라 정식으로 저장되는 상태다. 요청 본문을 provider에 넘겼지만 결과를 읽지 못했다는 뜻이다.
수신자 전달에 모호한 attempt가 있는 동안에는 자동 재시도와 자동 채널 전환이 모두 막힌다.
지원하지 않는 것
위의 어떤 채널도 뒷받침할 수 없으므로 플랫폼은 다음 중 어떤 것도 주장하지 않는다.
- 전달 보장(guaranteed delivery)
- 읽음 보장(guaranteed read)
- 사람에게 가는 알림의 정확히 한 번(exactly-once) 전달
- 읽지 못한 응답 뒤의 조건 없는 다중 provider failover
- 공개 API의 provider SDK 타입
- 대상 선정, 캠페인 세분화, 관할 판정
대상 모델
FCM_FID가 모바일 push의 기본 대상이다. FCM_REGISTRATION_TOKEN_LEGACY와 APNS_DEVICE_TOKEN은 수명 주기가 다른 별도
종류다. 하나의 문자열 칸으로 합치지 않는다.