# 배치 분석 가이드

> 2026-09-27 정리: `BATCH_GUIDE.md` 와 `BATCH_ANALYSIS_GUIDE.md` 두 문서를 하나로 합쳤다.
> 두 문서가 종목 수(200 vs 60)·cron 시각(09:00 vs 08:50)·실행 스크립트를 서로 다르게 적고 있었고,
> 양쪽 모두 **존재하지 않는 스크립트**(`run-batch.sh`, `start-all.sh`)를 안내하고 있었다.
> 아래 내용은 실제 코드(`setup-cron.sh`, `backend/batch_daily_analysis.py`, `config.py`)를 확인해 작성했다.

## 개요

장 시작 전에 전체 종목을 분석해 `stock_analysis` 테이블에 캐시한다. 대시보드 첫 진입 시 실시간 분석(30초)을 기다리지 않고 DB에서 바로 읽는다.

배치는 **선택사항**이다. 실행하지 않아도 첫 진입 시 실시간 분석이 자동 수행되며, 그 경우 10~30초가 걸린다.

## 무엇이 언제 도는가

`setup-cron.sh` 가 등록하는 cron 잡은 **3개**다(모두 평일, `docker exec autostock-backend` 경유).

| 시각 | 스크립트 | 로그 |
|------|----------|------|
| 06:00 | `prefetch_token.py` | `logs/token_prefetch.log` |
| 08:50 | `batch_daily_analysis.py` | `logs/batch_analysis.log` |
| 09:00~15:00 매 10분 | `batch_intraday_analysis.py` | `logs/batch_intraday.log` |

토큰 프리페치가 06:00에 먼저 도는 이유: KIS 토큰 발급은 1분에 1회 제한이라, 08:50 배치가 토큰 발급부터 시작하면 실패 시 재시도 여유가 없다.

## 수동 실행

컨테이너 밖에서 돌릴 때는 프로젝트 venv 를 쓴다.

```bash
cd backend

# 테스트 (10종목)
../.venv/bin/python batch_daily_analysis.py --test

# 개수 제한
../.venv/bin/python batch_daily_analysis.py --limit 30

# 전체
../.venv/bin/python batch_daily_analysis.py
```

컨테이너 안에서:

```bash
docker exec autostock-backend python /app/batch_daily_analysis.py --test
```

인자는 `--test`(10종목)와 `--limit N` 두 개뿐이다.

## 자동 실행

```bash
./setup-cron.sh          # 3개 잡 등록 (이미 있으면 건너뜀)
crontab -l | grep batch  # 확인
crontab -e               # 제거는 해당 라인 삭제
```

`setup-cron.sh` 는 `docker` 명령을 찾지 못하면 중단한다. 컨테이너명은 `autostock-backend` 로 고정되어 있다.

## 로그

```bash
tail -f logs/batch_analysis.log
tail -100 logs/batch_analysis.log
```

## 동작 방식

1. 종목 목록 조회 — 네이버 시가총액 순위(`naver_finance`, KOSPI+KOSDAQ). 실패 시 `stock_daily_prices` 최근 거래일 기준으로 폴백
2. 종목별 기술적 분석 — RSI, MA5/20/60, 볼린저, 스토캐스틱 등
3. `stock_analysis` 테이블에 upsert
4. 장 시작 후 첫 진입은 이 캐시를 읽는다

분석 종목 수는 `config.py` 의 `ANALYSIS_STOCK_COUNT`(기본 **300**)가 결정한다. 이 값은 `strategy_configs` DB 테이블로도 덮일 수 있다 — CLAUDE.md §0 파라미터 우선순위 참고.

## 소요 시간

종목당 API 대기가 있어 개수에 거의 비례한다. 10종목 약 30초, 30종목 약 2분 기준으로 추정하면 된다. 정확한 값은 `logs/batch_analysis.log` 의 실제 실행 기록을 보는 것이 맞다.

## API 제한 대응

KIS API 제한:
- 토큰 발급 1분에 1회
- 호출 초당 2회 권장

배치 쪽 대응:
- 종목 분석 사이 대기
- 에러 시 지수 백오프 재시도

## 조회 API

전역 프리픽스는 `/api/v1` 이다.

```bash
# 빠른 조회 (DB 캐시)
GET /api/v1/recommendations/rule-based

# 실시간 분석 (느림)
GET /api/v1/recommendations/rule-based?realtime=true
GET /api/v1/recommendations/rule-based/realtime   # 분석 후 DB upsert + 반환
```

프론트엔드는 기본을 DB 조회로 두고, 실시간은 명시적 버튼으로 분리하는 것이 좋다.

## `stock_analysis` 주요 컬럼

`backend/app/models/models.py` 의 `StockAnalysis` 가 정본이다.

```
stock_code, stock_name, analysis_date, current_price, change_rate, volume,
rsi, ma5, ma20, ma60, stochastic_k, stochastic_d, signals(JSONB), score, ...
```

## 문제 해결

**cron 이 실행되지 않음** (macOS)
```bash
sudo launchctl list | grep cron
```
cron 잡이 `docker exec` 를 쓰므로 Docker Desktop 이 떠 있어야 한다.

**"접근토큰 발급 잠시 후 다시 시도하세요" 반복**
토큰 발급 1분 제한에 걸린 것이다. 06:00 프리페치 잡이 등록됐는지 먼저 확인하고, 수동 실행을 연달아 하지 않는다.
⚠️ 로컬에서 배치를 돌릴 때 NAS 와 같은 앱키를 쓰면 **서로 토큰을 무효화**한다. 로컬 실행은 앱키를 분리하거나 피한다.

**DB 연결 에러**
```bash
docker compose ps
docker compose logs autostock-db --tail 50
```