docs: add detailed README.md with project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 04:47:06 +09:00
parent df70cf6373
commit 442ea38d97
1 changed files with 139 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,139 @@
+# 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