[DABOM-453] v23.1 family_quota 분리 및 family redis 키 suffix 적용

[DABOM-453] v23.1 family_quota 분리 및 family redis 키 suffix 적용

Author: k0081915

ARCHITECTURE.md

@@ -1,9 +1,9 @@
 # 실시간 가족 데이터 통합 관리 시스템 - 아키텍처 설계서
 
-> **문서 버전**: v23.0
+> **문서 버전**: v23.1
 > **작성일**: 2026-03-15
 > **작성자**: DABOM 팀
-> **변경 이력**: v22.0 - API_SPECIFICATION v22.2 Major 버전 동기화: 엔드포인트 총 60개 반영 | v21.0 - API_SPECIFICATION v21.6 동기화: 도메인 리네이밍 (NEGOTIATIONS→APPEALS, REPORTS→RECAPS), 엔드포인트 경로 갱신 6건, 알림 subType APPEAL_*/EMERGENCY_APPROVED 전환, 배치 흐름 FamilyRecapBatchJob/communication_score 갱신, SSE 경로 /families/usage/sse 반영 | v11.0 - 2차기획서 Phase 2 기능 반영: api-core 도메인 확장, 알림 subType 확장, E2E 플로우 추가, 배치 설계 추가 | v10.2 - POLICY 테이블 is_activate → is_active 리네이밍 버전 동기화 | v10.0 - web-core 서브도메인 분리: web-service (www.dabom.site) + web-admin (admin.dabom.site), 모노레포 구조 반영 | v9.0 - api-spec 최종 동기화: 도메인 구조 변경 (7→5도메인), 엔드포인트 URL/메서드/응답 구조 변경 | v8.0 - 전체 문서 버전 통일 (공유 Major + 독립 Minor 체계 도입) | v7.0 - simulator-traffic → simulator-usage 리네이밍, 기술 스택 Go 확정 | v6.0 - ERD v6.0 동기화: customerId 네이밍, POLICY 스키마 반영 | v5.0 - ERD v5.0 동기화: daily→monthly 전환, Redis 키/Lua Script 업데이트, 관리자 전용 인증 API 추가, CUSTOMER/ADMIN 분리 반영; v4.0 - API 엔드포인트 전면 재구성 (api-spec.csv 기반, /api/v1 prefix 제거, 도메인별 그룹핑, JWT familyId 추론, REST 알림 API 추가)
+> **변경 이력**: v23.1 - `family`의 월별 상태를 `family_quota`로 분리하고, Family Redis 키(`info`, `remaining`, `alert`)에 `{yyyyMM}` suffix를 적용하는 구조로 동기화 | v22.0 - API_SPECIFICATION v22.2 Major 버전 동기화: 엔드포인트 총 60개 반영 | v21.0 - API_SPECIFICATION v21.6 동기화: 도메인 리네이밍 (NEGOTIATIONS→APPEALS, REPORTS→RECAPS), 엔드포인트 경로 갱신 6건, 알림 subType APPEAL_*/EMERGENCY_APPROVED 전환, 배치 흐름 FamilyRecapBatchJob/communication_score 갱신, SSE 경로 /families/usage/sse 반영 | v11.0 - 2차기획서 Phase 2 기능 반영: api-core 도메인 확장, 알림 subType 확장, E2E 플로우 추가, 배치 설계 추가 | v10.2 - POLICY 테이블 is_activate → is_active 리네이밍 버전 동기화 | v10.0 - web-core 서브도메인 분리: web-service (www.dabom.site) + web-admin (admin.dabom.site), 모노레포 구조 반영 | v9.0 - api-spec 최종 동기화: 도메인 구조 변경 (7→5도메인), 엔드포인트 URL/메서드/응답 구조 변경 | v8.0 - 전체 문서 버전 통일 (공유 Major + 독립 Minor 체계 도입) | v7.0 - simulator-traffic → simulator-usage 리네이밍, 기술 스택 Go 확정 | v6.0 - ERD v6.0 동기화: customerId 네이밍, POLICY 스키마 반영 | v5.0 - ERD v5.0 동기화: daily→monthly 전환, Redis 키/Lua Script 업데이트, 관리자 전용 인증 API 추가, CUSTOMER/ADMIN 분리 반영; v4.0 - API 엔드포인트 전면 재구성 (api-spec.csv 기반, /api/v1 prefix 제거, 도메인별 그룹핑, JWT familyId 추론, REST 알림 API 추가)
 
 ---
 
@@ -523,27 +523,25 @@ flowchart LR
 
 | Key 패턴 | 타입 | 설명 | TTL |
 |----------|------|------|-----|
-| `family:{fid}:info` | Hash | 가족 기본 정보 (name, total_quota, created_at) | 영구 |
-| `family:{fid}:remaining` | String | 가족 공용 실시간 잔여량 (DECRBY 대상) | 월초 리셋 |
+| `family:{fid}:info:{yyyyMM}` | Hash | 가족 월별 메타 정보 (name, total_quota 등) | 해당 월 만료 시 |
+| `family:{fid}:remaining:{yyyyMM}` | String | 가족 월별 실시간 잔여량 (DECRBY 대상) | 해당 월 만료 시 |
 
 ```bash
-HSET family:100:info name "HappyFamily" total_quota "107374182400" created_at "1707462000"
-SET family:100:remaining "12884901888"
+HSET family:100:info:202603 name "HappyFamily" total_quota "107374182400"
+SET family:100:remaining:202603 "12884901888"
 ```
 
-#### 5.1.2 사용자 사용량 (기간별 집계)
+#### 5.1.2 사용자 월 사용량
 
-정책 확장을 위해 사용량을 **기간별(Period)**로 분리 저장. Lua Script는 정책에 설정된 기간의 Key를 동적으로 참조합니다.
+현재 월별 고객 사용량 키는 월 suffix를 포함한 단일 패턴으로 고정합니다.
 
 | Key 패턴 | 타입 | 설명 | TTL |
 |----------|------|------|-----|
-| `family:{fid}:customer:{cid}:usage:{period}` | String | 기간별 누적 사용량 | 해당 기간 만료 시 |
+| `family:{fid}:customer:{cid}:usage:monthly:{yyyyMM}` | String | 고객 월 누적 사용량 | 해당 월 만료 시 |
 
 ```bash
-# 월별 사용량 (이번 달 5GB 사용)
-SET family:100:customer:1:usage:monthly "5368709120"
-# 일일 사용량 (오늘 500MB 사용)
-SET family:100:customer:1:usage:daily "524288000"
+# 월별 사용량 (2026년 3월 5GB 사용)
+SET family:100:customer:1:usage:monthly:202603 "5368709120"
 ```
 
 #### 5.1.3 런타임 제약 (Runtime Constraints) - 핵심 설계
@@ -577,7 +575,7 @@ HMSET family:100:customer:1:constraints \
 | Key 패턴 | 타입 | 설명 | TTL |
 |----------|------|------|-----|
 | `event:dedup:{uuid}` | String | Kafka 이벤트 중복 처리 방지 | 1시간 |
-| `family:{fid}:alert:{type}:{value}` | String | 알림 중복 발송 방지 | 월초 리셋 |
+| `family:{fid}:alert:THRESHOLD:{threshold}:{yyyyMM}` | String | 월별 임계치 알림 중복 발송 방지 | 해당 월 만료 시 |
 
 #### 5.1.5 정책 메타데이터 (API용)
 
@@ -712,7 +710,7 @@ sequenceDiagram
     KF->>AN: notification-events 수신
 
     AN->>RD: 알림 발송 여부 확인
-    Note over AN,RD: family:{familyId}:alert:50
+    Note over AN,RD: family:{familyId}:alert:THRESHOLD:50:{yyyyMM}
 
     alt 미발송
         RD-->>AN: 없음
@@ -806,8 +804,8 @@ constraints Hash를 순회하며 BLOCK/LIMIT/THROTTLE 등 다양한 정책을 **
 
 | 구분 | Key/Arg | 설명 |
 |------|---------|------|
-| `KEYS[1]` | `family:{fid}:remaining` | 가족 잔여 데이터량 |
-| `KEYS[2]` | `family:{fid}:customer:{cid}:usage` | 기간별 사용량 Key Prefix |
+| `KEYS[1]` | `family:{fid}:remaining:{yyyyMM}` | 가족 월별 잔여 데이터량 |
+| `KEYS[2]` | `family:{fid}:customer:{cid}:usage:monthly:{yyyyMM}` | 고객 월별 사용량 Key |
 | `KEYS[3]` | `family:{fid}:customer:{cid}:constraints` | 제약 조건 Hash |
 | `ARGV[1]` | `request_bytes` | 요청 데이터량 |
 | `ARGV[2]` | `app_id` | 현재 실행 앱 패키지명 |
@@ -1338,7 +1336,8 @@ Spring Scheduler (매월 1일 00:20 트리거)
 Spring Scheduler (매월 1일 00:01 트리거)
 → [Acquire Lock]
 → [Reset Family Month]              DB: family.family_month 갱신
-→ [Reset Family Redis Keys]         Redis: remaining + alert 임계치 키 삭제
+→ [Precreate Next Family Quota]    MySQL: 다음 달 family_quota 선생성
+→ [Reset Family Redis Keys]         Redis: 전월 info + remaining + alert 임계치 키 삭제
 → [Reset Customer Monthly Usage]    Redis: 전월 suffix 구성원 월사용량 키 삭제
 → [Release Lock]
 ```
@@ -1357,8 +1356,8 @@ Spring Scheduler (매월 1일 00:01 트리거)
 ```
 Spring Scheduler (매일 03:00 트리거)
 → [Acquire Lock]
-→ [Invalidate Family Keys]              Redis: family:{id}:info, remaining 삭제
-→ [Invalidate Customer Monthly Usage]   Redis: 구성원 월사용량 키 삭제
+→ [Invalidate Family Keys]              Redis: family:{id}:info:{yyyyMM}, remaining:{yyyyMM} 삭제
+→ [Invalidate Customer Monthly Usage]   Redis: 구성원 월사용량 suffix 키 삭제
 → [Release Lock]
 ```
 

BACK_SPECIFICATION.md

@@ -4,6 +4,7 @@
 
 | 버전 | 날짜 | 변경 내용 |
 |------|------|-----------|
+| v23.1 | 2026-03-15 | `family` 월별 상태를 `family_quota`로 분리하고 Family Redis 키(`info`, `remaining`, `alert`)에 `{yyyyMM}` suffix 규칙 반영 |
 | v23.0 | 2026-03-15 | Major 버전 동기화 |
 | v22.0 | 2026-03-12 | API_SPECIFICATION v22.2 동기화: UPLOADS 도메인 추가 (upload 패키지, `POST /uploads/images`, UploadType enum), 보상 템플릿 상세 조회 엔드포인트 추가 (`GET /admin/rewards/templates/{id}`) |
 | v21.0 | 2026-03-12 | API_SPECIFICATION v21.6 동기화: 도메인 리네이밍 (negotiation→appeal, report→recap), 엔티티/Enum 갱신, 엔드포인트 경로 갱신, 알림 타입 APPEAL_* 전환, admin 로그인/리프레시 권한 수정 |
@@ -354,6 +355,20 @@ CREATE INDEX idx_notif_family ON notification_log(family_id, sent_at DESC);
 
 **UNIQUE 제약**: `(family_id, customer_id, current_month)` + `deleted_at`
 
+### FamilyQuota 엔티티
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `id` | Long | PK (auto-increment) |
+| `familyId` | Long | 가족 ID |
+| `currentMonth` | LocalDate | 기준 월 (yyyy-MM-01) |
+| `totalQuotaBytes` | Long | 월별 총 할당량 스냅샷 |
+| `usedBytes` | Long | 월별 총 사용량 |
+
+**UNIQUE 제약**: `(family_id, current_month)` + `deleted_at`
+
+> 가족 월별 총량 조회의 Source of Truth는 `family`가 아니라 `family_quota`다.
+
 ---
 
 ## 인증 & 인가
@@ -715,11 +730,12 @@ usage-persist (Topic) → UsagePersistKafkaConsumer → UsagePersistService.pers
 
 | 키 패턴 | 타입 | 설명 |
 |---------|------|------|
-| `family:{familyId}:info` | Hash | 가족 메타데이터 (`total_quota` 등) |
-| `family:{familyId}:remaining` | String | 가족 잔여 데이터량 (bytes) |
-| `family:{familyId}:customer:{customerId}:usage:monthly` | String | 고객 월간 사용량 (bytes) |
+
+| `family:{familyId}:info:{yyyyMM}` | Hash | 가족 월별 메타 정보 (name, total_quota 등) |
+| `family:{familyId}:remaining:{yyyyMM}` | String | 가족 월별 잔여 데이터량 (bytes) |
+| `family:{familyId}:customer:{customerId}:usage:monthly:{yyyyMM}` | String | 고객 월간 사용량 (bytes) |
 | `family:{familyId}:customer:{customerId}:constraints` | Hash | 고객별 정책 제약 조건 |
-| `family:{familyId}:alerts` | Hash | 임계치 경고 발송 이력 |
+| `family:{familyId}:alert:THRESHOLD:{threshold}:{yyyyMM}` | String | 월별 임계치 경고 발송 이력 |
 | `event:dedup:policy:{eventId}:{customerId}` | String | 정책 이벤트 중복 방지 (TTL: 1시간) |
 | `event:dedup:usage-persist:{originEventId}` | String | 사용량 DB 저장 중복 방지 (TTL: 10분) |
 
@@ -793,7 +809,7 @@ usage-persist (Topic) → UsagePersistKafkaConsumer → UsagePersistService.pers
 
 ### 중복 발송 방지
 
-- **임계치 알림**: 50%, 30%, 10% 각각 한 번만 발송 (Redis `alerts` Hash)
+- **임계치 알림**: 50%, 30%, 10% 각각 한 번만 발송 (Redis `family:{familyId}:alert:THRESHOLD:{threshold}:{yyyyMM}` String key 존재 여부로 중복 방지)
 - **정책 이벤트**: `event:dedup:policy:{eventId}:{customerId}` (TTL 1시간)
 - **DB 저장 이벤트**: `event:dedup:usage-persist:{originEventId}` (TTL 10분)