diff --git a/README.md b/README.md
index 4e47ec6..e5e1b64 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,294 @@
-# Template Backend
+<div align="center">
 
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ureca-mini2-div4_template-backend&metric=alert_status&token=35bd9a636ce0f7bc836903d9cd4487365306b29c)](https://sonarcloud.io/summary/new_code?id=ureca-mini2-div4_template-backend)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ureca-mini2-div4_template-backend&metric=coverage&token=35bd9a636ce0f7bc836903d9cd4487365306b29c)](https://sonarcloud.io/summary/new_code?id=ureca-mini2-div4_template-backend)
+# 🚀 dabom-processor-usage
+
+### Kafka `usage-events` 기반
+### **실시간 사용량 판단 · DB 직접 정산 · Notification 발행/복구 연계 서비스**
+
+<br/>
+
+<p>
+  <img src="https://img.shields.io/badge/Java-21-ff9a3c?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Spring_Boot-3.4.0-6DB33F?style=for-the-badge&logo=springboot&logoColor=white" />
+  <img src="https://img.shields.io/badge/Kafka-3.6.0-000000?style=for-the-badge&logo=apachekafka" />
+  <img src="https://img.shields.io/badge/Redis-7.1.0-DC382D?style=for-the-badge&logo=redis&logoColor=white" />
+<img src="https://img.shields.io/badge/MySQL-8.0-4479A1?style=for-the-badge&logo=mysql&logoColor=white" />
+</p>
+
+<p>
+  <img src="https://img.shields.io/badge/Real--time-Decision-ff4d6d?style=flat-square" />
+  <img src="https://img.shields.io/badge/Direct-Settlement-00b894?style=flat-square" />
+  <img src="https://img.shields.io/badge/Immediate_Publish-Outbox_Recovery-f39c12?style=flat-square" />
+</p>
+
+</div>
+
+---
+
+## ✨ Overview
+
+`dabom-processor-usage`는 DABOM 시스템에서 **사용량 이벤트 처리 전담 레포**다.
+
+이 레포는 단순 Kafka consumer가 아니라, 아래 흐름을 **하나의 서비스 안에서 직접 처리**한다.
+
+- `usage-events` 수신
+- payload 및 `familyId-customerId` 검증
+- Redis warmup
+- Redis + Lua 기반 실시간 사용량 판단
+- DB 직접 정산
+- notification 대상 판단
+- notification 즉시 비동기 발행
+- 실패 건에 대한 Outbox 기반 복구 연계
+
+### 📌 At a Glance
+
+<div align="center">
+
+| Area | Responsibility |
+|---|---|
+| ⚡ Real-time Decision | Redis + Lua |
+| 🧾 Direct Settlement | MySQL |
+| 🔔 Publish & Recovery | `notification-events` + Outbox |
+
+</div>
+
+즉 이 레포는 아래 역할을 동시에 담당한다.
+
+| 역할 | 설명 |
+|---|---|
+| ⚡ 실시간 판단 서비스 | Redis + Lua로 사용량 상태를 빠르게 계산 |
+| 🧾 정산 서비스 | DB를 기준으로 최종 사용량과 quota를 반영 |
+| 🔔 알림 파생 서비스 | notification 대상 여부를 결정하고 발행과 복구를 연계 |
+
+---
+
+## 🏗️ Architecture Summary
+
+현재 구조는 **`usage-events` 중심 직접 처리 구조**다.
+
+과거에는 usage 처리 결과가 `usage-persist`, `usage-realtime`, `notification-events` 등 여러 Kafka 토픽으로 분산되던 구조가 있었지만, 현재는 다음 방향으로 단순화되었다.
+
+- DB 정산은 이 서비스가 직접 수행
+- notification은 대상 이벤트만 Outbox에 저장
+- usage 서비스가 먼저 즉시 비동기 발행 시도
+- 실패 건은 `PUBLISH_PENDING` 유지
+
+```mermaid
+flowchart LR
+    A[Kafka: usage-events] --> B[Usage Consumer]
+    B --> C[Validation]
+    C --> D[Redis Warmup]
+    D --> E[Lua Decision]
+    E --> F[DB Settlement]
+    F --> G{Should Notify?}
+    G -- No --> H[Done]
+    G -- Yes --> I[Save Outbox PUBLISH_PENDING]
+    I --> J[Async Publish to notification-events]
+    J --> K{Broker Ack}
+    K -- Success --> L[Mark SENT]
+    K -- Fail --> M[Keep PUBLISH_PENDING]
+    M --> N[External Recovery Process]
+```
+
+> 핵심은 **다중 토픽 분산 구조를 줄이고**, usage 처리의 핵심 책임을 이 서비스 안으로 모았다는 점이다.
+
+---
+
+## 🎯 Why This Repository Exists
+
+사용량 처리에서는 아래 요구가 동시에 존재한다.
+
+- **빠르게 판단해야 한다**
+- **정확하게 정산해야 한다**
+- **중복 이벤트와 재처리를 견뎌야 한다**
+- **알림은 즉시 보내되 실패 시 복구 가능해야 한다**
+
+이 레포는 이 요구를 아래처럼 분리해서 해결한다.
+
+### Redis + Lua
+- 빠른 판단
+- dedup 제어
+- 실시간 정책 처리
+- 경고/차단 상태 계산
+
+### DB
+- 최종 정산
+- 영속 데이터 관리
+- source of truth 역할
+
+### Outbox
+- notification 대상 이벤트만 저장
+- 즉시 발행 실패 시 복구 기준점 유지
+
+```mermaid
+flowchart TD
+    A[Redis + Lua] -->|빠른 판단| D[Usage Processing]
+    B[DB] -->|최종 정산| D
+    C[Outbox] -->|발행 실패 복구 기준점| D
+```
+
+---
+
+## 🧩 Responsibilities
+
+### 1) Validation
+- payload 기본 검증
+- `familyId-customerId` 관계 검증
+- invalid input는 뒤 단계로 보내지 않음
+
+### 2) Redis + Lua Decision
+- Redis warmup
+- duplicate 판단
+- 사용량 반영
+- 경고/차단 상태 계산
+- 알림 dedup 판단
+
+### 3) Direct DB Settlement
+- `usage_record` 기반 멱등 정산
+- `customer_quota`, `family_quota` 직접 반영
+- blocked 이벤트는 차단 상태만 반영
+
+### 4) Notification Publish & Recovery
+- notification 대상 판단
+- Outbox에 `PUBLISH_PENDING` 저장
+- `notification-events` 즉시 비동기 발행
+- 성공 시 `SENT`, 실패 시 `PUBLISH_PENDING` 유지
+
+```mermaid
+sequenceDiagram
+    participant K as Kafka usage-events
+    participant U as Usage Service
+    participant R as Redis/Lua
+    participant D as DB
+    participant O as Outbox
+    participant N as Kafka notification-events
+
+    K->>U: usage-events 1건
+    U->>U: payload / family-customer 검증
+    U->>R: warmup + Lua 실행
+    R-->>U: duplicate, status, shouldNotify
+    U->>D: DB 직접 정산
+    alt shouldNotify = true
+        U->>O: PUBLISH_PENDING 저장
+        U->>N: 비동기 발행 시도
+        alt ack success
+            U->>O: SENT 반영
+        else ack fail
+            U->>O: PUBLISH_PENDING 유지
+        end
+    else shouldNotify = false
+        U->>U: Outbox row 생성 없음
+    end
+```
+
+---
+
+## 📨 Kafka Topics
+
+<div align="center">
+
+| Type | Topic |
+|---|---|
+| 📥 Consumed | `usage-events` |
+| 📤 Produced | `notification-events` |
+| 🕰️ Historical | `usage-persist`, `usage-realtime` |
+
+</div>
+
+---
+
+## 🏗️ Key Design Decisions
+
+<details>
+<summary><b>1. Redis와 DB의 역할 분리</b></summary>
+
+<br/>
+
+- Redis: 빠른 판단과 실시간 상태 계산
+- DB: 최종 정산과 영속 기준점
+
+즉, **Redis는 속도**, **DB는 정확성**을 담당하도록 분리했다.
+
+</details>
+
+<details>
+<summary><b>2. DB 정산은 멱등하게 재진입 가능</b></summary>
+
+<br/>
+
+- `usage_record`가 선행 멱등 가드 역할
+- quota 반영은 새 insert 성공 시에만 수행
+- blocked 상태는 재적용되어도 최종 상태가 깨지지 않음
+
+즉 duplicate와 retry를 **예외가 아니라 기본 전제**로 보고 설계했다.
+
+</details>
+
+<details>
+<summary><b>3. 잘못된 입력은 초입에서 차단</b></summary>
+
+<br/>
+
+membership 검증을 초입으로 끌어올려, 비정상 입력이 Redis, DB, notification 단계까지 내려가지 않도록 막는다.
+
+</details>
+
+<details>
+<summary><b>4. Notification은 즉시성과 복구성을 함께 가져감</b></summary>
+
+<br/>
+
+- usage 서비스가 먼저 즉시 비동기 발행
+- 실패 건만 Outbox에 남겨 후속 복구 가능
+
+즉, **즉시성**과 **복구성**을 동시에 고려했다.
+
+</details>
+
+<details>
+<summary><b>5. Outbox는 publish-candidate only</b></summary>
+
+<br/>
+
+- 모든 이벤트를 저장하지 않음
+- notification 대상 이벤트만 저장
+- 고TPS 환경에서 불필요한 DB hot path write를 줄이기 위한 선택
+
+</details>
+
+---
+
+## 🚨 Failure Handling
+
+| 유형 | 처리 방식 |
+|---|---|
+| IGNORE | payload 계약 위반, 잘못된 family-customer 조합 |
+| RETRY | Redis 실패, Lua 실패, DB 정산 실패, Outbox 저장 실패 |
+| DLQ / Non-Retryable | 상태 계약 불일치, 복구 불가능한 직렬화/역직렬화 오류 |
+
+---
+
+## 📚 Further Reading
+
+공식 문서는 `docs/` 아래 문서를 참고한다.
+
+- [서비스 개요 및 구조 변화](./docs/01_SERVICE_OVERVIEW.md)
+- [현재 처리 플로우](./docs/02_PROCESSING_FLOW.md)
+- [Outbox 및 재시도](./docs/03_OUTBOX_AND_RETRY.md)
+- [예외 처리 및 복구 전략](./docs/04_EXCEPTION_AND_RECOVERY.md)
+- [데이터 모델 및 Redis 키 구조](./docs/05_DATA_MODEL_AND_KEYS.md)
+
+---
+
+## 📝 Summary
+
+`dabom-processor-usage`의 핵심은 다음으로 정리할 수 있다.
+
+- 초기의 다중 토픽 분산 구조를 줄였다.
+- `usage-events` 중심으로 DB 정산 책임을 이 서비스에 모았다.
+- Redis + Lua로 실시간 판단을 수행한다.
+- notification은 즉시 비동기 발행과 Outbox 기반 복구를 분리한다.
+- Outbox는 발행 대상 이벤트만 저장해 고TPS 비용을 줄인다.
+
+> 즉 이 레포는 단순 consumer 구현이 아니라,  
+> **실시간성 · 정합성 · 복구성 · 운영 가능성**을 함께 고려해서 정리된 usage processing 서비스다.
\ No newline at end of file
diff --git a/docs/01_SERVICE_OVERVIEW.md b/docs/01_SERVICE_OVERVIEW.md
new file mode 100644
index 0000000..86c470f
--- /dev/null
+++ b/docs/01_SERVICE_OVERVIEW.md
@@ -0,0 +1,331 @@
+# Service Overview
+
+## 1. Purpose
+
+`dabom-processor-usage`는 `usage-events`를 소비해 사용량 이벤트를 처리하는 서비스다.
+
+현재 이 서비스가 수행하는 일은 아래와 같다.
+
+- payload 기본 검증
+- `familyId-customerId` 관계 검증
+- Redis warmup
+- Redis + Lua 기반 상태 계산
+- DB 직접 정산
+- notification 대상 판단
+- notification 즉시 비동기 발행 시도
+- 발행 실패 건에 대한 복구 기준점 저장
+
+즉 이 서비스는 단순 consumer가 아니라, 실시간 판단과 정산, notification 파생을 함께 담당하는 usage processing service다.
+
+## 2. What the Previous Structure Looked Like
+
+초기에는 usage 처리 결과가 여러 Kafka 토픽으로 분산되는 구조였다.
+
+- `usage-events`
+- `usage-persist`
+- `usage-realtime`
+- `notification-events`
+
+당시 흐름은 대략 아래와 같았다.
+
+1. `usage-events` 수신
+2. Redis/Lua로 상태 계산
+3. `usage-persist`로 DB 정산용 이벤트 발행
+4. `usage-realtime`로 실시간 사용량 이벤트 발행
+5. `notification-events`로 알림 이벤트 발행
+
+즉 usage 이벤트 1건이 들어오면, 그 결과가 여러 토픽으로 다시 분기되는 구조였다.
+
+```mermaid
+flowchart LR
+    A[usage-events] --> B[Redis + Lua 판단]
+    B --> C[usage-persist]
+    B --> D[usage-realtime]
+    B --> E[notification-events]
+```
+
+## 3. Why the Structure Changed
+
+이전 구조는 기능을 토픽으로 분리했다는 점에서는 단순해 보일 수 있었지만, 실제 usage 처리 관점에서는 아래 문제가 있었다.
+
+### 3.1 DB 정산 책임이 멀리 떨어져 있었다
+
+usage 상태를 계산하는 곳과 DB 정산을 수행하는 곳이 `usage-persist` 경로로 분리돼 있었다.
+
+이 때문에:
+- 사용량 판단과 최종 정산을 한 흐름으로 설명하기 어려웠고
+- 실패 시 어디부터 다시 봐야 하는지가 분산되었고
+- 멱등성 보장을 어느 지점이 책임지는지 바로 읽히지 않았다.
+
+### 3.2 하나의 이벤트가 여러 토픽으로 분기됐다
+
+usage 이벤트 1건이 들어오면 `usage-persist`, `usage-realtime`, `notification-events`로 다시 나갔다.
+
+이 때문에:
+- 운영자가 하나의 usage 이벤트를 추적하려면 여러 토픽을 같이 봐야 했고
+- 장애 시 “이 이벤트가 어느 단계까지 진행됐는가”를 설명하기 어려웠고
+- 실시간 판단과 정산, 알림 사이의 관계가 문서 없이 코드만 봐서는 잘 드러나지 않았다.
+
+### 3.3 notification의 즉시성과 복구 지점이 분리돼 있었다
+
+알림은 발행 자체는 Kafka 경로로 보내지만, 발행 실패 후 어떤 기준으로 다시 복구할 것인지는 명확한 경계가 필요했다.
+
+이 때문에:
+- 즉시 발행과 복구 발행의 책임을 나눌 필요가 있었고
+- usage 서비스가 어디까지 책임지는지를 분명히 해야 했다.
+
+### 3.4 잘못된 입력을 더 앞에서 끊어야 했다
+
+usage 처리에서 `familyId-customerId` 관계가 틀린 입력은 Redis, Lua, DB, notification까지 내려가지 않는 것이 맞다.
+
+이전보다 더 앞단에서:
+- payload 계약 위반
+- family-customer 불일치
+를 끊는 구조가 필요했다.
+
+## 4. How the Current Structure Solves It
+
+현재 구조는 usage 처리의 핵심 책임을 `usage-events` 처리 서비스 안으로 모으는 방향으로 정리되었다.
+
+### 4.1 DB 정산을 usage 서비스가 직접 수행
+
+이제 `usage-events`를 소비한 직후:
+- validation
+- Redis/Lua 판단
+- DB 정산
+이 하나의 서비스 흐름 안에서 이어진다.
+
+효과:
+- usage 이벤트 1건이 어떤 순서로 처리되는지 설명이 쉬워짐
+- 정산 멱등성과 복구 지점이 이 서비스 기준으로 정리됨
+
+### 4.2 실시간 판단과 영속 정산의 경계 명확화
+
+현재 구조는 역할을 아래처럼 나눈다.
+
+- Redis + Lua: 빠른 판단과 상태 계산
+- DB: 최종 정산과 영속 기준점
+
+효과:
+- Redis는 실시간성
+- DB는 정합성
+을 담당한다는 점이 구조적으로 분명해졌다.
+
+### 4.3 notification은 대상 이벤트만 저장하고, 즉시 발행과 복구를 분리
+
+현재 notification 흐름은 아래와 같다.
+
+- notification 대상일 때만 Outbox row 생성
+- usage 서비스가 즉시 비동기 발행 시도
+- 실패 시 `PUBLISH_PENDING` 유지
+- 외부 복구 프로세스가 pending row를 다시 발행
+
+효과:
+- 즉시성은 usage 서비스가 담당
+- 복구는 Outbox를 기준으로 후속 프로세스가 담당
+- notification 관련 상태가 DB row 기준으로 관리된다.
+
+### 4.4 invalid input를 초입에서 차단
+
+`familyId-customerId` 관계를 Redis membership cache와 DB fallback으로 검증한다.
+
+효과:
+- 잘못된 입력이 Redis 상태를 오염시키지 않음
+- 잘못된 입력이 DB 정산이나 notification으로 이어지지 않음
+
+## 5. Why These Technologies
+
+## 5.1 Why a Messaging Queue Was Needed
+
+usage 도메인은 사용량 이벤트가 한 번에 몰릴 수 있고, 생산 시점과 처리 시점을 느슨하게 분리할 필요가 있다.
+
+메시징 큐를 두면 아래가 가능해진다.
+
+- usage 발생 서비스와 usage 처리 서비스를 분리
+- burst traffic를 흡수하면서 순차 처리 기준 유지
+- consumer 재처리와 장애 복구 기준 확보
+- 후속 파생 처리(notification 등)를 이벤트 중심으로 연결
+
+즉 이 서비스에서 메시징 큐는 단순 전송 채널이 아니라, usage 이벤트를 안정적으로 흘려보내는 비동기 처리 기반이다.
+
+## 5.2 Why Kafka
+
+이 서비스가 Kafka를 쓰는 이유는 아래와 같다.
+
+- usage 이벤트는 실시간으로 많이 들어오는 스트림 성격이 강하다.
+- 이벤트를 순서 있게 계속 소비해야 한다.
+- 장애 시 같은 레코드를 다시 처리할 수 있는 재처리 모델이 중요하다.
+- usage, notification처럼 다른 후속 토픽과도 자연스럽게 연결된다.
+
+Kafka는 이런 usage stream 처리에 잘 맞는다.
+
+- 토픽 기반으로 이벤트 흐름을 분리할 수 있다.
+- consumer group으로 수평 확장이 가능하다.
+- offset 기반이라 재처리와 운영 추적이 명확하다.
+- 고TPS 이벤트 스트림 처리에 적합하다.
+
+또한 이 서비스는 가족 단위 상태를 많이 다룬다.
+
+- `family_quota`
+- 가족 잔여량
+- 가족 단위 경고/차단 판단
+
+이런 구조에서는 같은 가족의 이벤트를 같은 흐름에서 순서 있게 처리하는 것이 유리하다. Kafka는 key 기반 partitioning을 기본적으로 지원하므로, `familyId`를 기준으로 같은 가족 이벤트를 같은 파티션 흐름에 태우는 모델과 잘 맞는다.
+
+즉 Kafka는 “업무 명령 전달”보다 “지속적으로 쌓이는 이벤트 스트림 처리”와 “가족 기준 순서가 중요한 usage 처리”에 더 잘 맞는 선택이다.
+
+## 5.3 Why Not RabbitMQ
+
+RabbitMQ 같은 메시지 브로커도 충분히 훌륭하지만, 이 서비스가 다루는 문제와는 성격이 조금 다르다.
+
+RabbitMQ가 더 잘 맞는 경우는 보통 아래와 같다.
+
+- 작업 큐 기반의 명령 처리
+- 복잡한 라우팅 규칙
+- 빠른 단건 전달과 ack 중심의 메시징
+
+반면 `dabom-processor-usage`는 아래 특성이 더 중요하다.
+
+- 사용량 이벤트가 지속적으로 들어오는 stream 처리
+- offset 기준 재처리
+- consumer group 확장
+- 같은 가족 이벤트의 순서 있는 처리
+
+RabbitMQ에서도 유사한 구성을 만들 수는 있지만, 일반 queue 모델에서는 Kafka처럼 key 기반 partitioning이 기본 모델은 아니다. 같은 가족의 이벤트를 같은 흐름에서 안정적으로 처리하려면 추가 라우팅 설계나 stream 계열 구성이 필요하다.
+
+즉 이 서비스는 “하나의 작업을 누가 소비할까”보다 “계속 들어오는 usage 이벤트 흐름을 어떻게 안정적으로 처리할까”가 더 중요한 서비스다. 그 점에서 Kafka가 더 자연스럽다.
+
+## 5.4 Why Redis
+
+usage 처리에는 DB만으로는 부족한 구간이 있다.
+
+이 서비스는 아래를 매우 빠르게 판단해야 한다.
+
+- 가족 잔여량이 얼마나 남았는지
+- 개인 월 사용량이 얼마인지
+- 현재 차단 시간대인지
+- 특정 앱이 차단 상태인지
+- 지금 알림을 보내야 하는지
+
+이걸 매 이벤트마다 DB만 보고 처리하면:
+- 읽기 비용이 커지고
+- 동시에 여러 이벤트가 들어올 때 race condition 관리가 어려워지고
+- 실시간 판단 속도가 떨어진다.
+
+Redis를 두면:
+- 필요한 상태를 메모리에서 빠르게 읽고
+- Lua로 원자적으로 갱신과 판단을 같이 수행할 수 있다.
+
+즉 Redis는 단순 캐시가 아니라, usage 실시간 판단 엔진의 일부 역할을 한다.
+
+## 5.5 Why Lua
+
+Redis만 쓰는 것으로는 충분하지 않다. 사용량 증가, 상태 계산, 알림 dedup 판단이 분리되어 있으면 race condition이 생길 수 있기 때문이다.
+
+Lua를 사용하면:
+- duplicate 확인
+- remaining / monthly usage 반영
+- 차단 판단
+- 경고 판단
+- alert dedup 기록
+을 한 번에 원자적으로 처리할 수 있다.
+
+즉 Lua는 “여러 Redis 명령을 한 트랜잭션처럼 묶어 일관된 판단 결과를 만드는 도구”다.
+
+## 5.6 Why Direct DB Settlement
+
+현재 구조는 usage 서비스가 DB 정산을 직접 수행한다.
+
+이렇게 한 이유는 아래와 같다.
+
+- usage 상태 계산과 정산을 한 흐름으로 설명하기 쉽다.
+- `usage_record` 기반 멱등 정산을 바로 수행할 수 있다.
+- `usage-persist` 같은 중간 토픽을 줄여 처리 경로를 단순화할 수 있다.
+
+즉 직접 정산 구조는 “어디서 최종 정산이 일어나는가”를 usage 서비스 안으로 명확히 모으는 선택이다.
+
+## 5.7 Why Outbox
+
+notification은 즉시 발행만으로 끝내기 어렵다. Kafka publish는 실패할 수 있고, 실패 후 다시 보낼 기준점이 필요하다.
+
+Outbox를 두면:
+- notification 대상 이벤트만 DB row로 남기고
+- 즉시 발행 실패 시 `PUBLISH_PENDING`을 기준으로 다시 발행할 수 있다.
+
+즉 Outbox는 notification 실패 후 복구 기준점 역할을 한다.
+
+## 6. Current Architecture
+
+현재 구조의 사실은 아래와 같다.
+
+- Kafka listener는 `usage-events` 하나를 처리한다.
+- Redis/Lua로 `duplicate`, `status`, `shouldNotify`를 계산한다.
+- DB 정산은 이 서비스가 직접 수행한다.
+- notification 대상일 때만 Outbox row를 만든다.
+- usage 서비스가 notification을 즉시 비동기로 먼저 발행한다.
+- 발행 성공 시 `SENT`, 실패 시 `PUBLISH_PENDING`을 유지한다.
+
+```mermaid
+flowchart LR
+    A[Kafka: usage-events] --> B[Usage Consumer]
+    B --> C[Validation]
+    C --> D[Redis Warmup]
+    D --> E[Lua Decision]
+    E --> F[DB Settlement]
+    F --> G{Should Notify?}
+    G -- No --> H[Done]
+    G -- Yes --> I[Save Outbox PUBLISH_PENDING]
+    I --> J[Async Publish to notification-events]
+    J --> K{Broker Ack}
+    K -- Success --> L[Mark SENT]
+    K -- Fail --> M[Keep PUBLISH_PENDING]
+    M --> N[External Recovery Process]
+```
+
+## 7. Core Design Points
+
+### 7.1 Redis와 DB의 역할 분리
+
+- Redis: 빠른 판단과 실시간 상태 계산
+- DB: 최종 정산과 영속 기준점
+
+### 7.2 DB 정산은 재진입 가능
+
+- `usage_record`가 선행 멱등 가드 역할을 한다.
+- allowed 이벤트는 새 `usage_record` insert 성공 시에만 quota를 반영한다.
+- blocked 이벤트는 `usage_record` 없이 차단 상태만 반영한다.
+
+### 7.3 잘못된 입력은 초입에서 차단
+
+- `familyId-customerId` 관계를 Redis membership cache와 DB fallback으로 검증한다.
+- 실제로 잘못된 조합이면 `IllegalArgumentException`으로 중단한다.
+- Redis/DB 조회 자체가 실패하면 retryable 예외로 전파한다.
+
+### 7.4 Notification은 publish-candidate outbox를 사용
+
+- 모든 usage 이벤트를 저장하지 않는다.
+- notification 대상 이벤트만 `PUBLISH_PENDING` row를 만든다.
+- 즉시 발행 실패 시 row를 남겨 후속 복구가 가능하도록 한다.
+
+## 8. Kafka Topics
+
+| Type | Topic |
+|---|---|
+| Consumed | `usage-events` |
+| Produced | `notification-events` |
+| Historical | `usage-persist`, `usage-realtime` |
+
+## 9. Service Boundary
+
+### This Repository Handles
+- `usage-events` 소비
+- 실시간 사용량 판단
+- DB 직접 정산
+- notification 대상 판단
+- notification 즉시 발행 시도
+- notification 복구 기준점 저장
+
+### External Recovery Process Handles
+- `PUBLISH_PENDING` 조회
+- 재발행 시도
+- `SENT` 또는 `FAILED` 반영
diff --git a/docs/02_PROCESSING_FLOW.md b/docs/02_PROCESSING_FLOW.md
new file mode 100644
index 0000000..5077eba
--- /dev/null
+++ b/docs/02_PROCESSING_FLOW.md
@@ -0,0 +1,210 @@
+# Processing Flow
+
+## 1. End-to-End Flow
+
+현재 `dabom-processor-usage`의 usage 이벤트 처리 흐름은 아래와 같다.
+
+1. Kafka에서 `usage-events`를 수신한다.
+2. payload를 검증한다.
+3. `familyId-customerId` 관계를 검증한다.
+4. Redis warmup을 수행한다.
+5. Lua가 `duplicate`, `status`, `shouldNotify`를 계산한다.
+6. Java가 Lua 결과를 해석한다.
+7. DB 정산을 직접 수행한다.
+8. notification 대상이면 Outbox에 `PUBLISH_PENDING`을 저장한다.
+9. notification을 즉시 비동기 발행한다.
+10. 성공하면 `SENT`, 실패하면 `PUBLISH_PENDING`을 유지한다.
+11. notification 비대상이더라도, 같은 `eventId`에 pending row가 남아 있으면 즉시 발행을 다시 시도한다.
+
+## 2. Validation
+
+### 2.1 Payload Validation
+
+초입에서 아래를 검증한다.
+
+- payload null 여부
+- `familyId > 0`
+- `customerId > 0`
+- `bytesUsed > 0`
+
+이 검증은 가장 앞에서 잘못된 메시지를 차단하기 위한 단계다.
+
+효과:
+- Redis 상태 오염 방지
+- DB 정산 오염 방지
+- 불필요한 후속 처리 방지
+
+### 2.2 Family-Customer Validation
+
+`familyId-customerId` 관계를 Redis membership cache와 DB fallback으로 검증한다.
+
+순서:
+1. Redis `family:{familyId}:members` 확인
+2. cache hit면 통과
+3. miss 또는 불일치면 DB fallback
+4. DB에도 없으면 invalid input
+5. Redis와 DB 조회가 실패하면 retryable 예외로 전파
+
+이 단계는 usage 이벤트가 실제 가족 구성원 관계를 만족하는지 확인하는 단계다.
+
+효과:
+- 잘못된 family-customer 조합 차단
+- Redis, Lua, DB, notification까지 잘못된 입력이 내려가지 않음
+
+## 3. Redis + Lua
+
+### 3.1 Redis Warmup
+
+Lua 실행 전에 필요한 Redis 상태를 채운다.
+
+대상:
+- 가족 info
+- 가족 remaining
+- 개인 월 사용량
+- policy constraints
+
+warmup은 Redis에 값이 없을 때 DB를 읽어 필요한 키를 채우는 역할을 한다.
+
+효과:
+- Lua가 필요한 기준값을 항상 Redis에서 읽을 수 있음
+- 월초 첫 이벤트나 캐시 miss 상황에서도 동일한 처리 경로 유지
+
+### 3.2 Lua Decision
+
+Lua는 아래를 원자적으로 수행한다.
+
+- duplicate 여부 확인
+- 사용량 반영
+- 차단 여부 판단
+- 경고 상태 판단
+- 알림 dedup 판단
+- 결과 캐시 저장
+
+대표 결과:
+- `duplicate`
+- `status`
+- `shouldNotify`
+- `totalUsed`
+- `remaining`
+- `monthlyUsed`
+- `userRatio`
+- `monthlyLimit`
+
+왜 Lua를 쓰는가:
+- Redis read/write와 상태 계산을 한 번에 수행할 수 있기 때문이다.
+- 사용량 증가와 상태 판단을 분리하면 race condition이 생길 수 있다.
+- Lua는 Redis 내부에서 원자적으로 실행되므로 같은 이벤트가 몰려도 일관된 결과를 만든다.
+
+## 4. Java Decision
+
+Java는 Lua status를 중앙 매퍼에서 해석한다.
+
+지원하는 status:
+- `NORMAL`
+- `WARNING_50`
+- `WARNING_30`
+- `WARNING_10`
+- `MANUAL`
+- `APP_BLOCK`
+- `TIME_BLOCK`
+- `MONTHLY_LIMIT_EXCEEDED`
+- `FAMILY_QUOTA_EXCEEDED`
+
+이 단계에서 아래가 정해진다.
+
+- DB persist result
+- notification 대상 여부
+- notification payload 의미
+
+즉 Lua는 상태 문자열을 반환하고, Java는 그 문자열을 후속 처리 규칙으로 바꾸는 역할을 맡는다.
+
+## 5. Direct DB Settlement
+
+DB 정산은 usage 서비스가 직접 수행한다.
+
+### 5.1 allowed 이벤트
+1. `usage_record` insert 시도
+2. 새 insert 성공 시에만
+   - `customer_quota`
+   - `family_quota`
+   반영
+
+### 5.2 blocked 이벤트
+- `usage_record`는 만들지 않음
+- `customer_quota` 차단 상태 반영
+
+allowed와 blocked를 나누는 이유는 아래와 같다.
+
+- allowed 이벤트는 실제 사용량 증가를 영속화해야 한다.
+- blocked 이벤트는 사용이 허용되지 않았으므로 사용량 row를 만들지 않고 차단 상태만 반영한다.
+
+같은 이벤트가 다시 들어와도 `usage_record`가 멱등 가드 역할을 한다.
+
+## 6. Notification Flow
+
+notification은 아래 조건을 모두 만족할 때만 대상이다.
+
+- status 기준으로 알림 대상
+- Lua 결과 기준 `shouldNotify = true`
+
+notification 대상이면:
+1. Outbox에 `PUBLISH_PENDING` 저장
+2. `NotificationPayload`를 직렬화해 `payload_json`에 저장
+3. usage 서비스가 즉시 비동기로 발행 시도
+4. 성공하면 `SENT`
+5. 실패하면 `PUBLISH_PENDING` 유지
+
+notification 비대상이면 새 Outbox row는 만들지 않는다.
+
+이 구조의 의미는 아래와 같다.
+
+- 즉시성은 usage 서비스가 담당한다.
+- 발행 실패 후 복구 기준점은 Outbox가 담당한다.
+- notification 대상이 아닌 이벤트는 불필요한 DB row를 남기지 않는다.
+
+## 7. Processing Sequence
+
+```mermaid
+sequenceDiagram
+    participant K as Kafka usage-events
+    participant U as Usage Service
+    participant M as Membership Cache
+    participant R as Redis/Lua
+    participant D as DB
+    participant O as Outbox
+    participant N as Kafka notification-events
+
+    K->>U: usage-events 1건
+    U->>U: payload 검증
+    U->>M: family-customer 검증
+    U->>R: warmup + Lua 실행
+    R-->>U: duplicate, status, shouldNotify
+    U->>D: DB 직접 정산
+    alt shouldNotify = true
+        U->>O: PUBLISH_PENDING 저장
+        U->>N: 비동기 발행 시도
+        alt ack success
+            U->>O: SENT 반영
+        else ack fail
+            U->>O: PUBLISH_PENDING 유지
+        end
+    else shouldNotify = false
+        U->>U: Outbox row 생성 없음
+    end
+```
+
+## 8. Why This Flow Matters
+
+이 흐름에서 중요한 점은 아래 세 가지다.
+
+1. 실시간 판단과 영속 정산이 분리되어 있다.
+- Redis/Lua는 빠른 판단
+- DB는 최종 정산
+
+2. 멱등성이 구조 안에 들어가 있다.
+- Redis dedup
+- `usage_record` 기반 DB 멱등 정산
+
+3. notification은 즉시성과 복구성을 동시에 가진다.
+- 즉시 비동기 발행
+- Outbox 기반 후속 복구
diff --git a/docs/03_OUTBOX_AND_RETRY.md b/docs/03_OUTBOX_AND_RETRY.md
new file mode 100644
index 0000000..4987e47
--- /dev/null
+++ b/docs/03_OUTBOX_AND_RETRY.md
@@ -0,0 +1,169 @@
+# Outbox and Retry
+
+## 1. Outbox Role
+
+`usage_event_outbox`는 notification 발행 상태를 남기기 위한 테이블이다.
+
+현재 구조의 핵심은 아래와 같다.
+
+- 모든 usage 이벤트를 저장하지 않는다.
+- notification 대상 이벤트만 저장한다.
+- 저장되는 payload는 `EventEnvelope`가 아니라 `NotificationPayload` JSON이다.
+- 즉시 발행 실패 시 `PUBLISH_PENDING`이 남는다.
+
+즉 이 테이블은 usage 이벤트 전체 로그가 아니라, notification 발행과 복구를 위한 상태 저장소다.
+
+## 2. Why the Outbox Shape Changed
+
+초기에는 usage 처리 전체를 더 넓게 추적하는 방향도 고려할 수 있었지만, 현재 구조는 notification 대상 이벤트만 저장하는 방향으로 정리되었다.
+
+이렇게 정리한 이유는 아래와 같다.
+
+- usage 도메인에서는 notification 비대상 이벤트 비율이 높을 수 있다.
+- 고TPS 환경에서는 모든 이벤트를 DB row로 남기는 방식이 부담이 커진다.
+- 실제로 복구가 필요한 지점은 notification 발행 실패 구간이다.
+
+그래서 현재 Outbox는 아래 역할에 집중한다.
+
+- notification 대상 확정
+- 즉시 발행 후 상태 추적
+- 후속 복구 프로세스 인계
+
+## 3. Stored Data
+
+주요 컬럼 의미:
+- `event_id`: 원본 usage 이벤트 식별자
+- `family_id`: 가족 ID
+- `customer_id`: trigger 사용자 ID
+- `status`: `PUBLISH_PENDING`, `SENT`, `FAILED`
+- `payload_json`: 최종 `NotificationPayload` JSON
+- `retry_count`, `next_retry_at`, `last_error`: 복구 프로세스 상태 관리용
+
+여기서 `event_id`는 notification 이벤트 id가 아니라, 원본 usage 이벤트 id다.
+즉 이 row가 어떤 usage 이벤트에서 파생됐는지를 추적하는 키다.
+
+## 4. Payload Shape
+
+Outbox에는 `EventEnvelope`가 아니라 최종 `NotificationPayload` JSON을 저장한다.
+
+이렇게 한 이유는 아래와 같다.
+
+- 즉시 발행과 복구 발행이 같은 payload를 사용하게 하기 위해서
+- 복구 프로세스가 payload를 다시 조립하지 않고 바로 재발행할 수 있게 하기 위해서
+- notification의 business payload와 Kafka envelope 생성을 분리하기 위해서
+
+즉 Outbox는 “무엇을 보낼 것인가”를 저장하고, 실제 envelope 생성은 발행 시점에 수행한다.
+
+## 5. Outbox Status
+
+### 5.1 PUBLISH_PENDING
+- notification 발행 대상 확정 완료
+- 아직 성공적으로 마감되지 않은 상태
+
+이 상태는 아래 상황을 포함한다.
+- 즉시 발행 전
+- 즉시 발행 실패 후
+- 후속 복구 프로세스 대기 중
+
+### 5.2 SENT
+- notification Kafka publish 성공이 반영된 상태
+
+### 5.3 FAILED
+- 복구 프로세스가 최종 실패로 마감한 상태
+
+## 6. Immediate Publish Policy
+
+usage 서비스는 notification을 즉시 비동기로 먼저 발행한다.
+
+- 성공 callback이면 `SENT`
+- 실패 callback이면 `PUBLISH_PENDING` 유지
+
+즉 usage 서비스는 즉시성을 담당하고, 복구 프로세스는 pending row를 기준으로 후속 발행을 수행한다.
+
+이 구조를 사용하면:
+- 정상 케이스에서는 즉시 알림 전파
+- 실패 케이스에서는 row 기준 복구
+가 가능해진다.
+
+## 7. Retry Layers
+
+### 7.1 Consumer Retry
+
+lib-kafka 분류 기준:
+- `IllegalArgumentException` -> `IGNORE`
+- `KafkaMessageProcessingException` -> `RETRY`
+- `NonRetryableKafkaMessageProcessingException` -> `DLQ`
+
+현재 이 레포는 consumer retry 설정을 별도로 override하지 않는다.
+
+즉 usage 이벤트 처리 도중 발생한 retryable 예외는 consumer 레벨에서 다시 처리된다.
+
+### 7.2 Service Re-entry
+
+같은 `eventId`가 다시 들어오면 아래가 다시 수행될 수 있다.
+
+- Redis warmup
+- Lua 실행
+- DB 정산
+- pending notification 재발행 시도
+
+이 레이어는 duplicate와 retry를 엄격히 구분하기보다, 같은 이벤트 재진입을 안전하게 흡수하는 역할을 한다.
+
+### 7.3 External Recovery Process
+
+복구 프로세스는 `PUBLISH_PENDING`을 대상으로 아래 순서로 동작한다.
+
+1. `PUBLISH_PENDING` 조회
+2. `payload_json` 역직렬화
+3. `notification-events` 재발행
+4. 성공 시 `SENT` 반영
+5. 필요 시 `retry_count`, `next_retry_at`, `last_error` 갱신
+6. 최종 실패 시 `FAILED` 반영
+
+즉 usage 서비스는 즉시 발행까지, 복구 프로세스는 pending row 후속 발행까지 담당한다.
+
+## 8. Failure Handling Summary
+
+| 유형 | 처리 방식 |
+|---|---|
+| invalid payload / 잘못된 family-customer | `IGNORE` |
+| membership lookup, Redis warmup, Lua, DB 정산, Outbox 저장 실패 | `RETRY` |
+| 상태 계약 불일치 / 복구 불가 직렬화 오류 | `DLQ` |
+| 즉시 notification 발행 실패 | `PUBLISH_PENDING` 유지 |
+
+## 9. Outbox Sequence
+
+```mermaid
+sequenceDiagram
+    participant U as Usage Service
+    participant O as Outbox
+    participant N as Kafka notification-events
+    participant B as External Recovery Process
+
+    U->>O: PUBLISH_PENDING 저장
+    U->>N: 즉시 비동기 발행
+    alt ack success
+        U->>O: SENT 반영
+    else ack fail
+        U->>O: PUBLISH_PENDING 유지
+        B->>O: PUBLISH_PENDING 조회
+        B->>N: 재발행
+        B->>O: SENT 또는 FAILED 반영
+    end
+```
+
+## 10. Why This Design Matters
+
+현재 Outbox 설계의 핵심은 아래 세 가지다.
+
+1. notification 대상 이벤트만 저장한다.
+- 불필요한 row를 줄인다.
+- 고TPS 환경에서 DB hot path 비용을 줄인다.
+
+2. payload를 최종 notification 형태로 저장한다.
+- 즉시 발행과 복구 발행이 같은 데이터를 사용한다.
+- 복구 프로세스가 단순해진다.
+
+3. 즉시성과 복구성을 분리한다.
+- usage 서비스는 즉시 발행을 담당
+- Outbox와 복구 프로세스는 실패 후 후속 발행을 담당
diff --git a/docs/04_EXCEPTION_AND_RECOVERY.md b/docs/04_EXCEPTION_AND_RECOVERY.md
new file mode 100644
index 0000000..ed34470
--- /dev/null
+++ b/docs/04_EXCEPTION_AND_RECOVERY.md
@@ -0,0 +1,163 @@
+# Exception and Recovery Guide
+
+## 1. Purpose
+
+이 문서는 `usage-events` 처리 각 단계에서 예외가 발생했을 때 현재 구조가 어떤 방식으로 복구와 정합성을 유지하는지 정리한다.
+
+핵심은 아래 세 가지다.
+
+- 잘못된 입력은 초입에서 차단한다.
+- retryable 예외는 같은 Kafka 레코드를 다시 처리한다.
+- duplicate와 재처리를 구조적으로 흡수한다.
+
+## 2. Step-by-Step Recovery
+
+| 단계 | 실패 유형 | 처리 방식 | 복구 전략 |
+|---|---|---|---|
+| Payload Validation | payload null, 음수/0 값 | `IllegalArgumentException` | 잘못된 입력으로 종료 |
+| Family-Customer Validation | 실제 소속 불일치 | `IllegalArgumentException` | 잘못된 입력으로 종료 |
+| Family-Customer Validation | Redis/DB 조회 실패 | `KafkaMessageProcessingException` | consumer 재처리 |
+| Redis Warmup | info/remaining/monthly usage warmup 실패 | `KafkaMessageProcessingException` | consumer 재처리 |
+| Lua Execution | null 결과, invalid 배열 | `KafkaMessageProcessingException` | consumer 재처리 |
+| Lua Status Mapping | 지원하지 않는 status | `NonRetryableKafkaMessageProcessingException` | DLQ |
+| DB Settlement | `usage_record`, quota 반영 실패 | 예외 전파 | 트랜잭션 롤백 + consumer 재처리 |
+| Outbox Serialization | payload JSON 직렬화/역직렬화 실패 | `NonRetryableKafkaMessageProcessingException` | DLQ |
+| Outbox Save | `PUBLISH_PENDING` 저장 실패 | 예외 전파 | consumer 재처리 |
+| Immediate Publish | Kafka publish ack 실패 | 예외 콜백 처리 | `PUBLISH_PENDING` 유지 + 복구 프로세스 재발행 |
+
+## 3. Why Each Recovery Strategy Exists
+
+### 3.1 Validation 단계는 재시도보다 격리가 중요하다
+
+payload 계약 위반이나 family-customer 불일치는 다시 처리해도 바뀌지 않는다.
+
+그래서 이 단계의 목표는:
+- 빨리 실패시키고
+- 뒤 단계를 오염시키지 않고
+- 불필요한 재시도를 만들지 않는 것
+이다.
+
+### 3.2 Redis/Lua/DB 단계는 다시 처리할 수 있어야 한다
+
+이 단계들은 일시적인 인프라 문제나 타이밍 이슈가 발생할 수 있다.
+
+그래서 이 단계의 목표는:
+- retryable 예외로 분류하고
+- 같은 usage 이벤트를 다시 처리하게 하고
+- 같은 이벤트 재진입 시에도 결과가 깨지지 않게 하는 것
+이다.
+
+### 3.3 notification 단계는 복구 기준점이 필요하다
+
+즉시 발행은 실패할 수 있다. 그래서 usage 서비스는 발행 대상일 때 Outbox에 `PUBLISH_PENDING`을 남긴다.
+
+이 단계의 목표는:
+- 정상 케이스에서는 바로 보내고
+- 실패 케이스에서는 pending row를 기준으로 다시 보낼 수 있게 하는 것
+이다.
+
+## 4. Loss Prevention Strategy
+
+### 4.1 Invalid Input Isolation
+
+잘못된 payload와 잘못된 family-customer 조합은 초입에서 차단한다.
+
+효과:
+- Redis 오염 방지
+- DB 오염 방지
+- 불필요한 notification 방지
+
+### 4.2 Redis Re-apply Prevention
+
+Lua는 `event:dedup:usage:{eventId}` 키를 사용해 같은 이벤트가 다시 들어와도 Redis 증감을 다시 수행하지 않는다.
+
+효과:
+- consumer 재처리 시 Redis 중복 반영 방지
+- duplicate와 retry가 같은 경로로 들어와도 Redis 상태 안정화
+
+### 4.3 DB Idempotent Settlement
+
+allowed 이벤트는 `usage_record` insert가 먼저 수행되고, 새 insert 성공 시에만 quota를 반영한다.
+
+효과:
+- 같은 `eventId` 재처리 시 `usage_record`가 멱등 가드 역할
+- `customer_quota`, `family_quota` 중복 반영 방지
+
+### 4.4 Notification Recovery Point
+
+notification 대상 이벤트는 Outbox에 `PUBLISH_PENDING`을 저장한 뒤 즉시 비동기 발행을 시도한다.
+
+효과:
+- 즉시 발행 성공 시 `SENT` 반영
+- 즉시 발행 실패 시 `PUBLISH_PENDING`을 기준으로 후속 복구 가능
+
+## 5. Recovery Sequence Examples
+
+### 5.1 Redis 반영 후 DB 정산 실패
+
+```mermaid
+sequenceDiagram
+    participant U as Usage Service
+    participant R as Redis/Lua
+    participant D as DB
+    participant K as Kafka Retry
+
+    U->>R: Lua 실행 및 Redis 반영
+    R-->>U: status 반환
+    U->>D: DB 정산 시도
+    D-->>U: 예외 발생
+    U-->>K: retryable 예외 전파
+    K->>U: 같은 eventId 재처리
+    U->>R: Lua 재실행
+    R-->>U: duplicate 결과 재사용
+    U->>D: DB 정산 재진입
+```
+
+이 시나리오의 핵심은 아래와 같다.
+
+- Redis는 이미 반영되었지만
+- 같은 이벤트 재처리 시 Lua dedup cache가 Redis 재반영을 막는다.
+- DB 정산은 다시 진입하고, 최종적으로 영속 상태가 Redis 판단 결과를 따라간다.
+
+### 5.2 Outbox 저장 후 즉시 발행 실패
+
+```mermaid
+sequenceDiagram
+    participant U as Usage Service
+    participant O as Outbox
+    participant N as Kafka notification-events
+    participant B as Recovery Process
+
+    U->>O: PUBLISH_PENDING 저장
+    U->>N: 즉시 비동기 발행
+    N-->>U: ack 실패
+    U->>O: PUBLISH_PENDING 유지
+    B->>O: pending row 조회
+    B->>N: 재발행
+    B->>O: SENT 또는 FAILED 반영
+```
+
+이 시나리오의 핵심은 아래와 같다.
+
+- 즉시 발행은 실패할 수 있다.
+- 하지만 pending row가 이미 남아 있으므로 복구 기준점은 유지된다.
+- 후속 복구 프로세스는 payload를 다시 만들지 않고 row 기준으로 재발행할 수 있다.
+
+## 6. Stage-by-Stage Guarantees
+
+| 구간 | 정합성 포인트 |
+|---|---|
+| Validation | 잘못된 입력은 뒤 단계로 내려가지 않음 |
+| Redis + Lua | duplicate 결과와 상태 계산을 원자적으로 처리 |
+| DB Settlement | `usage_record` 기반 멱등 정산 |
+| Notification | 대상 이벤트만 Outbox 저장 + 발행 상태 관리 |
+
+## 7. Reading Guide
+
+이 문서를 볼 때는 아래 순서로 읽으면 된다.
+
+1. 어떤 실패가 retryable인지 확인한다.
+2. 그 실패가 Redis, DB, notification 중 어느 계층에서 일어나는지 본다.
+3. 이후 재처리 기준점이 Redis dedup인지, DB 멱등성인지, Outbox인지 확인한다.
+
+즉 현재 구조는 실패 유형마다 복구 기준점을 다르게 두는 방식으로 정리되어 있다.
diff --git a/docs/05_DATA_MODEL_AND_KEYS.md b/docs/05_DATA_MODEL_AND_KEYS.md
new file mode 100644
index 0000000..67eb95d
--- /dev/null
+++ b/docs/05_DATA_MODEL_AND_KEYS.md
@@ -0,0 +1,170 @@
+# Data Model and Redis Keys
+
+## 1. Purpose
+
+이 문서는 `dabom-processor-usage`가 사용하는 핵심 저장 구조를 정리한다.
+
+- MySQL 영속 데이터
+- notification outbox payload
+- Redis key 구조
+- Lua dedup/cache 구조
+
+핵심은 usage 이벤트 1건이 어떤 저장 구조를 통과하고, 그 구조가 각각 어떤 역할을 맡는지 이해하는 것이다.
+
+## 2. MySQL Settlement Model
+
+### 2.1 usage_record
+
+allowed 이벤트의 멱등 가드 역할을 한다.
+
+- 같은 `eventId`가 다시 들어오면 중복 insert를 막는다.
+- 새 row가 들어간 경우에만 quota 반영이 이어진다.
+
+즉 `usage_record`는 “이 usage 이벤트가 실제 사용량 증가로 정산되었는가”를 고정하는 기준점이다.
+
+### 2.2 customer_quota
+
+고객 기준 월 사용량과 차단 상태를 반영한다.
+
+- allowed 이벤트: 월 사용량 증가
+- blocked 이벤트: 차단 상태 반영
+
+즉 customer 단위 정책과 월 사용량을 영속 기준으로 관리하는 구조다.
+
+### 2.3 family_quota
+
+가족 기준 월 사용량을 반영한다.
+
+- allowed 이벤트에서만 증가
+- 가족 잔여량과 경고/차단 판단의 기준이 된다.
+
+즉 Redis에서 빠르게 판단하는 기준값도 결국 DB의 `family_quota` 영속 상태를 바탕으로 warmup 된다.
+
+## 3. Why This Model Matters
+
+현재 정산 구조가 이렇게 나뉜 이유는 아래와 같다.
+
+- `usage_record`: 이벤트 멱등성 기준점
+- `customer_quota`: 고객 단위 월 사용량과 차단 상태 기준점
+- `family_quota`: 가족 단위 총 사용량과 잔여량 기준점
+
+즉 하나의 테이블에 모든 의미를 몰아넣지 않고, usage 이벤트의 역할을 나누어 영속화한다.
+
+## 4. Outbox Payload Model
+
+Outbox에는 `EventEnvelope`가 아니라 최종 `NotificationPayload` JSON이 저장된다.
+
+주요 필드:
+- `familyId`
+- `customerId`
+- `type`
+- `title`
+- `message`
+- `data`
+
+`data`에는 아래 추적 정보가 들어간다.
+- `originEventId`
+- `eventTime`
+- `status`
+- `familyId`
+- `customerId`
+- `appId`
+- `bytesUsed`
+
+이렇게 저장하는 이유는 아래와 같다.
+
+- 즉시 발행과 복구 발행이 같은 payload를 사용하게 하기 위해서
+- 복구 프로세스가 notification 내용을 다시 계산하지 않게 하기 위해서
+- usage 이벤트와 notification payload의 연결 관계를 row 안에 보존하기 위해서
+
+## 5. Redis Key Structure
+
+### 5.1 Family State
+
+- `family:{familyId}:info:{yyyyMM}`
+- `family:{familyId}:remaining:{yyyyMM}`
+- `family:{familyId}:members`
+
+각 키의 의미:
+- `info`: 가족 총 quota와 메타 정보
+- `remaining`: 현재 가족 잔여량
+- `members`: family-customer 검증용 membership set
+
+### 5.2 Customer State
+
+- `family:{familyId}:customer:{customerId}:usage:monthly:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:constraints`
+
+각 키의 의미:
+- `usage:monthly`: 개인 월 사용량 캐시
+- `constraints`: 차단 시간, 앱 차단, 월 한도 같은 정책 제약
+
+### 5.3 Alert Dedup Keys
+
+경고 알림:
+- `family:{familyId}:customer:{customerId}:alert:THRESHOLD:50:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:alert:THRESHOLD:30:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:alert:THRESHOLD:10:{yyyyMM}`
+
+차단 알림:
+- `family:{familyId}:customer:{customerId}:alert:MANUAL:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:alert:APP_BLOCK:{appId}:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:alert:TIME_BLOCK:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:alert:MONTHLY_LIMIT_EXCEEDED:{yyyyMM}`
+- `family:{familyId}:customer:{customerId}:alert:FAMILY_QUOTA_EXCEEDED:{yyyyMM}`
+
+이 키들은 이번 달 같은 유형 알림을 다시 발행하지 않도록 제어하는 역할을 한다.
+
+### 5.4 Event Dedup Key
+
+- `event:dedup:usage:{eventId}`
+
+이 키에는 Lua 결과 캐시가 저장된다.
+
+즉 이 키는 같은 usage 이벤트가 다시 들어왔을 때 Redis 증감을 다시 하지 않게 하는 기준점이다.
+
+## 6. Lua Result Cache
+
+dedup cache에는 아래 정보가 함께 저장된다.
+
+- `totalUsed`
+- `remaining`
+- `status`
+- `monthlyUsed`
+- `userRatio`
+- `monthlyLimit`
+- `shouldNotify`
+- `duplicate`
+
+이 정보가 같이 저장되는 이유는 아래와 같다.
+
+- 같은 이벤트 재처리 시 Redis 재반영 방지
+- 이전 계산 결과 재사용
+- Java가 동일한 상태 해석을 다시 수행할 수 있음
+- duplicate와 retry가 같은 경로로 들어와도 일관된 결과 유지
+
+## 7. Data Flow View
+
+```mermaid
+flowchart TD
+    A[usage-events] --> B[Validation]
+    B --> C[Redis warmup]
+    C --> D[Lua decision]
+    D --> E[usage_record]
+    E --> F[customer_quota]
+    E --> G[family_quota]
+    D --> H[NotificationPayload]
+    H --> I[usage_event_outbox]
+    I --> J[notification-events]
+```
+
+## 8. Reading the Model as a Whole
+
+이 모델을 전체로 보면 역할이 다음처럼 나뉜다.
+
+- Redis: 빠른 상태 계산
+- `usage_record`: 이벤트 멱등성 기준점
+- `customer_quota`, `family_quota`: 최종 정산 기준점
+- Outbox: notification 발행 상태 기준점
+
+즉 `dabom-processor-usage`는 하나의 usage 이벤트를 처리하면서도, 각 저장 구조를 서로 다른 책임에 맞게 사용하도록 설계된 서비스다.