Files
clean-architecture-backend-…/docs/notification/support-matrix.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

103 lines
6.6 KiB
Markdown

# 알림 지원 매트릭스
채널마다 실제로 증명할 수 있는 것과, 플랫폼이 주장하기를 거부하는 것이다.
등급 칸은 의견이 아니다. `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에서 증명됐지만, 실제 전송과 장애 중단은 증명되지 않았다. 지금 등급이 말하는 것이 그것이다.
## 채널
| 채널 | 참조 구현 | 등급 | 플랫폼이 기본으로 기록하는 가장 강한 증거 |
|---|---|---|---|
| Email | 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`은 수명 주기가 다른 별도
종류다. 하나의 문자열 칸으로 합치지 않는다.