QuantEngineByItz/docs/KIS_DATA_COLLECTION_DOTNET_MIGRATION_WBS.md

KIS Data Collection Python→.NET Migration WBS

프로젝트: Python kis_data_collection_v1.py → C# QuantEngine.Application 포팅 + 코드 품질 개선
시작: 2026-07-05
목표: 완전한 기능 호환성 + SOLID + 정규화 + 테스트 커버리지
성공 기준: Python 테스트와 동등 검증 + 코드 리뷰 승인

---

📋 전체 작업 분해 (WBS)

Phase 0: 기초 설계 & 분석 ✅ (현재 진행 중)

• 0.1: Python 코드 분석 (kis_data_collection_v1.py 436줄 읽음)
• 0.2: .NET 현황 분석 (DataCollectionService.cs 부분 구현)
• 0.3: DB 스키마 분석 (DbMigrator.cs 11개 테이블)
• 0.4: Python 테스트 분석 (test_kis_data_collection_v1.py 데이터 규칙)
• 0.5: 마이그레이션 전략 수립 (과유불급 SOLID)
• 0.6: 이 WBS 문서 작성 및 검증 ← 현재

---

Phase 1: 데이터 모델 정의 (4 tasks)

1.1: Core Entity Models 작성

책임: QuantEngine.Core/Models/ 에 도메인 모델 정의
입출력:

• 입력: Python kis_data_collection_v1.py 라인 330-359 (_collect_one 반환값)
• 출력: C# 타입 정의 완료
• 파일:
  • CollectionSnapshot.cs (정규화된 스냅샷)
  • PriceCollectionResult.cs (수집 결과)
  • CollectionStatusEnum.cs (OK, PARTIAL, ERROR)

성공 규칙 (데이터 증빙):

✅ 체크리스트:
  1. CollectionSnapshot에 Python _collect_one() 반환값의 모든 필드 포함
     - ticker, name, sector, current_price, open, high, low, volume
     - price_status, orderbook_status, short_sale_status
     - collection_as_of (ISO 8601 KST)
  2. 타입 안전성
     - nullable fields는 `?` 명시 (price: double?, status: string)
  3. Serialization 지원
     - [JsonPropertyName] attribute로 Python 필드명 맵핑
  4. 테스트 가능성
     - 기본 생성자, 공개 속성

완료 기준:

// 컴파일 성공, 타입 일관성, 스키마와 1:1 매핑
[Theory]
[InlineData("005930", "삼성전자", "반도체")]
public void CollectionSnapshot_SerializeDeserialize_RoundTrips(string ticker, string name, string sector)
{
    var snapshot = new CollectionSnapshot 
    { 
        Ticker = ticker, 
        Name = name, 
        Sector = sector,
        CurrentPrice = 70000.5,
        PriceStatus = "OK"
    };
    var json = JsonSerializer.Serialize(snapshot);
    var deserialized = JsonSerializer.Deserialize<CollectionSnapshot>(json);
    Assert.Equal(ticker, deserialized.Ticker);
    Assert.Equal(70000.5, deserialized.CurrentPrice);
}

---

1.2: Price Source Result Model

책임: 모든 price source의 통일된 응답 표현
입출력:

• 입력: Python 라인 128-179 (_normalize_kis_fields 반환값)
• 출력: C# PriceSourceResult 클래스

성공 규칙:

✅ 체크리스트:
  1. KIS API 응답 필드 포함
     - current_price, open, high, low, volume
     - ask_1, bid_1, microstructure_pressure
     - short_turnover_share
  2. Status 추적
     - PriceStatus (OK, ERROR)
     - OrderbookStatus (OK, ERROR)
     - ShortSaleStatus (OK, ERROR)
  3. Raw 데이터 보존
     - current_price_raw, orderbook_raw, short_sale_raw (Dictionary)
  4. 소스 식별
     - source: enum (KIS, Naver, JSON)

완료 기준:

// Python _normalize_kis_fields() 결과와 동등한 C# 객체
var pythonResult = {
    "status": "OK",
    "current_price": 70000,
    "ask_1": 70100,
    "bid_1": 69900
};
var csharpResult = new PriceSourceResult 
{ 
    Status = "OK", 
    CurrentPrice = 70000, 
    Ask1 = 70100, 
    Bid1 = 69900 
};
// JSON 직렬화 동일

---

1.3: Collection Error Model

책임: 에러 추적 구조화
파일: CollectionErrorRecord.cs (이미 Infrastructure에 있음 — 검증만)

성공 규칙:

✅ 체크리스트:
  1. Python test_kis_data_collection_v1.py 라인 75-83 검증
     - ticker, error 필드
  2. 데이터베이스 스키마 (DbMigrator.cs 라인 94-106) 매핑
     - run_id, ticker, source_name, error_kind, error_message

---

1.4: Collection Run Summary Model

책임: 수집 실행 종합 결과
파일: CollectionRunResult.cs (DataCollectionService.cs 라인 24-101 기존 코드)

성공 규칙:

✅ 체크리스트:
  1. Python kis_data_collection_v1.py 라인 387-396 summary 구조 맵핑
  2. JSON 직렬화 (Temp/kis_data_collection_v1.json 출력)
     - formula_id, run_id, started_at, finished_at
     - row_count, source_counts, errors, rows
  3. 타입 안전성
     - source_counts: Dictionary<string, int> 또는 SortedDictionary

완료 기준:

{
  "formula_id": "KIS_DATA_COLLECTION_V1",
  "run_id": "abc123def456",
  "started_at": "2026-07-05T14:18:00+09:00",
  "finished_at": "2026-07-05T14:19:00+09:00",
  "row_count": 100,
  "source_counts": { "kis_open_api": 95, "gathertradingdata_json": 5 },
  "errors": [],
  "rows": [
    {
      "ticker": "005930",
      "name": "삼성전자",
      "sector": "반도체",
      "source_priority": "kis_open_api",
      "current_price": 70000
    }
  ]
}

---

Phase 2: Price Source 추상화 (SOLID I, S) (3 tasks)

2.1: IPriceSource 인터페이스 정의

책임: 모든 price source의 계약 정의
파일: QuantEngine.Core/Interfaces/IPriceSource.cs

성공 규칙:

✅ 체크리스트:
  1. 메서드 서명
     Task<PriceSourceResult> GetPriceDataAsync(string ticker, string account);
     - ticker: 6자리 숫자
     - account: "real" | "mock"
     - 반환: PriceSourceResult (status OK/ERROR 포함)
  2. Liskov Substitution
     - 모든 구현이 같은 계약 준수
  3. 에러 처리
     - 네트워크 에러, 타임아웃, 데이터 파싱 에러를 처리하고 status="ERROR" 반환

완료 기준:

public interface IPriceSource
{
    string SourceName { get; }
    Task<PriceSourceResult> GetPriceDataAsync(string ticker, string account);
}

// 모든 구현이 이 계약을 따름
public class KisApiPriceSource : IPriceSource
{
    public string SourceName => "kis_open_api";
    public async Task<PriceSourceResult> GetPriceDataAsync(string ticker, string account)
    {
        try { /* ... */ }
        catch (Exception ex)
        {
            return new PriceSourceResult { Status = "ERROR", Error = ex.Message };
        }
    }
}

---

2.2: KisApiPriceSource 구현

책임: Python _normalize_kis_fields() (라인 128-179) 포팅
파일: QuantEngine.Application/Services/KisApiPriceSource.cs

입출력:

• 입력:
  • Python _normalize_kis_fields(code, account) 함수
  • IKisApiClient (이미 있음)
• 출력:
  • C# KisApiPriceSource 클래스 (≈120줄)

성공 규칙 (데이터 증빙):

✅ 체크리스트:
  1. 기능 동등성
     - Python 라인 137-147: 가격 조회 → C# GetCurrentPriceAsync()
     - Python 라인 151-163: 호가 조회 → C# GetAskingPrice10LevelAsync()
     - Python 라인 165-177: 공매도 조회 → C# GetDailyShortSaleAsync()
  2. 데이터 정규화
     - CoerceFloat() 유틸로 문자열→float 변환
     - FindFirstValue() 유틸로 필드 탐색 (다중 경로 fallback)
  3. 에러 처리
     - 각 API 호출 별도 try-catch
     - status: "OK", "ERROR" 반환
  4. 타입 안전성
     - Dictionary<string, object> 대신 PriceSourceResult 반환
  5. 테스트 동등성
     - Python test_kis_data_collection_v1.py 라인 44-62 테스트와 동등

완료 기준:

[Fact]
public async Task GetPriceDataAsync_WithValidKisCredentials_ReturnsPriceSourceResult()
{
    // Python 테스트와 동등: _normalize_kis_fields() 반환값 검증
    var result = await _kisSource.GetPriceDataAsync("005930", "mock");
    
    Assert.Equal("OK", result.Status);
    Assert.NotNull(result.CurrentPrice);
    Assert.NotNull(result.Ask1);
    Assert.NotNull(result.Bid1);
    
    // JSON 직렬화 가능 (역정규화)
    var json = JsonSerializer.Serialize(result);
    Assert.NotEmpty(json);
}

---

2.3: NaverApiPriceSource 구현 (선택사항)

책임: Python _normalize_naver_price_history() (라인 102-125) 포팅 (선택)
우선순위: 낮음 (KIS만으로 충분 → 필요시 추가)

체크: 일단 스킵, 필요시 Phase 4에 추가

---

Phase 3: 데이터 정규화 레이어 (3 tasks)

3.1: DataNormalizationHelper 추출

책임: Python 유틸 함수 (라인 76-99) → C# 정적 메서드로 추출
파일: QuantEngine.Application/Services/DataNormalizationHelper.cs

성공 규칙:

✅ 체크리스트:
  1. CoerceFloat() — Python 라인 76-84
     - null, "" → null 반환
     - "1,234.56%" → 1234.56 변환
     - 예외 → null 반환
  2. FindFirstValue() — Python 라인 87-99
     - 재귀적 탐색 (dict/list 모두 지원)
     - 첫 non-null 값 반환
  3. 테스트 데이터
     - Python test 라인 111 (CoerceFloat("1,234.5") == 1234.5)

완료 기준:

[Theory]
[InlineData("1,234.56", 1234.56)]
[InlineData("1,234.56%", 1234.56)]
[InlineData(null, null)]
[InlineData("", null)]
public void CoerceFloat_WithVariousFormats_ParsesCorrectly(string? input, double? expected)
{
    var result = DataNormalizationHelper.CoerceFloat(input);
    Assert.Equal(expected, result);
}

---

3.2: PriceDataNormalizer 구현

책임: Python _collect_one() (라인 330-359) 로직 → C# 메서드
파일: QuantEngine.Application/Services/PriceDataNormalizer.cs

성공 규칙:

✅ 체크리스트:
  1. 입력 (Python 라인 331-340)
     - row: 시드 데이터 한 행 (Ticker, Name, Sector)
     - kis: KIS API 결과 (또는 null)
     - naver: Naver API 결과 (또는 null)
  2. 출력
     - normalized: 정규화된 Dictionary
     - provenance: 소스 추적 정보
  3. 소스 우선순위 (Python 라인 342-354)
     - KIS status=="OK" 있으면 kis_open_api 1순위
     - Naver 있으면 naver_finance 추가
     - 기본은 gathertradingdata_json
  4. 데이터 폴백 (Python 라인 355)
     - 소스에서 누락된 필드는 row 데이터로 폴백

완료 기준:

[Fact]
public async Task NormalizeCollectionRow_WithKisAndNaver_ReturnsNormalizedData()
{
    // Python test 라인 44-62 동등
    var row = new { Ticker = "005930", Name = "삼성전자", Sector = "반도체" };
    var kis = new PriceSourceResult { Status = "OK", CurrentPrice = 70000 };
    var naver = new PriceSourceResult { Status = "OK", CurrentPrice = 65000 };
    
    var (normalized, provenance) = _normalizer.NormalizeCollectionRow(row, kis, naver);
    
    Assert.Equal(70000, normalized["current_price"]); // KIS 우선
    Assert.Equal(new[] { "kis_open_api", "naver_finance" }, provenance["source_priority"]);
}

---

3.3: SourcePriorityResolver 구현

책임: 소스별 우선순위 결정 (Python 라인 208-229 _resolve_price_source)
파일: QuantEngine.Application/Services/SourcePriorityResolver.cs

성공 규칙:

✅ 체크리스트:
  1. 입력
     - ticker: 식별자
     - kis, naver: 각 소스 결과
     - includeLiveKis, includeNaver: 플래그
  2. 출력
     - source_priority: List<string> (정렬된)
  3. 로직 (Python 라인 219-227)
     - KIS status=="OK" → kis_open_api 1순위
     - Naver status=="OK" or "DATA_MISSING" → naver_finance 추가
  4. 테스트 동등성
     - Python test 라인 44-62

---

Phase 4: 컬렉션 오케스트레이터 (SOLID O, D) (2 tasks)

4.1: ICollectionOrchestrator 인터페이스

책임: 메인 파이프라인의 계약
파일: QuantEngine.Core/Interfaces/ICollectionOrchestrator.cs

성공 규칙:

✅ 체크리스트:
  1. 메서드
     Task<CollectionRunResult> RunCollectionAsync(
         string runId, 
         string account, 
         List<string> tickers)
  2. 의존성 주입 가능 (테스트 목 용이)
  3. 에러 처리
     - 개별 종목 에러 → 계속 진행 (robust)
     - 치명적 에러 → 실패 상태로 마무리

---

4.2: KisDataCollectionOrchestrator 구현

책임: Python collect_to_sqlite() (라인 361-436) 포팅
파일: QuantEngine.Application/Services/KisDataCollectionOrchestrator.cs

입출력:

• 입력:
  • runId, account, tickers
  • GatherTradingData.json (시드 데이터)
• 출력:
  • CollectionRunResult
  • Temp/kis_data_collection_v1.json (JSON 파일)
  • DB 저장 (kis_collection_runs, kis_collection_snapshots, kis_collection_errors)

성공 규칙 (데이터 증빙):

✅ 체크리스트:
  1. 시드 데이터 로드 (Python 라인 182-199)
     - GatherTradingData.json 파싱
     - data.data_feed[] 배열
     - core_satellite merge
  2. 종목별 수집 루프 (Python 라인 399-435)
     - 각 종목마다 PriceSourceResult 수집
     - 정규화 및 저장
     - 에러 추적
  3. 결과 요약 (Python 라인 303-327)
     - started_at, finished_at (KST)
     - source_counts 집계
     - 상태: PASS / PASS_WITH_WARNINGS / FAIL
  4. JSON 출력 (Python 라인 309-312)
     - Temp/kis_data_collection_v1.json 생성
     - UTF-8, indent=2
  5. DB 저장 (Python 라인 313-326)
     - collection_runs 테이블
     - collection_snapshots 테이블
     - collection_source_errors 테이블
  6. 테스트 동등성
     - Python test_kis_data_collection_v1.py 라인 39-83 (모든 케이스)

완료 기준:

[Fact]
public async Task RunCollectionAsync_WithValidSeedAndKisAccount_ReturnsSuccessAndCreatesJson()
{
    // Python test 라인 39-83 동등
    var result = await _orchestrator.RunCollectionAsync(
        runId: "test-run-123",
        account: "mock",
        tickers: new[] { "005930", "000660" }.ToList()
    );
    
    // 1. 결과 검증
    Assert.Equal("COMPLETED", result.Status);
    Assert.True(result.SuccessCount > 0);
    
    // 2. JSON 파일 생성 확인
    var jsonPath = Path.Combine(Path.GetTempPath(), "kis_data_collection_v1.json");
    Assert.True(File.Exists(jsonPath));
    var json = JsonDocument.Parse(File.ReadAllText(jsonPath));
    Assert.Equal("KIS_DATA_COLLECTION_V1", json.RootElement.GetProperty("formula_id").GetString());
    
    // 3. DB 저장 확인
    var runs = await _repository.GetRunsByIdAsync("test-run-123");
    Assert.Single(runs);
}

---

Phase 5: 시드 데이터 파서 (1 task)

5.1: GatherTradingDataParser 구현

책임: Python _build_seed_rows() (라인 182-199) 포팅
파일: QuantEngine.Application/Services/GatherTradingDataParser.cs

성공 규칙:

✅ 체크리스트:
  1. 입력 형식
     {
       "data": {
         "data_feed": [ { "Ticker": "005930", "Name": "삼성전자", ... } ],
         "core_satellite": [ { "Ticker": "005930", "Sector": "반도체" } ]
       }
     }
  2. 병합 로직 (Python 라인 185-197)
     - data_feed와 core_satellite를 Ticker로 병합
     - core_satellite 필드를 data_feed 행에 추가
  3. 검증
     - Ticker 필수 (비어있으면 스킵)
     - Name, Sector는 선택
  4. 테스트 동등성
     - Python test 라인 39-42 (_build_seed_rows)

완료 기준:

[Fact]
public void ParseGatherTradingData_WithCoreAndSatellite_MergesCorrectly()
{
    // Python test 라인 39-42 동등
    var json = JsonDocument.Parse(@"
    {
      ""data"": {
        ""data_feed"": [{ ""Ticker"": ""005930"", ""Name"": ""삼성전자"" }],
        ""core_satellite"": [{ ""Ticker"": ""005930"", ""Sector"": ""반도체"" }]
      }
    }");
    
    var rows = _parser.ParseGatherTradingData(json);
    
    Assert.Single(rows);
    Assert.Equal("005930", rows[0]["Ticker"]);
    Assert.Equal("삼성전자", rows[0]["Name"]);
    Assert.Equal("반도체", rows[0]["Sector"]);
}

---

Phase 6: 통합 & 엔드포인트 (2 tasks)

6.1: DataCollectionService 통합 리팩토링

책임: 기존 DataCollectionService.cs 개선 (라인 1-230)
파일: QuantEngine.Application/Services/DataCollectionService.cs

개선 사항:

✅ 체크리스트:
  1. 의존성 주입
     - ICollectionOrchestrator 추가
     - IPriceSource[] 제거 (Orchestrator가 관리)
  2. 메서드 분리
     - RunCollectionAsync() → 직접 구현 X, Orchestrator 위임
     - CollectOneAsync() → 유틸만 (테스트용)
  3. 에러 처리 구조화
     - Generic Exception → PriceCollectionException, DataValidationException
  4. 로깅
     - ILogger<DataCollectionService> 주입

완료 기준:

public class DataCollectionService
{
    private readonly ICollectionOrchestrator _orchestrator;
    private readonly ILogger<DataCollectionService> _logger;
    
    public async Task<CollectionRunResult> RunCollectionAsync(
        string runId, 
        string account, 
        List<string> tickers)
    {
        _logger.LogInformation("Starting collection run {RunId}", runId);
        try
        {
            return await _orchestrator.RunCollectionAsync(runId, account, tickers);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Collection run {RunId} failed", runId);
            throw;
        }
    }
}

---

6.2: API 엔드포인트 추가 (선택)

책임: HTTP 엔드포인트 (POST /api/collection/run)
파일: QuantEngine.Web/Endpoints/CollectionEndpoints.cs (이미 있음 — 확장)

성공 규칙:

✅ 체크리스트:
  1. 요청
     POST /api/collection/run
     {
       "account": "mock",
       "tickers": ["005930", "000660"]
     }
  2. 응답
     {
       "runId": "...",
       "status": "COMPLETED",
       "successCount": 2,
       "errorCount": 0,
       "startedAt": "2026-07-05T14:18:00+09:00"
     }
  3. 에러 처리
     - 400: 잘못된 account
     - 500: 내부 에러

---

Phase 7: 테스트 & 검증 (3 tasks)

7.1: Unit Tests (DataNormalizationHelper, Parsers)

파일: QuantEngine.Application.Tests/Services/DataNormalizationHelperTests.cs
범위: 300-400줄 (Python test 동등성)

성공 규칙:

✅ 체크리스트:
  1. DataNormalizationHelper
     - CoerceFloat (10 test cases)
     - FindFirstValue (8 test cases)
  2. GatherTradingDataParser
     - Basic parsing (3 cases)
     - Core-satellite merge (2 cases)
     - Invalid input (2 cases)
  3. SourcePriorityResolver
     - KIS only (1 case)
     - KIS + Naver (1 case)
     - Naver only (1 case)
  4. PriceDataNormalizer
     - With KIS (1 case)
     - With Naver (1 case)
     - Fallback to JSON (1 case)
  5. 커버리지
     - 목표: ≥85% 라인 커버리지
     - 신규 클래스: 100% 커버리지

완료 기준:

dotnet test QuantEngine.Application.Tests --collect:"XPlat Code Coverage"
# 결과: Lines: 85%+ ✅

---

7.2: Integration Tests (KisDataCollectionOrchestrator)

파일: QuantEngine.Application.Tests/Integration/KisDataCollectionOrchestratorTests.cs
범위: 200-300줄

성공 규칙 (데이터 증빙):

✅ 체크리스트:
  1. Happy Path
     - Mock KIS API + valid GatherTradingData.json
     - status = "COMPLETED", successCount > 0
  2. Partial Failure
     - 1개 종목 에러, 나머지 성공
     - status = "COMPLETED_WITH_ERRORS"
  3. JSON Output
     - Temp/kis_data_collection_v1.json 생성
     - 구조 검증 (formula_id, run_id, rows 배열)
  4. DB Persistence
     - kis_collection_runs 행 생성
     - kis_collection_snapshots 행 수 = successCount
     - kis_collection_source_errors 행 수 = errorCount
  5. Python 동등성
     - kis_data_collection_v1.py test와 동일 시나리오 재현

완료 기준:

[Fact]
public async Task KisDataCollectionOrchestrator_RunCollection_ProducesIdenticalOutputToPython()
{
    // Python test test_kis_data_collection_v1.py::test_persist_collection_row_and_failure_helpers
    // C# 동등 재현
    
    var result = await _orchestrator.RunCollectionAsync("run-1", "mock", new { "005930" }.ToList());
    
    // 1. 상태 확인
    Assert.NotNull(result.Status);
    Assert.True(result.SuccessCount >= 0);
    
    // 2. JSON 파일 확인
    var json = JsonDocument.Parse(File.ReadAllText(...));
    Assert.NotNull(json.RootElement.GetProperty("run_id"));
    
    // 3. DB 확인
    var run = await _repo.GetRunByIdAsync(result.RunId);
    Assert.NotNull(run);
    Assert.Equal("COMPLETED", run.Status);
}

---

7.3: E2E Test (API → DB → UI)

파일: QuantEngine.Web.Tests/E2E/CollectionEndpointTests.cs
범위: 100-150줄

성공 규칙:

✅ 체크리스트:
  1. HTTP 요청
     POST /api/collection/run
     { "account": "mock", "tickers": ["005930"] }
  2. HTTP 응답
     status 200, body.status == "COMPLETED"
  3. 부수 효과
     - Temp/kis_data_collection_v1.json 파일 생성
     - kis_collection_runs DB 행 생성
     - kis_collection_snapshots DB 행 생성
  4. 타이밍
     - 응답 시간 < 30초 (3개 API 호출)

---

Phase 8: 코드 리뷰 & 최종화 (2 tasks)

8.1: Code Review & Refactoring

책임: 스스로 코드 검토, SOLID 원칙 재확인
체크리스트:

✅ 코드 품질 검사:
  1. SOLID 원칙
     - S: DataCollectionService 단일 책임 ✓
     - O: IPriceSource로 확장 가능 ✓
     - L: 모든 구현이 계약 준수 ✓
     - I: 필요한 메서드만 expose ✓
     - D: 인터페이스에 의존 ✓
  2. 중복 제거
     - 유틸 함수 (CoerceFloat, FindFirstValue) 1곳만
     - 에러 처리 패턴 일관성
  3. 타입 안전성
     - Dictionary<string, object> → Model classes로 변환
     - Nullable 필드 명시 (?)
  4. 성능
     - 불필요한 배열 copy 제거
     - 큰 JSON 파일 스트리밍 (필요시)
  5. 테스트 가능성
     - 모든 의존성 주입 가능
     - Mock 가능
  6. 문서화
     - XML doc comments 추가 (public API)

완료 기준:

# 정적 분석
dotnet build /p:TreatWarningsAsErrors=true
# 0 errors, 0 warnings

# 테스트 커버리지
dotnet test --collect:"XPlat Code Coverage"
# Lines: ≥85%

# 코드 리뷰 체크리스트 통과
# - 변수명 명확성 ✓
# - 함수/메서드 크기 ≤50줄 ✓
# - 복잡도 <= 10 ✓

---

8.2: 최종 검증 & 문서화

책임: 모든 성공 기준 재확인, 문서 작성
체크리스트:

✅ 최종 검증:
  1. 기능 완성도
     - Python 336줄 → C# ≈450-550줄 (타입 추가로 인한 증가)
     - 모든 Python 기능 포팅 ✓
  2. 성능
     - 단일 종목 수집: < 2초
     - 100개 종목 수집: < 120초
  3. 호환성
     - GatherTradingData.json 읽음 ✓
     - kis_collection_runs/snapshots/errors 저장 ✓
     - Temp/kis_data_collection_v1.json 생성 ✓
  4. 안정성
     - 네트워크 에러 처리 ✓
     - NULL 값 처리 ✓
     - 부분 실패 시에도 진행 ✓
  5. 문서
     - README 작성 (아키텍처, 사용법, 확장 방법)
     - API 문서 (Swagger/OpenAPI)

출력물:

- ✅ docs/KIS_DATA_COLLECTION_ARCHITECTURE.md
- ✅ docs/KIS_DATA_COLLECTION_API.md
- ✅ CODE_REVIEW_CHECKLIST.md

---

📊 진행 상황 추적

Phase	Task	상태	완료 기한	담당
0	기초 설계 분석	✅	2026-07-05	Claude
1.1	Core Entity Models	⬜	2026-07-05	→
1.2	PriceSourceResult	⬜	2026-07-05	→
1.3	CollectionErrorRecord	✅	2026-07-05	✓
1.4	CollectionRunResult	🔄	2026-07-05	Claude
2.1	IPriceSource 인터페이스	⬜	2026-07-05	→
2.2	KisApiPriceSource	⬜	2026-07-06	→
2.3	NaverApiPriceSource	⏸️	2026-07-07	(선택)
3.1	DataNormalizationHelper	⬜	2026-07-05	→
3.2	PriceDataNormalizer	⬜	2026-07-06	→
3.3	SourcePriorityResolver	⬜	2026-07-06	→
4.1	ICollectionOrchestrator	⬜	2026-07-06	→
4.2	KisDataCollectionOrchestrator	⬜	2026-07-07	→
5.1	GatherTradingDataParser	⬜	2026-07-06	→
6.1	DataCollectionService 통합	⬜	2026-07-07	→
6.2	API 엔드포인트 (선택)	⏸️	2026-07-08	(선택)
7.1	Unit Tests	⬜	2026-07-07	→
7.2	Integration Tests	⬜	2026-07-08	→
7.3	E2E Tests	⬜	2026-07-08	→
8.1	Code Review & Refactoring	⬜	2026-07-08	→
8.2	최종 검증 & 문서화	⬜	2026-07-09	→

범례: ✅=완료, 🔄=진행중, ⬜=대기, ⏸️=선택사항

---

🎯 성공 기준 (데이터 증빙)

기능 동등성

✅ Python vs C# 동등 검증:
  1. 입출력 시그니처
     collect_to_sqlite(...) → RunCollectionAsync(...)
     같은 파라미터, 같은 반환값 구조
  
  2. 데이터 흐름
     GatherTradingData.json (입력)
     → 시드 데이터 파싱
     → KIS API 호출 (3개 endpoint)
     → 데이터 정규화
     → DB 저장 (3개 테이블)
     → JSON 출력 (Temp/kis_data_collection_v1.json)
  
  3. 에러 처리
     Python test_kis_data_collection_v1.py 모든 케이스 통과

코드 품질

✅ SOLID 원칙:
  1. Single Responsibility ✓
     - DataCollectionService: 오케스트레이션만
     - PriceDataNormalizer: 정규화만
     - GatherTradingDataParser: 파싱만
  
  2. Open/Closed ✓
     - IPriceSource 추가 시 기존 코드 수정 X
     - NaverApiPriceSource 추가 가능
  
  3. Liskov Substitution ✓
     - KisApiPriceSource, NaverApiPriceSource 모두 IPriceSource 준수
  
  4. Interface Segregation ✓
     - IPriceSource: 3 메서드만 (GetPriceDataAsync)
     - ICollectionOrchestrator: 2 메서드 (RunCollectionAsync, ...)
  
  5. Dependency Inversion ✓
     - 구체적 클래스 X, 인터페이스에 의존

테스트 커버리지

✅ 목표: ≥85% 라인 커버리지
  1. Unit Tests: 20+ test cases
     - CoerceFloat (10)
     - FindFirstValue (8)
     - GatherTradingDataParser (5)
     - SourcePriorityResolver (3)
     - PriceDataNormalizer (3)
  
  2. Integration Tests: 5+ scenarios
     - Happy path
     - Partial failure
     - All errors
     - JSON output
     - DB persistence
  
  3. E2E Tests: 3+ flows
     - POST /api/collection/run
     - File creation
     - DB verification

성능 기준

✅ 성능 목표:
  1. 단일 종목 수집
     - 목표: < 2초
     - KIS API 3개 호출 포함
  
  2. 배치 수집 (100개 종목)
     - 목표: < 120초
     - 평균 1.2초/종목
  
  3. JSON 파일 크기
     - 목표: < 10MB (100개 종목)

호환성 검증

✅ Python 동등성:
  1. 입력 형식
     GatherTradingData.json 구조 100% 호환
  
  2. 출력 형식
     Temp/kis_data_collection_v1.json 구조 100% 동일
     - JSON 필드명, 타입, 순서
  
  3. DB 스키마
     kis_collection_runs, snapshots, errors 모두 호환
  
  4. 에러 처리
     Python과 동일한 에러 메시지, status 코드

---

📝 진행 방식

매 Phase마다

1. Task 시작 전: 성공 기준 재확인
2. Task 진행 중: WBS의 체크리스트 항목 하나씩 수행
3. Task 완료 후:
   • 코드 자가 검토
   • 관련 테스트 작성 및 통과
   • WBS 문서에 완료 체크 표시
4. 최종 검증: 이 파일의 진행 상황 표 업데이트

커밋 규칙

Format: <Phase>.<Task>: <변경사항> — <성공기준 1개>

예시:
  1.1: Add CollectionSnapshot model — JSON serialization works ✅
  2.2: Implement KisApiPriceSource — Test passes vs Python ✅
  7.1: Add unit tests for DataNormalizationHelper — 85% coverage ✅

블록 상황 처리

1. 구현 중 막히면?
   - WBS 해당 Task의 "성공 규칙" 다시 읽기
   - Python 원본 코드 라인 번호 재확인
   - 테스트 케이스로 구현하기 (TDD)

2. 테스트 실패?
   - Python test 다시 실행 (비교)
   - 데이터 타입/값 불일치 확인
   - 로깅 추가해서 디버그

---

📎 참고

• Python 원본: src/quant_engine/kis_data_collection_v1.py (436줄)
• Python 테스트: tests/unit/test_kis_data_collection_v1.py (87줄)
• DB 스키마: src/dotnet/QuantEngine.Infrastructure/Data/DbMigrator.cs (라인 59-106)
• 기존 .NET: src/dotnet/QuantEngine.Application/Services/DataCollectionService.cs