From e11010f414ae23c73e35f80dec153b3820341704 Mon Sep 17 00:00:00 2001
From: katiekim17 <pyeongsuk.kim88@gmail.com>
Date: Mon, 30 Mar 2026 02:23:59 +0900
Subject: [PATCH] =?UTF-8?q?doc:=20=EC=84=A4=EA=B3=84=EB=AC=B8=EC=84=9C=20?=
 =?UTF-8?q?=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CONTEXT.md                                | 313 +++++++++++++++++++++
 docs/black-friday-simulator.md            | 326 ++++++++++++++++++++++
 docs/concepts/01-sorted-set-basic.mermaid |  26 ++
 docs/concepts/README.md                   |  20 ++
 http/commerce-api/seed-black-friday.http  |  64 +++++
 k6/breakpoint.js                          | 142 ++++++++++
 6 files changed, 891 insertions(+)
 create mode 100644 CONTEXT.md
 create mode 100644 docs/black-friday-simulator.md
 create mode 100644 docs/concepts/01-sorted-set-basic.mermaid
 create mode 100644 docs/concepts/README.md
 create mode 100644 http/commerce-api/seed-black-friday.http
 create mode 100644 k6/breakpoint.js

diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 000000000..4c0aeca0c
--- /dev/null
+++ b/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
diff --git a/docs/black-friday-simulator.md b/docs/black-friday-simulator.md
new file mode 100644
index 000000000..9acf65380
--- /dev/null
+++ b/docs/black-friday-simulator.md
@@ -0,0 +1,326 @@
+# 블랙프라이데이 주문 대기열 시뮬레이터
+
+> 작성 목적: 주문 대기열 시스템 학습 전, 문제를 먼저 재현하고 개선 효과를 수치로 검증한다.
+
+---
+
+## 배경 및 목적
+
+블랙프라이데이처럼 짧은 시간에 주문이 폭발적으로 몰리는 상황을 직접 재현해,
+현재 시스템이 어디서 무너지는지 수치로 확인한다.
+
+**학습 흐름**
+
+```
+[Phase 1] 한계점 탐색    →  현재 코드가 몇 명까지 버티는지 P99 기준으로 측정
+[Phase 2] 블프 spike 재현 →  한계를 넘었을 때 실제로 무슨 일이 생기는지 확인
+          ↓
+    [다음 주] 주문 대기열 시스템 구현
+          ↓
+[Phase 3] 개선 검증       →  같은 부하로 재실행, 수치 비교
+```
+
+---
+
+## 현재 코드 분석 (왜 문제가 생기는가)
+
+### 주문 트랜잭션 흐름
+
+```
+POST /api/v1/orders
+  └── OrderFacade.createOrder()  @Transactional  ← 트랜잭션 시작
+        ├── userService.authenticate()            ← DB 조회
+        ├── productService.getProducts()          ← DB 조회
+        ├── productService.getBrands()            ← DB 조회
+        ├── userCouponService.validateAndUse()    ← DB 조회 + UPDATE
+        └── orderService.createOrder()
+              └── StockDeductionService.deductAll()  @Transactional
+                    └── findByProductIdWithLock()    ← PESSIMISTIC_WRITE 락 획득
+                          └── stock.deduct()         ← 재고 차감
+                    └── 주문/주문아이템 INSERT
+                                                     ← 트랜잭션 커밋 (락 해제)
+```
+
+**핵심 코드 위치**
+- `StockDeductionService` — 비관적 락 획득 및 재고 차감
+- `StockJpaRepository` — `@Lock(LockModeType.PESSIMISTIC_WRITE)`
+- `OrderFacade.createOrder()` — 전체 주문 흐름 오케스트레이션 (`@Transactional`)
+
+### 현재 방어 메커니즘
+
+| 메커니즘 | 역할 | 한계 |
+|---|---|---|
+| `PESSIMISTIC_WRITE` 락 | 재고 정합성 보장 (oversell 방지) | 동시 요청 모두 직렬화 → 대기 시간 급증 |
+| productId 정렬 후 락 획득 | 데드락 방지 | — |
+| `CoreException(BAD_REQUEST)` | 재고 부족 시 400 반환 | — |
+
+### 문제: 정합성은 지키지만 성능은 못 지킨다
+
+```
+트랜잭션 1 ─── [락 획득] ───────────────── [커밋/락 해제]
+트랜잭션 2 ─────────────── [락 대기 중...] ─────────────
+트랜잭션 3 ─────────────── [락 대기 중...] ─────────────
+...N명 동시
+```
+
+N이 커질수록:
+- DB 커넥션이 모두 락 대기 상태로 점유됨
+- HikariCP 커넥션 풀 고갈 → 새 요청은 커넥션조차 못 얻고 에러
+- 락 대기 타임아웃 → 재고가 있어도 주문 실패
+- **결과**: 재고 50개인데 실제 성공 주문이 50개 미만
+
+---
+
+## 시뮬레이터 구성
+
+스크립트 2개를 순서대로 실행한다.
+
+| 스크립트 | 목적 | 특징 |
+|---|---|---|
+| `k6/breakpoint.js` | 한계점 탐색 | VU를 단계적으로 증가시켜 P99가 꺾이는 지점 찾기 |
+| `k6/black-friday.js` | 블프 재현 | 5초 만에 200명 spike, 무슨 일이 생기는지 확인 |
+
+---
+
+## Phase 1: 한계점 탐색 (`breakpoint.js`)
+
+### 목표
+"P99 < 2000ms 를 유지할 수 있는 최대 동시 요청 수"를 찾는다.
+
+### VU 증가 단계
+
+| 단계 | VU 수 | 유지 시간 | 예상 상태 |
+|---|---|---|---|
+| 1 | 10 | 30s | 정상 (베이스라인) |
+| 2 | 30 | 30s | 정상 |
+| 3 | 50 | 30s | 주의 |
+| 4 | 100 | 30s | **한계점 진입 예상** ⚠️ |
+| 5 | 150 | 30s | 한계 초과 예상 |
+| 6 | 200 | 30s | 블랙프라이데이 수준 |
+| 7 | 300 | 30s | 과부하 확인 |
+
+각 단계 전환 시 5초 ramp (급격한 spike 배제, 부하 자체에만 집중)
+
+### 한계점 판단 기준
+
+다음 중 하나라도 만족하면 그 VU 수를 "한계점"으로 기록:
+- P99 > 2000ms (응답시간 SLO 위반)
+- 비정상 에러율 > 5% (500, 타임아웃 등 재고 부족이 아닌 에러)
+- `hikari.connections.pending` > 0 (Grafana에서 확인)
+
+### 기대 결과 예시
+
+```
+ 10 VU → P99:   120ms   비정상 에러: 0%   ✅
+ 30 VU → P99:   340ms   비정상 에러: 0%   ✅
+ 50 VU → P99:   890ms   비정상 에러: 0%   ✅
+100 VU → P99:  2800ms   비정상 에러: 2%   ⚠️ 한계점
+150 VU → P99:  7200ms   비정상 에러: 18%  ❌
+200 VU → P99: 타임아웃   비정상 에러: 35%  ❌
+```
+*(실제 수치는 실행 환경에 따라 다름)*
+
+### 상품 설정
+
+재고 고갈로 인한 노이즈 제거를 위해 **재고 10,000개** 상품을 사용한다.
+→ 재고 부족이 아닌 순수 부하 압박에 의한 P99 변화만 관찰
+
+---
+
+## Phase 2: 블랙프라이데이 재현 (`black-friday.js`)
+
+### 목표
+한계점을 알고 있는 상태에서, 그 한계를 **5초 만에 초과**했을 때 무슨 일이 생기는지 확인한다.
+
+### 시나리오
+
+```
+[한정판 상품]  재고: 50개
+[동시 요청]    200명 (한계점 초과 수준)
+[이상적 결과]  50명 성공, 150명 재고 부족 400
+[예상 실제]    50명 미만 성공 + 다수 500/타임아웃
+```
+
+### 트래픽 패턴
+
+```
+ 0s →  5s : 0 → 200 VU   (정각 몰림: 급격한 spike)
+ 5s → 35s : 200 VU        (지속 압박)
+35s → 40s : 200 → 0 VU   (종료)
+```
+
+### 결과 분류
+
+| 응답 | 분류 | 의미 |
+|---|---|---|
+| 201 Created | `order_success` | 정상 성공 (재고 50개 한도 내) |
+| 400 + "재고가 부족합니다" | `stock_exhausted` | 예상된 실패 (정상) |
+| 400 기타 / 500 / 타임아웃 | `sys_error` | **비정상 에러 — 이게 문제** |
+
+---
+
+## 커스텀 메트릭
+
+두 스크립트 공통으로 아래 메트릭을 수집한다.
+
+| 메트릭 | 종류 | 설명 |
+|---|---|---|
+| `order_duration` | Trend | 주문 API 응답시간 (P50/P95/P99 분석용) |
+| `order_success` | Counter | 성공한 주문 수 |
+| `stock_exhausted` | Counter | 재고 부족으로 실패한 수 (예상된 실패) |
+| `sys_error` | Counter | 비정상 에러 수 (500, 타임아웃 등) |
+| `abnormal_error_rate` | Rate | 비정상 에러 비율 |
+
+---
+
+## 웹 대시보드 구성
+
+### 선택: InfluxDB + Grafana
+
+**이유**: Spring Boot 메트릭(DB 커넥션 풀 상태)과 k6 메트릭(P99, 에러율)을 같은 화면에서 보면 인과관계를 한눈에 확인할 수 있다.
+
+```
+k6 ──(--out influxdb)──→ InfluxDB (8086) ──→ Grafana (3000)
+                                                     ↑
+Spring Boot actuator ──→ Prometheus (9090) ──────────┘
+```
+
+### Grafana 대시보드 구성
+
+```
+┌──────────────────────────────────────────────────────┐
+│              블랙프라이데이 시뮬레이터                   │
+├──────────────────────┬───────────────────────────────┤
+│   k6 메트릭          │   Spring Boot 메트릭            │
+│   (InfluxDB)         │   (Prometheus)                 │
+│                      │                                │
+│  VU 수 추이          │  hikari.connections.active      │
+│  P99 응답시간 추이    │  hikari.connections.pending     │
+│  비정상 에러율        │  http_server_requests           │
+│  성공/재고부족/에러   │  jvm.threads.live               │
+└──────────────────────┴───────────────────────────────┘
+        ↑ 두 그래프가 같은 시점에 꺾이는 지점 = 한계점
+```
+
+k6 공식 Grafana 대시보드: **ID 2587** (Grafana UI에서 import)
+
+### 수정이 필요한 파일
+
+| 파일 | 수정 내용 |
+|---|---|
+| `docker/monitoring-compose.yml` | InfluxDB 서비스 추가 (influxdb:1.8, 포트 8086) |
+| `docker/grafana/provisioning/datasources/datasource.yml` | InfluxDB 데이터소스 추가 |
+| `docker/load-test-compose.yml` | k6 실행 시 `--out influxdb` 옵션 추가 |
+
+---
+
+## Seed 데이터 전략
+
+### 필요한 데이터
+
+```
+브랜드 1개 (ACTIVE)
+  └── 상품 A: 재고 10,000  → breakpoint.js 전용 (재고 고갈 노이즈 제거)
+  └── 상품 B: 재고 50      → black-friday.js 전용 (한정 수량 재현)
+
+유저 300명 (bp_user_001 ~ bp_user_300)
+  → k6 setup() 단계에서 자동 등록
+  → 이미 존재하면 무시 (멱등성)
+```
+
+### 재고 관리
+
+Admin API에 재고 수정 엔드포인트 없음 → 직접 SQL 사용
+
+```sql
+-- 재고 리셋 (테스트 재실행 시)
+UPDATE stock SET quantity = 50    WHERE product_id = {productId_B};
+UPDATE stock SET quantity = 10000 WHERE product_id = {productId_A};
+```
+
+### 관련 파일
+- `http/commerce-api/seed-black-friday.http` — 브랜드/상품 생성 요청 모음
+
+---
+
+## 실행 순서
+
+```bash
+# 1. 인프라 실행
+docker-compose -f docker/infra-compose.yml up -d
+
+# 2. 모니터링 실행 (InfluxDB 추가 후)
+docker-compose -f docker/monitoring-compose.yml up -d
+
+# 3. API 서버 실행
+./gradlew :apps:commerce-api:bootRun
+
+# 4. Seed 데이터 생성 (최초 1회)
+# http/commerce-api/seed-black-friday.http 순서대로 실행
+# → 이후 응답에서 productId 확인 후 SQL로 재고 등록
+
+# 5. Grafana 접속 후 k6 대시보드 import
+open http://localhost:3000  # admin / admin
+# Dashboards → Import → ID: 2587 입력
+
+# 6. Phase 1: 한계점 탐색
+k6 run -e PRODUCT_ID={productId_A} --out influxdb=http://localhost:8086/k6 k6/breakpoint.js
+
+# 7. Phase 2: 블랙프라이데이 재현 (재고 리셋 후)
+# SQL: UPDATE stock SET quantity = 50 WHERE product_id = {productId_B};
+k6 run -e PRODUCT_ID={productId_B} --out influxdb=http://localhost:8086/k6 k6/black-friday.js
+```
+
+---
+
+## Phase 3: 대기열 구현 후 검증 (다음 주)
+
+대기열 시스템 구현 후 **동일한 스크립트**를 재실행해서 비교한다.
+
+| 지표 | Phase 1/2 (현재) | Phase 3 (대기열 후) 기대값 |
+|---|---|---|
+| 한계점 VU 수 | ~100 VU | 더 높아짐 |
+| 블프 성공 주문 수 | 50개 미만 | 정확히 50개 |
+| 비정상 에러율 | 30%+ | ≈ 0% |
+| P99 응답시간 | 타임아웃 | 빠른 응답 (대기 번호 반환) |
+| DB 커넥션 pending | 고갈 | 낮음 (순차 처리) |
+
+---
+
+## 작업 체크리스트
+
+### 인프라 설정
+- [ ] `monitoring-compose.yml`에 InfluxDB 1.8 추가 (포트 8086, DB명: k6)
+- [ ] `datasource.yml`에 InfluxDB 데이터소스 추가
+- [ ] `load-test-compose.yml`에 `--out influxdb` 옵션 추가
+- [ ] Grafana에서 k6 대시보드 import (ID: 2587) 확인
+
+### Seed 데이터
+- [ ] 브랜드 생성 후 brandId 기록
+- [ ] 한계점 테스트 상품 생성 후 productId_A 기록
+- [ ] 블프 상품 생성 후 productId_B 기록
+- [ ] SQL로 재고 등록 확인 (A: 10,000 / B: 50)
+
+### breakpoint.js 실행
+- [ ] PRODUCT_ID=productId_A 로 실행
+- [ ] Grafana에서 P99 추이 확인
+- [ ] 한계점 VU 수 기록
+
+### black-friday.js 실행
+- [ ] 재고 50개 리셋 확인
+- [ ] PRODUCT_ID=productId_B 로 실행
+- [ ] 성공 주문 수 vs 50개 비교
+- [ ] 비정상 에러율 기록
+
+### Phase 3 (대기열 구현 후)
+- [ ] 재고 리셋
+- [ ] 두 스크립트 재실행
+- [ ] Before/After 수치 비교표 작성
+
+---
+
+## 하지 않을 것
+
+- 쿠폰 적용, 여러 상품 → 병목 포인트 단순화 (재고 락 하나에 집중)
+- 결제 플로우 → 주문 생성 단계가 핵심, 결제는 별개 분석
+- Spring Boot simulator 모듈 → k6로 충분, 다음 시뮬레이터 주제에서 별도 구성
\ No newline at end of file
diff --git a/docs/concepts/01-sorted-set-basic.mermaid b/docs/concepts/01-sorted-set-basic.mermaid
new file mode 100644
index 000000000..1bd64bfa9
--- /dev/null
+++ b/docs/concepts/01-sorted-set-basic.mermaid
@@ -0,0 +1,26 @@
+---
+title: Redis Sorted Set — 순서 보장 원리
+---
+flowchart LR
+    subgraph 입력["ZADD queue {score} {member}"]
+        A["userA\nscore: 1000"]
+        B["userC\nscore: 1500"]
+        C["userB\nscore: 2000"]
+    end
+
+    subgraph 저장["Sorted Set (항상 score 오름차순 유지)"]
+        direction TB
+        R1["1위 userA — score: 1000"]
+        R2["2위 userC — score: 1500"]
+        R3["3위 userB — score: 2000"]
+        R1 --> R2 --> R3
+    end
+
+    입력 --> 저장
+
+    subgraph 조회
+        Q1["ZRANK queue userC → 1 (0-indexed)"]
+        Q2["ZCARD queue → 3 (전체 인원)"]
+    end
+
+    저장 --> 조회
diff --git a/docs/concepts/README.md b/docs/concepts/README.md
new file mode 100644
index 000000000..8bbc3bb99
--- /dev/null
+++ b/docs/concepts/README.md
@@ -0,0 +1,20 @@
+# 개념 정리 다이어그램
+
+> 개념 학습 후 Claude가 Mermaid로 저장하는 공간입니다.
+> 각 파일은 하나의 개념 단위로 구성됩니다.
+
+## 파일 목록
+
+| 파일 | 개념 | 퀴즈 통과 |
+|------|------|----------|
+| `01-sorted-set-basic.mermaid` | Redis Sorted Set 기본 동작 | ⬜ |
+| `02-sorted-set-zadd-nx.mermaid` | ZADD NX 중복 방지 원리 | ⬜ |
+| `03-score-strategy.mermaid` | score 설계 전략 | ⬜ |
+| `04-toctou.mermaid` | TOCTOU race condition | ⬜ |
+| `05-queue-vs-ratelimit.mermaid` | 대기열 vs Rate Limiting | ⬜ |
+| `06-thundering-herd.mermaid` | Thundering Herd | ⬜ |
+| `07-batch-size.mermaid` | 배치 크기 N 산정 | ⬜ |
+| `08-token-ttl.mermaid` | 입장 토큰 & TTL 설계 | ⬜ |
+| `09-polling-vs-sse.mermaid` | Polling vs SSE | ⬜ |
+| `10-hikaricp.mermaid` | HikariCP 커넥션 풀 고갈 | ⬜ |
+| `11-redis-failure.mermaid` | Redis 장애 시나리오 | ⬜ |
diff --git a/http/commerce-api/seed-black-friday.http b/http/commerce-api/seed-black-friday.http
new file mode 100644
index 000000000..aa31ff9ab
--- /dev/null
+++ b/http/commerce-api/seed-black-friday.http
@@ -0,0 +1,64 @@
+### 블랙프라이데이 시뮬레이터 Seed 데이터
+### 실행 순서: 1 → 2 → 3 순서대로 실행
+### 전제: commerce-api 실행 중, Admin LDAP 헤더 필요
+
+@baseUrl = http://localhost:8080
+@adminLdap = loopers.admin
+
+### 1. 테스트 브랜드 생성
+POST {{baseUrl}}/api-admin/v1/brands
+Content-Type: application/json
+X-Loopers-Ldap: {{adminLdap}}
+
+{
+  "name": "블프테스트브랜드",
+  "description": "블랙프라이데이 부하 테스트 전용 브랜드",
+  "logoImageUrl": "https://example.com/logo.png"
+}
+
+###
+
+### 2-A. 한계점 탐색 전용 상품 생성 (재고 10,000 → 재고 고갈 노이즈 제거)
+### → 응답에서 productId 확인 후 아래 SQL로 재고 등록
+POST {{baseUrl}}/api-admin/v1/products
+Content-Type: application/json
+X-Loopers-Ldap: {{adminLdap}}
+
+{
+  "brandId": 1,
+  "name": "한계점테스트상품",
+  "price": 10000,
+  "description": "breakpoint.js 전용 - 재고 10000",
+  "thumbnailImageUrl": "https://example.com/bp.png"
+}
+
+###
+
+### 2-B. 블랙프라이데이 전용 상품 생성 (재고 50 → 한정 수량 재현)
+### → 응답에서 productId 확인 후 아래 SQL로 재고 등록
+POST {{baseUrl}}/api-admin/v1/products
+Content-Type: application/json
+X-Loopers-Ldap: {{adminLdap}}
+
+{
+  "brandId": 1,
+  "name": "한정판 블프 상품",
+  "price": 99000,
+  "description": "black-friday.js 전용 - 재고 50",
+  "thumbnailImageUrl": "https://example.com/bf.png"
+}
+
+###
+
+### 3. 재고 등록 (Admin API에 재고 수정 엔드포인트 없으므로 직접 SQL 사용)
+### MySQL 접속: localhost:3307 / root / root
+###
+### 한계점 테스트 상품 재고 (productId는 2-A 응답에서 확인):
+###   INSERT INTO stock (product_id, quantity) VALUES ({productId_A}, 10000);
+###
+### 블랙프라이데이 상품 재고 (productId는 2-B 응답에서 확인):
+###   INSERT INTO stock (product_id, quantity) VALUES ({productId_B}, 50);
+###
+### 재고 리셋 (테스트 재실행 시):
+###   UPDATE stock SET quantity = 50 WHERE product_id = {productId_B};
+###   UPDATE stock SET quantity = 10000 WHERE product_id = {productId_A};
\ No newline at end of file
diff --git a/k6/breakpoint.js b/k6/breakpoint.js
new file mode 100644
index 000000000..d502d7ef9
--- /dev/null
+++ b/k6/breakpoint.js
@@ -0,0 +1,142 @@
+/**
+ * 주문 시스템 한계점 탐색 (Breakpoint Test)
+ *
+ * 목적: 현재 코드(비관적 락 + @Transactional)에서 몇 명까지 P99 < 2000ms 를 유지할 수 있는지 찾기
+ *
+ * 실행 방법:
+ *   k6 run -e PRODUCT_ID=1 k6/breakpoint.js
+ *
+ * Grafana 연동 실행:
+ *   k6 run -e PRODUCT_ID=1 --out influxdb=http://localhost:8086/k6 k6/breakpoint.js
+ *
+ * 주의사항:
+ *   - PRODUCT_ID는 재고 10,000짜리 한계점 테스트 전용 상품 ID를 사용할 것
+ *   - seed-black-friday.http 먼저 실행 후 이 스크립트 실행
+ */
+
+import http from 'k6/http';
+import { check } from 'k6';
+import { Trend, Rate, Counter } from 'k6/metrics';
+
+const BASE_URL    = __ENV.BASE_URL    || 'http://localhost:8080';
+const PRODUCT_ID  = __ENV.PRODUCT_ID  || '1';
+const PASSWORD    = 'Bptest123!';
+const USER_PREFIX = 'bp_user_';
+const TOTAL_USERS = 300;
+
+// 커스텀 메트릭
+const orderDuration  = new Trend('order_duration', true);
+const orderSuccess   = new Counter('order_success');
+const stockExhausted = new Counter('stock_exhausted');
+const sysError       = new Counter('sys_error');
+const abnormalRate   = new Rate('abnormal_error_rate');
+
+export const options = {
+    // 단계적으로 VU 증가 → 어느 구간에서 P99가 꺾이는지 관찰
+    stages: [
+        { duration: '5s',  target: 10  },  // 1단계 진입
+        { duration: '30s', target: 10  },  // 1단계 유지 (베이스라인)
+        { duration: '5s',  target: 30  },  // 2단계 진입
+        { duration: '30s', target: 30  },  // 2단계 유지
+        { duration: '5s',  target: 50  },  // 3단계 진입
+        { duration: '30s', target: 50  },  // 3단계 유지
+        { duration: '5s',  target: 100 },  // 4단계 진입 (한계점 예상)
+        { duration: '30s', target: 100 },  // 4단계 유지
+        { duration: '5s',  target: 150 },  // 5단계 진입
+        { duration: '30s', target: 150 },  // 5단계 유지
+        { duration: '5s',  target: 200 },  // 6단계 진입 (블랙프라이데이 수준)
+        { duration: '30s', target: 200 },  // 6단계 유지
+        { duration: '5s',  target: 300 },  // 7단계 진입 (과부하)
+        { duration: '30s', target: 300 },  // 7단계 유지
+        { duration: '5s',  target: 0   },  // 종료
+    ],
+    thresholds: {
+        // 이 임계값을 어느 구간에서 위반하는지가 핵심 관찰 포인트
+        'order_duration': ['p(99)<2000'],
+        'abnormal_error_rate': ['rate<0.05'],
+    },
+    summaryTrendStats: ['avg', 'med', 'p(90)', 'p(95)', 'p(99)', 'max'],
+};
+
+export function setup() {
+    console.log(`[setup] 테스트 유저 ${TOTAL_USERS}명 등록 시작 (이미 존재하면 무시)`);
+
+    const headers = { 'Content-Type': 'application/json' };
+
+    for (let i = 1; i <= TOTAL_USERS; i++) {
+        const loginId = `${USER_PREFIX}${String(i).padStart(3, '0')}`;
+        http.post(
+            `${BASE_URL}/api/v1/users`,
+            JSON.stringify({
+                loginId,
+                password: PASSWORD,
+                name: `부하테스트${i}`,
+                birthDate: '19900101',
+                email: `${loginId}@loadtest.com`,
+            }),
+            { headers }
+        );
+    }
+
+    console.log('[setup] 유저 등록 완료. 테스트 시작.');
+    return { productId: parseInt(PRODUCT_ID) };
+}
+
+export default function (data) {
+    const vuIndex = ((__VU - 1) % TOTAL_USERS) + 1;
+    const loginId = `${USER_PREFIX}${String(vuIndex).padStart(3, '0')}`;
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Loopers-LoginId': loginId,
+        'X-Loopers-LoginPw': PASSWORD,
+    };
+
+    const res = http.post(
+        `${BASE_URL}/api/v1/orders`,
+        JSON.stringify({
+            items: [{ productId: data.productId, quantity: 1 }],
+        }),
+        { headers, timeout: '10s' }
+    );
+
+    orderDuration.add(res.timings.duration);
+
+    if (res.status === 201) {
+        orderSuccess.add(1);
+        abnormalRate.add(false);
+        check(res, { '주문 성공 (201)': (r) => r.status === 201 });
+    } else if (res.status === 400) {
+        const isStockError = res.body && res.body.includes('재고가 부족합니다');
+        if (isStockError) {
+            stockExhausted.add(1);
+            abnormalRate.add(false);
+        } else {
+            sysError.add(1);
+            abnormalRate.add(true);
+            check(res, { '비정상 400': () => false });
+        }
+    } else {
+        // 500, 타임아웃, 서킷브레이커 등 비정상 에러
+        sysError.add(1);
+        abnormalRate.add(true);
+        check(res, { [`비정상 에러 (${res.status})`]: () => false });
+    }
+    // sleep 없음 → 최대 처리량 생성, 한계점 빠르게 탐색
+}
+
+export function teardown() {
+    console.log('');
+    console.log('=== 한계점 탐색 결과 ===');
+    console.log('Grafana에서 order_duration p(99) 추이를 확인하세요.');
+    console.log('P99가 2000ms를 초과하는 구간의 VU 수 = 현재 시스템 한계점');
+    console.log('');
+    console.log('단계별 VU 기준:');
+    console.log('  1단계:  10 VU  (베이스라인)');
+    console.log('  2단계:  30 VU');
+    console.log('  3단계:  50 VU');
+    console.log('  4단계: 100 VU  ← 한계점 예상 구간');
+    console.log('  5단계: 150 VU');
+    console.log('  6단계: 200 VU  (블랙프라이데이 수준)');
+    console.log('  7단계: 300 VU  (과부하)');
+}