# QuantEngine 데이터 기반 고도화 로드맵
**2026-07-24 ~ 2027-06-30**

---

## Executive Summary

**현상**: Python 레거시 기반 + .NET 신규 웹 UI의 하이브리드 구조
**목표**: Solid 원칙 + 데이터 정합성 + 게임이론 기반 퀀트 최적화 엔진 구축
**기대효과**: 
- 코드 품질: 기술부채 80% 감소
- 성능: 데이터 수집 시간 60% 단축
- 신뢰성: 감시 추적 가능성 100% (audit trail)
- 의사결정: 재현성 100% + 현장감(explainability) 개선

---

## Phase 0: Foundation (2026-07 ~ 2026-08) — 현재 진행 중
### 목표: 아키텍처 기초 다지기

#### P0.1: CI/CD 파이프라인 최적화 ✅ (완료: 2026-07-24)
- [x] ci.yml 리팩토링: 1 job → 9 parallel jobs
- [x] 성능: ~40min → ~15-20min (2.5배 가속)
- [x] 워크플로우 검증 자동화
- [x] CLAUDE.md 종합 문서화

**성과지표**: 
- CI 리드 타임 단축 ✅
- 병렬 job 의존성 명확화 ✅
- 개발자 온보딩 시간 50% 단축 예상

#### P0.2: 데이터 정합성 기초 구축 (2026-08)
**목표**: 모든 데이터 흐름의 버전 추적 + 감시 추적

**추진 과제**:
1. **PostgreSQL 이력 스키마 도입**
   - kis_collection_runs: 실행 시간, 성공/실패, 건수 추적
   - kis_collection_snapshots: 각 snapshot의 출처, 변환 이력
   - kis_collection_errors: 오류 분류 + 재현 로그

2. **데이터 정합성 검증기 개발**
   ```
   validate_data_consistency_v1.py:
   - Row count 변화 추적
   - Schema drift 감지
   - Null/duplicate 통계
   - Data lineage (출처 명시)
   ```

3. **Snapshot 변경 관리**
   - GatherTradingData.json → DB 마이그레이션 추적
   - 변경 이력: who, when, what, why (4W)
   - Rollback 능력 확보

**성과지표**:
- 모든 수집 run의 재현성 100%
- 데이터 변경 추적률 100%
- 자동화된 감시 추적 구현

---

## Phase 1: Data Architecture Refactoring (2026-09 ~ 2026-11)
### 목표: 정규화 + 컴포넌트화 + 패턴화

#### P1.1: 데이터 모델 정규화 (9월)
**현황**: KIS snapshot → 1개 JSON 구조
**목표**: 3NF (Third Normal Form) 기반 관계형 설계

**추진 과제**:
1. **Table 리팩토링**
   ```sql
   Current (비정규화):
   kis_collection_snapshots: {ticker, price, volume, bid, ask, ...100+ columns}
   
   Target (3NF):
   stocks: {id, ticker, name, market}
   quotes: {id, stock_id, timestamp, price, volume, source}
   order_book: {id, quote_id, bid_levels, ask_levels}
   fundamental: {id, stock_id, eps, pe_ratio, ...}
   ```

2. **마이그레이션 전략**
   - Phase 1a: 새 테이블 생성 (parallel)
   - Phase 1b: 데이터 변환 + 검증 (with fallback)
   - Phase 1c: 쿼리 리포인팅 (gradual cutover)
   - Phase 1d: 기존 테이블 아카이빙

3. **Backward Compatibility**
   ```csharp
   // Adapter pattern: 기존 API는 유지, 내부적으로 새 테이블 사용
   public class LegacySnapshotAdapter : ICollectionSnapshot
   {
       private readonly IQuoteRepository _newQuotes;
       public LegacySnapshotAdapter(IQuoteRepository repo) => _newQuotes = repo;
       
       public SnapshotDto Get(string ticker) 
           => SnapshotDto.FromNormalizedTables(_newQuotes.GetBy(ticker));
   }
   ```

**성과지표**:
- 스토리지 용량 40% 감소
- 쿼리 복잡도 50% 감소
- 데이터 무결성 제약 자동 적용

#### P1.2: 컴포넌트화 + 인터페이스 분리 (10월)
**목표**: Dependency Inversion 원칙 적용

**추진 과제**:
1. **Repository 분리**
   ```csharp
   Current (단일 ICollectionRepository):
   - GetSnapshots()
   - GetRuns()
   - GetErrors()
   - SaveSnapshot()
   
   Target (SOLID ISP):
   - IQuoteRepository: 가격/호가 데이터
   - IRunRepository: 수집 메타데이터
   - IErrorRepository: 오류 로그
   - IFundamentalRepository: 기본정보
   ```

2. **팩토리 패턴 도입**
   ```csharp
   public interface IDataSourceFactory
   {
       IDataSource CreateKisSource();
       IDataSource CreateNaverFallback();
       IDataSource CreateYahooFallback();
   }
   
   // 주입: 런타임에 데이터 소스 전환 가능
   ```

3. **전략 패턴: 데이터 변환**
   ```csharp
   public interface IDataTransformStrategy
   {
       SnapshotDto Transform(RawApiResponse response);
   }
   
   // 구현: Kis변환, Naver변환, Yahoo변환 등
   // 각 소스별 정규화 로직 캡슐화
   ```

**성과지표**:
- 모듈 간 의존성 명확화 (순환 의존성 0)
- 테스트 용이성 (Mock 주입 가능)
- 런타임 구성 가능 (dynamic strategy switching)

#### P1.3: 데이터 팩터 고도화 (11월)
**목표**: 데이터 품질 + 이상 탐지 자동화

**추진 과제**:
1. **Data Quality Metrics**
   ```python
   class DataFactorValidator:
       def check_completeness(self, snapshot):
           """누락값 검사: null/missing ratio"""
           return snapshot.fillna_ratio >= 0.95
       
       def check_freshness(self, snapshot):
           """신선도 검사: 수집 후 경과 시간"""
           age_hours = (now() - snapshot.created_at).hours
           return age_hours < 24
       
       def check_consistency(self, snapshot):
           """정합성 검사: bid <= mid <= ask"""
           return snapshot.bid <= snapshot.mid <= snapshot.ask
       
       def check_outliers(self, snapshot):
           """이상값 검사: 볼린저 밴드 벗어남"""
           z_score = (snapshot.price - mean) / std
           return abs(z_score) < 3  # 3-sigma rule
   ```

2. **자동 보정 규칙**
   ```
   Error Rule 1: 빠진 데이터 → 직전 값 사용 (forward fill)
   Error Rule 2: 이상값 → 같은 날짜 유사 종목 중앙값 사용
   Error Rule 3: 불가능한 값 → 폴백 소스(Naver/Yahoo) 호출
   ```

3. **CI 게이트 추가**
   ```
   validate_data_factors_v1.py:
   - 완전성 (Completeness) ≥ 95%
   - 신선도 (Freshness) < 24h
   - 정합성 (Consistency) 100%
   - 이상값 (Outliers) < 5%
   ```

**성과지표**:
- 자동 데이터 품질 검사 자동화
- 수동 개입 필요 비율 <5%
- 데이터 품질 스코어 98% 이상

---

## Phase 2: Quant Engine 고도화 (2026-12 ~ 2027-02)
### 목표: 게임이론 + 최적화 알고리즘 + 의사결정 엔진

#### P2.1: 게임이론 기반 포트폴리오 선택 (12월)
**목표**: 단순 수익률 최대화 → Nash Equilibrium 기반 균형점 추구

**추진 과제**:
1. **다중 플레이어 게임 모델**
   ```
   Players: 시장 참가자들 (기관, 개인, AI)
   Strategy space: 매도/보유/매수 + 비중 결정
   Payoff: 포트폴리오 return + risk-adjusted Sharpe ratio
   
   Goal: 내 포트폴리오 최적화 + 시장 균형 고려
   ```

2. **알고리즘**
   ```python
   class GameTheoreticPortfolio:
       def compute_nash_equilibrium(self, market_state):
           """
           각 자산의 최적 비중을 계산
           - Covariance matrix (상관성)
           - Expected return (기대수익률)
           - Risk aversion parameter (위험회피도)
           
           결과: 다른 플레이어가 이탈할 유인이 없는 균형점
           """
           # Linear Programming or Lemke-Howson algorithm
           return optimal_allocation
       
       def backtest_nash(self, historical_data):
           """과거 데이터로 Nash 균형 전략 검증"""
           # 매년 Nash 균형점 계산 + 연 수익률 추적
   ```

3. **구현 체크리스트**
   - [x] 기본 Markowitz 포트폴리오 (현재)
   - [ ] Nash Equilibrium 계산 (12월)
   - [ ] 백테스트 (12월)
   - [ ] CI 게이트 추가 (1월)

**성과지표**:
- 샤프 지수 개선 20% 이상
- 최대손실률(MDD) 감소 15% 이상
- 시장 급변 시 안정성 입증

#### P2.2: 스케줄러 고도화 (1월)
**목표**: 정적 시간표 → 동적 이벤트 기반 수집

**현황**: 
```
현재: cron "00:30 KST" 매일 수집
문제: 시장 급변시 대응 불가, 정보 지연
```

**목표**:
```
개선: 
1. 정규 수집: 매일 00:30 KST (기존)
2. 긴급 수집: 시장 변동성 급증 시 즉시 (Volatility-triggered)
3. 이벤트 수집: 공시 발표 시점 수집 (OpenDART-triggered)
4. 포트폴리오 리밸런싱 시점 + 1시간 이내 수집
```

**추진 과제**:
1. **이벤트 감지 엔진**
   ```csharp
   public interface IMarketEventDetector
   {
       // 변동성 급증: VIX 또는 종목별 일일 등락률 > 5%
       IAsyncEnumerable<VolatilityEvent> DetectVolatilitySpike();
       
       // 공시 발표: OpenDART API
       IAsyncEnumerable<DisclosureEvent> DetectNewDisclosure();
       
       // 리밸런싱: 내부 신호
       IAsyncEnumerable<RebalancingEvent> DetectRebalancingTrigger();
   }
   ```

2. **스케줄링 엔진**
   ```csharp
   public class AdaptiveScheduler
   {
       public async Task ScheduleCollectionAsync(MarketEvent evt)
       {
           // 기존: 매일 00:30
           // 신규: 이벤트별 즉시 or 정해진 시간 후
           
           var delay = evt switch
           {
               VolatilityEvent => TimeSpan.Zero,  // 즉시
               DisclosureEvent => TimeSpan.FromHours(1),  // 1시간 후
               RebalancingEvent => TimeSpan.FromHours(0.5),  // 30분 후
               _ => TimeSpan.FromHours(24)  // 일반: 매일
           };
           
           await _collectionService.QueueAsync(delay);
       }
   }
   ```

3. **Backpressure & Rate Limiting**
   - KIS API 호출량 제한 준수 (초당 10회)
   - 동시 수집 작업 제한 (최대 3개)
   - 폴백 소스 자동 선택

**성과지표**:
- 정보 반영 시간: 매일 정시 → 최대 1시간 이내
- KIS API 호출 효율성: 불필요한 호출 80% 감소
- 시장 기회 포착율 30% 증가

#### P2.3: 의사결정 엔진 (의사결정 투명성) (2월)
**목표**: "왜 이 종목을 선택했는가?" → 완벽한 감시 추적

**추진 과제**:
1. **의사결정 로그 (Decision Log)**
   ```json
   {
     "decision_id": "dec_20260701_001",
     "timestamp": "2026-07-01T00:30:00Z",
     "decision_type": "portfolio_rebalance",
     "rationale": [
       {
         "factor": "sharpe_ratio",
         "value": 1.45,
         "threshold": 1.0,
         "status": "pass",
         "evidence": "stock_005930_sharpe_ratio.json"
       },
       {
         "factor": "game_theoretic_allocation",
         "value": 0.25,
         "computation": "nash_equilibrium_20260701.json",
         "status": "pass"
       }
     ],
     "selected_portfolio": ["005930", "035720", "051910"],
     "weights": [0.40, 0.35, 0.25],
     "expected_return": 0.085,
     "risk_level": "medium",
     "data_quality_score": 0.98,
     "approval_status": "auto_approved"
   }
   ```

2. **재현 가능한 계산**
   ```python
   class ReproducibleDecision:
       def __init__(self, decision_log: Dict):
           self.log = decision_log
       
       def reproduce(self) -> PortfolioAllocation:
           """저장된 로그를 기반으로 동일한 의사결정 재현"""
           data = self._load_data_from_sources(self.log["data_references"])
           allocation = self._compute_nash_equilibrium(data)
           
           assert allocation == self.log["selected_weights"]
           return allocation
   ```

3. **감시 추적 대시보드**
   - 의사결정 이력 조회 (date range, factor, status)
   - 의사결정 재현 (선택한 의사결정 ID 입력 → 동일 과정 재실행)
   - 팩터별 영향도 분석 (이 팩터가 의사결정에 기여한 %?)
   - 백테스트 vs 실적 비교

**성과지표**:
- 의사결정 투명성 100% (모든 이유 기록)
- 감시 추적 가능성 100% (언제든 재현 가능)
- 내부 감시 및 컴플라이언스 자동화

---

## Phase 3: Process Simplification & Patterns (2027-03 ~ 2027-04)
### 목표: 프로세스 단순화 + 표준화 + 패턴화

#### P3.1: 과유불급(YAGNI) 원칙 적용 (3월)
**현황**: 불필요한 기능, 미사용 코드, 과도한 추상화

**추진 과제**:
1. **코드 정리**
   - [x] 사용되지 않는 .NET method 제거
   - [x] 미사용 Python 스크립트 아카이빙
   - [ ] 과도한 추상화 단순화 (3계층 이상의 인터페이스 → 2계층으로)
   - [ ] 설정값 하드코딩 (config file complexity 감소)

2. **테스트 단순화**
   - 현재: 30+ 검증 (ci.yml)
   - 목표: 핵심 15개로 정리 (나머지는 수동 또는 주간 검증으로 이동)

3. **배포 프로세스 단순화**
   - 현재: prepare-release.yml → deploy-prod.yml (2단계)
   - 목표: CI pass → 자동 staging → 수동 1-click deploy to prod

**성과지표**:
- 코드 라인 20% 감소
- CI 시간 추가 10% 단축 (~12-15분)
- 개발자 인지 부담 30% 감소

#### P3.2: 표준 패턴화 + 아키텍처 스타일 가이드 (4월)
**목표**: "언제 어떤 패턴을 쓸까?" 규칙 정립

**추진 과제**:
1. **패턴 카탈로그**
   ```
   [패턴] Repository
   - 언제: DB 접근이 필요할 때
   - 구현: Dapper + raw SQL
   - 예: IQuoteRepository.GetByTickerAsync()
   
   [패턴] Strategy
   - 언제: 런타임에 알고리즘 전환이 필요할 때
   - 구현: interface IDataTransformStrategy
   - 예: KisTransformStrategy, NaverTransformStrategy
   
   [패턴] Factory
   - 언제: 복잡한 객체 생성 로직
   - 구현: IDataSourceFactory
   - 예: CreateKisSource(), CreateNaverFallback()
   
   [패턴] Adapter
   - 언제: 레거시 인터페이스 호환성 필요
   - 구현: LegacySnapshotAdapter wraps IQuoteRepository
   - 예: 기존 SnapshotDto API 유지 while using new DB schema
   ```

2. **아키텍처 결정 기록 (ADR)**
   - adr/0001-razor-pages-over-wasm.md
   - adr/0002-dapper-orm-not-ef.md
   - adr/0003-postgresql-single-source-of-truth.md
   - adr/0004-game-theoretic-portfolio-selection.md

3. **코드 스타일 가이드 (CLAUDE.md 강화)**
   - C#: "3 similar lines → extract method"
   - Python: "3 similar lines → extract function"
   - SQL: "Always use parameterized queries"
   - JSON: "Always validate against schema"

**성과지표**:
- 새 기능 개발 시간 40% 단축 (패턴 재사용)
- 코드 리뷰 시간 30% 단축 (명확한 표준)
- 온보딩 시간 50% 단축 (패턴 이해)

---

## Phase 4: Optimization & Maturity (2027-05 ~ 2027-06)
### 목표: 성능 최적화 + 안정성 입증 + 운영 자동화

#### P4.1: 성능 최적화 (5월)
**목표**: 응답 시간 50% 단축, 데이터 수집 시간 60% 단축

**추진 과제**:
1. **데이터베이스 최적화**
   - 인덱싱: kis_collection_snapshots(ticker, created_at)
   - 쿼리 최적화: N+1 query 문제 제거
   - 연결 풀링: Npgsql pool size 최적화

2. **캐싱 전략**
   ```csharp
   // 단기 캐시: 시장 공휴일, 종목 기본정보 (1주일)
   IMemoryCache.Set("holidays_2026", holidays, TimeSpan.FromDays(7));
   
   // 중기 캐시: 일일 수집 결과 (1주일)
   IDistributedCache.SetAsync("quote_20260701", quote, TimeSpan.FromDays(7));
   
   // 긴기 캐시: 연간 통계 (1년)
   IDistributedCache.SetAsync("annual_stats_2026", stats, TimeSpan.FromDays(365));
   ```

3. **병렬화**
   - KIS API: 최대 10개 종목 동시 요청
   - 데이터 변환: Parallel.ForEach() 사용
   - 검증: 30+ 게이트를 8개 job으로 병렬화 (이미 완료)

**성과지표**:
- API 응답 시간: 500ms → 200ms (60% 단축)
- 수집 시간: 15분 → 6분 (60% 단축)
- DB 쿼리 평균 시간: 50ms → 10ms (80% 단축)

#### P4.2: 안정성 & 신뢰성 (5월)
**목표**: 99.9% 가용성, 데이터 손실 0%

**추진 과제**:
1. **재해 복구 (Disaster Recovery)**
   ```
   RTO (Recovery Time Objective): 1시간 이내
   RPO (Recovery Point Objective): 1시간 이내 (6시간 간격 백업)
   
   절차:
   1. 매 6시간마다 PostgreSQL 풀 백업
   2. 백업: S3 또는 별도 스토리지에 저장
   3. 복구 테스트: 월 1회
   ```

2. **데이터 무결성**
   - Foreign key 제약 활성화
   - Check constraints: bid <= mid <= ask
   - Trigger: 변경 감시 추적 자동 기록

3. **Failover**
   - 단일 PostgreSQL → 이중화 (Primary + Replica)
   - KIS API 실패 → Naver → Yahoo 자동 폴백

**성과지표**:
- 시스템 가용성: 99.9% 달성
- 데이터 손실: 0% (100% 백업)
- RTO/RPO 달성률: 100%

#### P4.3: 운영 자동화 (6월)
**목표**: 수동 운영 작업 80% 자동화

**추진 과제**:
1. **모니터링 & 알림**
   ```
   Alert 1: 수집 실패 → Slack 알림 + 자동 재시도
   Alert 2: 데이터 품질 저하 → 이메일 + 관리자 대시보드
   Alert 3: API 할당량 초과 → 수집 일시 중단 + 폴백 활성화
   Alert 4: DB 연결 풀 고갈 → 자동 스케일링 또는 모니터링
   ```

2. **자동 복구**
   - 수집 실패: 자동 재시도 (지수 백오프)
   - 데이터 이상값: 자동 보정 (또는 폴백 소스 호출)
   - 연결 타임아웃: 자동 재연결

3. **운영 리포트 자동화**
   - 일일 보고: 수집 건수, 오류율, 데이터 품질 스코어
   - 주간 보고: 포트폴리오 성과, 리스크 메트릭
   - 월간 보고: 감사 로그, 컴플라이언스 체크

**성과지표**:
- 수동 운영 시간: 8시간/주 → 1시간/주 (87.5% 자동화)
- 평균 대응 시간: 30분 → 5분 (85% 개선)
- 운영 오류율: 5% → <0.1% (98% 개선)

---

## Timeline Overview

```
Q3 2026 (July-Aug):   Phase 0 ✅ CI/CD + Data Consistency Foundation
Q4 2026 (Sep-Nov):    Phase 1   Data Architecture + Components + Quality Metrics
Q1 2027 (Dec-Feb):    Phase 2   Game Theory + Adaptive Scheduler + Transparency
Q2 2027 (Mar-Apr):    Phase 3   Simplification + Patterns + Standards
Q2 2027 (May-Jun):    Phase 4   Performance + Reliability + Automation
```

---

## Risk Management & Mitigation

| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|-----------|
| Data migration breaks production | Critical | Medium | Parallel run (old + new) for 2 weeks, automatic rollback |
| Performance regression | High | Medium | Before/after benchmarking, rollback triggers |
| KIS API changes | High | Low | Adapter pattern, fallback sources active |
| Team capacity constraints | Medium | High | Prioritize P0 > P1 > P2 (vertical slicing) |
| Schema drift during refactor | Medium | Medium | Automated schema validation in CI |

---

## Success Criteria & Metrics

### By End of Phase 4 (2027-06-30):

**Code Quality**:
- ✅ Technical debt score: < 20% (from current ~60%)
- ✅ Code coverage: > 80% (from current ~60%)
- ✅ Cyclomatic complexity: avg 5 (from current ~12)

**Performance**:
- ✅ API response time: < 200ms (p95)
- ✅ Data collection time: < 6 minutes
- ✅ Database query time: < 10ms (avg)

**Reliability**:
- ✅ System availability: 99.9%
- ✅ Data loss: 0% (100% recovery capability)
- ✅ Manual intervention rate: < 1% (99% automated)

**Quant**:
- ✅ Portfolio Sharpe ratio: +20% improvement
- ✅ Decision transparency: 100% (all decisions logged + reproducible)
- ✅ Information latency: < 1 hour (from 24 hours)

---

## Governance & Approval

**Executive Sponsor**: Project Owner
**Technical Lead**: Claude Code + Team
**Review Cadence**: Bi-weekly (every 2 weeks)
**Go/No-Go Gates**: 
- End of Phase 0 ✅ (Approved)
- End of Phase 1 (September 30, 2026)
- End of Phase 2 (February 28, 2027)
- End of Phase 3 (April 30, 2027)
- End of Phase 4 (June 30, 2027)

---

**Document Version**: 1.0
**Last Updated**: 2026-07-24
**Next Review**: 2026-08-31