# Trading AI — 프로젝트 구조 정리

> 한국 주식 AI 투자 분석 시스템. 뉴스·공시·주가·미국증시를 수집해
> 워런 버핏식 가치투자 + 퀀트 멀티팩터로 분석하고 매수/매도를 추천한다.
> (개발자 상세 가이드는 `CLAUDE.md`, 이 파일은 전체 구조 요약)

---

## 1. 한눈에

- **무엇을**: 약 1,500개 한국 상장사를 매일 0~100점으로 스코어링 → 등급(강력매수~강력매도)
- **어떻게**: 정형 데이터(재무·주가·수급)와 비정형 데이터(뉴스·공시 텍스트)를 결합
- **결과**: 대시보드(웹) + 텔레그램 알림으로 추천 전달
- **철학**: 가치투자가 기본 관점, 실제 엔진은 가치·성장·모멘텀·퀄리티를 섞은 멀티팩터

## 2. 데이터 흐름

```
뉴스/공시 수집 → 형태소분석(바른) → 임베딩(bge-m3) → 중복제거(Qdrant)
   → EXAONE LLM 감성분석(호재/악재·강도·catalyst)
주가·수급·미국증시 수집 ─────────────────────────────┐
재무제표(DART) 수집 ────────────────────────────────┤
                                                    ▼
                              종합 스코어링 (score-engine)
                                                    ▼
                       매수/매도 추천 → 대시보드 + 텔레그램
```

## 3. 인프라

| 항목 | 값 |
|------|-----|
| 서버 | Ubuntu 22.04, GPU 2장 (RTX 3060 12G / RTX 3070 8G) |
| DB | PostgreSQL `trading_ai` |
| 캐시 | Redis (중복제거·가격캐시) |
| 벡터DB | Qdrant (뉴스 유사도) |
| 컨테이너 | docker compose, 16개 서비스 |
| LLM | Ollama — EXAONE 3.5 7.8B(추론) + bge-m3(임베딩) |

## 4. 서비스 구조 (16개 컨테이너)

| 서비스 | 포트 | 역할 |
|--------|------|------|
| news-collector | 8787 | 뉴스 수집 + 형태소 + 임베딩 + EXAONE 감성분석 |
| bareunaapi / bareun | 5757 / 5656 | 한국어 형태소분석 |
| dart-collector | 8888 | DART 공시·재무제표·배당·자사주·섹터 수집 |
| score-engine | 8686 | 종합 스코어링 + 학습 + 텔레그램 + 백테스트 |
| ta-engine | 8484 | 기술적 분석 (MA·RSI·MACD·볼린저 등) |
| dashboard-api | 8989 | 대시보드 웹 + REST API |
| kis-api | 8585 | 한국 주가 수집 + 매매시그널 |
| aux-signal | 8282 | 컨센서스·기관/외국인 수급 + 매크로(ECOS) |
| us-market | 8383 | 미국증시 → 한국 동조 시그널 + 새벽 브리핑 |
| graph-engine | 9090 | GAT 그래프 신경망 → graph_score |
| telegram-bot | - | 텔레그램 명령 처리 (/buy /sell /stock 등) |
| ollama | 11434 | LLM 추론·임베딩 |
| postgres / redis / qdrant | - | DB·캐시·벡터DB |
| n8n / n8n-worker | 5678 | 워크플로우 자동화 |

## 5. 종합점수 산정

```
종합점수 = 펀더멘털통합 ×0.24 + 뉴스 ×0.18 + 기술 ×0.15
        + DART공시 ×0.10 + 외국인수급 ×0.14 + 공매도 ×0.06
        + 가격모멘텀 ×0.03 + DCF안전마진 ×0.10
        + 시장레짐 보정 + 앙상블 보팅(±18) + 미국증시(±15)
        + 보조신호(컨센서스·수급·매크로 등)
        + 사이클 고점 가드(경기민감주 실적정점 함정 −6~−12)
```

- **펀더멘털통합** = 버핏점수 + 추세 + 이익품질 + 매직포뮬러 + F-Score + **주주환원율 보너스**
- **추천 등급**: 강력매수(≥70·매수보팅≥3) / 매수관심 / 관망 / 매도관심 / 강력매도

## 6. 10공식 앙상블 + 학습

매직포뮬러 · F-Score · 알트만Z · PEG · 12-1모멘텀 · Beneish · GP/A · G-Score · Amihud · 베타(BAB)
— 각 공식이 매수/매도/관망 투표 → 학습 가중치로 결합.

**학습 시스템**
- `/learn-weights` — 공식별 가중치를 백테스트 edge로 학습 (국면별 segment 지원)
- `/learn-pricing` — 26+1개 피처로 7d/30d 수익률 예측 모델 학습 (Ridge·RF·XGBoost, walk-forward CV)
  - 학습 데이터: 전 종목 stock_scores 이력 × stock_ohlcv 실현수익률 (약 9,400 표본)
  - RF/XGB 모델은 DB에 직렬화 저장 → `/predict-price`가 직접 추론
- 일요일 자동 재학습 (04:00 가중치 / 05:00 가격모델)

## 7. 핵심 DB 테이블

| 테이블 | 내용 |
|--------|------|
| `news_analysis` | 뉴스별 감성·강도·catalyst·종목매핑 |
| `stock_scores` | 종목별 일일 종합점수·세부점수·추천등급·신호 |
| `dart_financials` | 재무제표 + ROE·부채비율 등 비율 + **자사주매입액** |
| `dart_dividends` | 배당금(DPS·총액) |
| `stock_technical` | 기술적 지표 |
| `stock_ohlcv` | 일봉 시계열 (수익률·베타·학습용) |
| `recommendation_performance` | 추천 성과 추적 (7d/30d 수익률·알파) |
| `weight_config` / `pricing_model_v2` | 학습된 가중치 / 가격예측 모델(직렬화 포함) |
| `us_overnight_signal` | 미국증시 → 한국 동조 보정값 |

## 8. 대시보드 (15개 탭)

종합 · 추천성과 · 매매시그널 · 거래량급증 · **포트폴리오** · 내 종목 분석 ·
추천종목 · 뉴스피드 · 수급 · 알림 · 10공식 · 백테스트 · **미증시** · 매크로 · **용어설명**

- 좌측 사이드바 네비게이션, 모바일 대응(햄버거 메뉴)
- 포트폴리오 탭: 보유종목 손익·섹터비중·리밸런싱 진단 + AI 추천 포트폴리오 구성
- 미증시 탭: 새벽 미국 핫/저조 종목 → 관련 KOSPI 추천
- 용어설명 탭: 차트·지표·재무·시장제도·투자스타일 용어 풀이

## 9. 주요 운영 명령

```bash
docker compose ps                                  # 서비스 상태
docker logs trading-<서비스> --tail 50 -f           # 로그
docker compose build <서비스> && docker compose up -d <서비스>   # 재배포

curl -X POST http://localhost:8686/score/calculate        # 전체 재스코어링
curl -X POST 'http://localhost:8686/learn-weights?days=90' # 가중치 학습
curl -X POST 'http://localhost:8686/learn-pricing?target=return_7d'  # 가격모델 학습
curl    http://localhost:8686/backtest                    # 백테스트
curl -X POST 'http://localhost:8888/collect/financials?count=3000'   # 재무 수집
curl -X POST  http://localhost:8888/collect/sectors        # 섹터 수집
```

## 10. 개선 이력 (2026-05)

- **백테스트 신뢰성**: 수익률 라벨을 OHLCV 정확한 날짜 종가로 정정, 거래비용 반영, 실제 MDD(자산곡선) 계산, 10공식 가중치 동기화
- **학습 데이터 140배 확장**: 추천종목 63건 → 전 종목 단면 9,394건. 모델 R² −0.40 → +0.38
- **모델 직렬화**: RF/XGB 모델을 DB에 저장 → `/predict-price`가 실제 모델로 추론
- **주주환원율 팩터**: (배당 + 자사주매입) / 시총 → 펀더멘털 보너스 (코리아 디스카운트 방어)
- **사이클 고점 가드**: 경기민감주 실적정점 함정 방어
- **미증시 새벽 브리핑**: 미국 핫/저조 종목 → 관련 KOSPI 추천
- **UI**: 좌측 사이드바 + 모바일 대응, 용어설명 탭 신설
- **포트폴리오 4종**: 추천 구성 · 자산곡선 백테스트 · 보유 관리 · 통합 탭
- **텔레그램**: 하루 4회 → 3회로 축소