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

2.7 KiB

전달 증거 모델

모양

NotificationRequest
  └─ RecipientDelivery
       └─ DeliveryAttempt
            └─ ProviderEvent (append-only)
                 └─ channel projector
                      └─ SubmissionOutcome / DeliveryOutcome / EvidenceLevel
                         + EngagementFacts + SuppressionFacts

신원 넷, 수명 주기 넷이다. 논리 요청은 수신자 작업이 아니고, 수신자 작업은 provider attempt가 아니고, provider attempt는 그것을 설명하는 이벤트 흐름이 아니다.

상태 enum 하나가 아닌 이유

일직선 상태 하나는 「무슨 일이 있었나」에 값 하나로 답해야 하는데, 실제 답은 한 줄에 들어가지 않는다.

  • 이메일은 DELIVERED가 된 뒤 complaint를 낼 수 있다. 두 사실이 다 참이고 다 중요하다. 하나는 보고에, 다른 하나는 억제에 쓴다.
  • Twilio는 콜백 순서를 보장하지 않아서 sent가 delivered 뒤에 오는 일이 흔하다. 순번 규칙에서는 뒤에 온 약한 이벤트가 강한 이벤트를 조용히 덮어쓴다.
  • APNs는 알림을 수락한 뒤 저장하거나, 바꾸거나, 버릴 수 있다.

그래서 ledger는 이벤트를 저장하고, channel projector가 명시한 전이 표로 그것을 합친다. 공통 규칙은 StandardDeliveryProjector가 가지고, provider projector는 자기 이벤트 어휘만 더한다.

합치는 규칙

전이 결과
sent → delivered 적용
delivered → sent 무시, 이벤트는 저장
delivered → complaint complaint 사실을 더하고 전달은 유지
complaint → delivered 전달을 적용하고 complaint는 유지
accepted → bounced 적용
read → displayed 무시
hard bounce → delivered 무시, hard bounce는 끝 상태

참여(opened, clicked)는 전달 결과 옆에 저장하고 그것을 바꾸지 않는다.

모호함

platform ──── send ────▶ provider
                            │
                            └── accepted
        ✗ connection reset

알림이 실제로 보내졌는데 플랫폼은 provider request id를 하나도 가지지 못할 수 있다. attempt는 requestStarted, requestBodyCommitted, providerResponseReceived와 그 각각의 EvidenceCertainty를 기록한다. 그래서 나중의 판단이 「아무것도 보내지 않았음을 안다」와 「답을 읽지 못했다」를 가릴 수 있다.

ProviderSubmissionResult가 이것을 강제한다. 모호한 결과는 PROVIDER_ACCEPTED를 주장할 수 없고, 어떤 제출 결과도 전달 결과를 실을 수 없다.