# stock_chart_site

개인용 주식 차트 + 단기 예측 사이트. 한국 종목 검색 → 현재 차트 표시 → "예상차트 보기" 클릭 시 Chronos+LightGBM 앙상블로 향후 1~5거래일 예측을 차트에 이어 붙임. 사용자가 한 번이라도 예측을 확인한 종목은 자동 저장해서 다음날 실제 가격과 비교 → 오차/방향성 적중률을 누적 → 앙상블 가중치를 자동 보정.

스펙 원문: `/home/claude/EJClaw/groups/stock_predictor/SPEC.md` (별도 채팅 그룹).

## 빠른 시작 (Windows + Docker Desktop + RTX 3070 Ti)

전제: Docker Desktop이 이미 설치되어 있고, GPU 사용하려면 `Settings → Resources → WSL Integration → GPU support`가 켜져 있어야 합니다.

```cmd
git clone https://git.tkrmagid.kr/tkrmagid/stock_chart_site.git
cd stock_chart_site
build.bat
```

`build.bat`이 자동으로
1. `.env.example` → `.env` 복사 (없는 경우)
2. `nvidia-smi` 로 GPU 감지 → GPU 있으면 GPU 모드, 없으면 CPU 폴백
3. `docker compose build` + `up -d`

확인:
- Web: http://localhost:3000
- Backend health: http://localhost:8000/health
- DB extensions: http://localhost:8000/health/db (`timescaledb`, `vector`, `pg_trgm` 셋 다 켜져 있어야 정상)

정지:
```cmd
docker compose down
```

## 빌드 모드 (수동)

```bash
# GPU 모드 (RTX 3070 Ti 등 NVIDIA GPU 사용)
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build

# CPU 모드
docker compose up -d --build
```

## API 키 발급 (모두 무료)

키 없어도 pykrx 기반 일봉/뉴스 RSS 만으로 일단 동작합니다. 다음 키를 받으면 데이터 품질이 좋아집니다.

### 1) 한국투자증권 KIS OpenAPI (실시간 시세 + EOD)

1. https://apiportal.koreainvestment.com 회원가입 (한국투자증권 계좌 필요)
2. 좌측 "Open API 신청" → 모의/실전 중 하나 신청
3. 발급 완료 후 마이페이지에서 App Key, App Secret, 계좌번호 확인
4. `.env` 에 입력:
   ```
   KIS_APP_KEY=...
   KIS_APP_SECRET=...
   KIS_ACCOUNT_NO=...
   ```

### 2) DART OpenAPI (전자공시 본문)

1. https://opendart.fss.or.kr 회원가입
2. 마이페이지 → 인증키 신청 → 즉시 발급
3. `.env` 에 입력:
   ```
   DART_API_KEY=...
   ```

### 3) HuggingFace (선택, 모델 다운로드 가속)

토큰 없어도 공개 모델 (`amazon/chronos-bolt-base`, `snunlp/KR-FinBert`) 다운로드가 됩니다. 토큰이 있으면 rate limit이 완화되고 첫 다운로드가 빨라집니다.

1. https://huggingface.co 회원가입
2. https://huggingface.co/settings/tokens 에서 Read 토큰 생성
3. `.env` 에 입력:
   ```
   HUGGINGFACE_TOKEN=hf_...
   ```

## 학습/배치 대상 시드 종목 (10개)

검색은 KRX 전 종목을 대상으로 동작하지만, 일별 배치/재학습/메트릭 누적은 아래 10개를 우선 대상으로 합니다. 운영하면서 더 의미있는 종목이 보이면 교체합니다.

| 분류 | 종목 | 코드 |
|---|---|---|
| 대형 인기주 | 삼성전자 | 005930 |
| 대형 인기주 | SK하이닉스 | 000660 |
| 변동성 큰 종목 | 에코프로비엠 | 247540 |
| 변동성 큰 종목 | 한미반도체 | 042700 |
| 최근 인기 테마 | 두산에너빌리티 | 034020 |
| 최근 인기 테마 | 한화에어로스페이스 | 012450 |
| 최근 인기 테마 | HD현대중공업 | 329180 |
| 전통 IT/플랫폼 | NAVER | 035420 |
| 방어주/저변동 | KT&G | 033780 |
| 방어주/저변동 | 한국가스공사 | 036460 |

## 디렉토리 구조

```
stock_chart_site/
├── build.bat                       # Windows: 빌드+기동
├── docker-compose.yml              # db + backend + web
├── docker-compose.gpu.yml          # GPU 오버레이 (NVIDIA reservation)
├── .env.example                    # 환경 변수 템플릿
├── backend/
│   ├── Dockerfile                  # CUDA 12.1 + Python 3.11
│   ├── pyproject.toml
│   └── app/
│       ├── main.py                 # FastAPI entry
│       ├── config.py               # env settings
│       ├── db/
│       │   ├── connection.py
│       │   └── migrations/
│       │       └── 001_init.sql    # DB 스키마
│       ├── fetch/                  # KIS / pykrx / DART / 뉴스 (Phase 1)
│       ├── models/                 # Chronos / LightGBM / KR-FinBERT (Phase 2~4)
│       ├── pipelines/              # daily_batch / inference / retrain (Phase 1, 4)
│       └── api/                    # FastAPI 라우터 (Phase 5)
└── web/
    ├── Dockerfile
    ├── package.json
    └── app/
        ├── layout.tsx
        └── page.tsx                # 검색 + 차트 UI (Phase 6)
```

## 진행 계획

- Phase 0 — 스캐폴드 (현재): Docker 환경 + DB 스키마 + 빈 FastAPI/Next.js + build.bat
- Phase 1a — pykrx 데이터 파이프: 일봉/외인기관/지수 + DART + 뉴스 RSS + 거시
- Phase 1b — KIS EOD (키 받으면)
- Phase 2 — KR-FinBERT 감성 점수 + 일별 집계
- Phase 3 — Chronos zero-shot 예측 적재
- Phase 4 — LightGBM walk-forward + `prediction_outcomes` 누적 시작
- Phase 5 — FastAPI 엔드포인트 (검색, 차트, on-demand 예측, 메트릭)
- Phase 6 — Next.js UI (검색 + 현재 차트 + 예상차트 토글)
- Phase 7 (옵션) — 백테스트 페이지 + 주간 자동 재학습

## 동작 모델 메모

- 예측 트리거: 사용자가 "예상차트 보기" 누른 종목에 대해 즉시 inference. 결과는 `predictions(user_triggered=TRUE)` 로 저장.
- 다음날 00:30 (또는 16:30) 배치: `user_triggered=TRUE` 인 예측 중 `target_date`가 도래한 것들에 대해 실제 가격과 매칭 → `prediction_outcomes` 적재.
- 주간 02:00: 종목/모델별 최근 30일 hit rate 기반으로 앙상블 가중치를 자동 보정. hit rate가 임계 미만이면 LGBM 재학습.

## 안전/한계

- 본인 1인 개인용. 외부 공개/상업 사용 안 함.
- 자동매매 연결 없음. 예측은 참고용.
- 백테스트 정확도와 라이브 정확도는 다르며 단기 방향성 모델의 라이브 상한은 보통 55~60%.