130 lines
3.8 KiB
Markdown
130 lines
3.8 KiB
Markdown
# stock-catalyst
|
|
|
|
한국 주식 분석 플랫폼의 **카탈리스트 탐지 서비스**. 스크리닝된 종목의 공시와 뉴스를 분석하여 긍정적 촉매(카탈리스트)와 밸류 트랩 신호를 식별합니다.
|
|
|
|
## 기능
|
|
|
|
- **카탈리스트 탐지**: 키워드 패턴 매칭으로 공시에서 긍정적 이벤트 식별
|
|
- **밸류 트랩 경고**: 저평가처럼 보이지만 위험한 종목 신호 감지
|
|
- **공시 데이터 조회**: MongoDB에서 종목별 공시 이력 조회
|
|
- **카테고리 분류**: 실적호전, 대규모계약, 주주환원, M&A, 규제긍정
|
|
- **비동기 워커**: Redis Streams 기반 파이프라인 연동
|
|
|
|
## 카탈리스트 카테고리
|
|
|
|
| 카테고리 | 키워드 예시 |
|
|
|---------|------------|
|
|
| **실적 서프라이즈** | 어닝서프라이즈, 실적 호조, 영업이익 증가, 흑자전환, 사상최대 |
|
|
| **대규모 계약** | 대규모 계약, 수주, 공급계약, 납품계약, 신규 수주 |
|
|
| **주주 환원** | 배당, 자사주, 자기주식, 주주환원, 배당금 증가 |
|
|
| **M&A** | 인수, 합병, M&A, 지분 취득, 경영권 |
|
|
| **규제 긍정** | 규제 완화, 인허가, 승인, 보조금, 세제 혜택 |
|
|
|
|
### 밸류 트랩 경고 키워드
|
|
|
|
매출 감소, 영업손실, 적자 전환, 적자 지속, 구조조정, 감자, 상장폐지, 관리종목, 자본잠식
|
|
|
|
## API 엔드포인트
|
|
|
|
| 메서드 | 경로 | 설명 |
|
|
|--------|------|------|
|
|
| GET | `/health` | 서비스 상태 |
|
|
| GET | `/streams` | Redis Stream 큐 길이 |
|
|
| POST | `/detect` | 카탈리스트 탐지 트리거 |
|
|
| GET | `/results/{stock_code}` | 종목별 공시/카탈리스트 조회 |
|
|
|
|
### 요청 예시
|
|
|
|
```bash
|
|
# 카탈리스트 탐지 트리거
|
|
curl -X POST http://localhost:8005/detect \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"stock_code": "005930", "run_id": "abc-123", "composite_score": 85.3}'
|
|
|
|
# 결과 조회
|
|
curl http://localhost:8005/results/005930?limit=10
|
|
```
|
|
|
|
### 응답 예시
|
|
|
|
```json
|
|
// GET /results/{stock_code}
|
|
{
|
|
"stock_code": "005930",
|
|
"disclosures": [
|
|
{
|
|
"_id": "...",
|
|
"stock_code": "005930",
|
|
"title": "삼성전자 사업보고서",
|
|
"dart_id": "20241220000001",
|
|
"disclosed_at": "2024-12-20T00:00:00"
|
|
}
|
|
]
|
|
}
|
|
|
|
// 탐지 결과 (내부)
|
|
{
|
|
"catalyst_score": 60,
|
|
"detected_catalysts": [
|
|
{"category": "earnings_surprise", "keyword": "영업이익 증가", "title": "..."}
|
|
],
|
|
"value_trap_signals": [],
|
|
"is_value_trap": false
|
|
}
|
|
```
|
|
|
|
## 점수 체계
|
|
|
|
- **Catalyst Score**: 0~100점. 탐지된 카탈리스트 1개당 +20점
|
|
- **밸류 트랩 감지**: 경고 신호 2개 이상 → `is_value_trap: true`, 점수 -40점
|
|
- 뉴스 기반 탐지: 카탈리스트 1개당 +15점
|
|
|
|
## 데이터 파이프라인
|
|
|
|
```
|
|
queue:screened (스크리닝 결과)
|
|
│
|
|
▼
|
|
Worker (CatalystDetector)
|
|
│
|
|
├── MongoDB에서 공시 데이터 조회
|
|
├── 키워드 매칭으로 카탈리스트 탐지
|
|
│
|
|
▼
|
|
queue:catalysts ──→ stock-llm-analyzer
|
|
```
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
stock-catalyst/
|
|
├── pyproject.toml
|
|
├── Dockerfile
|
|
├── .dockerignore
|
|
└── src/stock_catalyst/
|
|
├── __init__.py
|
|
├── api.py # FastAPI 엔드포인트
|
|
├── detector.py # CatalystDetector (키워드 패턴 매칭)
|
|
└── worker.py # Redis Stream 소비자 + API 서버 실행
|
|
```
|
|
|
|
## 환경변수
|
|
|
|
| 변수 | 설명 | 기본값 |
|
|
|------|------|--------|
|
|
| `REDIS_URL` | Redis 연결 URL | `redis://localhost:6379/0` |
|
|
| `MONGODB_URI` | MongoDB 연결 URI | `mongodb://localhost:27017` |
|
|
| `MONGODB_DB` | MongoDB 데이터베이스명 | `stock_analysis` |
|
|
|
|
## 로컬 실행
|
|
|
|
```bash
|
|
pip install -e ../stock-common && pip install -e .
|
|
python -m stock_catalyst.worker
|
|
```
|
|
|
|
## 의존성
|
|
|
|
- `stock-common` - 공유 라이브러리
|
|
- Python >= 3.12
|