QuantEngineByItz/docs/CICD_ANALYSIS_AND_ROADMAP.md

# QuantEngine CI/CD 파이프라인 — 근본적 개선 분석 및 로드맵

**작성일**: 2026-07-11  
**분석 대상**: 522 workflow runs (모두 실패 또는 skipped)  
**핵심 발견**: 원론적 아키텍처 결함, 중복 빌드, 불명확한 실패 원인

---

## 📊 현재 상태 분석

### 1. Workflow 구조의 문제

```
Current (병렬 & 독립적):
  
  push → build.yml      → GitHub Release 발행 → 🔴 실패
       → ci.yml         → 30+ validators     → 🔴 실패
       → deploy-prod.yml → 배포                → 🔴 실패
       → wbs_9_3_*.yml  → 검증                → 🔴 실패
  
  문제점:
  - 세 workflow가 동시에 실행 (경합 위험)
  - build.yml과 deploy-prod.yml이 각각 독립적으로 빌드
  - 아티팩트 공유 메커니즘 없음
  - GitHub Release action 사용 (Gitea에서 미지원)
  - ci.yml의 30+ 단계 중 어느 것이 실패하는지 불명확
```

### 2. 실패 패턴 (최근 20개 run 분석)

```
build.yml:         18/20 실패 (90%)
ci.yml:            18/20 실패 (90%)
deploy-prod.yml:   18/20 실패 (90%)
wbs_9_3_*.yml:      5/5  실패 (100%)
validate-ui-*:      5/5  skipped (조건부 실행)

일관된 실패 = 시스템적 문제 (간헐적 flake 아님)
```

### 3. 주요 근본 원인

| 원인 | 영향 | 심각도 |
|------|------|--------|
| **빌드 중복** | CI runner 리소스 낭비, 시간 증가 | 🔴 High |
| **Workflow 의존성 부재** | 각 workflow가 독립적 → 아티팩트 비동기화 | 🔴 High |
| **30+ Python validators 순차 실행** | 하나 실패 시 전체 ci.yml 중단 → 원인 파악 어려움 | 🔴 High |
| **GitHub Release 사용** | Gitea에서 미지원 → build.yml 실패 | 🔴 High |
| **로그 분산** | 실패 원인 추적 어려움 | 🟠 Medium |
| **Secret 관리 부재** | QUANTENGINE_DB_PASSWORD 미설정 | 🟠 Medium |

---

## 🎯 원론적 개선 방향 (Principled Architecture)

### Phase 1: Pipeline 아키텍처 재설계 (필수)

**목표**: SSOT (Single Source of Truth) + 명확한 흐름

```
재설계 (순차 & 의존적):

  push → stage: Validate (fast gates)
         ├─ Lint & Format Check
         ├─ Security Scan (KIS API governance)
         └─ Spec Validation (YAML/JSON)
         → stage: Build (공유 아티팩트)
         ├─ dotnet build
         ├─ Unit tests
         └─ Package creation
         → stage: Test (통합 테스트)
         ├─ Python validators (병렬, 독립적 재시도)
         └─ E2E tests
         → stage: Deploy (조건부)
         ├─ Pre-deployment checks
         ├─ Green-Blue deployment
         └─ Health check

효과:
- 빌드 1회만 → 시간 50% 단축
- 아티팩트 중앙화 → 동기화 문제 제거
- 각 stage 독립 실패 처리 → 원인 명확
- Validator 병렬 실행 가능 → 시간 개선
```

### Phase 2: Quality Gates 계층화

```
Tier 1: Fast Gates (< 2분, 모든 PR)
  ├─ YAML/JSON lint
  ├─ File size check
  ├─ Branch naming convention
  └─ → 실패 시 즉시 피드백

Tier 2: Critical Gates (3-5분, 모든 PR)
  ├─ KIS API read-only enforcement
  ├─ No hardcoded secrets
  ├─ Security scanning
  └─ → 실패 시 배포 차단

Tier 3: Integration Gates (10-15분, merge 시에만)
  ├─ 30+ Python validators (병렬 실행)
  ├─ Unit tests
  └─ → 실패 시 skipped (로그만 저장)

효과:
- PR 속도 개선 (2분 내 피드백)
- 중요한 gate만 배포 차단
- Validators 실패 = 정보만 저장 (배포는 진행)
```

### Phase 3: Observability 강화

```
각 단계별 명확한 출력:

✅ Stage: Validate
   └─ Lint: PASS
   └─ Security: PASS
   └─ Specs: PASS (3/3 files)

✅ Stage: Build
   └─ Restore: PASS (1.2s)
   └─ Build: PASS (45s)
   └─ Tests: PASS (8/8)
   └─ Package: quantengine-abc1234.tar.gz (2.6MB)

✅ Stage: Test
   ├─ validator-01-kis-governance: PASS
   ├─ validator-02-specs: PASS
   ├─ validator-03-formula: PASS
   ... (병렬 실행)
   └─ Summary: 28/30 PASS, 2 SKIP (ok)

✅ Stage: Deploy
   └─ Green-Blue: quantengine_20260711_ABC1234_523
   └─ Health: OK (HTTP 200)
   └─ Rollback: Available

효과:
- 각 단계 진행 상황 실시간 파악
- 실패 시 구체적인 단계 & 원인 명시
- Artifact 추적 가능
```

### Phase 4: Workflow 파일 구조화

```
새로운 파일 구조:

.gitea/workflows/
├─ _common/                  # 공유 로직
│  ├─ build-artifact.yml     # dotnet build & package
│  ├─ quick-gates.yml        # Lint, 정적분석
│  ├─ deploy.yml             # Green-Blue deployment
│  └─ notify.yml             # Slack/Telegram 알림
│
├─ pr-validation.yml         # PR 검증 (Fast gates 만)
├─ merge-to-main.yml         # main 병합 (Critical + Integration)
├─ deploy-production.yml     # 배포 (main 태그/release)
│
└─ scheduled/
   ├─ nightly-validators.yml # 야간 전체 검증
   └─ cleanup-deployments.yml# 배포 정리

각 workflow 책임:
- pr-validation.yml: 2분 내 피드백 (Tier 1)
- merge-to-main.yml: 15분 내 완료 (Tier 1+2+3)
- deploy-production.yml: 10분 내 배포 (Tier 2+3+Deploy)
```

---

## 🛠 구체적 개선 작업 (다음 세션)

### 1단계: 빌드 파이프라인 통일 (1시간)
- [ ] `.gitea/workflows/_common/build-artifact.yml` 생성
- [ ] build.yml → `_common/build-artifact.yml` 참조로 변경
- [ ] deploy-prod.yml → `_common/build-artifact.yml` 참조로 변경
- [ ] 아티팩트 S3/Gitea Release storage로 중앙화

### 2단계: Validator 최적화 (2시간)
- [ ] ci.yml의 30+ validator를 3개 그룹으로 분류
  - Group A: Tier 1 (빠른 gates)
  - Group B: Tier 2 (중요 gates)
  - Group C: Tier 3 (정보성)
- [ ] 각 그룹을 병렬 job으로 분리
- [ ] Validator 실패 시 `continue-on-error: true` 설정

### 3단계: Workflow 통합 (2시간)
- [ ] `pr-validation.yml` 생성 (Tier 1 only)
- [ ] `merge-to-main.yml` 생성 (Tier 1+2+3)
- [ ] `deploy-production.yml` 정리 (Tier 2+3+Deploy)
- [ ] 각 workflow의 outputs 명확히 (success/failure/artifact)

### 4단계: 모니터링 & 알림 (1시간)
- [ ] `.gitea/workflows/_common/notify.yml` 생성
- [ ] 각 stage 완료 후 알림
- [ ] 실패 시 상세 로그 링크 포함

### 5단계: 문서화 & 테스트 (1시간)
- [ ] README.md 업데이트 (workflow 흐름)
- [ ] 로컬에서 workflow 검증 가능한 스크립트
- [ ] CI/CD 트러블슈팅 가이드

---

## 🚀 기대 효과

| 지표 | 현재 | 개선 후 | 개선율 |
|------|------|--------|--------|
| 빌드 시간 | 3-4분 | 1-2분 | -60% |
| 전체 workflow 시간 | 10-15분 | 15-20분 (더 안정적) | +정확성 |
| 실패율 | 90% | <10% | -80% |
| 평균 실패 원인 파악 시간 | 30분 | 5분 | -83% |
| PR 피드백 시간 | 5분 (전체 CI 완료 후) | 2분 (Tier 1만) | -60% |

---

## 📋 최종 체크리스트

- [ ] 새 DB password 설정 (QUANTENGINE_DB_PASSWORD secret)
- [ ] GitHub Release action → Gitea-compatible 버전으로 변경
- [ ] Build artifact 저장소 선정 (S3 / Gitea Releases / 로컬)
- [ ] Validator 병렬화 방안 검토
- [ ] Notification 채널 구성 (Slack/Telegram/Gitea comment)

---

## 참고: 기존 대비 개선 원칙

| 원칙 | 현재 상태 | 개선 방향 |
|------|----------|---------|
| **Single Build** | ❌ 중복 빌드 (build.yml + deploy-prod.yml) | ✅ 공유 아티팩트 |
| **Clear Deps** | ❌ 의존성 없음 (병렬 실행) | ✅ 순차 & 조건부 |
| **Fast Feedback** | ❌ 15분 대기 | ✅ 2분 내 피드백 |
| **Fail Fast** | ❌ 30 validators 순차 | ✅ Validator 병렬 |
| **Observability** | ❌ 로그 분산 | ✅ 단계별 명확한 출력 |
| **Secret Security** | ⚠️ 환경변수만 | ✅ Gitea secret + fail-fast |