volume-8

CONTEXT.md

@@ -0,0 +1,313 @@
+# 📚 Weekly Study Context
+
+> 이 파일은 집/회사 어디서든 같은 컨텍스트를 유지하기 위한 파일입니다.
+> 세션 시작 시 "컨텍스트 불러와줘" 라고 말하면 Claude가 이 파일을 읽고 바로 이어집니다.
+
+---
+
+## 🎓 학습 진행 방식
+
+### 순서
+```
+1단계: 개념 잡기        → 모르면 Claude한테 물어보기, Mermaid로 정리
+2단계: 개념 퀴즈        → 중간중간 Claude가 질문 → 내가 답변 → 확인
+3단계: 시뮬레이션       → Phase 1/2 실행 (문제 직접 겪기)
+4단계: 설계             → 고민 목록 → 결정 사항으로 이동
+5단계: 코드 구현        → TDD (Red → Green → Refactor)
+6단계: Phase 3 검증     → Before/After 수치 비교
+7단계: PR + 블로그 + WIL
+```
+
+### 개념 학습 규칙
+- 개념 정리 요청 시 → Claude가 Mermaid 다이어그램으로 `docs/concepts/` 에 저장
+- 각 개념 끝나면 → Claude가 퀴즈 1~2개 출제, 내가 답변 후 확인
+- 퀴즈 통과 기준 → 아래 개념 체크리스트에 ✅ 표시
+
+### 📖 개념 체크리스트
+
+#### Redis 자료구조
+- [ ] **Sorted Set 기본** — ZADD, ZRANK, ZREM, ZCARD, ZSCORE 동작 원리
+- [ ] **ZADD NX 옵션** — 중복 방지 원리 (왜 NX가 멱등성을 보장하는가)
+- [ ] **score 설계** — 진입 순서 보장을 위한 score 전략 (timestamp vs sequence)
+- [ ] **TOCTOU 문제** — 조회 후 조건 분기 시 발생하는 race condition
+
+#### 대기열 시스템 설계
+- [ ] **대기열 vs Rate Limiting** — 언제 어떤 전략을 쓰는가
+- [ ] **Thundering Herd** — 대기열 열릴 때 동시 진입 폭발 문제와 대응
+- [ ] **배치 크기 N 산정** — `N = 커넥션 수 × (주기 / 평균 처리 시간)` 공식 근거
+
+#### 토큰 & TTL
+- [ ] **입장 토큰 설계** — Redis String + TTL이 왜 적합한가
+- [ ] **TTL 기준 산정** — 몇 분으로 설정해야 하는가, 그 근거
+- [ ] **토큰 검증 위치** — Filter vs Interceptor vs AOP 비교
+
+#### 실시간 순번 조회
+- [ ] **Polling 구조** — 클라이언트가 어떻게 주기적으로 조회하는가
+- [ ] **Polling vs SSE** — 각각 언제 쓰는가, 왜 Polling을 선택했는가
+- [ ] **예상 대기 시간 계산** — 공식과 한계
+
+#### 시스템 안정성
+- [ ] **HikariCP 커넥션 풀** — 고갈이 왜 생기고 대기열이 어떻게 해결하는가
+- [ ] **Redis 장애 시나리오** — Redis 죽으면 어떻게 해야 하는가
+
+---
+
+## 🗓️ 이번 주 (2026-03-30 ~ 2026-04-03)
+
+### 마감
+- **코드 PR**: 2026-04-03 (금) 18:00
+- **블로그 (Technical Writing)**: 2026-04-03 (금) 18:00
+- **WIL (Weekly I Learned)**: 2026-04-03 (금) 18:00
+
+### 주제
+**Redis 기반 대기열 시스템** (Black Friday 주문 API 앞단)
+
+---
+
+## 🧪 Phase 0 — 시뮬레이션 (문제 재현 먼저)
+<!-- 왜 이렇게 만들어야 하는지, 안 하면 뭐가 문제인지 직접 겪고 나서 구현 -->
+
+### 시뮬레이션 1 — 대기열 없이 주문 API에 동시 요청 폭탄
+> 목적: Rate Limiting도 없고 대기열도 없으면 어떻게 터지는지 확인
+
+**재현 방법**
+```bash
+# k6로 200 VU가 동시에 주문 API 직접 호출
+k6 run --vus 200 --duration 10s simulate/no-queue.js
+```
+
+**확인 포인트**
+- [ ] DB 커넥션 풀(HikariCP) 고갈 → `Connection is not available` 에러
+- [ ] 응답 시간 급격히 증가 (정상 20ms → 수 초)
+- [ ] 재고 음수 or 중복 처리 발생 여부
+
+**예상 결론**: → 대기열이 왜 필요한지 체감
+
+---
+
+### 시뮬레이션 2 — Sorted Set 없이 List로 대기열 구현
+> 목적: 순서 보장과 중복 방지가 왜 Sorted Set이어야 하는지 확인
+
+**재현 방법**
+- `LPUSH queue:waiting userId` 로 단순 List 구현
+- 동시에 같은 userId로 여러 번 진입 시도
+
+**확인 포인트**
+- [ ] 동일 userId가 List에 중복 등록되는지
+- [ ] 순서가 뒤집히는 케이스 발생하는지 (LPUSH vs RPUSH)
+- [ ] 순번 조회 시 O(N) 스캔 성능 문제
+
+**예상 결론**: → Sorted Set의 `score 기반 순서 보장 + 중복 방지(ZADD NX)`가 왜 맞는지
+
+---
+
+### 시뮬레이션 3 — 토큰 없이 주문 API 바로 열어두기
+> 목적: 대기열 통과 검증 없으면 어떤 일이 생기는지 확인
+
+**재현 방법**
+- 토큰 검증 인터셉터 비활성화 상태에서
+- 대기열 진입 안 한 유저가 주문 API 직접 호출
+
+**확인 포인트**
+- [ ] 대기열 우회 가능한지
+- [ ] 대기 중인 유저들이 손해 보는지
+
+**예상 결론**: → 토큰 기반 입장 제어가 왜 필요한지
+
+---
+
+### 시뮬레이션 4 — TTL 없는 토큰
+> 목적: 토큰에 만료 시간이 없으면 어떤 문제가 생기는지 확인
+
+**재현 방법**
+- Redis에 TTL 없이 토큰 저장
+- 오래된 토큰으로 주문 API 재시도
+
+**확인 포인트**
+- [ ] 수 시간 후에도 토큰으로 주문 가능한지
+- [ ] 대기열 공정성 훼손 여부 (대기 안 하고 나중에 사용)
+
+**예상 결론**: → TTL 설계 기준의 의미
+
+---
+
+### 시뮬레이션 5 — 스케줄러 배치 크기를 너무 크게 잡았을 때
+> 목적: 배치 크기 N이 DB 커넥션 풀보다 크면 어떻게 되는지 확인
+
+**재현 방법**
+- HikariCP `maximum-pool-size=10` 설정
+- 스케줄러 배치 크기 N=50으로 설정 후 실행
+
+**확인 포인트**
+- [ ] 커넥션 대기 타임아웃 발생 여부
+- [ ] 다른 API 응답 지연 여부
+
+**예상 결론**: → 배치 크기 산정 근거 (`N ≤ 커넥션 풀 크기 × 주기 / 처리시간`)
+
+---
+
+## ✅ Checklist
+
+### 🚪 Step 1 — 대기열
+- [ ] `POST /queue/enter` — Redis Sorted Set 기반 대기열 진입 API
+- [ ] `GET /queue/position` — 순번 조회 API
+- [ ] userId 기반 중복 진입 방지
+- [ ] 전체 대기 인원 조회
+
+### 🎫 Step 2 — 입장 토큰 & 스케줄러
+- [ ] 스케줄러: 주기적으로 대기열에서 N명 꺼내 입장 토큰 발급
+- [ ] 토큰 TTL 설정 (e.g. 5분)
+- [ ] 주문 API 진입 시 토큰 검증
+- [ ] 주문 완료 후 토큰 삭제
+- [ ] 처리량 기준 스케줄러 배치 크기 산정 근거 문서화
+
+### 📡 Step 3 — 실시간 순번 조회
+- [ ] 예상 대기 시간 계산 로직
+- [ ] Polling 기반 순번 + 예상 대기 시간 응답
+- [ ] 토큰 발급 시 순번 조회 응답에 토큰 포함
+
+### 🧪 검증
+- [ ] 동시 진입 테스트 — 대기열 순서 보장 확인
+- [ ] 토큰 만료 테스트 — TTL 초과 시 무효화 확인
+- [ ] 처리량 초과 테스트 — 배치 크기 초과 요청에도 안정적인지 확인
+
+---
+
+## 🤔 설계 고민 목록 (미결)
+<!-- 구현 전/중에 판단해야 할 것들. 결론 나면 아래 "설계 결정 사항"으로 이동 -->
+
+### Step 1 — 대기열
+- [ ] **Redis Sorted Set score 기준**: `System.currentTimeMillis()` vs `AtomicLong` 시퀀스?
+  - 밀리초 충돌 가능성 있음 → 동시 진입 시 순서 보장 어떻게?
+- [ ] **중복 진입 방지 구현 방식**: `ZSCORE` 조회 후 조건 분기 vs Lua 스크립트로 원자적 처리?
+  - 분리하면 TOCTOU(Time-of-Check-Time-of-Use) 문제 가능성 있음
+- [ ] **대기열 만료 처리**: 대기 중 연결 끊긴 유저는 어떻게 처리?
+  - 무기한 대기 vs TTL 설정 후 자동 제거
+
+### Step 2 — 입장 토큰 & 스케줄러
+- [ ] **토큰 저장소**: Redis String (TTL 활용) vs DB?
+  - Redis 선택 시 → 장애 시 토큰 일괄 소멸 문제
+- [ ] **스케줄러 배치 크기 N 산정 근거**:
+  - DB 커넥션 풀 기본값(HikariCP default=10), 평균 주문 처리 시간 기준으로 계산해야 함
+  - `N = 커넥션 수 × (스케줄 주기 / 평균 처리 시간)` 공식 검토
+- [ ] **토큰 검증 위치**: Filter vs Interceptor vs AOP?
+- [ ] **스케줄러 중복 실행 방지**: 단일 인스턴스면 괜찮지만, 멀티 인스턴스 시 분산 락 필요?
+
+### Step 3 — 실시간 순번 조회
+- [ ] **예상 대기 시간 계산 공식**:
+  - `예상 대기 시간 = 내 순번 × (스케줄 주기 / 배치 크기 N)`?
+  - 더 정교한 계산 방식 있는지 검토
+- [ ] **Polling 주기**: 몇 초마다 호출? 클라이언트에서 결정하는가?
+  - 대기 인원 많을 때 주기 늘리는 Adaptive Polling 고려 여부
+- [ ] **Polling 부하 완화**: Redis만 조회하면 충분? DB 조회 없이 가능?
+
+---
+
+## 💭 설계 결정 사항 (확정)
+<!-- 고민 끝에 내린 판단들. 블로그/PR 소재가 됩니다 -->
+
+| 항목 | 결정 | 이유 |
+|------|------|------|
+| Polling vs SSE | - | 미결 |
+| 토큰 TTL | - | 미결 |
+| 스케줄러 배치 크기 N | - | 미결 |
+| Redis 장애 시 fallback | - | 미결 |
+
+---
+
+## 📝 진행 로그
+<!-- 매일 작업 후 간략히 기록 -->
+
+### 2026-03-30 (월)
+- 프로젝트 세팅 및 컨텍스트 파일 생성
+- 작업 시작 예정
+
+---
+
+## 🔖 다음 세션에 이어서 할 일
+<!-- 세션 종료 전 반드시 업데이트 -->
+- Step 1 설계부터 시작: Redis Sorted Set 구조 결정, 패키지 구조 설계
+
+---
+
+## ✍️ 블로그 & WIL 소재 메모
+<!-- 구현하다 떠오르는 인사이트, 고민, 트레이드오프 메모 -->
+
+### 블로그 후보 주제 (Technical Writing)
+- Rate Limiting으로 거부하는 것 vs 대기열로 줄 세우는 것: 어떤 상황에서?
+- 스케줄러 배치 크기 산정 근거 (DB 커넥션 풀, 평균 처리 시간 기준)
+- Thundering Herd 대응
+- Redis 장애 시 서비스는 어떻게 되어야 하는가?
+- Polling vs SSE — 왜 그 방식을 선택했는가?
+- 토큰 TTL을 몇 분으로 설정했고, 그 기준은?
+
+### WIL (Weekly I Learned) 작성 가이드
+> WIL은 블로그보다 가볍게, "이번 주 내가 배운 것"을 솔직하게 정리하는 글
+
+**작성 항목**
+- 이번 주 배운 기술/개념 (Redis Sorted Set, 토큰 TTL 설계, Polling 부하 등)
+- 가장 어려웠던 부분과 해결 과정
+- 잘 됐던 것 vs 아쉬웠던 것
+- 다음 주에 가져갈 인사이트
+
+---
+
+## 📋 PR 작성 양식 (참고 템플릿)
+<!-- PR 작성 시 이 구조를 따를 것 -->
+
+```
+📌 Summary
+한 단락으로 이번 PR의 핵심을 요약 (무엇을, 왜, 핵심 결과)
+불릿으로 핵심 포인트 3~5개
+
+🧭 Context & Decision
+문제 정의 (코드 블록으로 Before 구조 표현)
+리스크 테이블
+핵심 결정 요약 테이블 (#, 결정 항목, 최종 선택, 핵심 근거)
+
+각 결정별:
+  - 의도 (왜 이 결정을 내렸는가)
+  - 코드 스니펫 (Before/After 비교)
+  - 설계도 (Mermaid 다이어그램)  ← 중간중간 흐름도 필수!
+  - 대안 비교 테이블 (전략 / 장단점 / 선택 이유)
+  - 관련 클래스 테이블 (컴포넌트 / 파일경로 / 메서드 / 역할)
+
+🏗️ Design Overview
+변경 범위 (기존 변경 / 신규 추가)
+주요 컴포넌트 & 핵심 메서드 테이블
+
+🔁 Flow Diagram
+Mermaid로 전체 흐름 다이어그램  ← 설계도 필수!
+
+✅ Checklist
+Step별 체크리스트
+
+🔍 리뷰 포인트
+멘토/리뷰어에게 묻고 싶은 판단 2~3개
+  - 해결하려는 비즈니스 문제
+  - 시도한 접근
+  - 코드 위치
+  - 이렇게 선택한 이유
+  - 인지하고 있는 트레이드오프
+  - 여쭙고 싶은 점
+```
+
+### PR 작성 시 핵심 원칙
+- "무엇을 했다" 가 아니라 **"왜 그렇게 판단했는가"** 중심
+- 각 결정마다 **대안 비교 테이블** 포함 (왜 이걸 선택했고 나머지는 왜 버렸는지)
+- **Mermaid 설계도** 중간중간 삽입 (흐름도, 상태 머신, 시퀀스 다이어그램)
+- 리뷰 포인트에서 **솔직하게 판단이 서지 않는 부분** 질문
+
+---
+
+## 🏗️ 프로젝트 구조 (참고)
+```
+apps/commerce-api/src/main/java/com/loopers/
+├── application/    # Facade (usecase 조합)
+├── domain/         # Entity, Service, Repository interface
+├── infrastructure/ # Repository 구현체 (JPA, Redis)
+├── interfaces/api/ # Controller, DTO, ApiSpec
+└── support/        # CoreException, ErrorType
+```
+
+**Tech Stack**: Java 21, Spring Boot 3.4.4, Redis, MySQL 8.0, Kafka