# stock-kis-collector

한국 주식 분석 플랫폼의 **KIS(한국투자증권) 시세/종목 수집 서비스**. [KIS Open API](https://apiportal.koreainvestment.com/)를 통해 주가, 시가총액, 종목 정보를 수집하고, PostgreSQL에 저장된 데이터를 조회하는 REST API를 제공합니다.

## 기능

- **종목 수집**: KOSPI/KOSDAQ 시가총액 상위 종목 목록 수집
- **가격 수집**: 현재가 + 일별 시세 수집 (OHLCV, 시가총액)
- **종목 조회 API**: 검색, 시장 필터, 페이징 지원
- **종목 상세 API**: 최근 30일 가격 + 밸류에이션 지표
- **OAuth2 인증**: AppKey/AppSecret → access token 자동 갱신 (24시간 TTL)
- **비동기 워커**: Redis Streams 기반 작업 큐 소비

## API 엔드포인트

| 메서드 | 경로 | 설명 |
|--------|------|------|
| GET | `/health` | 서비스 상태 |
| GET | `/streams` | Redis Stream 큐 길이 |
| GET | `/stocks` | 종목 목록 (검색, 필터, 페이징) |
| GET | `/stocks/{stock_code}` | 종목 상세 (가격 + 밸류에이션) |
| POST | `/collect/stocks` | 종목 목록 수집 트리거 |
| POST | `/collect/prices` | 가격 수집 트리거 |

### GET /stocks 파라미터

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `market` | string | `all` | 시장 필터 (`all`, `KOSPI`, `KOSDAQ`) |
| `search` | string | `""` | 종목명/코드 검색 (ILIKE) |
| `limit` | int | `100` | 한 페이지당 개수 |
| `offset` | int | `0` | 페이징 오프셋 |

### 요청 예시

```bash
# 종목 검색
curl "http://localhost:8002/stocks?search=삼성&market=KOSPI&limit=10"

# 종목 상세
curl http://localhost:8002/stocks/005930

# 가격 수집 트리거
curl -X POST http://localhost:8002/collect/prices \
  -H "Content-Type: application/json" \
  -d '{"stock_codes": ["005930", "000660"]}'
```

### 응답 예시

```json
// GET /stocks
{
  "total": 1500,
  "stocks": [
    {
      "stock_code": "005930",
      "stock_name": "삼성전자",
      "market": "KOSPI",
      "sector": "전기전자",
      "close": 72000,
      "volume": 15000000,
      "market_cap": 429000000000000,
      "change_pct": 1.41
    }
  ]
}

// GET /stocks/{code}
{
  "stock_code": "005930",
  "stock_name": "삼성전자",
  "market": "KOSPI",
  "prices": [{"date": "2024-12-20", "open": 71500, "close": 72000, ...}],
  "valuation": {"per": 12.5, "pbr": 1.1, "roe": 8.7, "debt_ratio": 28.3, ...}
}
```

## 데이터 파이프라인

```
POST /collect/stocks or /collect/prices
        │
        ▼
  queue:trigger-kis  ──→  Worker (KISCollector)
                                  │
                          ┌───────┴───────┐
                          ▼               ▼
                  queue:raw-stocks   queue:raw-prices
```

## KIS API 세부사항

| 항목 | 값 |
|------|---|
| Base URL (실전) | `https://openapi.koreainvestment.com:9443` |
| Base URL (모의) | `https://openapivts.koreainvestment.com:9443` |
| 인증 | OAuth2 (AppKey + AppSecret → Bearer token) |
| 토큰 유효기간 | 24시간 |
| Rate Limit | 초당 20건 |
| 종목 목록 | `FHPST01740000` (시가총액 랭킹) |
| 현재가 | `FHKST01010100` (주식현재가 조회) |
| 일별 시세 | `FHKST03010100` (일별차트 조회) |

## 프로젝트 구조

```
stock-kis-collector/
├── pyproject.toml
├── Dockerfile
├── .dockerignore
└── src/stock_kis_collector/
    ├── __init__.py
    ├── api.py          # FastAPI 엔드포인트 (GET + POST)
    ├── collector.py    # KISCollector (KIS API 호출, OAuth2)
    └── worker.py       # Redis Stream 소비자 + API 서버 실행
```

## 환경변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `KIS_APP_KEY` | KIS 앱 키 | (필수) |
| `KIS_APP_SECRET` | KIS 앱 시크릿 | (필수) |
| `KIS_BASE_URL` | KIS API 베이스 URL | `https://openapi.koreainvestment.com:9443` |
| `REDIS_URL` | Redis 연결 URL | `redis://localhost:6379/0` |
| `POSTGRES_HOST` | PostgreSQL 호스트 | `localhost` |

## 로컬 실행

```bash
pip install -e ../stock-common && pip install -e .
python -m stock_kis_collector.worker
```

## 의존성

- `stock-common` - 공유 라이브러리
- Python >= 3.12