From 4dea47e0c15531144f9c7b5beb686bdd43c79461 Mon Sep 17 00:00:00 2001
From: yakenator <yakenator@gitea.yakenator.io>
Date: Tue, 24 Feb 2026 04:47:05 +0900
Subject: [PATCH] docs: add detailed README.md with project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0c9790b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,123 @@
+# 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