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

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1531a6e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,121 @@
+# stock-cli
+
+한국 주식 분석 플랫폼의 **CLI(명령줄 인터페이스) 도구**. Redis Streams를 통해 각 마이크로서비스에 작업을 트리거하고, 파이프라인 상태를 모니터링합니다.
+
+## 기능
+
+- **데이터 수집 트리거**: DART 공시/재무, KIS 주가/종목, 뉴스 크롤링
+- **스크리닝 실행**: 전략/시장/Top N 설정으로 정량 스크리닝
+- **파이프라인 상태**: Redis Stream 큐 길이를 테이블로 확인
+- **Rich 콘솔 출력**: 컬러, 테이블, 스타일링된 터미널 출력
+
+## 설치
+
+```bash
+pip install -e ../stock-common && pip install -e .
+```
+
+## 사용법
+
+### 데이터 수집
+
+```bash
+# DART 공시 수집 (최근 7일)
+stock collect dart --days 7
+
+# DART 특정 종목 수집
+stock collect dart --stock-codes "005930,000660" --days 30
+
+# KIS 주가 수집
+stock collect kis
+
+# KIS 특정 종목 수집
+stock collect kis --stock-codes "005930,000660"
+
+# 뉴스 크롤링 (종목 필수)
+stock collect news --stock-codes "005930,000660" --max-pages 5
+```
+
+### 스크리닝
+
+```bash
+# 기본 (balanced 전략, 전체 시장, 상위 50개)
+stock screen
+
+# Value 전략, KOSPI만, 상위 30개
+stock screen --strategy value --market KOSPI --top-n 30
+
+# Growth 전략
+stock screen --strategy growth
+```
+
+### 파이프라인 상태 확인
+
+```bash
+stock status
+```
+
+출력 예시:
+
+```
+              Pipeline Status
+┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ Stream                   ┃ Length ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ queue:trigger-dart       │ 0      │
+│ queue:trigger-kis        │ 0      │
+│ queue:trigger-news       │ 0      │
+│ queue:raw-financials     │ 12     │
+│ queue:raw-prices         │ 150    │
+│ queue:raw-news           │ 45     │
+│ queue:raw-disclosures    │ 23     │
+│ queue:trigger-screen     │ 0      │
+│ queue:screened           │ 50     │
+│ queue:catalysts          │ 30     │
+│ queue:results            │ 25     │
+└─────────────────────────┴────────┘
+```
+
+## 명령어 구조
+
+```
+stock
+├── collect                # 데이터 수집
+│   ├── dart               # DART 공시/재무제표
+│   ├── kis                # KIS 주가/종목
+│   └── news               # 뉴스 크롤링
+├── screen                 # 스크리닝 실행
+└── status                 # 파이프라인 상태 확인
+```
+
+## Redis Streams 매핑
+
+| 명령어 | 트리거 스트림 |
+|--------|-------------|
+| `collect dart` | `queue:trigger-dart` |
+| `collect kis` | `queue:trigger-kis` |
+| `collect news` | `queue:trigger-news` |
+| `screen` | `queue:trigger-screen` |
+
+## 프로젝트 구조
+
+```
+stock-cli/
+├── pyproject.toml
+└── src/stock_cli/
+    ├── __init__.py
+    └── main.py         # Typer CLI 앱 (collect, screen, status)
+```
+
+## 환경변수
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `REDIS_URL` | Redis 연결 URL | `redis://localhost:6379/0` |
+
+## 의존성
+
+- `stock-common` - 공유 라이브러리 (Redis 클라이언트, 설정)
+- `typer` - CLI 프레임워크
+- `rich` - 터미널 출력 스타일링
+- Python >= 3.12