# 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