docs(adr)!: 알림 결정 기록을 docs/adr로 옮긴다
결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다. 문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이 모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지 보기」도 두 곳을 가리킨다. NOTIF-ADR-001~005를 이름 그대로 docs/adr/로 옮긴다(git mv, 본문·머리 블록 그대로). 가리키던 곳을 함께 고친다. - 루트 README 문서 지도 행, docs/README.md 지도·수명 표·머리 블록 절 - scripts/check-docs.py의 RECORD_KINDS·DECISION_PREFIXES와 설명 - NotificationReleaseGateTest: ADR 넷의 존재를 docs/adr/에서 본다 - docs/upgrade/2026-11-docs-records.md: 옮긴 경로 표와 찾는 명령 파일 이름 앞머리(NOTIF-ADR-)는 바꾸지 않았다. 설계서·리뷰·모듈 문서가 NOTIF-ADR-005처럼 번호로 부르고 있어, 이름을 ADR-NOTIF-로 바꾸면 기록 본문의 부름이 맞지 않게 된다. 위험: 이 ADR을 가리키던 문서·주석을 가진 파생 서비스는 경로를 바꿔야 한다(upgrade 안내 3절). notification-platform.yml의 pull_request 경로 필터 docs/notification/**는 이제 이 ADR을 보지 않는다. ADR 존재 시험 (NotificationReleaseGateTest)은 PR의 ci(:adapter:outbound:notification: check)에서 계속 돈다. workflow는 이 변경에서 고치지 않았다. 이 ADR을 예외로 둔 줄은 없었다(합친 트리의 예외 목록이 이미 비어 있다). 검증(노트북): check-docs.py OK(language·head·reference·number·map· readme 걸림 0), 자기 시험 65 OK, check-work-docs.py OK, check-repo-layout.py OK, 살아 있는 문서에서 notification/adr 참조 0. BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로 옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로 바꾼다.
This commit is contained in:
@@ -1,34 +0,0 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
- 요약: 알림 submit()은 영속적으로 받아들였다는 뜻이라는 결정이다.
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-001 — `submit()`은 durable 접수를 뜻한다
|
||||
|
||||
## 상태
|
||||
|
||||
채택.
|
||||
|
||||
## 배경
|
||||
|
||||
알림 플랫폼의 뻔한 API는 성공이나 실패를 돌려주는 `send()`다. 이 플랫폼이 지원하는 모든 채널이 그 반환값을 거짓말로 만든다:
|
||||
|
||||
- SES는 요청을 받고 `MessageId`를 돌려준 뒤에도 보내기를 거절할 수 있다.
|
||||
- Twilio는 `accepted`, `sent`, `delivered`를 따로따로, 나중에 오는 이벤트로 나눈다.
|
||||
- APNs는 알림을 받은 뒤 전달하거나, 저장하거나, 버릴 수 있다.
|
||||
- Web Push는 프로토콜 수준에서 push service의 접수와 user agent의 확인 응답을 나눈다.
|
||||
|
||||
## 결정
|
||||
|
||||
`submit()`과 `schedule()`은 논리 요청과 그 수신자 job이 데이터베이스에 커밋되면 돌아온다. 접수증은 `notificationId`,
|
||||
`RequestStatus`, `acceptedAt`을 싣고, `delivered`·`sent`·`read` 요소가 없다. 트랜잭션이 열려 있는 동안에는 어떤 provider에도
|
||||
연락하지 않는다.
|
||||
|
||||
## 결과
|
||||
|
||||
타입이 그렇게 읽을 길을 주지 않으므로, 호출자는 접수를 전달로 착각할 수 없다. 전달 상태는 provider 이벤트 원장에서 만든
|
||||
projection에 대한 따로 둔 query다. 비용은 「도착했나?」가 두 번째 질문이라는 것이다 — 그것이 정직한 질문 수다.
|
||||
@@ -1,31 +0,0 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
- 요약: 알림 상태를 덧붙이기만 하는 이벤트 원장과 채널별 projector로 둔다는 결정이다.
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-002 — 채널 projector를 둔 append-only 이벤트 원장
|
||||
|
||||
## 상태
|
||||
|
||||
채택.
|
||||
|
||||
## 배경
|
||||
|
||||
선형 전달 상태 하나는 제자리에서 고쳐야 하고, 그러면 새 이벤트가 저장된 것보다 앞서는지 정할 규칙이 필요하다. 자연스러운 규칙 —
|
||||
ordinal 비교 — 은 실제 provider traffic에서 틀린다. Twilio는 callback 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 온다. email은
|
||||
전달 뒤에 불만 신고를 낸다. 두 경우 모두 ordinal 규칙 아래에서 정보를 잃는다.
|
||||
|
||||
## 결정
|
||||
|
||||
provider 이벤트는 어떤 projection이 돌기 전에 바뀌지 않는 원장에 덧붙인다. 채널별 projector가 명시한 전이 표로 이벤트를
|
||||
`SubmissionOutcome`, `DeliveryOutcome`, `EvidenceLevel`, `EngagementFacts`, `SuppressionFacts`로 합친다. projection은 멱등이고 원장에서
|
||||
다시 돌릴 수 있다.
|
||||
|
||||
## 결과
|
||||
|
||||
중복, 순서가 뒤바뀐, 늦은 이벤트는 결함이 아니라 보통 입력이다. 잘못 project한 이벤트가 아직 저장돼 있으므로 projector 결함은
|
||||
회복할 수 있다. projector 버전은 다시 돌려서 옮길 수 있다. 비용은 이벤트마다 두 번째 쓰기와, 원장보다 늦을 수 있는 projection이다.
|
||||
@@ -1,42 +0,0 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
- 요약: 결과가 모호한 제출을 정식 상태로 둔다는 결정이다.
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-003 — 모호한 제출은 정식 상태다
|
||||
|
||||
## 상태
|
||||
|
||||
채택.
|
||||
|
||||
## 배경
|
||||
|
||||
가장 흔한 심각한 실패는 거절이 아니다. body는 provider에 닿았는데 응답이 돌아오지 않은 요청이다. 플랫폼에는 provider 요청 id가 없고,
|
||||
사용자는 알림을 받았을 수도 안 받았을 수도 있다.
|
||||
|
||||
그것을 실패로 다루면 중복이 생긴다: 재시도가 두 번째 메시지를 보내고, 채널을 넘는 대체가 이미 도착한 push 옆에 SMS를 보낸다. 성공으로
|
||||
다루면 실제 실패를 잃는다.
|
||||
|
||||
## 결정
|
||||
|
||||
`AMBIGUOUS`는 저장되는 `SubmissionOutcome`이자 `AttemptConfirmation`이다. 시도는 `requestStarted`, `requestBodyCommitted`,
|
||||
`providerResponseReceived`를 기록하고, 각각 `PROVEN`, `INFERRED`, `UNKNOWN` 중 하나의 `EvidenceCertainty`를 가진다. 그래서 모르는
|
||||
어댑터가 `false`로 답하도록 강요받지 않는다.
|
||||
|
||||
수신자 전달에 모호한 시도가 있는 동안에는:
|
||||
|
||||
- provider가 요청별 멱등성을 증명하지 않으면 자동 재시도를 막는다
|
||||
- 채널을 넘는 자동 대체는 조건 없이 막는다
|
||||
- provider가 상태 query를 지원하면 맞춰 보기를 돌린다
|
||||
- 그렇지 않으면 전달을 멈추고 운영자를 기다린다
|
||||
|
||||
모호한 시도를 운영자가 다시 보내려면 중복 위험을 명시해 승인해야 한다.
|
||||
|
||||
## 결과
|
||||
|
||||
어떤 알림은 사람이나 맞춰 보기 한 바퀴가 필요한 상태에서 멈춘다. 그것이 의도한 거래다: 풀리지 않은 모름이 보장된 중복보다 싸고,
|
||||
상태는 어느 쪽으로든 소리 없이 풀리지 않고 보인다.
|
||||
@@ -1,33 +0,0 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
- 요약: FCM 대상은 installation id를 먼저 쓴다는 결정이다.
|
||||
- 현재 정본: `docs/notification/provider-runbooks.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-004 — FCM installation id가 주 대상이다
|
||||
|
||||
## 상태
|
||||
|
||||
채택.
|
||||
|
||||
## 배경
|
||||
|
||||
Firebase는 이제 installation id(FID)를 권하고 registration token multicast 경로를 옛것으로 다룬다. `token` 문자열 하나 위에 세운
|
||||
contact point 모델은 옛 모델을 유일한 것으로 담게 되고, 나중의 옮기기는 런타임 해석 문제가 된다: 같은 문자열 필드가 행마다 다른
|
||||
뜻이 된다.
|
||||
|
||||
## 결정
|
||||
|
||||
`MobilePushTarget`은 `FcmInstallationId`, `LegacyFcmRegistrationToken`, `ApnsDeviceToken`으로 된 sealed 계층이다. 종류는 문자열 필드
|
||||
하나의 구분자가 아니라 따로 둔 타입이고, 각각 자기 `ContactPointType`을 싣는다. 그래서 유일성 범위와 암호화 associated data가 다르다.
|
||||
|
||||
APNs token은 환경도 싣는다. sandbox와 production은 flag가 아니라 따로 둔 namespace이기 때문이다.
|
||||
|
||||
## 결과
|
||||
|
||||
대상 종류를 옮기는 것은 런타임 짐작이 아니라 빠짐없는 `switch`를 쓴 컴파일 시점 변경이다. 어댑터가 종류마다 자기 wire 표현으로
|
||||
대응시키므로, provider가 한 경로를 바꿔도 다른 경로가 소리 없이 바뀌지 않는다. 비용은 문자열 필드보다 타입이 하나 더 필요하다는
|
||||
것이다.
|
||||
@@ -1,86 +0,0 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-15
|
||||
- 요약: 어느 알림 API가 canonical인지 정한 결정이다. R1 타입은 2026-09-25에 지웠다.
|
||||
- 현재 정본: `docs/notification/module-mapping.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NOTIF-ADR-005 — 어느 notification API가 canonical인가
|
||||
|
||||
## 상태
|
||||
|
||||
채택(2026-08-15). NTF-018 대응.
|
||||
|
||||
**갱신 (2026-09-25):** R1 type은 삭제됐다. production consumer가 끝까지 0건이었고 fake로만 증명된
|
||||
계약이라, 새 consumer를 막는 ArchUnit 규칙을 유지할 이유가 없어졌다. 남은 것은 adapter core의
|
||||
`RoutingNotifier`가 구현하는 단순 알림 포트 3개(`NotificationPort`, `Notification`,
|
||||
`NotificationChannel`)뿐이다. 그래서 아래 「강제」의 `NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER`
|
||||
규칙과 `compatibility.r1` 예외 패키지도 함께 없어졌다. 삭제 목록과 마지막 커밋은
|
||||
`docs/capability-status.md`의 「제거된 코드」 표에 있다. 아래 본문은 결정 당시 기록이다.
|
||||
|
||||
## 문제
|
||||
|
||||
같은 저장소에 notification 모델이 **두 개** 있다.
|
||||
|
||||
| 세대 | 위치 | 규모 |
|
||||
| --- | --- | --- |
|
||||
| R0 legacy | `adapter:outbound:notification`의 router/provider seam | 삭제 예정 |
|
||||
| R1 | `dev.caskeleton.application.notification` (직속) | public type 100개 |
|
||||
| Platform | `dev.caskeleton.application.notification.platform..` | 신규 |
|
||||
|
||||
`application-core/CLAUDE.md`는 R1을 "R1 canonical"이라 부르고,
|
||||
`docs/notification/migration-guide.md`는 R0 → platform 이행만 설명하며 R1의 처분을 전혀 다루지 않는다.
|
||||
`Channel`, plan, dispatch, receipt/evidence 모델이 두 namespace에 중복 존재하고 둘 사이에 production
|
||||
bridge도 import도 없다.
|
||||
|
||||
**실패 모드는 "무엇이 깨지는가"가 아니라 "무엇을 써야 하는가"다.** 새 consumer가 어느 API를 쓸지 알 수
|
||||
없고, 두 모델이 각자 진화하며, R0를 지운 뒤에도 R1 graph가 고아로 남거나 platform이 R1 정책을 우회하는
|
||||
이중 canonical이 된다.
|
||||
|
||||
## 결정
|
||||
|
||||
**Platform이 canonical이다.** R1은 유지되지만 새 production consumer를 받지 않는다.
|
||||
|
||||
이유는 능력이 아니라 증거다. platform은 durable acceptance, fenced claim, event ledger, projection,
|
||||
reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며
|
||||
스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes.
|
||||
It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime
|
||||
wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호
|
||||
검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다.
|
||||
|
||||
## 처분
|
||||
|
||||
R1 public type 100개의 처분은 네 가지 중 하나다.
|
||||
|
||||
| 처분 | 의미 | 대상 |
|
||||
| --- | --- | --- |
|
||||
| `replace` | platform에 동등물이 있다. 새 consumer는 platform을 쓴다 | `Channel`, plan/dispatch/receipt/evidence 계열 |
|
||||
| `bridge` | 변환이 필요하다. 변환은 ACL 한 곳에만 둔다 | writer-cutover / receipt 적용 경로 |
|
||||
| `retain` | platform이 다루지 않는 관심사다. 그대로 둔다 | consent/quiescence verifier port |
|
||||
| `delete` | R0와 함께 사라진다 | R0 router가 쓰던 seam |
|
||||
|
||||
전수 분류표는 이 ADR이 아니라 `docs/notification/module-mapping.md`가 소유한다. ADR은 규칙을,
|
||||
mapping 문서는 목록을 소유한다 — 목록을 두 곳에 복제하면 드리프트하는 쪽이 늘어난다.
|
||||
|
||||
## 강제
|
||||
|
||||
두 namespace 사이의 production dependency는 **0건**이며, 이것은 문서가 아니라 ArchUnit 규칙이 지킨다
|
||||
(`ApplicationBoundaryArchitectureTest`의 `NOTIFICATION_R1_AND_PLATFORM_DO_NOT_DEPEND_ON_EACH_OTHER`).
|
||||
|
||||
변환이 필요해지면 `dev.caskeleton.application.notification.compatibility.r1` 한 패키지에만 두고, 그
|
||||
패키지만 규칙에서 예외로 인정한다. 예외를 한 곳으로 모으는 것이 목적이다 — 두 모델이 서로를 아는
|
||||
지점이 여러 곳이면 "어느 쪽이 canonical인가"라는 질문에 코드가 답하지 못한다.
|
||||
|
||||
## 결과
|
||||
|
||||
- 새 production consumer는 `..notification.platform..`만 쓴다.
|
||||
- R1 type은 남지만, 새 코드가 그것을 import하면 ArchUnit이 막는다.
|
||||
- R0 삭제는 이 ADR과 무관하게 진행된다. R1은 R0와 함께 사라지지 않는다.
|
||||
|
||||
## 하지 않은 것
|
||||
|
||||
R1 100개 type에 `@Deprecated(forRemoval = true)`를 붙이지 않았다. 제거 시점이 정해지지 않았고,
|
||||
`forRemoval`은 "이 릴리스 이후 사라진다"는 약속이라 시점 없이 붙이면 그 자체가 거짓 신호다. 경계는
|
||||
ArchUnit이 강제하고, deprecation은 제거 계획이 생길 때 붙인다.
|
||||
Reference in New Issue
Block a user