QuantEngineByItz/docs/KIS_MIGRATION_PROGRESS.md

KIS Data Collection Migration — 진행 추적

마지막 업데이트: 2026-07-05 14:30 KST
전체 진행률: 📊 [████░░░░░░] 5% (Phase 0/1 시작)

---

📋 Phase별 진행 상황

✅ Phase 0: 기초 설계 & 분석 (100%)

Timeline: 2026-07-05 11:00 ~ 14:30 (3.5시간)

Task	항목	상태	완료시각	검증
0.1	Python 코드 분석	✅	14:00	kis_data_collection_v1.py 436줄 읽음
0.2	.NET 현황 분석	✅	14:05	DataCollectionService.cs 부분 구현 확인
0.3	DB 스키마 분석	✅	14:10	DbMigrator.cs 11개 테이블 확인
0.4	Python 테스트 분석	✅	14:15	test_kis_data_collection_v1.py 데이터 규칙 파악
0.5	마이그레이션 전략	✅	14:20	SOLID 원칙, 과유불급 결정
0.6	WBS 문서 작성	✅	14:30	KIS_DATA_COLLECTION_DOTNET_MIGRATION_WBS.md 생성

Phase 0 산출물:

• ✅ WBS 문서 (22KB, 600+ 줄)
• ✅ 성공 기준 정의 (22개 체크리스트)
• ✅ 개별 Task별 테스트 케이스 명시

---

🔄 Phase 1: 데이터 모델 정의 (0%)

Timeline: 2026-07-05 14:30 ~ (예상 2시간)
계획 완료: 2026-07-05 17:00

1.1: Core Entity Models 작성

파일: src/dotnet/QuantEngine.Core/Models/ 추정 시간: 30분

상태: ⬜ 대기

체크리스트:

• CollectionSnapshot.cs 작성

  • Ticker (string) 필드
  • Name (string?) 필드
  • Sector (string?) 필드
  • CurrentPrice (double?) 필드
  • Open, High, Low, Volume (double?) 필드
  • PriceStatus, OrderbookStatus, ShortSaleStatus (string) 필드
  • CollectionAsOf (string, ISO 8601) 필드
  • [JsonPropertyName] attribute 맵핑
  • Unit test: Round-trip serialization ✅

• PriceCollectionResult.cs 작성

  • Status (string: OK, PARTIAL, ERROR) 필드
  • SuccessCount (int) 필드
  • ErrorCount (int) 필드
  • FinishedAt (string?) 필드
  • ErrorMessage (string?) 필드

• CollectionStatusEnum.cs

  • OK = 0
  • PARTIAL = 1
  • ERROR = 2

검증 명령:

cd src/dotnet
dotnet build QuantEngine.Core
# 0 errors, 0 warnings

테스트 명령:

dotnet test QuantEngine.Core.Tests --filter "CollectionSnapshot*"
# ✅ All tests passed

완료 기준:

• 컴파일 성공 (0 errors, 0 warnings)
• Round-trip JSON serialization 테스트 통과
• Python 테스트 라인 22-26과 동등한 구조

---

1.2: Price Source Result Model

파일: src/dotnet/QuantEngine.Core/Models/PriceSourceResult.cs 추정 시간: 20분

상태: ⬜ 대기

체크리스트:

• 기본 필드 (Python 라인 128-179 참조)

  • Status (string: OK, ERROR)
  • Error (string?)
  • CurrentPrice (double?)
  • Open, High, Low, Volume (double?)
  • Ask1, Bid1 (double?)
  • MicrostructurePressure (double?)
  • ShortTurnoverShare (double?)

• Raw 데이터 필드

  • CurrentPriceRaw (Dictionary?)
  • OrderbookRaw (Dictionary?)
  • ShortSaleRaw (Dictionary?)

• 소스 식별

  • Source (enum: KIS, Naver, JSON)

테스트:

[Theory]
[InlineData("OK")]
[InlineData("ERROR")]
public void PriceSourceResult_WithStatus_SerializesCorrectly(string status)
{
    var result = new PriceSourceResult { Status = status, CurrentPrice = 70000 };
    var json = JsonSerializer.Serialize(result);
    var deserialized = JsonSerializer.Deserialize<PriceSourceResult>(json);
    Assert.Equal(status, deserialized.Status);
}

---

1.3: Collection Error Model (검증)

파일: src/dotnet/QuantEngine.Infrastructure/Repositories/CollectionErrorRecord.cs (이미 있음) 추정 시간: 10분

상태: ✅ 검증 완료

확인사항:

• Python test 라인 75-83과 일치
• DB 스키마와 일치
• JSON 직렬화 가능

---

1.4: Collection Run Summary Model (기존 검증)

파일: src/dotnet/QuantEngine.Application/Services/CollectionRunResult.cs 추정 시간: 10분

상태: 🔄 검증 진행 중

확인사항:

• Python 라인 387-396 summary 구조 모두 포함 확인
• JSON 직렬화 테스트
• SourceCounts 필드 타입 확인 (Dictionary<string, int>)

---

🚫 Phase 2: Price Source 추상화 (대기)

Timeline: 2026-07-06 09:00 ~ (예상 4시간)
계획 완료: 2026-07-06 13:00

상태: ⬜ 대기 (Phase 1 완료 후 시작)

Task	예상 시간	상태
2.1: IPriceSource 인터페이스	20분	⬜
2.2: KisApiPriceSource 구현	150분	⬜
2.3: NaverApiPriceSource (선택)	100분	⏸️

---

🚫 Phase 3: 데이터 정규화 레이어 (대기)

Timeline: 2026-07-06 13:00 ~ (예상 3시간)
계획 완료: 2026-07-06 17:00

상태: ⬜ 대기

Task	예상 시간	상태
3.1: DataNormalizationHelper	40분	⬜
3.2: PriceDataNormalizer	100분	⬜
3.3: SourcePriorityResolver	40분	⬜

---

🚫 Phase 4: 컬렉션 오케스트레이터 (대기)

Timeline: 2026-07-07 09:00 ~ (예상 4시간)
계획 완료: 2026-07-07 14:00

상태: ⬜ 대기

Task	예상 시간	상태
4.1: ICollectionOrchestrator	30분	⬜
4.2: KisDataCollectionOrchestrator	210분	⬜

---

🚫 Phase 5: 시드 데이터 파서 (대기)

Timeline: 2026-07-06 18:00 ~ (예상 1시간)

상태: ⬜ 대기

Task	예상 시간	상태
5.1: GatherTradingDataParser	60분	⬜

---

🚫 Phase 6: 통합 & 엔드포인트 (대기)

Timeline: 2026-07-07 14:00 ~ (예상 2시간)

상태: ⬜ 대기

Task	예상 시간	상태
6.1: DataCollectionService 리팩토링	90분	⬜
6.2: API 엔드포인트 (선택)	60분	⏸️

---

🚫 Phase 7: 테스트 & 검증 (대기)

Timeline: 2026-07-07 16:00 ~ (예상 4시간)

상태: ⬜ 대기

Task	예상 시간	상태
7.1: Unit Tests	120분	⬜
7.2: Integration Tests	90분	⬜
7.3: E2E Tests	60분	⬜

---

🚫 Phase 8: 코드 리뷰 & 최종화 (대기)

Timeline: 2026-07-08 09:00 ~ (예상 3시간)

상태: ⬜ 대기

Task	예상 시간	상태
8.1: Code Review & Refactoring	120분	⬜
8.2: 최종 검증 & 문서화	60분	⬜

---

📊 통계

시간 추정

총 예상 시간: ~24시간 (8일, 하루 3시간 기준)

Phase별:
  Phase 0: 3.5시간 ✅
  Phase 1: 1.3시간
  Phase 2: 4.3시간
  Phase 3: 3.2시간
  Phase 4: 4시간
  Phase 5: 1시간
  Phase 6: 2.5시간
  Phase 7: 4.3시간
  Phase 8: 3시간

코드 라인 예상

Python 원본: 436줄
C# 포팅 예상: 450-550줄 (타입 추가)
  - Models: 150줄
  - Interfaces: 50줄
  - Implementations: 250줄
  - Tests: 300줄

테스트 커버리지 목표

목표: ≥85% 라인 커버리지

현재: 0% (신규 작성)
최종: 85%+ (전체 신규 코드)

---

🔍 이슈 & 블록

현재 이슈: 없음

블록 사항: 없음

결정 대기: 없음

---

🎯 다음 단계

지금 해야 할 일 (2026-07-05 현재)

1. Phase 1.1 시작 — CollectionSnapshot 모델 작성

   • 파일 생성: QuantEngine.Core/Models/CollectionSnapshot.cs
   • 필드 정의 (ticker, name, sector, prices, statuses)
   • JSON serialization 속성 추가
   • 기본 테스트 작성

2. 검증

   • dotnet build QuantEngine.Core 성공
   • 기본 테스트 통과

3. 커밋

   git add src/dotnet/QuantEngine.Core/Models/CollectionSnapshot.cs
   git commit -m "1.1: Add CollectionSnapshot model — JSON round-trip ✅"
   

---

📝 커밋 히스토리

오늘 (2026-07-05)

14:30 0.6: Create comprehensive WBS — 22 phases, 85+ test cases ✅

예정 (2026-07-05~09)

// Phase 1
17:00 1.1: Add CollectionSnapshot model — Round-trip JSON ✅
17:30 1.2: Add PriceSourceResult model — Serialization ✅
18:00 1.4: Validate CollectionRunResult — Structure check ✅

// Phase 2
13:00 2.1: Add IPriceSource interface — Contract ✅
15:30 2.2: Implement KisApiPriceSource — Python parity ✅

// Phase 3
18:00 3.1: Extract DataNormalizationHelper — Utilities ✅
19:30 3.2: Implement PriceDataNormalizer — Field mapping ✅
20:30 3.3: Implement SourcePriorityResolver — Source ranking ✅

// Phase 4
14:00 4.1: Add ICollectionOrchestrator interface — Pipeline contract ✅
16:30 4.2: Implement KisDataCollectionOrchestrator — Main pipeline ✅

// Phase 5
19:00 5.1: Implement GatherTradingDataParser — JSON parsing ✅

// Phase 6
14:00 6.1: Refactor DataCollectionService — Integration ✅

// Phase 7
16:00 7.1: Add unit tests — 85% coverage ✅
18:30 7.2: Add integration tests — E2E flow ✅
20:00 7.3: Add E2E tests — HTTP verification ✅

// Phase 8
12:00 8.1: Code review & refactoring — SOLID check ✅
14:00 8.2: Final validation & docs — Documentation ✅

---

📚 참고 문서

• WBS: docs/KIS_DATA_COLLECTION_DOTNET_MIGRATION_WBS.md (이 프로젝트의 마스터 로드맵)
• Python 원본: src/quant_engine/kis_data_collection_v1.py (436줄)
• Python 테스트: tests/unit/test_kis_data_collection_v1.py (87줄)
• .NET 기존: src/dotnet/QuantEngine.Application/Services/DataCollectionService.cs

---

🔗 관련 파일 링크

프로젝트 구조:
├── src/dotnet/
│   ├── QuantEngine.Core/
│   │   ├── Models/ (← 신규 모델들 추가)
│   │   └── Interfaces/ (← 신규 인터페이스 추가)
│   ├── QuantEngine.Application/
│   │   └── Services/ (← 신규 서비스 구현)
│   ├── QuantEngine.Infrastructure/
│   │   └── Repositories/ (← 기존 repository 활용)
│   └── QuantEngine.Web/
│       └── Endpoints/ (← 기존 엔드포인트 확장)
├── tests/
│   └── unit/ (← 신규 테스트 추가)
└── docs/
    └── KIS_DATA_COLLECTION_DOTNET_MIGRATION_WBS.md