# stock-dart-collector

한국 주식 분석 플랫폼의 **DART 공시/재무제표 수집 서비스**. [DART OpenAPI](https://opendart.fss.or.kr/)를 통해 상장기업의 공시 정보와 재무제표를 수집합니다.

## 기능

- **재무제표 수집**: DART OpenAPI에서 개별/연결 재무제표 데이터 추출 (매출액, 영업이익, 순이익, 총자산, 총부채, 자본총계, 영업현금흐름)
- **공시 수집**: 최근 N일간 공시 목록 크롤링 (보고서명, 유형, 링크)
- **기업 코드 매핑**: stock_code ↔ corp_code 자동 변환 (DART corpCode.xml)
- **REST API**: 수집 트리거 + 상태 모니터링
- **비동기 워커**: Redis Streams 기반 작업 큐 소비

## API 엔드포인트

| 메서드 | 경로 | 설명 |
|--------|------|------|
| GET | `/health` | 서비스 상태 (Redis 연결, uptime) |
| GET | `/streams` | Redis Stream 큐 길이 |
| POST | `/collect/financials` | 재무제표 수집 트리거 |
| POST | `/collect/disclosures` | 공시 수집 트리거 |

### 요청 예시

```bash
# 재무제표 수집
curl -X POST http://localhost:8001/collect/financials \
  -H "Content-Type: application/json" \
  -d '{"stock_codes": ["005930", "000660"], "year": 2024}'

# 공시 수집 (최근 7일)
curl -X POST http://localhost:8001/collect/disclosures \
  -H "Content-Type: application/json" \
  -d '{"days": 7}'
```

### 응답

```json
{"status": "queued", "message_id": "1700000000000-0", "stock_codes": ["005930", "000660"]}
```

## 데이터 파이프라인

```
POST /collect/financials
        │
        ▼
  queue:trigger-dart  ──→  Worker (DARTCollector)
                                   │
                           ┌───────┴───────┐
                           ▼               ▼
               queue:raw-financials   queue:raw-disclosures
                           │               │
                           ▼               ▼
                     (downstream services consume)
```

Worker는 Redis Stream `queue:trigger-dart`를 소비하고, 수집 결과를 `queue:raw-financials` 또는 `queue:raw-disclosures` 스트림에 발행합니다.

## 워커 동작

서비스 시작 시 두 가지가 동시에 실행됩니다:

1. **REST API 서버** (uvicorn, port 8001) - 트리거 수신, 헬스체크
2. **Redis Stream 워커** - 큐 메시지 소비 → DART API 호출 → 결과 발행

워커가 크래시해도 API 서버는 계속 동작하며, 10초 후 워커가 자동 재시작합니다.

## DART API 세부사항

| 항목 | 값 |
|------|---|
| Base URL | `https://opendart.fss.or.kr/api` |
| Rate Limit | 10,000 req/day (약 10 req/s) |
| 인증 | `crtfc_key` 쿼리 파라미터 |
| 재무제표 | `fnlttSinglAcntAll.json` (개별재무제표) |
| 공시 목록 | `list.json` |
| 기업 코드 | `corpCode.xml` (ZIP 다운로드 후 XML 파싱) |

## 프로젝트 구조

```
stock-dart-collector/
├── pyproject.toml
├── Dockerfile
├── .dockerignore
└── src/stock_dart_collector/
    ├── __init__.py
    ├── api.py          # FastAPI 엔드포인트
    ├── collector.py    # DARTCollector (DART API 호출)
    └── worker.py       # Redis Stream 소비자 + API 서버 실행
```

## 환경변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `DART_API_KEY` | DART OpenAPI 인증키 | (필수) |
| `REDIS_URL` | Redis 연결 URL | `redis://localhost:6379/0` |
| `POSTGRES_HOST` | PostgreSQL 호스트 | `localhost` |
| `LOG_LEVEL` | 로그 레벨 | `INFO` |

## 로컬 실행

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

## Docker

```bash
# stock-gateway의 docker-compose 사용 (권장)
cd ../stock-gateway && docker compose up stock-dart-collector

# 단독 빌드 (stock-common 필요)
docker build -f Dockerfile -t stock-dart-collector ..
```

## 의존성

- `stock-common` - 공유 라이브러리 (모델, DB, Redis, API 팩토리)
- Python >= 3.12