From db0c2b1146f8c7732182a867531e006957d3639a Mon Sep 17 00:00:00 2001 From: yakenator Date: Tue, 24 Feb 2026 04:47:04 +0900 Subject: [PATCH] docs: add detailed README.md with project documentation Co-Authored-By: Claude Opus 4.6 --- README.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9a66eb5 --- /dev/null +++ b/README.md @@ -0,0 +1,154 @@ +# stock-gateway + +한국 주식 분석 마이크로서비스 플랫폼의 **API Gateway 및 Docker Compose 오케스트레이션** 프로젝트. + +APISIX API Gateway를 통해 6개 백엔드 서비스를 단일 진입점(`/api/v1/...`)으로 통합하고, Docker Compose로 전체 인프라(Redis, PostgreSQL, MongoDB)와 서비스를 한 번에 구동합니다. + +## 아키텍처 + +``` +Browser (localhost:3000) + │ + ▼ +┌─────────────────────────────────────────────────────┐ +│ APISIX API Gateway (:9080) │ +│ /api/v1/dart/... → stock-dart-collector (:8001) │ +│ /api/v1/kis/... → stock-kis-collector (:8002) │ +│ /api/v1/news/... → stock-news-crawler (:8003) │ +│ /api/v1/screening/… → stock-screener (:8004) │ +│ /api/v1/catalyst/… → stock-catalyst (:8005) │ +│ /api/v1/analysis/… → stock-llm-analyzer (:8006) │ +└─────────────────────────────────────────────────────┘ + │ │ │ + ▼ ▼ ▼ + Redis 7 PostgreSQL MongoDB 7 + (:6379) (TimescaleDB) (:27017) + (:5432) +``` + +## 컨테이너 구성 (11개) + +| 카테고리 | 서비스 | 이미지 | 포트 | +|---------|--------|--------|------| +| **인프라** | Redis | `redis:7-alpine` | 6379 | +| | PostgreSQL | `timescale/timescaledb:latest-pg16` | 5432 | +| | MongoDB | `mongo:7` | 27017 | +| **게이트웨이** | APISIX | `apache/apisix:3.8.0-debian` | 9080, 9091 | +| **수집** | stock-dart-collector | Python 3.12 | 8001 | +| | stock-kis-collector | Python 3.12 | 8002 | +| | stock-news-crawler | Python 3.12 | 8003 | +| **분석** | stock-screener | Python 3.12 | 8004 | +| | stock-catalyst | Python 3.12 | 8005 | +| | stock-llm-analyzer | Python 3.12 | 8006 | +| **프론트엔드** | stock-frontend | Node.js 20 | 3000 | + +## 빠른 시작 + +### 1. 환경변수 설정 + +```bash +cp .env.example .env +# .env 파일을 편집하여 API 키 설정 +``` + +필수 API 키: +- `DART_API_KEY` - [DART OpenAPI](https://opendart.fss.or.kr/) 인증키 +- `KIS_APP_KEY` / `KIS_APP_SECRET` - [한국투자증권 Open API](https://apiportal.koreainvestment.com/) 앱 키 +- `ANTHROPIC_API_KEY` - [Anthropic API](https://console.anthropic.com/) 키 (LLM 분석용) + +### 2. 전체 스택 실행 + +```bash +docker compose up -d --build +``` + +### 3. 상태 확인 + +```bash +# 게이트웨이 헬스체크 +curl http://localhost:9080/api/health + +# 개별 서비스 헬스체크 (게이트웨이 경유) +curl http://localhost:9080/api/v1/dart/health +curl http://localhost:9080/api/v1/kis/health + +# 전체 컨테이너 상태 +docker compose ps +``` + +## APISIX 게이트웨이 설정 + +### 동작 모드 + +- **Standalone (declarative)**: etcd 없이 `apisix.yaml` 파일로 라우팅 설정 +- 설정 변경 시 APISIX 컨테이너 재시작 필요 + +### API 라우팅 + +모든 API 경로는 `/api/v1/{service}/{path}` 패턴을 따릅니다. `proxy-rewrite` 플러그인이 버전 프리픽스를 제거하여 백엔드 서비스에 전달합니다. + +``` +요청: GET /api/v1/kis/stocks?market=KOSPI + → 변환: GET /stocks?market=KOSPI → stock-kis-collector:8002 +``` + +### 글로벌 플러그인 + +| 플러그인 | 설정 | +|---------|------| +| **CORS** | `allow_origins: *`, 모든 메서드/헤더 허용 | +| **Rate Limiting** | 100 req/s, burst 50, IP 기반, 초과 시 429 | +| **Prometheus** | `:9091`에서 메트릭 노출 | + +### 헬스체크 + +모든 업스트림에 Active Health Check 설정: +- 정상: 10초 간격, 2회 연속 성공 → healthy +- 비정상: 5초 간격, 3회 연속 실패 → unhealthy + +## API 엔드포인트 목록 + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET | `/api/health` | 게이트웨이 상태 (버전 정보 포함) | +| GET | `/api/v1/{svc}/health` | 개별 서비스 헬스체크 | +| GET | `/api/v1/{svc}/streams` | Redis Stream 큐 길이 | +| GET | `/api/v1/kis/stocks` | 종목 목록 (검색, 필터, 페이징) | +| GET | `/api/v1/kis/stocks/{code}` | 종목 상세 (가격, 밸류에이션) | +| GET | `/api/v1/screening/results/latest` | 최근 스크리닝 결과 | +| GET | `/api/v1/catalyst/results/{code}` | 종목별 공시/카탈리스트 | +| GET | `/api/v1/analysis/results/{code}` | 종목별 AI 분석 결과 | +| POST | `/api/v1/dart/collect/financials` | DART 재무제표 수집 트리거 | +| POST | `/api/v1/dart/collect/disclosures` | DART 공시 수집 트리거 | +| POST | `/api/v1/kis/collect/stocks` | KIS 종목 목록 수집 트리거 | +| POST | `/api/v1/kis/collect/prices` | KIS 가격 수집 트리거 | +| POST | `/api/v1/news/collect/news` | 뉴스 크롤링 트리거 | +| POST | `/api/v1/screening/screen` | 스크리닝 실행 트리거 | +| POST | `/api/v1/catalyst/detect` | 카탈리스트 탐지 트리거 | +| POST | `/api/v1/analysis/analyze` | LLM 분석 트리거 | + +## 프로젝트 구조 + +``` +stock-gateway/ +├── docker-compose.yml # 전체 스택 오케스트레이션 +├── .env.example # 환경변수 템플릿 +└── apisix/ + └── conf/ + ├── config.yaml # APISIX 서버 설정 (standalone mode) + └── apisix.yaml # 라우트, 업스트림, 글로벌 룰 정의 +``` + +## 관련 프로젝트 + +| 프로젝트 | 설명 | +|---------|------| +| [stock-common](../stock-common) | 공유 라이브러리 (모델, DB, Redis, 설정) | +| [stock-dart-collector](../stock-dart-collector) | DART 공시/재무제표 수집 | +| [stock-kis-collector](../stock-kis-collector) | KIS 주가/종목 수집 | +| [stock-news-crawler](../stock-news-crawler) | 뉴스 크롤링 | +| [stock-screener](../stock-screener) | 정량 스크리닝 | +| [stock-catalyst](../stock-catalyst) | 카탈리스트 탐지 | +| [stock-llm-analyzer](../stock-llm-analyzer) | LLM 기반 AI 분석 | +| [stock-cli](../stock-cli) | CLI 파이프라인 관리 도구 | +| [stock-frontend](../stock-frontend) | Next.js 웹 대시보드 |