Files

yakenator 4dea47e0c1 docs: add detailed README.md with project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-24 04:47:05 +09:00

3.9 KiB

Raw Blame History

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 스트림에 발행합니다.

워커 동작

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

REST API 서버 (uvicorn, port 8001) - 트리거 수신, 헬스체크
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

3.9 KiB Raw Blame History