Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역

충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄).
This commit is contained in:
DongHyeonka
2026-11-07 18:07:16 +09:00
83 changed files with 2266 additions and 2566 deletions
+77 -87
View File
@@ -1,77 +1,53 @@
# Notification payload at rest — threat model and decision (NTF-INT-007)
# 저장된 알림 payload — 위협 모델과 결정 (NTF-INT-007)
Wave 2 Task D6 offers two branches and requires that one be chosen and implemented fully:
결론: 템플릿 변수(payload)는 저장소 경계에서 암호화한다(branch (a)). 변수를 「민감하지 않은 값」으로 제한하는 길
(branch (b))은 쓸 수 없다. 변수가 곧 메시지의 내용이기 때문이다.
- **(a) encryption** — a codec/port, ciphertext envelope, key id, rotation and history, row migration,
and a decryption-failure contract;
- **(b) restriction** — this document plus a static restriction proving the variable types cannot
carry sensitive values.
Wave 2 Task D6은 두 길을 주고, 하나를 골라 끝까지 구현하라고 요구했다.
The plan recommends (b) **"if and only if the variable types can genuinely be restricted to
non-sensitive values"**. They cannot. This document records why, what that leaves, and when the
remaining branch lands.
- **(a) 암호화** — codec·port, 암호문 envelope, key id, 교체와 이력, 행 마이그레이션, 복호화 실패 계약.
- **(b) 제한** — 이 문서, 그리고 변수 타입이 민감한 값을 담을 수 없음을 보이는 정적 제한.
## What is stored, and where
계획은 **「변수 타입을 정말로 민감하지 않은 값으로 제한할 수 있을 때만」** (b)를 권했다. 제한할 수 없다. 이 문서는
그 이유와, 그래서 고른 (a)가 지금 어떻게 들어가 있는지를 적는다.
`CanonicalNotificationPlanWriter.request(...)` puts `encoded.variablesPayload()` into
`NotificationRequestRecord` verbatim. `JpaNotificationRequestStore` writes that record to
`notification_request.variables_payload` with no transformation. There is no encryption anywhere on
this path.
## 지금 상태
## Why the restriction branch is unavailable
- `NotificationPayloadProtection`이 애플리케이션이 가진 port이고, `AesGcmNotificationPayloadProtection`이 AES-GCM
구현이다.
- `NotificationRecordMapper`가 그것을 **필수** 생성자 인자로 받아 적용한다. 그래서 payload를 평문으로 둔 채 알림
저장소를 조립할 수 없다.
- 쓰기 경로는 조립에서 닿는다. `NotificationJpaPersistenceFacade`는 persistence-notification leaf의
`AutoConfiguration.imports`가 올린다.
- 평문 행이 이미 있는 배포는 마이그레이션에서 멈춘다. `V10__variables_payload_envelope_guard.sql`은 행을 다시
암호화하지 않고, 보호되지 않은 행이 있으면 실패한다.
- `NotificationPayloadAtRestContractTest`가 이 문서가 기대는 사실을 모두 단언한다. 하나라도 거짓이 되면 그 테스트가
실패하므로, 결정이 저절로 낡지 않는다.
- 알림은 Stable이 아니다(`docs/notification/support-matrix.md`).
Template variables are a closed algebra — `NotificationVariable` permits `TextValue`, `NumberValue`,
`BooleanValue`, `NullValue`, `ListValue`, `ObjectValue` — which is a real improvement over the
`Map<String, Object>` it replaced. But `TextValue` holds an arbitrary UTF-8 string of up to 8 KiB,
and that is not an oversight to be tightened: **the variables are the recipient-specific content of
the message**. A password-reset code, an order total, a delivery address, a patient's appointment
time — those are what a notification is for.
## 무엇이 어디에 저장되나
A restriction to "non-sensitive values" would therefore be one of two things, and both are worse
than the problem:
`CanonicalNotificationPlanWriter.request(...)`는 `encoded.variablesPayload()`를 그대로 `NotificationRequestRecord`에
넣는다. 애플리케이션은 그것을 렌더링해야 하므로 여기서는 평문이 맞다. 「저장된(at rest)」은 행 안을 뜻하므로
envelope는 여기가 아니라 저장소 경계에서 씌운다. `notification_request.variables_payload`에는 base64 AES-GCM
envelope가 들어간다.
- **unenforceable** — a comment saying callers should not put sensitive data in a field designed to
carry the message's content, which is a policy no type checks and no reviewer can see violated;
- **enforced and useless** — a type that refuses free text, which does not restrict the capability so
much as delete it.
## 제한 가지를 쓸 수 없는 이유
The precondition on the plan's recommendation is false. Branch (b) is not available.
템플릿 변수는 닫힌 대수다. `NotificationVariable`은 `TextValue`, `NumberValue`, `BooleanValue`, `NullValue`,
`ListValue`, `ObjectValue`만 허용한다. 이것이 대신한 `Map<String, Object>`보다 확실히 낫다. 그러나 `TextValue`는 8 KiB까지의
아무 UTF-8 문자열을 담고, 그것은 조여야 할 실수가 아니다. **변수는 메시지의 수신자별 내용이다.** 비밀번호 재설정
코드, 주문 합계, 배송 주소, 환자의 예약 시각, 알림은 그것을 보내려고 있다.
> **Status: branch (a) implemented at the storage boundary.** `NotificationPayloadProtection` is the
> application-owned port, `AesGcmNotificationPayloadProtection` the AES-GCM implementation, and
> `NotificationRecordMapper` applies it — as a **required** constructor argument, so a composition
> cannot assemble the notification stores while leaving the payload in plaintext. What remains before
> the facade can be imported is the row migration for any deployment that already has plaintext rows,
> and the `local-notification-*` lanes. The analysis below is kept as written, because it is what the
> decision rests on.
그래서 「민감하지 않은 값」으로의 제한은 둘 중 하나가 되고, 둘 다 문제보다 나쁘다.
## Decision: branch (a), landing with the persistence wiring
- **강제할 수 없음** — 메시지 내용을 담으려고 만든 칸에 민감한 데이터를 넣지 말라는 주석. 어떤 타입도 확인하지
않고, 어떤 리뷰어도 위반을 볼 수 없는 정책이다.
- **강제하지만 쓸모없음** — 자유 텍스트를 거부하는 타입. capability를 제한한다기보다 지운다.
Encryption is therefore the required branch. Its scope is unchanged from the plan: a codec behind an
application port, a ciphertext envelope carrying its key id, key rotation with history so an old row
stays readable, a migration for existing rows, and an explicit contract for what a decryption failure
does to a request.
계획의 권고에 붙은 전제가 거짓이다. (b)는 쓸 수 없다.
**It lands in the change unit that makes the write path reachable, and not before.** The reason is a
fact the spec did not have: `NotificationJpaPersistenceFacade`, which assembles
`JpaNotificationRequestStore`, is imported by nothing. The composition root's component scan excludes
the persistence package by design, and no configuration imports the facade — so the notification
capability has **no JPA persistence at all**, and no deployment currently writes this payload
anywhere. The defect is real in the code and latent in the runtime.
Designing key rotation and a row migration for rows that no deployment produces would be building the
migration before the table. Worse, it would settle the envelope's shape before the store that has to
read it is wired, which is the order that produces an envelope the store cannot use.
**One correction, learned by trying it.** This section said the envelope "lands with the wiring".
Wiring the facade first — to register the SMTP assembler — made
`NotificationPayloadAtRestContractTest` fail on the case asserting the write path is reachable from
no composition, which is exactly what that case is for. The wave forbids connecting wiring over a
known security finding on a runtime path, so the wiring was reverted and the envelope built first.
The honest ordering is **envelope before or with the wiring, never after**, and the contract test now
enforces it by failing on the wiring alone.
### The envelope, and why it has a key id
## envelope와 key id를 두는 이유
```
byte version always 1
@@ -81,36 +57,50 @@ byte[12] nonce
byte[] ciphertext + GCM tag
```
The key id is the reason there is a format at all. This repository's callback protection stores nonce
and ciphertext and nothing else, so the day the active key changes, every row written under the
previous one becomes unreadable and nothing in the row can say which key it needed — that is not a
rotation story with a gap in it, it is the absence of one. `SecretMaterialProvider` already exposes
`keyById`, so reading the id back and asking for that specific key makes rotation a change of default
rather than a data migration. The version byte costs one byte and is what allows the format to change
at all.
형식을 두는 이유는 key id다. 이 저장소의 콜백 보호는 한때 nonce와 암호문만 저장했다. 그러면 활성 키가 바뀌는 날
앞 키로 쓴 행은 모두 읽을 수 없게 되고, 행 안의 어떤 것도 어느 키가 필요했는지 말하지 못한다. 틈 있는 교체가 아니라
교체가 없는 것이다. `SecretMaterialProvider`가 이미 `keyById`를 드러내므로, id를 다시 읽어 바로 그 키를 달라고 하면
교체는 데이터 마이그레이션이 아니라 기본값 변경이 된다. version 바이트는 1바이트이고, 형식을 바꿀 수 있게 해 준다.
The header is passed as **AAD**, not merely prefixed: without that, the key id is attacker-editable
and an envelope could be redirected at a key of the attacker's choosing.
header는 앞에 붙이기만 하는 것이 아니라 **AAD**로 넘긴다. 그러지 않으면 공격자가 key id를 고쳐 envelope를 자기가
고른 키로 돌릴 수 있다.
A failed decryption throws `NotificationPayloadUnreadableException` rather than returning empty. A
caller handed an empty payload renders every variable as nothing and sends "Hello , your code is " to
a real person — the failure delivered instead of reported. All three causes (unknown key, wrong key,
modified ciphertext) collapse into one message, because telling them apart tells an attacker which of
the three they achieved.
복호화에 실패하면 빈 값을 돌려주지 않고 `NotificationPayloadUnreadableException`을 던진다. 빈 payload를 받은
호출자는 모든 변수를 빈 값으로 렌더링해 실제 사람에게 "Hello , your code is "를 보낸다. 실패를 보고하는 대신 실패를
배달하는 것이다. 세 원인(모르는 키, 틀린 키, 고쳐진 암호문)은 한 메시지로 합친다. 셋을 구별해 주면 공격자에게 셋 중
무엇을 해냈는지 알려 주기 때문이다.
## What must not be done instead
## 키 교체 순서
**Requiring `PAYLOAD_ENCRYPTION` in `INGEST_ONLY` is not a fix.** That secret is consumed by exactly
one thing — `AesGcmCallbackPayloadProtection`, which protects raw callback bodies — and by nothing on
the accept path. Demanding it would make a deployment supply a key that protects nothing while the
payload it appears to be about stays in plaintext. The repository already has one defect of that
exact shape: `app.graphql.cursor.key-ids` (key removed 2026-09-25), which production refuses to start without and which no
code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.
설정 키는 `app.notification.platform.secrets` 아래에 있다(`notification.yml`).
## Consequence
1. 새 키 값과 새 key id를 같은 배포에서 바꾼다(예: `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY`와
`APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID`). 고정된 id는 교체를 앞 키와 구별할 수 없게 한다.
2. 같은 배포에서 밀려난 키 값을 `historical-keys.<목적>.<옛 id>` 아래에 둔다(예:
`historical-keys.PAYLOAD_ENCRYPTION.payload-2026-01`). 목적은 id에서 알아낼 수 없고, id로 키를 푸는 쪽은 목적이 다른
키를 거부한다. 그러니 다른 목적 아래 둔 옛 키는 풀리기는 해도 거부된다.
3. 옛 키로 쓴 행이 남아 있는 동안 옛 키를 그대로 둔다. `SettingsSecretMaterialProvider.keyById`는 모르는 id를 현재
키로 대신하지 않고 거부한다. 대신하면 이력의 모든 행이 읽을 때 인증 tag 실패가 된다.
Notification is **not promoted to Stable**, per the index's scope boundaries, until branch (a) is
complete. The three notification Compose lanes stay non-blocking. `NotificationPayloadAtRestContractTest`
holds every fact this decision rests on, so the decision expires automatically if any of them stops
being true — in particular, the assertion that no encryption sits on the accept path fails the moment
somebody adds one, which is the change this document is waiting for.
## 결정의 이력
> 이력: 결정 당시(Wave 2) `NotificationJpaPersistenceFacade`는 아무도 import하지 않았다. 조립 루트의 component scan은
> 설계상 persistence 패키지를 빼고, 어떤 설정도 facade를 import하지 않아서, 알림 capability에는 JPA 영속성이 아예 없었다.
> 결함은 코드에는 있고 런타임에는 숨어 있었다. 그래서 처음에는 「envelope는 그 wiring과 함께 들어간다」고 정했다.
> 아무 배포도 만들지 않는 행을 위해 키 교체와 행 마이그레이션을 설계하는 것은 테이블보다 마이그레이션을 먼저 짓는
> 일이었다.
>
> 해 보고 배운 정정이 하나 있다. SMTP assembler를 등록하려고 facade를 먼저 wiring하자,
> `NotificationPayloadAtRestContractTest`의 「쓰기 경로가 어느 조립에서도 닿지 않는다」 단언이 실패했다. 그 단언은 바로
> 그것을 잡으려고 있었다. Wave는 런타임 경로에 알려진 보안 발견을 둔 채 wiring을 잇는 것을 막았으므로 wiring을 되돌리고
> envelope를 먼저 지었다. 맞는 순서는 **envelope를 wiring 전이나 함께, 뒤에는 절대 아니다**이다.
>
> 결정 당시 `PAYLOAD_ENCRYPTION` secret을 쓰는 곳은 원본 콜백 본문을 보호하는 `AesGcmCallbackPayloadProtection` 하나뿐이었고
> 받기 경로에는 없었다. 그래서 `INGEST_ONLY`에서 그것을 요구하는 것은 고침이 아니었다. 아무것도 보호하지 않는 키를
> 배포에 요구하고, 그것이 다룬다고 보이는 payload는 평문으로 남는다. 저장소에는 이미 그런 꼴의 결함이 하나 있었다.
> `app.graphql.cursor.key-ids`(2026-09-25에 키를 지움)는 운영이 그것 없이는 뜨지 않으면서, 어떤 코드도 그것으로 cursor에
> 서명하지 않았다(GQL-INT-003). 지금은 `AesGcmNotificationPayloadProtection` 하나가 같은 envelope로 받은 payload와 보관하는
> 콜백을 모두 덮고, `NotificationSecretRequirements`가 이 목적을 모든 설정에서 요구한다.
>
> 결정 당시 결론은 이랬다. 알림은 색인의 범위 경계에 따라 (a)가 끝날 때까지 Stable로 올리지 않는다. 알림 Compose
> lane 셋은 막지 않는 lane으로 둔다.
+27 -28
View File
@@ -1,6 +1,6 @@
# Callbacks and reconciliation
# 콜백과 맞추기(reconciliation)
## Ingestion order
## 받는 순서
```text
body size limit
@@ -16,41 +16,40 @@ body size limit
→ 2xx
```
Appending before projecting is what makes a fast 2xx honest. The provider is told the event is
recorded, and a projector defect becomes a replay problem rather than a lost event.
projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고,
projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.
A rejected signature is recorded in the security audit, never in the provider event ledger. Writing
it to the ledger would let anyone who can reach the endpoint fill a delivery history with noise.
서명이 거부된 콜백은 provider event ledger가 아니라 보안 감사에 기록한다. ledger에 쓰면 엔드포인트에 닿는 누구나
전달 이력을 잡음으로 채울 수 있다.
## Duplicates and ordering
## 중복과 순서
Duplicate suppression uses `(providerProfileId, providerEventId)` where the provider supplies an
event id, and a deterministic fingerprint over profile, request id, event type, occurrence time and
payload digest where it does not. A duplicate is acknowledged and projected exactly once.
중복 억제는 provider가 event id를 주면 `(providerProfileId, providerEventId)`를 쓰고, 주지 않으면 profile, request id,
event 종류, 발생 시각, payload digest로 만든 결정적 fingerprint를 쓴다. 중복은 확인 응답하고 projection은 정확히 한 번
한다.
Out-of-order callbacks are normal. Ordering is resolved by event semantics, not by arrival time.
순서가 뒤바뀐 콜백은 보통이다. 순서는 도착 시각이 아니라 이벤트의 뜻으로 정한다.
## Unknown fields
## 모르는 칸
Callback parsers tolerate unknown JSON fields. Normalization only rejects a payload when a field
required to identify the attempt is missing. Providers add fields; that must not stop ingestion.
콜백 parser는 모르는 JSON 칸을 받아들인다. 정규화는 attempt를 가리키는 데 필요한 칸이 없을 때만 payload를 거부한다.
provider는 칸을 더한다. 그것 때문에 받기가 멈추면 안 된다.
## Reconciliation
## 맞추기
Reconciliation targets:
맞추기 대상:
- attempts stuck in `DISPATCHING` past their lease
- ambiguous submissions
- accepted attempts whose callback SLA has expired
- unmatched provider events
- lease가 지나도 `DISPATCHING`에 멈춘 attempt
- 모호한 제출
- 콜백 SLA가 지난, 수락된 attempt
- 짝이 없는 provider 이벤트
A confirmed query result is appended to the same ledger with `source = RECONCILIATION` and projected
by the same projector, so projection replay stays possible: there is no privileged second path that
writes projections directly.
확인된 조회 결과는 `source = RECONCILIATION`으로 같은 ledger에 추가하고 같은 projector가 projection한다. 그래서
projection replay가 계속 가능하다. projection을 직접 쓰는 특별한 두 번째 길은 없다.
Where a provider has no status-query capability, the platform records `Unsupported` and leaves the
attempt ambiguous. It does not infer a final status.
provider에 상태 조회 기능이 없으면 플랫폼은 `Unsupported`를 기록하고 attempt를 모호한 채로 둔다. 최종 상태를 짐작하지
않는다.
The shipped families, SES and SMTP, have no reconciliation: their assemblers contribute no
`ReconciliationCapability`, so every reconciliation job for them ends `Unsupported`. The slot on
`AssembledProvider` is for a provider family an adopter assembles with a status query of its own.
내보내는 family인 SES와 SMTP는 맞추기가 없다. 그 assembler는 `ReconciliationCapability`를 보태지 않으므로, 둘의 맞추기
작업은 모두 `Unsupported`로 끝난다. `AssembledProvider`의 그 자리는 도입하는 쪽이 자기 상태 조회와 함께 조립하는 provider
family를 위한 것이다.
+144 -153
View File
@@ -1,211 +1,202 @@
# Configuration reference
# 설정 참조
The notification delivery platform binds under `app.notification.platform`. The tree lives in
`src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`,
which the support leaf's `ModuleDefaultsEnvironmentPostProcessor` loads at the lowest precedence,
so an application without the module carries none of it. The module is in no default composition: a
service selects it with `runtimeOnly project(':composition:notification-platform')` (plus the
persistence-jpa line) in `app-bootstrap/build.gradle`, and it is on when present. Every value carries
an inline default, so a deployment that switches the platform off supplies nothing.
알림 전달 플랫폼은 `app.notification.platform` 아래에 묶인다. 설정 트리는
`src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`에 있고,
support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽는다. 그래서 이 모듈이 없는
애플리케이션에는 이 설정이 하나도 없다. 이 모듈은 어느 기본 조립에도 없다. 서비스가
`app-bootstrap/build.gradle`에 `runtimeOnly project(':composition:notification-platform')`(와 persistence-jpa 줄)를
더해 고르고, 모듈이 있으면 켜진다. 값마다 기본값이 붙어 있으므로 플랫폼을 끄는 배포는 아무것도 주지 않아도 된다.
Until 2026-08-15 this page named properties the binding did not have — `max-retry-concurrency`,
`scheduler-poll-interval`, `callback-worker-concurrency` — and omitted three it did. There was no
tree in `application.yml` at all, so the only way to configure the platform was to guess environment
variable names from Boot's relaxed binding. `NotificationEnvironmentRegistryTest`
(`:composition:notification-platform:test`) now fails when the shipped YAML and
`docs/registries/env-keys.yaml` disagree.
> 이력: 2026-08-15까지 이 문서는 바인딩에 없는 속성(`max-retry-concurrency`, `scheduler-poll-interval`,
> `callback-worker-concurrency`)을 적었고, 있는 속성 셋을 빠뜨렸다. `application.yml`에 트리가 아예 없어서, 플랫폼을
> 설정하려면 Boot의 relaxed binding으로 환경 변수 이름을 짐작해야 했다.
## Master switch
지금은 내보내는 YAML과 `docs/registries/env-keys.yaml`이 다르면 `NotificationEnvironmentRegistryTest`
(`:composition:notification-platform:test`)가 실패한다.
| Property | Environment variable | Default | Meaning |
## 주 스위치
| 속성 | 환경 변수 | 기본값 | 뜻 |
|---|---|---|---|
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | On while the module is present. `false` binds nothing at all: no runtime, no schema check, no scheduler thread, no secret required |
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch: it builds no provider runtime but records each enabled profile's route, so a request accepted now is delivered later on that route by a `SERVING` deployment (handoff) |
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | 모듈이 있으면 켜진다. `false`면 아무것도 묶지 않는다. 런타임도, 스키마 검사도, scheduler 스레드도, 필요한 secret도 없다 |
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING`은 동작하는 provider가 없으면 뜨기를 거부한다. `INGEST_ONLY`는 요청을 저장만 하고 보내지 않는다. provider 런타임을 만들지 않지만 켜진 profile마다 route를 기록하므로, 지금 받은 요청은 나중에 `SERVING` 배포가 그 route로 보낸다(handoff) |
## Dispatch
## 발송
| Property | Environment variable | Default | Bound |
| 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---|
| `dispatch.claim-batch-size` | `APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE` | `50` | 1..1000 |
| `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | positive, finite |
| `dispatch.poll-interval` | `APP_NOTIFICATION_PLATFORM_POLL_INTERVAL` | `1s` | positive, finite |
| `dispatch.max-global-concurrency` | `APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY` | `64` | positive |
| `dispatch.max-additional-attempts` | `APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS` | `4` | non-negative |
| `dispatch.max-queue-age` | `APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE` | `24h` | positive |
| `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | 양수, 유한 |
| `dispatch.poll-interval` | `APP_NOTIFICATION_PLATFORM_POLL_INTERVAL` | `1s` | 양수, 유한 |
| `dispatch.max-global-concurrency` | `APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY` | `64` | 양수 |
| `dispatch.max-additional-attempts` | `APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS` | `4` | 0 이상 |
| `dispatch.max-queue-age` | `APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE` | `24h` | 양수 |
| `dispatch.allow-ambiguous-fallback` | `APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK` | `false` | boolean |
Every value is bounded. "Unlimited" is not an accepted configuration.
모든 값에 상한이 있다. 「무제한」은 받는 설정이 아니다.
The lease must outlast a provider call plus its timeout. Below that, a delivery a live worker is
still waiting on gets claimed by a second worker, and the recipient receives the notification twice.
lease는 provider 호출과 그 시간 상한보다 길어야 한다. 그보다 짧으면, 살아 있는 worker가 아직 기다리는 전달을 두 번째
worker가 claim하고, 수신자는 알림을 두 번 받는다.
## Callbacks
## 콜백
| Property | Environment variable | Default | Bound |
| 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---|
| `callbacks.enabled` | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED` | `false` | boolean |
| `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65251` | 1..65251 |
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `1h` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected. The default is SNS's longest HTTP/S retry period (3,600 s), so a bounce or complaint SNS redelivers after an outage is still accepted; a replay inside the window is a duplicate in the provider event ledger, not a second event (review 05-20) |
| `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `1h` | 양수. `Timestamp`가 받은 시각에서 이보다 멀리(앞이든 뒤든) 떨어진 SNS 메시지는 거절한다. 기본값은 SNS의 HTTP/S 재시도 기간 중 가장 긴 값(3,600 s)이라, 장애 뒤에 SNS가 다시 보내는 bounce·complaint도 받는다. 창 안의 replay는 provider event ledger에서 중복이지 두 번째 이벤트가 아니다(review 05-20) |
콜백 응답: 기록(중복 포함) `204`, 거절 `400`(서명·topic·시각·형식), 본문 초과 `413`. SNS 서명 인증서를 가져오지 못하면(5xx·408·429·네트워크 실패) 거절하지 않고 `503`+`Retry-After`로 답한다 — SNS는 4xx를 처리 완료로 보고 재전송을 멈추지만 5xx는 다시 보낸다(review 05-20). 인증서 URL이 그 밖의 4xx(403·404 등)로 답하면 SNS가 발급하지 않은 인증서를 가리킨 위조 콜백이므로 서명 검증 실패로 `400` 거절하고 보안 감사(`callbackSignatureRejected`)에 남긴다(review 2026-11-03 RR-07-03). 호스트 검사를 통과한 URL이라 답하는 쪽은 SNS다.
콜백 응답: 기록(중복 포함) `204`, 거절 `400`(서명·topic·시각·형식), 본문 초과 `413`. SNS 서명 인증서를 가져오지
못하면(5xx·408·429·네트워크 실패) 거절하지 않고 `503`+`Retry-After`로 답한다. SNS는 4xx를 처리 완료로 보고 재전송을
멈추지만 5xx는 다시 보낸다(review 05-20). 인증서 URL이 그 밖의 4xx(403·404 등)로 답하면 SNS가 발급하지 않은 인증서를
가리킨 위조 콜백이므로 서명 검증 실패로 `400` 거절하고 보안 감사(`callbackSignatureRejected`)에 남긴다(review
2026-11-03 RR-07-03). 호스트 검사를 통과한 URL이라 답하는 쪽은 SNS다.
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다.
`trusted-proxies`가 비어 있으면 forwarded 헤더를 **믿지 않고** 컨테이너가 관측한 값을 쓴다. 무조건 믿으면
아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다. 로드밸런서 뒤에 있는 배포는
그 peer를 명시한다.
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다. provider가
서명한 URL은 컨테이너가 보고한 값으로 다시 만든다. 콜백 전용 proxy 목록은 없다. 로드밸런서 뒤에 있는 배포는
`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`로 두고 그 proxy를 `server.tomcat.remoteip.internal-proxies`에 적는다.
forwarded 헤더를 무조건 믿으면 아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다.
65251 is not a round number by accident: it is the ciphertext column's 65536 bytes minus the largest
envelope the protector writes — a version byte, a key-id length byte, a key id of up to 255 bytes, the
AES-GCM nonce and tag. A larger configured value is refused when the settings bind, so the capability
does not start; before that check existed it passed every layer above the database and failed the
`CHECK` constraint after the callback had already been acknowledged to the provider. The shipped
default was 65508 (nonce and tag only) for a while after the envelope gained its key id, and every
deployment that turned the platform on failed to start until it was corrected (review 2026-11-01
r3-i, found by booting the compose lanes).
65251은 우연히 고른 수가 아니다. 암호문 칸의 65536바이트에서 protector가 쓰는 가장 큰 envelope를 뺀 값이다. version
바이트, key id 길이 바이트, 255바이트까지의 key id, AES-GCM nonce와 tag다. 이보다 큰 값은 설정을 묶을 때 거부되므로
capability가 뜨지 않는다. 그 검사가 생기기 전에는 DB 위의 모든 층을 통과한 뒤, 콜백을 provider에 이미 확인 응답한 다음
`CHECK` 제약에서 실패했다.
## Provider profiles
> 이력: envelope에 key id가 붙은 뒤에도 한동안 내보낸 기본값이 65508(nonce와 tag만 뺀 값)이었고, 플랫폼을 켠 배포는 그
> 값을 고칠 때까지 모두 뜨지 못했다(review 2026-11-01 r3-i, compose lane을 띄워서 찾음).
Profiles are a map under `providers`, keyed by profile id. Arbitrary deployment-chosen ids can be
supplied as YAML or through Spring relaxed binding (`APP_NOTIFICATION_PLATFORM_PROVIDERS_<ID>_<FIELD>`).
The shipped reference profiles `smtp` and `ses` additionally expose explicit `APP_NOTIFICATION_PLATFORM_SMTP_*`
and `APP_NOTIFICATION_PLATFORM_SES_*` aliases so operators do not have to invent binding names.
## provider profile
| Field | Meaning |
profile은 `providers` 아래의 map이고, 키는 profile id다. 배포가 정한 아무 id나 YAML이나 Spring relaxed binding
(`APP_NOTIFICATION_PLATFORM_PROVIDERS_<ID>_<FIELD>`)으로 줄 수 있다. 내보내는 참조 profile `smtp`와 `ses`는 그 밖에
`APP_NOTIFICATION_PLATFORM_SMTP_*`와 `APP_NOTIFICATION_PLATFORM_SES_*` 별칭도 드러내므로, 운영자가 바인딩 이름을
지어낼 필요가 없다.
| 칸 | 뜻 |
|---|---|
| `type` | `SES`, `SMTP` — a closed enum, so an unknown value fails binding rather than assembling into nothing |
| `enabled` | A disabled profile is bound and validated but contributes no runtime |
| `primary-for-channel` | Exactly one primary per channel |
| `environment` | Required when enabled |
| `credential-profile` | Provider credential key id resolved through `SecretMaterialProvider`; never inline secret material |
| `timeout` | Positive and finite |
| `max-concurrency` | Positive |
| `rate-per-second` | Positive |
| `type` | `SES`, `SMTP`. 닫힌 enum이라 모르는 값은 아무것도 조립하지 않고 넘어가는 대신 바인딩에서 실패한다 |
| `enabled` | 꺼진 profile도 묶이고 검증되지만 런타임에 아무것도 보태지 않는다 |
| `primary-for-channel` | 채널마다 primary는 정확히 하나 |
| `environment` | 켜면 필요하다 |
| `credential-profile` | `SecretMaterialProvider`로 푸는 provider 자격 증명 key id. secret 값을 직접 적지 않는다 |
| `timeout` | 양수, 유한 |
| `max-concurrency` | 양수 |
| `rate-per-second` | 양수 |
A profile pins provider type, environment, credential profile, timeouts, concurrency and rate limit.
Sender identity and credential profile are separate concerns.
profile 하나가 provider 종류, 환경, 자격 증명 profile, 시간 상한, 동시성, 속도 제한을 고정한다. 보내는 쪽 신원과 자격
증명 profile은 서로 다른 문제다.
### SES profile fields
### SES profile 칸
An enabled SES profile adds a typed `ses` block:
켜진 SES profile에는 타입이 있는 `ses` 블록이 더해진다.
| Field | Meaning |
| 칸 | 뜻 |
|---|---|
| `ses.endpoint` | SES API base URI, used as the AWS SDK client's endpoint override |
| `ses.region` | AWS region the SDK signs for |
| `ses.sender-identity` | verified SES From identity |
| `ses.access-key-id` | AWS access key id; identifier only, not secret material |
| `ses.configuration-set` | optional SES configuration-set name |
| `ses.allowed-topic-arns` | SNS topic ARNs whose SES events this profile accepts (`APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, comma-separated). Required when `callbacks.enabled=true`: binding fails without it, because a valid SNS signature only proves AWS sent the message and anyone can own a topic |
| `credential-profile` | key id for the secret access-key material; generation 1 is activated at assembly |
| `ses.endpoint` | SES API 기본 URI. AWS SDK 클라이언트의 endpoint override로 쓴다 |
| `ses.region` | SDK가 서명하는 AWS region |
| `ses.sender-identity` | 검증된 SES From 신원 |
| `ses.access-key-id` | AWS access key id. 식별자일 뿐 secret 값이 아니다 |
| `ses.configuration-set` | 선택. SES configuration-set 이름 |
| `ses.allowed-topic-arns` | 이 profile이 SES 이벤트를 받는 SNS topic ARN(`APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, 쉼표로 구분). `callbacks.enabled=true`면 필요하다. 없으면 바인딩이 실패한다. 유효한 SNS 서명은 AWS가 메시지를 보냈다는 것만 증명하고, topic은 누구나 가질 수 있기 때문이다 |
| `credential-profile` | secret access key 값의 key id. 조립할 때 세대 1이 활성화된다 |
The shipped reference profile is `providers.ses` and is disabled by default. It is controlled by
`APP_NOTIFICATION_PLATFORM_SES_*`; its secret material comes from
`APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`, whose active key id must match
`APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`.
내보내는 참조 profile은 `providers.ses`이고 기본으로 꺼져 있다. `APP_NOTIFICATION_PLATFORM_SES_*`로 다룬다. secret 값은
`APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`에서 오고, 그 활성 key id는
`APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`와 같아야 한다.
`type` lists only the families the shipped composition can assemble. Current shipped
reachability is:
`type`에는 내보내는 조립이 만들 수 있는 family만 있다. 지금 내보내는 것으로 닿는 범위는 다음과 같다.
| Provider type | Contract/adapter code | Shipped dispatch assembler | Shipped callback assembler | What happens when enabled for dispatch |
| provider 종류 | 계약·어댑터 코드 | 내보내는 발송 assembler | 내보내는 콜백 assembler | 발송용으로 켜면 |
|---|---|---|---|---|
| `SMTP` | yes | **yes** | no | assembles when Spring Mail relay settings are complete |
| `SES` | yes | **yes** | **yes** | assembles an EMAIL runtime from the typed `ses` block; SNS callback verification remains available in `INGEST_ONLY` |
| `SMTP` | 있음 | **있음** | 없음 | Spring Mail relay 설정이 다 있으면 조립한다 |
| `SES` | 있음 | **있음** | **있음** | 타입 있는 `ses` 블록으로 EMAIL 런타임을 조립한다. SNS 콜백 검증은 `INGEST_ONLY`에서도 쓸 수 있다 |
APNs, FCM, Twilio, Web Push and Webhook adapters used to ship as protocol code with no assembler, so
enabling one failed startup. They were removed; the `docs/capability-status.md` "제거된 코드" table
names the last commit that had them. Adding a family back means adding its adapter, a
`ProviderRuntimeAssembler`, its `ProviderType` constant and the settings/secret inputs it actually
needs, together.
APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있어서 켜면 기동이 실패했다. 그래서
지웠다. 마지막으로 그것을 가진 커밋은 `docs/capability-status.md` 「제거된 코드」 표가 적는다. family를 다시 더하려면
그 어댑터, `ProviderRuntimeAssembler`, `ProviderType` 상수, 실제로 필요한 설정·secret 입력을 함께 더한다.
## SMTP relay
The one provider profile the template ships, off. A deployment that wants the common case sets
`APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true` and the relay address; one that wants a different
profile id or a second family declares it in its own YAML instead.
템플릿이 내보내는 provider profile 하나이고, 꺼져 있다. 흔한 경우를 원하는 배포는
`APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true`와 relay 주소를 준다. 다른 profile id나 두 번째 family를 원하는 배포는
대신 자기 YAML에 선언한다.
The profile and the relay are separate tables below because they answer different questions. The
profile says *which* provider serves EMAIL and under what limits; the relay says *what the transport
is*. Host, port and credentials are not here at all — they stay `spring.mail.*`, because Spring
already owns them and a second spelling would be a second thing to keep in step.
profile과 relay는 다른 질문에 답하므로 아래 두 표로 나눈다. profile은 *어느* provider가 EMAIL을 어떤 한도로 맡는지를
말하고, relay는 *전송이 무엇인지*를 말한다. host, port, 자격 증명은 여기에 아예 없다. `spring.mail.*`에 그대로 둔다.
Spring이 이미 그것을 가지고 있고, 두 번째 표기는 맞춰 둘 것을 하나 더 만든다.
| Property | Environment variable | Default | Bound |
| 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---|
| `providers.smtp.enabled` | `APP_NOTIFICATION_PLATFORM_SMTP_ENABLED` | `false` | boolean |
| `providers.smtp.primary-for-channel` | `APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY` | `true` | boolean; exactly one primary per channel |
| `providers.smtp.environment` | `APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT` | `local` | required when enabled |
| `providers.smtp.credential-profile` | `APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE` | `default` | resolved through `SecretMaterialProvider`, never inline material |
| `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `10s` | positive, finite |
| `providers.smtp.max-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY` | `4` | positive |
| `providers.smtp.rate-per-second` | `APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND` | `10` | positive |
| `providers.smtp.primary-for-channel` | `APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY` | `true` | boolean. 채널마다 primary는 정확히 하나 |
| `providers.smtp.environment` | `APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT` | `local` | 켜면 필요하다 |
| `providers.smtp.credential-profile` | `APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE` | `default` | `SecretMaterialProvider`로 푼다. 값을 직접 적지 않는다 |
| `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `10s` | 양수, 유한 |
| `providers.smtp.max-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY` | `4` | 양수 |
| `providers.smtp.rate-per-second` | `APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND` | `10` | 양수 |
| Property | Environment variable | Default | Bound |
| 속성 | 환경 변수 | 기본값 | 범위 |
|---|---|---|---|
| `smtp.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | address |
| `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | positive |
| `smtp.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | 주소 |
| `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | 양수 |
SMTP transport configuration has one owner: Spring Mail. The actual `JavaMailSenderImpl` must use required STARTTLS (`mail.smtp.starttls.enable=true` plus `mail.smtp.starttls.required=true`) or implicit TLS (`mail.smtp.ssl.enable=true`). It must also have positive `mail.smtp.connectiontimeout`, `mail.smtp.timeout`, and `mail.smtp.writetimeout` values. SMTP assembly fails before serving traffic when those properties are absent or invalid.
SMTP 전송 설정의 소유자는 Spring Mail 하나다. 실제 `JavaMailSenderImpl`은 필수 STARTTLS
(`mail.smtp.starttls.enable=true`와 `mail.smtp.starttls.required=true`)나 암묵적 TLS(`mail.smtp.ssl.enable=true`)를
써야 한다. `mail.smtp.connectiontimeout`, `mail.smtp.timeout`, `mail.smtp.writetimeout`도 양수여야 한다. 이 속성이
없거나 틀리면 SMTP 조립이 트래픽을 받기 전에 실패한다.
The native environment contract is `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, optional
`SPRING_MAIL_USERNAME` / secret `SPRING_MAIL_PASSWORD`, plus the
`SPRING_MAIL_PROPERTIES_MAIL_SMTP_*` TLS and timeout keys listed in `.env.example`. These names stay
Spring-native because Spring Boot itself owns and consumes `spring.mail.*`; the notification module
does not create a second alias for the same relay.
환경 변수 계약은 Spring 그대로다. `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, 선택인 `SPRING_MAIL_USERNAME`과 secret
`SPRING_MAIL_PASSWORD`, 그리고 `.env.example`에 있는 `SPRING_MAIL_PROPERTIES_MAIL_SMTP_*` TLS·시간 상한 키다. Spring
Boot 자신이 `spring.mail.*`를 가지고 읽으므로 이름을 Spring 그대로 둔다. 알림 모듈은 같은 relay에 두 번째 별칭을
만들지 않는다.
The default sender is an RFC 2606 reserved domain that resolves nowhere, so a deployment that forgot
to set one produces a traceable bounce instead of mail apparently sent from an address it does not
own.
기본 보내는 주소는 어디로도 풀리지 않는 RFC 2606 예약 도메인이다. 그래서 보내는 주소 설정을 잊은 배포는, 자기가
가지지 않은 주소로 메일을 보낸 것처럼 보이는 대신 추적할 수 있는 bounce를 낸다.
## Startup failures
## 기동 실패
Startup fails rather than degrading when:
다음이면 기능을 줄여 뜨지 않고 기동이 실패한다.
- a payload or queue setting is unbounded
- a timeout is negative
- a TTL-required profile has no expiry source
- a callback signing secret is missing
- a production profile enables trust-all
- an SES profile is missing its `ses` block, or callbacks are on and `ses.allowed-topic-arns` is empty
- two provider profiles share an id
- a route points only at disabled providers
- `mode` is `SERVING` and no provider profile is enabled
- the notification schema stream is not applied and promoted
- payload나 큐 설정에 상한이 없다
- 시간 상한이 음수다
- TTL이 필요한 profile에 만료 출처가 없다
- 콜백 서명 secret이 없다
- 운영 profile이 trust-all을 켠다
- SES profile에 `ses` 블록이 없거나, 콜백이 켜졌는데 `ses.allowed-topic-arns`가 비어 있다
- 두 provider profile의 id가 같다
- route가 꺼진 provider만 가리킨다
- `mode`가 `SERVING`인데 켜진 provider profile이 없다
- 알림 스키마 stream이 적용·승격되지 않았다
## Secrets
## secret
All key material arrives through `SecretMaterialProvider`. Nothing is read from source, from a
committed file, or from a plaintext log. Contact point encryption and lookup HMAC keys must be
distinct, and the encryption key must be exactly 256 bits.
키 값은 모두 `SecretMaterialProvider`로 들어온다. 소스, 커밋한 파일, 평문 로그에서는 아무것도 읽지 않는다. 연락처
암호화 키와 조회 HMAC 키는 서로 달라야 하고, 암호화 키는 정확히 256비트여야 한다.
Seven purposes, seven keys. Each is base64 of at least 32 bytes and each must differ from every
other; the platform decodes them at startup and refuses to boot if one is blank, short or shared. A
blank value used to be skipped, which meant the platform started without the key and found out on
the first contact point — in production, on a recipient's notification.
목적 일곱, 키 일곱이다. 각각 32바이트 이상의 base64이고 다른 모든 키와 달라야 한다. 플랫폼은 기동할 때 키를 풀어
보고, 하나라도 비었거나 짧거나 겹치면 뜨기를 거부한다. 전에는 빈 값을 건너뛰었고, 그래서 플랫폼이 키 없이 뜬 뒤 첫
연락처에서야, 운영에서는 수신자의 알림에서야 그것을 알았다.
Every default below is **unset**, deliberately. Supply the values out of band, per environment. Do
not write one into this table, into `application.yml`, into an `.env` file that is tracked, or into
any example: a value that appears in the repository is a value that has been disclosed.
아래 기본값은 모두 일부러 **비어 있다**. 값은 환경마다 따로 준다. 이 표, `application.yml`, 추적되는 `.env` 파일, 어느
예시에도 값을 쓰지 않는다. 저장소에 나타난 값은 이미 드러난 값이다.
| Purpose | Key material | Active key id |
| 목적 | 키 값 | 활성 key id |
|---|---|---|
| Contact point encryption | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID` |
| Contact point lookup HMAC | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID` |
| Callback signing | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID` |
| Callback fingerprint HMAC | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID` |
| Provider credential encryption | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID` |
| Provider request lookup HMAC | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID` |
| Payload encryption | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID` |
| 연락처 암호화 | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID` |
| 연락처 조회 HMAC | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID` |
| 콜백 서명 | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID` |
| 콜백 fingerprint HMAC | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID` |
| provider 자격 증명 암호화 | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID` |
| provider 요청 조회 HMAC | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID` |
| payload 암호화 | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID` |
A key id is not secret — an id identifies key material without revealing it — but it is required,
and it has no default on purpose. A constant id makes a rotation indistinguishable from the key it
replaced, so nothing could decrypt what was written before it. Change the id in the same deployment
that changes the material, and keep the superseded key readable under its old id until the data it
wrote has been re-encrypted. The rotation sequence is in
[at-rest-threat-model.md](at-rest-threat-model.md).
key id는 secret이 아니다. id는 키 값을 드러내지 않고 그것을 가리킨다. 그래도 필요하고, 일부러 기본값이 없다. 고정된
id는 교체를 바뀌기 전 키와 구별할 수 없게 만들어서, 그 전에 쓴 것을 아무것도 풀지 못하게 한다. 키 값을 바꾸는 배포에서
id도 함께 바꾸고, 밀려난 키는 그 키로 쓴 데이터를 다시 암호화할 때까지 옛 id로 읽을 수 있게 둔다. 교체 순서는
[at-rest-threat-model.md](at-rest-threat-model.md)에 있다.
## Readiness
## readiness
The platform contributes a `notifications` actuator endpoint and a health indicator. It reports DOWN
when a provider's credentials were rejected, when a configured provider has no channel route, and
when the measured backlog, stuck-lease count, projection lag or reconciliation lag passes the
thresholds in `NotificationServingThresholds`. See [operations.md](operations.md).
플랫폼은 `notifications` actuator 엔드포인트와 health indicator를 보탠다. provider 자격 증명이 거부됐을 때, 설정된
provider에 채널 route가 없을 때, 그리고 잰 backlog, 멈춘 lease 수, projection 지연, 맞추기(reconciliation) 지연이
`NotificationServingThresholds`의 임계값을 넘을 때 DOWN을 보고한다. [operations.md](operations.md)를 본다.
+29 -32
View File
@@ -1,6 +1,6 @@
# Delivery evidence model
# 전달 증거 모델
## The shape
## 모양
```text
NotificationRequest
@@ -12,39 +12,37 @@ NotificationRequest
+ EngagementFacts + SuppressionFacts
```
Four identities, four lifecycles. A logical request is not a recipient job, a recipient job is not a
provider attempt, and a provider attempt is not the event stream that describes it.
신원 넷, 수명 주기 넷이다. 논리 요청은 수신자 작업이 아니고, 수신자 작업은 provider attempt가 아니고, provider attempt는
그것을 설명하는 이벤트 흐름이 아니다.
## Why not one status enum
## 상태 enum 하나가 아닌 이유
A single linear status would have to answer "what happened?" with one value, and the real answers do
not fit on one line:
일직선 상태 하나는 「무슨 일이 있었나」에 값 하나로 답해야 하는데, 실제 답은 한 줄에 들어가지 않는다.
- An email can be `DELIVERED` and then generate a complaint. Both facts are true and both matter:
one for reporting, the other for suppression.
- Twilio does not guarantee callback ordering, so `sent` routinely arrives after `delivered`. Under
an ordinal rule the later, weaker event silently overwrites the stronger one.
- APNs may accept a notification and then store, replace or discard it.
- 이메일은 `DELIVERED`가 된 뒤 complaint를 낼 수 있다. 두 사실이 다 참이고 다 중요하다. 하나는 보고에, 다른 하나는
억제에 쓴다.
- Twilio는 콜백 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 오는 일이 흔하다. 순번 규칙에서는 뒤에 온 약한
이벤트가 강한 이벤트를 조용히 덮어쓴다.
- APNs는 알림을 수락한 뒤 저장하거나, 바꾸거나, 버릴 수 있다.
So the ledger stores events and a channel projector merges them through an explicit transition table.
`StandardDeliveryProjector` holds the shared rules; provider projectors add only their own event
vocabulary.
그래서 ledger는 이벤트를 저장하고, channel projector가 명시한 전이 표로 그것을 합친다. 공통 규칙은
`StandardDeliveryProjector`가 가지고, provider projector는 자기 이벤트 어휘만 더한다.
## Merge rules
## 합치는 규칙
| Transition | Result |
| 전이 | 결과 |
|---|---|
| `sent` → `delivered` | applied |
| `delivered` → `sent` | ignored, event still stored |
| `delivered` → `complaint` | complaint fact added, delivery preserved |
| `complaint` → `delivered` | delivery applied, complaint preserved |
| `accepted` → `bounced` | applied |
| `read` → `displayed` | ignored |
| hard bounce → `delivered` | ignored, hard bounce is terminal |
| `sent` → `delivered` | 적용 |
| `delivered` → `sent` | 무시, 이벤트는 저장 |
| `delivered` → `complaint` | complaint 사실을 더하고 전달은 유지 |
| `complaint` → `delivered` | 전달을 적용하고 complaint는 유지 |
| `accepted` → `bounced` | 적용 |
| `read` → `displayed` | 무시 |
| hard bounce → `delivered` | 무시, hard bounce는 끝 상태 |
Engagement (`opened`, `clicked`) is stored beside the delivery outcome and never changes it.
참여(`opened`, `clicked`)는 전달 결과 옆에 저장하고 그것을 바꾸지 않는다.
## Ambiguity
## 모호함
```text
platform ──── send ────▶ provider
@@ -53,10 +51,9 @@ platform ──── send ────▶ provider
✗ connection reset
```
The platform may hold no provider request id while the notification really was sent. The attempt
records `requestStarted`, `requestBodyCommitted`, `providerResponseReceived` and an
`EvidenceCertainty` for each, so a later decision can tell "we know nothing was sent" apart from "we
could not read the answer".
알림이 실제로 보내졌는데 플랫폼은 provider request id를 하나도 가지지 못할 수 있다. attempt는 `requestStarted`,
`requestBodyCommitted`, `providerResponseReceived`와 그 각각의 `EvidenceCertainty`를 기록한다. 그래서 나중의 판단이
「아무것도 보내지 않았음을 안다」와 「답을 읽지 못했다」를 가릴 수 있다.
`ProviderSubmissionResult` enforces this: an ambiguous result may not claim `PROVIDER_ACCEPTED`, and
no submission result of any kind may carry a delivery outcome.
`ProviderSubmissionResult`가 이것을 강제한다. 모호한 결과는 `PROVIDER_ACCEPTED`를 주장할 수 없고, 어떤 제출 결과도
전달 결과를 실을 수 없다.
+24 -31
View File
@@ -1,45 +1,38 @@
# Migration guide
# 이행 안내
## From the R0 routing seam
## R0 routing seam에서
The pre-existing `dev.caskeleton.adapter.outbound.notification` router (`RoutingNotifier`,
`FailOpenNotificationProvider`, the Google email and Slack webhook seams) stays untouched. The
delivery platform lives beside it under `…notification.platform` and does not modify or delete any
R0 class.
이미 있던 `dev.caskeleton.adapter.outbound.notification` router(`RoutingNotifier`, `FailOpenNotificationProvider`, Google
email과 Slack webhook seam)는 건드리지 않는다. 전달 플랫폼은 그 옆 `…notification.platform` 아래에 있고, R0 클래스를
고치거나 지우지 않는다.
Migration order per capability:
capability마다 이행 순서:
1. Register the contact points behind `ContactPointStorePort` so the platform owns protected values.
2. Publish the template version, and pin the template id, version and locale at every call site.
3. Move the call site from the router to the N1 typed facade for the channel.
4. Verify evidence in the snapshot rather than in the caller's return value: `submit()` is durable
acceptance and nothing more.
5. Remove the R0 route only after the platform route has produced provider evidence in the target
environment.
1. 플랫폼이 보호된 값을 가지도록 연락처를 `ContactPointStorePort` 뒤에 등록한다.
2. 템플릿 버전을 게시하고, 모든 호출 지점에서 템플릿 id, 버전, locale을 고정한다.
3. 호출 지점을 router에서 그 채널의 N1 typed facade로 옮긴다.
4. 증거는 호출자의 반환값이 아니라 snapshot에서 확인한다. `submit()`은 durable 수락일 뿐이다.
5. 대상 환경에서 플랫폼 route가 provider 증거를 낸 뒤에만 R0 route를 지운다.
## Return-value semantics change
## 반환값의 뜻이 바뀐다
The R0 seam returned a send-shaped result. `NotificationReceipt` returns `notificationId`, a request
status and an acceptance time. Callers that treated the old return value as proof of delivery must be
changed; there is no compatibility shim, because a shim would have to invent the delivery claim this
platform exists to avoid.
R0 seam은 보낸 결과 모양을 돌려줬다. `NotificationReceipt`는 `notificationId`, 요청 상태, 수락 시각을 돌려준다. 옛
반환값을 전달 증거로 다룬 호출자는 고쳐야 한다. 호환 shim은 없다. shim은 이 플랫폼이 피하려고 있는 전달 주장을 지어내야
하기 때문이다.
## FCM target migration
## FCM 대상 이행
Registration tokens keep working through `LegacyFcmRegistrationToken`. New registrations should use
`FcmInstallationId`. The two are distinct types, so a migration is a compile-time task rather than a
runtime guess.
registration token은 `LegacyFcmRegistrationToken`으로 계속 쓸 수 있다. 새 등록은 `FcmInstallationId`를 쓴다. 둘은 서로
다른 타입이라 이행은 런타임 짐작이 아니라 컴파일 시점의 일이다.
## R1의 처분 (NOTIF-ADR-005)
이 문서는 R0 router → platform 이행만 설명해 왔고, `dev.caskeleton.application.notification` 직속의
R1 public type 100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지
문서 어디에도 답이 없었다.
이 문서는 R0 router → platform 이행만 설명해 왔고, `dev.caskeleton.application.notification` 직속의 R1 public type
100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지 문서 어디에도 답이 없었다.
- **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다.
- **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은
단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의
`catalog/`, `provider/`, `template/` 실험 구현도 제거했다. 실제 runtime은
`dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
- **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은 단순 알림 포트
`NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의 `catalog/`, `provider/`,
`template/` 실험 구현도 제거했다. 실제 runtime은 `dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
- 삭제 목록과 마지막 커밋은 `docs/capability-status.md`의 「제거된 코드」 표에 있다.
+61 -73
View File
@@ -1,39 +1,37 @@
# Notification Delivery Platform — module mapping
# 알림 전달 플랫폼 — 모듈 대응표
> Source design: `docs/design/2026-08-10-notification-platform-design.md`
> 출처 설계서: `docs/design/2026-08-10-notification-platform-design.md`
>
> Source plan: `docs/history/plans/2026-08-10-notification-platform-implementation-plan.md`
> 출처 계획서: `docs/history/plans/2026-08-10-notification-platform-implementation-plan.md`
## Why a mapping exists
## 대응표가 있는 이유
The plan was written against a hypothetical repository (`modules/notification/**`, root package
`io.backend.skeleton.notification`, 31 Gradle projects). This repository is a fail-closed
19-leaf Clean Architecture template: `src/settings.gradle` rejects any registry that does not
contain exactly the 19 modules in `src/config/architecture/modules.json`, and
`verifyCleanArchitectureDependencies` rejects any project edge outside `allowed_dependencies`.
계획은 가상의 저장소(`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를 거부한다.
Creating 31 new Gradle projects would violate HARD-STOP #5 of `AGENTS.md`. The package README
anticipates this and instructs the implementer to map dependency catalog and package/file paths onto
the host repository's rules while preserving the public contracts and reliability semantics.
Gradle 프로젝트 31개를 새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다. 패키지 README도 이것을 내다보고, 공개 계약과
신뢰성 의미를 지키면서 의존성 카탈로그와 패키지·파일 경로를 받는 저장소의 규칙에 맞추라고 구현자에게 지시한다.
Every logical module of the plan is therefore implemented as a **package** inside the registered leaf
that owns its responsibility. No public contract, evidence rule, or reliability semantic is dropped.
그래서 계획의 논리 모듈마다 그 책임을 가진 등록 leaf 안의 **패키지**로 구현했다. 공개 계약, 증거 규칙, 신뢰성 의미는
하나도 빠지지 않았다.
## Logical module → registered leaf
## 논리 모듈 → 등록 leaf
| Plan module | Registered leaf | Package |
| 계획 모듈 | 등록 leaf | 패키지 |
|---|---|---|
| `notification-core-api` | `application-core` | `dev.caskeleton.application.notification.platform.api` |
| `notification-content-api` | `application-core` | `…platform.api.content` |
| `notification-contact-api` | `application-core` | `…platform.contact` |
| `notification-template-api` | `application-core` | `…platform.template` |
| `notification-policy` | `application-core` | `…platform.policy` |
| `notification-provider-spi` | `application-core` | `…platform.provider` |
| `notification-callback-api` | `application-core` | `…platform.callback` |
| `notification-inbox-api` | `application-core` | `…platform.inbox` |
| `notification-admin-api` | `application-core` | `…platform.admin` |
| `notification-security` (ports) | `application-core` | `…platform.security` |
| `notification-observability` (ports) | `application-core` | `…platform.observation` |
| `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` |
@@ -42,20 +40,20 @@ that owns its responsibility. No public contract, evidence rule, or reliability
| `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` (store adapters), `….platform.entity` (JPA rows), `….platform.repository` (Spring Data interfaces and SQL text) |
| `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform` (`JpaNotificationInbox`, `InboxCommitEventPublisher`, `InboxOutboxRecordFactory`); row and repository in `….platform.entity` / `….platform.repository` |
| `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` |
| application composition (use cases, callback bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
| `notification-testkit` | test source sets of the owning leaves | `…platform.testkit` |
| 애플리케이션 조립(use case, 콜백 bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
| `notification-testkit` | 소유 leaf의 test source set | `…platform.testkit` |
## Dependency-direction consequences
## 의존 방향의 결과
The plan's module DAG (`*-api` → `provider-spi`/`policy` → runtime/adapters → starter) is preserved
by the leaf DAG that the registry already enforces:
계획의 모듈 DAG(`*-api` → `provider-spi`/`policy` → runtime/adapters → starter)는 registry가 이미 강제하는 leaf DAG로
지켜진다.
```text
application-core (all *-api, provider SPI, policy, callback contracts)
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)
@@ -64,50 +62,40 @@ adapter:outbound:notification adapter:outbound:persistence-notification ad
app-bootstrap (one line)
```
Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports:
계획의 edge 둘은 이 저장소에서 프로젝트 edge로 표현할 수 없어서 port로 바꿨다.
1. `notification-email-ses` → `httpclient platform`. (The Twilio, FCM, APNs, Web Push and
Webhook adapters that shared this edge were removed: none had an assembler.)
`adapter-outbound-notification` is not allowed to depend on `adapter-outbound-httpclient`, and
SES no longer needs it: the SES adapter sends through the AWS SDK v2 `sesv2` client (owner
decision 17), which signs requests itself. The adapter-local JDK HTTP gateway and SigV4 signer
were deleted with that change. The client is built per profile with SDK retries off, no default
credential chain (each request carries its profile's credential) and the profile's endpoint,
which still passes the notification routability guard.
2. `notification-inbox-jpa` → `optional messaging outbox integration`.
`adapter-outbound-persistence-notification` may not depend on `adapter-outbound-messaging`; the inbox
publishes through the existing persistence outbox tables plus the
`NotificationInboxSignalPort` application port, and `app-bootstrap` binds the relay.
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`가 조립한다.
## Commit policy
## 커밋 정책
`AGENTS.md` pins commit policy to `human-only`. Step 5 (`git add` / `git commit`) of every plan task
is therefore intentionally **not** executed by the agent; the working tree carries the change and the
human owner commits.
`AGENTS.md`는 커밋 정책을 `human-only`로 고정한다. 그래서 계획의 모든 task에 있는 Step 5(`git add` / `git commit`)는
에이전트가 일부러 **하지 않았다**. 작업 트리가 변경을 싣고, 사람 소유자가 커밋한다.
## Runtime reachability after the R1 adapter cleanup
## R1 어댑터 정리 뒤 런타임 도달 범위
The application R1 contract covered by NOTIF-ADR-005 is a separate question from the abandoned
outbound implementation that had been built around it. The latter is gone: the notification leaf no
longer contains top-level `catalog/`, `provider/`, or `template/` R1 adapter packages. They had no
production composition consumer and were proved only by their own fakes.
NOTIF-ADR-005가 다루는 애플리케이션 R1 계약은, 그것을 둘러싸고 만들었다가 버린 outbound 구현과는 다른 문제다. 뒤의 것은
없어졌다. 알림 leaf에는 최상위 `catalog/`, `provider/`, `template/` R1 어댑터 패키지가 더는 없다. 그것들은 운영 조립의
consumer가 없었고 자기 fake로만 증명됐다.
The useful rendering invariant from that experiment was not discarded. R2
`platform.template.TemplateSlotPolicy` now validates the final HTML against the reviewed tag and
attribute subset in addition to escaping substituted values. Active script markup, event-handler
attributes and non-HTTPS HTML links are refused.
그 실험의 쓸모 있던 렌더링 불변식은 버리지 않았다. R2 `platform.template.TemplateSlotPolicy`가 이제 치환한 값을
escape하는 것에 더해, 최종 HTML을 검토한 태그·속성 부분집합과 대조한다. 실행되는 script markup, event handler 속성,
HTTPS가 아닌 HTML 링크는 거부한다.
R2 provider protocol packages remain because they implement the canonical platform SPI and have
contract tests. Their presence does **not** make them shipped dispatch runtimes. Current composition
reachability is SMTP and SES for dispatch, with SES also available for callback ingestion; the remaining
provider packages are extension assets until a composition contributes a `ProviderRuntimeAssembler`
with the settings and secret sources that family requires. See `support-matrix.md` for the explicit table.
R2 provider 프로토콜 패키지는 canonical 플랫폼 SPI를 구현하고 계약 테스트가 있어서 남아 있다. 남은 것은 `ses`와
`smtp`이고, 둘 다 내보내는 조립이 발송에 쓴다(SES는 콜백 받기에도 쓴다). 다른 family는 조립이 그 family에 필요한 설정·secret
출처와 함께 `ProviderRuntimeAssembler`를 보탤 때 생긴다. 표는 `support-matrix.md`에 있다.
## R1 public types (NOTIF-ADR-005)
## R1 public type (NOTIF-ADR-005)
NOTIF-ADR-005 made `..notification.platform..` canonical. The R1 types directly under
`dev.caskeleton.application.notification` had no production consumer and were removed on
2026-09-25, together with the ArchUnit rule that kept the two namespaces apart. What remains there
is the simple notification port the adapter core implements — `NotificationPort`, `Notification`,
`NotificationChannel`. The removed types and their last commit are listed in
`docs/capability-status.md` under "제거된 코드".
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` 「제거된 코드」에 있다.
+21 -25
View File
@@ -1,6 +1,6 @@
# Operations
# 운영
## Runtime shape
## 런타임 모양
```text
durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED)
@@ -12,35 +12,31 @@ durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED)
→ provider adapter
```
Provider calls run outside every database transaction. The attempt row is committed first, so after a
crash the row is either absent (nothing was sent) or present in `DISPATCHING` (reconciliation has
something to ask about).
provider 호출은 모든 DB 트랜잭션 밖에서 돈다. attempt 행을 먼저 커밋하므로, 장애 뒤 그 행은 없거나(아무것도 보내지
않음) `DISPATCHING`으로 있다(맞추기가 물어볼 것이 있음).
## Guards that exist for specific incidents
## 특정 장애를 막으려고 있는 장치
| Guard | The incident it prevents |
| 장치 | 막는 장애 |
|---|---|
| Credential failure opens the provider route | One expired key multiplied by a queue becomes a self-inflicted outage |
| Retry budget per provider profile | A provider outage turning every queued notification into its own retry loop |
| Ambiguous attempts block automatic fallback | A push whose response was lost arriving alongside the "just in case" SMS |
| Permits released during backoff | A slow provider pinning the whole concurrency budget on work that is only waiting |
| Fail-fast intake on capacity | An unbounded in-memory queue absorbing a burst it cannot survive |
| 자격 증명 실패가 provider route를 연다 | 만료된 키 하나가 큐만큼 곱해져 스스로 만든 장애가 된다 |
| provider profile마다 재시도 예산 | provider 장애가 큐의 모든 알림을 저마다의 재시도 반복으로 만든다 |
| 모호한 attempt는 자동 전환을 막는다 | 응답을 잃은 push와 「혹시 몰라」 보낸 SMS가 함께 도착한다 |
| 백오프 동안 허가를 돌려준다 | 느린 provider가 기다리기만 하는 일로 동시성 예산 전체를 붙잡는다 |
| 용량이 차면 받기를 바로 거부한다 | 상한 없는 메모리 큐가 버틸 수 없는 폭주를 받아들인다 |
## Scheduling
## 일정
`scheduleAt` activates the job, `notBefore` is the earliest permitted provider submission, and
`expiresAt` blocks new attempts, retries and fallbacks. Suppression and expiry are re-checked
immediately before dispatch, because a scheduled notification can sit in the queue for hours and the
user may have opted out in the meantime.
`scheduleAt`은 작업을 활성화하고, `notBefore`는 provider 제출을 허용하는 가장 이른 시각이고, `expiresAt`은 새 attempt,
재시도, 전환을 막는다. 억제와 만료는 발송 직전에 다시 확인한다. 예약된 알림은 큐에서 몇 시간을 기다릴 수 있고, 그동안
사용자가 수신을 거부했을 수 있다.
## Redrive
## 다시 보내기(redrive)
A redrive preserves `NotificationId` and `RecipientDeliveryId`, creates a new `DeliveryAttemptId`, and
reuses the pinned template version and rendered digest. Sending different content is a new
notification, not a redrive. Redriving an ambiguous attempt requires explicit duplicate-risk approval,
because the platform genuinely cannot tell whether the first submission reached the user.
redrive는 `NotificationId`와 `RecipientDeliveryId`를 유지하고, 새 `DeliveryAttemptId`를 만들고, 고정된 템플릿 버전과
렌더링 digest를 다시 쓴다. 다른 내용을 보내는 것은 redrive가 아니라 새 알림이다. 모호한 attempt를 redrive하려면 중복
위험 승인을 명시해야 한다. 첫 제출이 사용자에게 닿았는지 플랫폼이 정말로 알 수 없기 때문이다.
## Actuator surface
## actuator 표면
Provider runtime states and generations, queue depth and age, callback and reconciliation health.
Never addresses, never credentials.
provider 런타임 상태와 세대, 큐 깊이와 나이, 콜백과 맞추기 상태. 주소와 자격 증명은 절대 싣지 않는다.
+19 -19
View File
@@ -1,34 +1,34 @@
# Provider runbooks
# provider runbook
## SMTP
| Symptom | Classification | Action |
| 증상 | 분류 | 조치 |
|---|---|---|
| Final `2xx` after `DATA` | `CONFIRMED_ACCEPTED` / `PROVIDER_ACCEPTED` | None; this is acceptance, not inbox delivery |
| `4yz` | `TRANSIENT_PROVIDER` | Retry under budget and deadline |
| `5yz` | `PERMANENT_PROVIDER` or `INVALID_RECIPIENT` | Stop, or invalidate the contact point |
| Connection lost after `DATA` | `AMBIGUOUS_SUBMISSION` | Reconcile or escalate; do not resend automatically |
| `DATA` 뒤 최종 `2xx` | `CONFIRMED_ACCEPTED` / `PROVIDER_ACCEPTED` | 없음. 받은편지함 도착이 아니라 수락이다 |
| `4yz` | `TRANSIENT_PROVIDER` | 예산과 마감 안에서 다시 시도한다 |
| `5yz` | `PERMANENT_PROVIDER` 또는 `INVALID_RECIPIENT` | 멈추거나, 연락처를 무효로 한다 |
| `DATA` 뒤 연결 끊김 | `AMBIGUOUS_SUBMISSION` | 맞추거나 넘긴다. 자동으로 다시 보내지 않는다 |
Connection, read, write and pool-acquire timeouts are all finite. There is no unbounded timeout.
연결, 읽기, 쓰기, 풀 획득 시간 상한은 모두 유한하다. 상한 없는 시간 상한은 없다.
## Amazon SES
`MessageId` is acceptance evidence. SES itself documents that it can accept a request and then not
send, so `MessageId` is never mapped to `DELIVERED`.
`MessageId`는 수락 증거다. SES 자신이 요청을 수락한 뒤 보내지 않을 수 있다고 문서에 적으므로, `MessageId`는 절대
`DELIVERED`로 매핑하지 않는다.
| Event | Normalized |
| 이벤트 | 정규화 |
|---|---|
| `Send` | reinforces `PROVIDER_ACCEPTED` |
| `Send` | `PROVIDER_ACCEPTED`를 보강한다 |
| `Delivery` | `DELIVERY_CONFIRMED` / `NETWORK_OR_CARRIER_ACCEPTED` |
| `DeliveryDelay` | delay fact |
| `Bounce` (permanent) | `BOUNCED_HARD` plus hard-bounce suppression |
| `Bounce` (transient) | `BOUNCED_SOFT`; retry policy input, not a suppression reason |
| `Complaint` | complaint fact plus suppression |
| `DeliveryDelay` | 지연 사실 |
| `Bounce` (permanent) | `BOUNCED_HARD`와 hard bounce 억제 |
| `Bounce` (transient) | `BOUNCED_SOFT`. 억제 사유가 아니라 재시도 정책의 입력이다 |
| `Complaint` | complaint 사실과 억제 |
| `Reject` | `PROVIDER_REJECTED` |
| `RenderingFailure` | `TEMPLATE_FAILURE` |
## Removed provider families
## 지운 provider family
Twilio, FCM, APNs, Web Push and Webhook adapters were removed because nothing assembled them; their
runbooks went with them. The last commit that had both is named in `docs/capability-status.md`
(제거된 코드). A deployment that adds one of these providers back writes its runbook here with it.
Twilio, FCM, APNs, Web Push, Webhook 어댑터는 아무것도 조립하지 않아서 지웠고, 그 runbook도 함께 지웠다. 둘을 모두
가진 마지막 커밋은 `docs/capability-status.md`(제거된 코드)에 있다. 이 provider 중 하나를 다시 더하는 배포는 그 runbook을
여기에 함께 쓴다.
+26 -36
View File
@@ -1,54 +1,44 @@
# Security and privacy
# 보안과 개인정보
## Protected values
## 보호하는 값
Email addresses, phone numbers, FCM installation ids and legacy tokens, APNs device tokens, Web Push
endpoints and keys, VAPID private keys, provider credentials, callback signing secrets, template
variables, rendered bodies, attachment references and unsubscribe tokens.
이메일 주소, 전화번호, FCM installation id와 legacy token, APNs device token, Web Push endpoint와 키, VAPID private key,
provider 자격 증명, 콜백 서명 secret, 템플릿 변수, 렌더링한 본문, 첨부 참조, 수신 거부 token.
## At rest
## 저장할 때
Contact points are encrypted with AES-256-GCM. Equality lookup uses a separate HMAC-SHA-256
fingerprint.
연락처는 AES-256-GCM으로 암호화한다. 같은지 찾는 조회는 따로 둔 HMAC-SHA-256 fingerprint를 쓴다.
Two keys, not one, because the requirements are opposite: the ciphertext must be non-deterministic so
two records of the same address are not visibly identical, while equality lookup must be
deterministic. The fingerprint is keyed rather than a plain digest because phone numbers and email
addresses come from a small, enumerable space — an unkeyed hash of a phone number is recoverable in
seconds.
요구가 반대라서 키가 하나가 아니라 둘이다. 암호문은 결정적이지 않아야 같은 주소의 두 기록이 겉으로 같아 보이지 않고,
같은지 찾는 조회는 결정적이어야 한다. fingerprint를 그냥 digest가 아니라 키가 있는 것으로 두는 이유는 전화번호와 이메일
주소가 작고 셀 수 있는 공간에서 오기 때문이다. 키 없는 전화번호 hash는 몇 초면 되살린다.
The contact point kind is bound into the GCM associated data, so a ciphertext cannot be moved between
contact kinds without failing the authentication tag.
연락처 종류를 GCM associated data에 묶으므로, 암호문을 다른 연락처 종류로 옮기면 인증 tag가 실패한다.
An unknown key id is refused rather than silently falling back to the current key: a silent fallback
would turn every historical row into a tag failure at read time.
모르는 key id는 현재 키로 조용히 대신하지 않고 거부한다. 조용히 대신하면 이력의 모든 행이 읽을 때 tag 실패가 된다.
## Never logged, never a metric tag
## 로그에도 메트릭 태그에도 넣지 않는 것
Addresses, tokens, Web Push endpoints and keys, message bodies, template variables, provider
credentials, unsubscribe tokens, attachment URLs, raw callback payloads and raw provider request ids.
주소, token, Web Push endpoint와 키, 메시지 본문, 템플릿 변수, provider 자격 증명, 수신 거부 token, 첨부 URL, 원본 콜백
payload, 원본 provider request id.
`CardinalityGuard` enforces this for metrics rather than convention: it validates every metric tag
against a closed allowlist.
메트릭은 관례가 아니라 `CardinalityGuard`가 강제한다. 모든 메트릭 태그를 닫힌 허용 목록과 대조한다.
An allowlist rather than a denylist, because the failure mode of a denylist is that the one field
nobody thought of is the one that leaks.
거부 목록이 아니라 허용 목록인 이유가 있다. 거부 목록이 실패하는 꼴은, 아무도 생각하지 못한 그 칸 하나가 새는 것이다.
Every contact point value type overrides `toString()` to print `[redacted]`. That covers the case a
central redactor cannot: a value interpolated into a log line by accident.
모든 연락처 값 타입은 `toString()`을 고쳐 `[redacted]`를 찍는다. 그것은 중앙 redactor가 막지 못하는 경우, 실수로 로그
줄에 끼워 넣은 값을 막는다.
## Web Push endpoints
## Web Push endpoint
RFC 8030 defines the push URI as a capability URL — knowing it is sufficient to push to the
subscriber. It is handled as a secret, not as a URL.
RFC 8030은 push URI를 capability URL로 정의한다. 그것을 알면 구독자에게 push할 수 있다. 그래서 URL이 아니라 secret으로
다룬다.
## Callbacks
## 콜백
TLS, provider signature verification over the exact received bytes and external URL, replay defence
where a timestamp or nonce is available, body-size and content-type limits, profile binding, rate
limiting, idempotent ingestion and a security audit trail for rejections.
TLS, 받은 그대로의 바이트와 외부 URL에 대한 provider 서명 검증, timestamp나 nonce가 있으면 replay 방어, 본문 크기와
content type 한도, profile 묶기, 속도 제한, 멱등한 받기, 거부를 남기는 보안 감사 기록.
## Tenant isolation
## 테넌트 격리
Every store port carries the tenant boundary in its signature. Administrative operations require an
explicit tenant or a global authority.
모든 저장소 port는 시그니처에 테넌트 경계를 싣는다. 관리 작업에는 명시한 테넌트나 전역 권한이 필요하다.
+63 -70
View File
@@ -1,109 +1,102 @@
# Notification support matrix
# 알림 지원 매트릭스
What each channel can actually prove, and what the platform refuses to claim.
채널마다 실제로 증명할 수 있는 것과, 플랫폼이 주장하기를 거부하는 것이다.
The grade column is not an opinion. `docs/notification/evidence-manifest.json` declares which claims
each grade requires and which executable artifact proves each claim, and
`NotificationEvidenceVerifierTest` (in `:adapter:outbound:notification:test`) refuses a grade whose
claims are not all backed by a file that exists. Raising a grade means adding the artifact first.
등급 칸은 의견이 아니다. `docs/notification/evidence-manifest.json`이 등급마다 필요한 claim과 claim마다 그것을 증명하는
실행 산출물을 선언하고, `NotificationEvidenceVerifierTest`(`:adapter:outbound:notification:test`)가 claim이 모두 실제
파일로 뒷받침되지 않은 등급을 거부한다. 등급을 올리려면 산출물을 먼저 더한다.
Five channels read `Stable` until 2026-08-15. Nothing in the pipeline had ever sent a request to a
provider — the sandbox job's whole body was two `echo` statements behind `continue-on-error` — and
no test killed a worker mid-dispatch. The protocols are implemented and their contracts are proven
against real PostgreSQL; the wire and the crash are not. That is what the grade now says.
2026-08-15까지 다섯 채널이 `Stable`이었다. 파이프라인의 어떤 것도 provider에 요청을 보낸 적이 없었고(sandbox job의 본문
전체가 `continue-on-error` 뒤의 `echo` 두 줄이었다), 발송 도중 worker를 죽인 테스트도 없었다. 프로토콜은 구현돼 있고 그
계약은 실제 PostgreSQL에서 증명됐지만, 실제 전송과 장애 중단은 증명되지 않았다. 지금 등급이 말하는 것이 그것이다.
## Channels
## 채널
| Channel | Reference implementation | Grade | Strongest evidence the platform records by default |
| 채널 | 참조 구현 | 등급 | 플랫폼이 기본으로 기록하는 가장 강한 증거 |
|---|---|---|---|
| Email | SMTP, Amazon SES API | Contract implemented / runtime unqualified | Provider acceptance; recipient mail-server delivery, bounce and complaint when the provider publishes events |
| SMS | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
| Mobile push (FCM, APNs) | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
| Web Push | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
| In-app inbox | Own database | Optional stable | `PERSISTED`, `SEEN`, `READ` |
| Webhook | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the receiving HTTP contract states |
| 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 계약이 말하는 것 |
## Shipped provider assembly reachability
## 내보내는 provider 조립이 닿는 범위
The grade above describes protocol/reliability evidence. It does **not** mean every reference
implementation is selectable in the default composition. Dispatch reachability is a separate axis:
위 등급은 프로토콜·신뢰성 증거를 말한다. 모든 참조 구현을 기본 조립에서 고를 수 있다는 뜻이 **아니다**. 발송이 닿는지는
따로 보는 축이다.
| Provider family | Dispatch assembler in shipped composition | Callback assembler | Current use |
| provider family | 내보내는 조립의 발송 assembler | 콜백 assembler | 지금 쓰임 |
|---|---|---|---|
| SMTP | **yes** | no | EMAIL dispatch reference family |
| SES | **yes** | **yes** | EMAIL dispatch + SNS callback ingestion; disabled reference profile ships in `config/module-defaults/notification.yml` (`composition:notification-platform`) |
| SMTP | **있음** | 없음 | EMAIL 발송 참조 family |
| SES | **있음** | **있음** | EMAIL 발송 + SNS 콜백 수집. 꺼진 참조 profile이 `config/module-defaults/notification.yml`(`composition:notification-platform`)에 들어 있다 |
APNs, FCM, Twilio, Web Push and Webhook adapters shipped as protocol code with no assembler and
were removed; `ProviderType` now lists only SES and SMTP, so such a profile fails binding as an
unknown type. An enabled dispatch profile with no assembler fails startup by profile/family; it never silently
assembles into an empty runtime. SMTP additionally names `spring.mail.host` when its shipped
assembler is absent because the relay was not configured.
APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있다가 지워졌다. 이제
`ProviderType`에는 SES와 SMTP만 있으므로 그런 profile은 모르는 종류로 바인딩에서 실패한다. assembler가 없는 켜진 발송
profile은 profile·family 이름을 대며 기동에 실패한다. 빈 런타임으로 조용히 조립되는 일은 없다. SMTP는 relay가 설정되지
않아 내보내는 assembler가 없으면 `spring.mail.host`도 이름 댄다.
## What each grade requires
## 등급마다 필요한 것
| Grade | Requires |
| 등급 | 필요한 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 | nothing; the receiving contract owns its own guarantees |
| Experimental | nothing; the grade is the warning |
| Extension | 없음. 받는 쪽 계약이 자기 보장을 가진다 |
| Experimental | 없음. 등급 자체가 경고다 |
`recoverable` is backed by two tests. `WorkerCrashRecoveryContractTest` walks the four phases a
dispatch passes through — claimed, attempt written, request started, body committed — and pins the
rows a dead worker leaves at each: a passed lease, and from the attempt insert on an unfinished
attempt carrying that phase's evidence. It writes those rows itself, so it checks recovery's input,
not recovery. `PostgreSqlNotificationBackgroundPassIntegrationTest` runs lease recovery and
reconciliation over rows the dispatcher's own factory wrote and asserts the outcome: requeued before
any attempt, reconciled after one (review 05-01, RR-03-07).
`recoverable`은 테스트 둘이 뒷받침한다. `WorkerCrashRecoveryContractTest`는 발송이 지나는 네 단계(claim됨, attempt 기록됨,
요청 시작됨, 본문 커밋됨)를 따라가며 단계마다 죽은 worker가 남기는 행을 고정한다. 지난 lease, 그리고 attempt insert부터는
그 단계의 증거를 가진 끝나지 않은 attempt다. 그 행을 테스트가 직접 쓰므로, 복구가 아니라 복구의 입력을 확인한다.
`PostgreSqlNotificationBackgroundPassIntegrationTest`는 dispatcher 자신의 factory가 쓴 행에 lease 복구와 맞추기를 돌리고
결과를 단언한다. attempt 전이면 다시 큐에 넣고, attempt 뒤면 맞춘다(review 05-01, RR-03-07).
The remaining unmet claim, and what would meet it:
남은 미충족 claim과 그것을 채울 것:
- **provider-wire-qualified** — a real provider sandbox call producing an immutable, uploaded
artifact with a correlation id. No request has ever left the process in CI.
- **provider-wire-qualified** — 실제 provider sandbox 호출로 correlation id가 있는 불변 산출물을 만들어 올린다. CI에서
프로세스 밖으로 요청이 나간 적이 한 번도 없다.
## Evidence levels
## 증거 수준
`NONE` → `PLATFORM_QUEUED` → `PROVIDER_ACCEPTED` → `NETWORK_OR_CARRIER_ACCEPTED` →
`DEVICE_DELIVERED` → `USER_AGENT_DISPLAYED` → `USER_READ`
| Provider signal | Highest evidence it may produce |
| provider 신호 | 그 신호가 낼 수 있는 가장 높은 증거 |
|---|---|
| Internal queue commit | `PLATFORM_QUEUED` |
| 내부 큐 커밋 | `PLATFORM_QUEUED` |
| SES `MessageId` | `PROVIDER_ACCEPTED` |
| SES `Delivery` | `NETWORK_OR_CARRIER_ACCEPTED` |
| In-app row commit | `PROVIDER_ACCEPTED` |
| In-app `seen` endpoint | `USER_AGENT_DISPLAYED` |
| In-app `read` endpoint, authenticated app receipt | `USER_READ` |
| 앱 안 행 커밋 | `PROVIDER_ACCEPTED` |
| 앱 안 `seen` 엔드포인트 | `USER_AGENT_DISPLAYED` |
| 앱 안 `read` 엔드포인트, 인증된 앱 수신 확인 | `USER_READ` |
Promotions the platform will not make, in code or in configuration:
플랫폼이 코드에서도 설정에서도 하지 않는 승격:
- A push or SMS acceptance, from any provider adapter a deployment adds, is not `DEVICE_DELIVERED`.
- A provider 2xx is not `DELIVERED`.
- An SES `MessageId` is not `DELIVERED`.
- An SMTP `250` is not inbox delivery.
- 배포가 더한 어느 provider 어댑터에서 온 것이든 push·SMS 수락은 `DEVICE_DELIVERED`가 아니다.
- provider의 2xx는 `DELIVERED`가 아니다.
- SES `MessageId`는 `DELIVERED`가 아니다.
- SMTP `250`은 받은편지함 도착이 아니다.
## Submission outcomes
## 제출 결과
`NOT_SUBMITTED`, `CONFIRMED_ACCEPTED`, `CONFIRMED_REJECTED`, `AMBIGUOUS`.
`AMBIGUOUS` is a first-class stored state, not an error path. It means the request body was committed
to the provider and the outcome could not be read. While an ambiguous attempt exists on a recipient
delivery, automatic retry and automatic cross-channel fallback are both blocked.
`AMBIGUOUS`는 오류 경로가 아니라 정식으로 저장되는 상태다. 요청 본문을 provider에 넘겼지만 결과를 읽지 못했다는 뜻이다.
수신자 전달에 모호한 attempt가 있는 동안에는 자동 재시도와 자동 채널 전환이 모두 막힌다.
## Not supported
## 지원하지 않는 것
The platform will not claim any of the following, because no channel above can support them:
위의 어떤 채널도 뒷받침할 수 없으므로 플랫폼은 다음 중 어떤 것도 주장하지 않는다.
- guaranteed delivery
- guaranteed read
- exactly-once human notification
- unconditional multi-provider failover after an unread response
- provider SDK types in the public API
- audience selection, campaign segmentation or jurisdiction rulings
- 전달 보장(guaranteed delivery)
- 읽음 보장(guaranteed read)
- 사람에게 가는 알림의 정확히 한 번(exactly-once) 전달
- 읽지 못한 응답 뒤의 조건 없는 다중 provider failover
- 공개 API의 provider SDK 타입
- 대상 선정, 캠페인 세분화, 관할 판정
## Target model
## 대상 모델
`FCM_FID` is the primary mobile push target. `FCM_REGISTRATION_TOKEN_LEGACY` and
`APNS_DEVICE_TOKEN` are separate types with separate lifecycles; they are never flattened into one
string field.
`FCM_FID`가 모바일 push의 기본 대상이다. `FCM_REGISTRATION_TOKEN_LEGACY`와 `APNS_DEVICE_TOKEN`은 수명 주기가 다른 별도
종류다. 하나의 문자열 칸으로 합치지 않는다.