stock-dart-collector

한국 주식 분석 플랫폼의 DART 공시/재무제표 수집 서비스. DART OpenAPI를 통해 상장기업의 공시 정보와 재무제표를 수집합니다.

기능

• 재무제표 수집: 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	공시 수집 트리거

요청 예시

# 재무제표 수집
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}'

응답

{"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

로컬 실행

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

Docker

# 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