수정본

docs/BATCH_ANALYSIS_GUIDE.md

@@ -0,0 +1,116 @@
+# 배치 분석 가이드
+
+## 개요
+매일 아침 장 시작 전에 전체 종목을 분석하여 DB에 캐시합니다.
+이를 통해 대시보드 첫 진입 시 빠른 로딩이 가능합니다.
+
+## 수동 실행
+
+### 테스트 (10개 종목만)
+```bash
+cd backend
+../.venv/bin/python batch_daily_analysis.py --test
+```
+
+### 제한된 개수 분석
+```bash
+cd backend
+../.venv/bin/python batch_daily_analysis.py --limit 30
+```
+
+### 전체 분석
+```bash
+cd backend
+../.venv/bin/python batch_daily_analysis.py
+```
+
+## 자동 실행 (Cron)
+
+### Cron Job 설정
+```bash
+./setup-cron.sh
+```
+
+이 스크립트는:
+- 매일 평일(월~금) 오전 8시 50분에 배치 분석 실행
+- 장 시작 전(9시) 데이터를 준비
+- 로그는 `logs/batch_analysis.log`에 저장
+
+### Cron Job 확인
+```bash
+crontab -l | grep batch_daily_analysis
+```
+
+### Cron Job 제거
+```bash
+crontab -e
+# 해당 라인 삭제 후 저장
+```
+
+## 로그 확인
+
+### 실시간 로그 보기
+```bash
+tail -f logs/batch_analysis.log
+```
+
+### 최근 로그 확인
+```bash
+tail -100 logs/batch_analysis.log
+```
+
+## 동작 방식
+
+1. **8:50 AM**: Cron이 배치 스크립트 실행
+2. **종목 조회**: KOSPI + KOSDAQ 거래량 상위 종목
+3. **기술적 분석**: 각 종목의 RSI, MA, 볼린저 밴드 등 계산
+4. **DB 저장**: `stock_analysis` 테이블에 저장
+5. **9:00 AM**: 장 시작
+6. **첫 진입**: DB에서 캐시된 데이터를 빠르게 로드 (1초 이내)
+
+## API 제한 대응
+
+한국투자증권 API는 다음 제한이 있습니다:
+- 토큰 발급: 1분에 1회
+- API 호출: 초당 2회 권장
+
+배치 스크립트는:
+- 각 종목 분석 후 2초 대기
+- API 에러 시 자동 재시도 (최대 3회)
+- 지수 백오프로 대기 시간 증가
+
+## 예상 소요 시간
+
+- 10개 종목: 약 30초
+- 30개 종목: 약 2분
+- 60개 종목 (전체): 약 4분
+
+## 문제 해결
+
+### Cron이 실행되지 않음
+```bash
+# Cron 데몬 상태 확인 (macOS)
+sudo launchctl list | grep cron
+
+# Cron 데몬 시작 (macOS)
+sudo launchctl start com.vix.cron
+```
+
+### API 토큰 에러
+로그에 "접근토큰 발급 잠시 후 다시 시도하세요" 메시지가 반복되면:
+- 배치 스크립트가 너무 빨리 실행됨
+- `batch_daily_analysis.py`의 `await asyncio.sleep(2)` 값을 3~5초로 증가
+
+### DB 연결 에러
+```bash
+# PostgreSQL 실행 확인
+pg_isready -h localhost -p 5432
+
+# 서비스 시작
+./start-all.sh
+```
+
+## 참고
+- 배치 분석은 선택사항입니다
+- 실행하지 않아도 첫 진입 시 실시간 분석이 자동으로 수행됩니다
+- 다만 실시간 분석은 10~30초 소요됩니다