QuantEngineByItz/docs/archive/MODERNIZATION_STRATEGY_ROADMAP_2026-2027.md

ARCHIVED (2026-07-30): 본 문서의 Phase 0-3 전략은 2026-07-24 기준이며, 최신 버전으로 대체되었습니다.
현재 마이그레이션 상태는 ../CLAUDE.md Migration Status 또는
STRATEGIC_EXECUTION_MASTER_PLAN.md를 참고하세요.

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)

• ci.yml 리팩토링: 1 job → 9 parallel jobs
• 성능: ~40min → ~15-20min (2.5배 가속)
• 워크플로우 검증 자동화
• 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 리팩토링

   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

   // 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 분리

   Current (단일 ICollectionRepository):
   - GetSnapshots()
   - GetRuns()
   - GetErrors()
   - SaveSnapshot()
   
   Target (SOLID ISP):
   - IQuoteRepository: 가격/호가 데이터
   - IRunRepository: 수집 메타데이터
   - IErrorRepository: 오류 로그
   - IFundamentalRepository: 기본정보
   

2. 팩토리 패턴 도입

   public interface IDataSourceFactory
   {
       IDataSource CreateKisSource();
       IDataSource CreateNaverFallback();
       IDataSource CreateYahooFallback();
   }
   
   // 주입: 런타임에 데이터 소스 전환 가능
   

3. 전략 패턴: 데이터 변환

   public interface IDataTransformStrategy
   {
       SnapshotDto Transform(RawApiResponse response);
   }
   
   // 구현: Kis변환, Naver변환, Yahoo변환 등
   // 각 소스별 정규화 로직 캡슐화
   

성과지표:

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

P1.3: 데이터 팩터 고도화 (11월)

목표: 데이터 품질 + 이상 탐지 자동화

추진 과제:

1. Data Quality Metrics

   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. 알고리즘

   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. 구현 체크리스트

   • 기본 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. 이벤트 감지 엔진

   public interface IMarketEventDetector
   {
       // 변동성 급증: VIX 또는 종목별 일일 등락률 > 5%
       IAsyncEnumerable<VolatilityEvent> DetectVolatilitySpike();
   
       // 공시 발표: OpenDART API
       IAsyncEnumerable<DisclosureEvent> DetectNewDisclosure();
   
       // 리밸런싱: 내부 신호
       IAsyncEnumerable<RebalancingEvent> DetectRebalancingTrigger();
   }
   

2. 스케줄링 엔진

   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)

   {
     "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. 재현 가능한 계산

   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. 코드 정리

   • 사용되지 않는 .NET method 제거
   • 미사용 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. 캐싱 전략

   // 단기 캐시: 시장 공휴일, 종목 기본정보 (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