StockLens-AI (Financial Reporter)

StockLens-AI는 사용자의 주식 포트폴리오와 관련 경제 뉴스를 자동으로 수집하여 Notion 리포트를 생성해주는 자동화 도구입니다.

초기 기획은 Kiwoom OpenAPI를 통해 모든 자산 데이터를 자동으로 동기화하는 것이었으나, 기술적 제약(해외주식 API 미지원 등)으로 인해 하이브리드 방식으로 전환하였습니다.

🚀 주요 변경 사항 및 특징 (Architecture Shift)

이전 계획 (Deprecated)

• Kiwoom Open API 직접 연결: 사용자의 계좌 정보를 직접 읽어오는 방식.
• 문제점:
  • Kiwoom OpenAPI(국내)는 미국 주식 조회를 지원하지 않음.
  • 해외 주식용 별도 모듈(OpenAPI W) 설치 필요 및 복잡한 인증 과정.
  • 32-bit Python 환경 강제 (최신 개발 환경과 호환성 부족).

현재 방식 (Current Architecture)

• YFinance + 수동 수량 관리:
  • 보유 수량(Qty): config.yaml 파일에 한 번만 입력.
  • 가격 및 환율(Price & Rate): yfinance를 통해 실시간 업데이트.
  • 장점: 증권사 서버 점검 시간과 무관하게 언제든 조회 가능하며, 미국/한국 주식을 통합 관리할 수 있음. Python 64-bit 최신 환경 지원.

---

📂 프로젝트 구조 (Project Structure)

StockLens-AI/
├── config.yaml          # [필수] 포트폴리오(종목/수량) 및 Notion 토큰 설정
├── main.py              # 메인 실행 파일
├── requirements.txt     # 필요한 라이브러리 목록
├── ISSUE_Kiwoom_Global_Limit.md # 기술적 전환 배경 상세 문서
└── src/
    ├── portfolio_manager.py # YFinance 기반 자산 가치 계산 모듈
    ├── notion.py            # Notion API 리포트 생성기
    └── news.py              # 구글 뉴스(RSS) 수집기

🛠️ 설치 및 실행 (Setup & Usage)

1. 환경 설정

Python 3.10 이상 (64-bit 권장)이 필요합니다.

# 가상환경 생성 (선택 사항)
python -m venv .venv
.venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

2. 설정 파일 수정 (config.yaml)

config.yaml 파일을 열어 다음 두 가지를 설정하세요.

1. Notion 설정: API 토큰과 데이터베이스 ID 입력.
2. 포트폴리오 입력:

   portfolio:
     stocks:
       - symbol: "AAPL"    # 종목 코드 (미국 주식 티커)
         qty: 10           # 보유 수량
         avg_price: 180.0  # 평단가 (달러)
         avg_exchange_rate: 1300.0 # 매수 당시 환율 (선택 사항)
       
       - symbol: "005930.KS" # 한국 주식은 뒤에 .KS(코스피) 붙임
         qty: 20
         avg_price: 70000

3. 실행

python main.py

실행이 완료되면 Notion 페이지에 깔끔한 리포트가 생성됩니다.

---

📝 참고 문서

기술적 전환에 대한 자세한 배경은 ISSUE_Kiwoom_Global_Limit.md 파일을 참고하세요.