diff --git a/ROADMAP_2026.md b/ROADMAP_2026.md new file mode 100644 index 00000000..a37c5071 --- /dev/null +++ b/ROADMAP_2026.md @@ -0,0 +1,218 @@ +# K-ArtSell Aegis v16.0: 완전 배포 로드맵 (2026-08-11 ~ 2026-12-31) + +## 🎯 최종 목표 +**프로덕션 배포 & 자동 운영 (2026-11-20)** + +--- + +## 📅 전체 일정 (4 Phases) + +### Phase 1: Shadow Run (자동 진행 중) +**기간:** 2026-08-11 ~ 2026-10-31 (50-90일) +**상태:** 🟢 자동 실행 중 (Job 3227) +**담당:** Hangfire 자동화 + +**산출물:** +- ✅ 252+ 트레이딩 데이 검증 (자동) +- ✅ PBO (Probability of Backtest Overfit) 메트릭 +- ✅ DSR (Daily Sharpe Ratio) 메트릭 +- ✅ OOS (Out-of-Sample) 분석 +- ✅ Crash Recovery 검증 (4/4 시나리오) + +**진행 상황:** +``` +08-11: Phase 1 시작 +08-11~10-31: 50-90일 자동 실행 +10-31: 예상 완료 (조정 가능) +``` + +--- + +### Phase 2: 증거 수집 & 검증 (예상 11-01 ~ 11-15) +**기간:** ~15일 +**상태:** ⏳ 대기 중 (Phase 1 완료 대기) +**담당:** 엔지니어링 팀 + +**작업 항목:** +``` +□ PBO 메트릭 검증 (< 20% threshold) +□ DSR 메트릭 검증 (> 0.5 threshold) +□ OOS 드리프트 검증 (< 2.5% threshold) +□ Crash Recovery 로그 분석 +□ 감시 이벤트 로그 검토 (DEBT-014/029) +□ 최종 기술부채 검토 (quarterly 20%) +□ Phase 1 전체 리포트 작성 +``` + +**산출물:** +- 최종 증거 보고서 +- PBO/DSR/OOS 검증 결과 +- 기술부채 20% 결제 확인 +- Production Sign-Off 문서 + +--- + +### Phase 3: 프로덕션 배포 (2026-11-20 예상) +**기간:** ~1-2일 +**상태:** ⏳ 대기 중 +**담당:** DevOps + 엔지니어링 + +**배포 작업:** +``` +□ kartsell.taxbaik.com 배포 준비 +□ 데이터베이스 마이그레이션 (0041 포함) +□ Environment 설정 (API keys, secrets) +□ Nginx 설정 (reverse proxy) +□ SSL 인증서 갱신 +□ 부하 테스트 (sandbox) +□ Smoke 테스트 (production) +□ 배포 실행 +□ 배포 후 검증 (모니터링 3일) +``` + +**산출물:** +- 배포 체크리스트 +- 배포 후 모니터링 결과 +- 프로덕션 상태 보고서 + +--- + +### Phase 4: 운영 & 모니터링 (2026-11-20 ~ 2026-12-31+) +**기간:** 무한 (지속 운영) +**상태:** ⏳ 대기 중 +**담당:** SRE 팀 + +**월별 작업:** +``` +11월 (배포 후 3주): +□ 안정성 모니터링 (SLA 99.5%) +□ 성능 메트릭 수집 +□ 사용자 피드백 수집 +□ 긴급 버그 패치 + +12월: +□ 기술부채 월별 20% 결제 +□ Q4 성과 리뷰 +□ Q1 2027 계획 수립 + +2027+: +□ Continuous Deployment +□ A/B 테스트 (새 모델) +□ 자동 모델 승격 (threshold 시) +□ 월별 기술부채 관리 +``` + +**모니터링 항목:** +``` +□ Model Drift (OOS, PBO, DSR) +□ Data Quality (duplicate detection, reconciliation) +□ System Health (99.5% SLA, response time) +□ Cost Analysis (infrastructure, API usage) +□ Business Metrics (advisory effectiveness) +``` + +--- + +## 📊 마일스톤 타임라인 + +``` +2026-08-11 +│ +├─ Phase 1 START (Job 3227) +│ └─ Automatic execution for 50-90 days +│ +2026-10-31 (예상) +│ +├─ Phase 1 COMPLETE +│ └─ PBO/DSR/OOS evidence ready +│ +2026-11-01 ~ 11-15 +│ +├─ Phase 2: Evidence Verification +│ └─ All thresholds verified +│ +2026-11-20 +│ +├─ Phase 3: PRODUCTION DEPLOYMENT +│ └─ kartsell.taxbaik.com live +│ +2026-11-20 ~ 12-31 +│ +└─ Phase 4: Monitoring & Operations + └─ Monthly debt paydown (20%) +``` + +--- + +## 🎯 성공 기준 + +| 단계 | 기준 | 검증 방법 | +|------|------|---------| +| **Phase 1** | 252+ trading days, all metrics ready | Job 3227 logs | +| **Phase 2** | PBO<20%, DSR>0.5, OOS<2.5% | Analysis report | +| **Phase 3** | Deployment successful, 99.5% SLA | Monitoring dashboard | +| **Phase 4** | Monthly 20% debt paydown, no P1 incidents | Git log, alerts | + +--- + +## 🚀 의존성 분석 + +``` +Phase 1 (자동) + ↓ (50-90일 자동 실행) +Phase 2 (증거 수집) + ↓ (검증 완료) +Phase 3 (배포) + ↓ (배포 성공) +Phase 4 (운영) + ↓ (지속 진행) + +병렬화 불가: +- Phase 1 완료 없이 Phase 2 불가 +- Phase 2 검증 없이 Phase 3 불가 + +빠른 경로 가능: +- Phase 1 조기 완료 → 배포 앞당김 +``` + +--- + +## ⚠️ 리스크 & 완화 전략 + +| 리스크 | 확률 | 영향 | 완화 | +|--------|------|------|------| +| Phase 1 기간 초과 | 중 | 배포 지연 | 주간 진행 모니터링 | +| PBO 임계값 미충족 | 저 | 배포 불가 | 모델 재조정 계획 | +| 배포 중 장애 | 저 | 서비스 중단 | 롤백 계획, sandbox 테스트 | +| 기술부채 누적 | 중 | 유지보수 비용 | 월별 20% 결제 강제 | + +--- + +## 📋 다음 체크포인트 + +``` +매주 금요일 (또는 필요시): +- Phase 1 진행률 확인 (Job 3227 로그) +- 이슈 식별 및 계획 조정 + +2026-10-20 (예상): +- Phase 1 완료 예측 검증 +- Phase 2 준비 시작 (팀 할당) + +2026-11-01: +- Phase 2 공식 시작 +- 증거 수집 병렬화 + +2026-11-15: +- Phase 3 배포 승인 (또는 지연 결정) + +2026-11-20: +- 프로덕션 배포 (또는 재일정) +``` + +--- + +**Document Version:** 1.0 +**Last Updated:** 2026-08-11 +**Owner:** Engineering Team +**Status:** ACTIVE diff --git a/STRATEGY_OPTIMAL_EXECUTION.md b/STRATEGY_OPTIMAL_EXECUTION.md new file mode 100644 index 00000000..9b8f4e82 --- /dev/null +++ b/STRATEGY_OPTIMAL_EXECUTION.md @@ -0,0 +1,694 @@ +# 최적 실행 전략: AGENTS.md v16.0 기반 + +**목표:** 로드맵 & WBS를 AGENTS.md v16.0 20가지 원칙에 따라 최적으로 실행 + +--- + +## 📋 원칙 기반 실행 전략 + +### 1. SOLID (Single Responsibility, Open-Closed, Liskov, Interface Segregation, Dependency Inversion) + +**로드맵 적용:** +``` +각 Phase는 단일 책임: +- Phase 1: 자동 검증 (Hangfire 담당) +- Phase 2: 증거 수집 (Engineering 담당) +- Phase 3: 배포 (DevOps 담당) +- Phase 4: 운영 (SRE 담당) + +교차 기능 팀 구성: +- 각 팀은 명확한 계약(contract) 기반 협력 +- 팀 간 직접 테이블 접근 금지 (API/이벤트 사용) +``` + +**실행 방법:** +``` +✅ Phase 2 증거 검증: 각 메트릭 팀 독립 실행 + └─ PBO 팀, DSR 팀, OOS 팀 병렬 진행 + └─ 최종 엔드포인트에서만 통합 검증 + +✅ Phase 3 배포: DBA ↔ DevOps ↔ Engineering 명확한 역할 + └─ 롤백 계획 미리 수립 (Open-Closed) + └─ 새로운 환경에서도 배포 스크립트 재사용 (Liskov) +``` + +--- + +### 2. 코드리팩토링 (Characterized, Isolated, Verified) + +**로드맵 적용:** +``` +Phase 2 시작 전: 기존 코드 특성화 +- 현재 테스트 커버리지 (249/266) 기록 +- 성능 기준선 (baseline) 수립 +- 알려진 이슈 문서화 + +Phase 2 진행 중: 격리된 변경 +- DEBT 해결 시 각 변경을 별도 커밋 +- 하나의 DEBT = 하나의 PR (atomic) +- 테스트 통과 후 머지 + +Phase 2 후: 검증 +- 테스트 커버리지 전후 비교 +- 성능 회귀 테스트 +- Golden 데이터셋 재검증 +``` + +**실행 방법:** +``` +✅ 매월 기술부채 결제 시 (Phase 4): + - 변경 전 테스트 스냅샷 (git tag: debt-{id}-before) + - 변경 적용 + - 변경 후 테스트 스냅샷 (git tag: debt-{id}-after) + - diff 분석 및 회귀 검증 +``` + +--- + +### 3. 데이터 정합성 (Normalization, PIT Queries) + +**로드맵 적용:** +``` +Phase 1: 감사 이벤트 정합성 검증 (자동) +- operation_audit_trail 3NF 유지 (자동) +- 모든 쿼리 PIT 패턴 (published_at <= cutoff) +- 중복 감지 자동 로깅 (DEBT-014) + +Phase 2: 데이터 무결성 검증 +- Phase 1 기간 중 저장된 모든 데이터 검증 +- 스키마 버전 호환성 확인 +- 마이그레이션 이후 데이터 무결성 재검증 (Phase 3 전) +``` + +**실행 방법:** +``` +✅ Phase 2 체크리스트: + □ operation_audit_trail row count 검증 + □ 모든 쿼리 PIT 패턴 재확인 (grep "published_at") + □ 중복 감지 로그 분석 (false positive < 0.1%) + □ 외래키 무결성 검증 (FK constraint) +``` + +--- + +### 4. 과유불급 (No Gold-Plating) + +**로드맵 적용:** +``` +Phase 2: 필요한 것만 검증 +- 배포 전 필수 증거만 수집 (PBO, DSR, OOS, DEBT, audit) +- 미래 기능 (auto-learning, auto-promotion)은 Phase 4로 이연 +- 추가 최적화는 배포 후 (운영 중 개선) + +Phase 3: 최소한의 배포 +- 현재 코드 그대로 배포 (새 기능 추가 금지) +- 배포 후 모니터링만 집중 +- 새 기능 개발은 Post-go-live로 계획 + +Phase 4: 점진적 개선 +- 월별 20% DEBT만 결제 +- 분기별 1-2개 기능만 추가 (A/B 테스트) +``` + +**실행 방법:** +``` +✅ 각 Phase 승인 기준: + - Phase 2 승인: PBO/DSR/OOS 임계값만 (추가 검증 금지) + - Phase 3 승인: 배포 체크리스트만 (feature freeze) + - Phase 4 진입: 72시간 모니터링 SLA 달성 +``` + +--- + +### 5. 정규화 (3NF Database Design) + +**로드맵 적용:** +``` +Phase 1 ~ Phase 3: 스키마 불변 +- operation_audit_trail 3NF 유지 +- 새 테이블 추가 금지 +- 마이그레이션 추가 금지 (0041만) + +Phase 4: 운영 중 최적화 +- Read-only 덴노말라이제이션 검토 +- 인덱스 최적화 (성능 메트릭 기반) +- 아카이빙 전략 (Phase 4.2 분기 검토) +``` + +**실행 방법:** +``` +✅ Phase 2 데이터 정합성 검증: + □ PK/FK 모두 존재하는지 확인 + □ NULL 값이 없어야 하는 컬럼 확인 + □ UNIQUE 제약 조건 적용 여부 확인 +``` + +--- + +### 6. 역정규화 (Denormalization for Read Performance) + +**로드맵 적용:** +``` +Phase 2: 읽기 성능 기준선 수립 +- 메트릭 조회 응답 시간 기록 (PBO, DSR, OOS) +- 감사 로그 조회 성능 측정 + +Phase 3: 배포 전 최적화 (필요시) +- 느린 쿼리 식별 (응답 > 500ms) +- 뷰(VIEW) 또는 캐시 추가 (읽기 최적화만) + +Phase 4: 진행 중 모니터링 +- 월별 응답 시간 추적 +- 병목 쿼리 식별 및 개선 +``` + +**실행 방법:** +``` +✅ Phase 2 성능 기준선: + - EXPLAIN ANALYZE로 각 주요 쿼리 분석 + - Index 사용 여부 확인 + - 응답 시간 기록 (Phase 3, 4에서 비교) +``` + +--- + +### 7. 프로세스 단순화 (Automation) + +**로드맵 적용:** +``` +Phase 1: 완전 자동화 (Hangfire Job 3227) +- 수동 개입 금지 +- 일일 메트릭 자동 계산 +- 주간 리포트 자동 생성 + +Phase 2: 반자동화 (검증 도구) +- 스크립트로 PBO/DSR/OOS 계산 +- SQL 쿼리로 감사 로그 자동 분석 +- 체크리스트 자동 생성 + +Phase 3: 배포 자동화 +- 배포 스크립트 (bash/powershell) +- 롤백 자동 스크립트 +- 모니터링 대시보드 자동 활성화 + +Phase 4: 운영 자동화 +- 월별 DEBT 식별 자동화 +- SLA 모니터링 자동 알림 +- 월간 리포트 자동 생성 +``` + +**실행 방법:** +``` +✅ Phase 2 준비 작업: + - Python/SQL 스크립트 미리 작성 + - 테스트 환경에서 실행 검증 + - 자동화 문서 작성 (재현 가능) + +✅ Phase 3 준비 작업: + - Deployment 스크립트 (sandbox 테스트 완료) + - Rollback 스크립트 (sandbox 테스트 완료) +``` + +--- + +### 8. 패턴화 (Standard Architecture Patterns) + +**로드맵 적용:** +``` +전 Phase: 기존 패턴만 사용 +- Outbox/Inbox (비동기 이벤트) +- Vertical Slice (기능 구조) +- PIT 쿼리 (시간축 데이터) +- DI 컨테이너 (의존성) +- Handler → Policy → SQL (계층화) + +Phase 2 검증: +- 모든 쿼리가 Vertical Slice 패턴인지 확인 +- 모든 이벤트가 Outbox/Inbox 패턴인지 확인 +- 모든 데이터 쿼리가 PIT 패턴인지 확인 + +Phase 4 개선: +- 새로운 패턴 도입은 금지 (기존 패턴만 사용) +- 기존 패턴 개선은 분기별 1-2개만 (리스크 최소화) +``` + +**실행 방법:** +``` +✅ Phase 2 패턴 검증: + grep -r "SELECT \*" src/ # 금지 패턴 + grep -r "new SqlCommand" src/ # 금지 패턴 + grep -r "published_at <=" src/ # PIT 패턴 확인 +``` + +--- + +### 9. 표준화 (Technology Stack) + +**로드맵 적용:** +``` +Phase 1 ~ Phase 4: 기존 스택만 사용 +- .NET 10 (변경 금지) +- Dapper (ORM, 변경 금지) +- FastEndpoints (API, 변경 금지) +- Hangfire (jobs, 변경 금지) +- PostgreSQL (DB, 버전 유지) +- Vue 3 (FE, 변경 금지) +- Vitest (테스트, 변경 금지) + +Phase 4 검토: +- 마이너 버전 업그레이드 (보안) +- 새로운 라이브러리는 분기별 1-2개만 +``` + +**실행 방법:** +``` +✅ Phase 2 스택 검증: + dotnet --version # .NET 10.x 확인 + psql --version # PostgreSQL 버전 확인 + npm list # 의존성 버전 확인 +``` + +--- + +### 10. 구조화 (Module Isolation) + +**로드맵 적용:** +``` +Phase 1 ~ Phase 3: 스키마 격리 유지 +- compliance.* (감사) ← 독립 +- model_operations.* (모델) ← 독립 +- signal_engine.* (신호) ← 독립 +- building_blocks.* (공유) ← 읽기만 + +Phase 2 검증: +- 각 모듈이 자신의 스키마만 수정하는지 확인 +- 모듈 간 직접 테이블 접근이 없는지 확인 (API만) + +Phase 4 개선: +- 모듈 경계 리팩토링 (분기별 1개) +``` + +**실행 방법:** +``` +✅ Phase 2 격리 검증: + grep -r "model_operations\." src/KArtSell.Modules.SignalEngine/ + # 금지: signal_engine 모듈이 model_operations 직접 접근 + + grep -r "outbox" src/ # Outbox 패턴 사용하는지 확인 +``` + +--- + +### 11. 바이브코딩 (Clear & Simple Code) + +**로드맵 적용:** +``` +Phase 2: 코드 리뷰 기준 강화 +- 클래스/메서드 이름이 목적을 명확히 하는지 +- 10줄 이상 주석은 금지 (한줄만) +- Cyclomatic complexity < 10 (Policy 제외) + +Phase 3: 코드 정리 +- Unused imports 제거 +- 사용되지 않는 메서드 제거 +- 일관된 포맷팅 (dotnet format) + +Phase 4: 지속적 개선 +- 매월 복잡한 메서드 1개씩 리팩토링 +- 월별 코드 커버리지 추적 +``` + +**실행 방법:** +``` +✅ Phase 2 검증: + dotnet format --verify-no-changes --verbosity diagnostic + dotnet test /p:CollectCoverage=true +``` + +--- + +### 12. 홀루시네이션 방지 (Real Data Validation) + +**로드맵 적용:** +``` +Phase 1: 실제 데이터 검증 (자동) +- 스텁 데이터 사용 금지 (실제 KRX API) +- Mock 제거 (실제 DB) + +Phase 2: 증거 검증 +- Phase 1 실제 데이터 분석 +- 계산 공식 재현 검증 (git 트래킹) + +Phase 3: 배포 검증 +- Sandbox에서 실제 config로 테스트 +- Production과 동일한 데이터로 smoke test + +Phase 4: 지속 모니터링 +- 실제 메트릭 추적 (대시보드) +- 이상치 자동 감지 +``` + +**실행 방법:** +``` +✅ Phase 1 검증: + grep -r "new Mock" src/ # Mock 사용 여부 확인 + grep -r "stub\|fake" src/ # Stub 데이터 확인 + +✅ Phase 2 검증: + - PBO 계산: 실제 Phase 1 데이터로 재계산 + - DSR 계산: 실제 수익률 데이터로 재계산 +``` + +--- + +### 13. 현장감 (On-Site Evidence) + +**로드맵 적용:** +``` +Phase 1: 실제 환경에서 자동 실행 +- 실제 Production DB (178.104.200.7) +- 실제 KRX/OpenDart API +- 실제 시장 데이터 + +Phase 2: 실제 결과 검증 +- Phase 1 실제 로그 분석 +- 실제 DB에서 데이터 쿼리 (개발 환경 아님) + +Phase 3: 실제 배포 +- Staging이 아닌 Production 배포 +- 실제 사용자 트래픽 + +Phase 4: 실제 모니터링 +- 실제 메트릭 추적 (mock이 아님) +- 실제 SLA 달성 검증 +``` + +**실행 방법:** +``` +✅ Phase 1 검증: + ssh kjh2064@178.104.200.7 # 실제 서버 확인 + psql kartsell # 실제 DB 데이터 확인 + +✅ Phase 2 검증: + select count(*) from compliance.operation_audit_trail; # 실제 데이터 +``` + +--- + +### 14. 재현성 (Reproducibility) + +**로드맵 적용:** +``` +Phase 1: 일일 스냅샷 저장 +- Job 3227 로그 일일 저장 (git) +- 메트릭 데이터 일일 백업 + +Phase 2: 계산 재현 가능 +- PBO 공식 문서화 (재현 가능) +- DSR 공식 문서화 (재현 가능) +- SQL 쿼리 모두 git 트래킹 + +Phase 3: 배포 재현 가능 +- 배포 스크립트 버전 관리 (git) +- 배포 절차 문서화 (README) + +Phase 4: 모니터링 재현 가능 +- 대시보드 쿼리 git 저장 +- 알림 규칙 코드화 (as-a-code) +``` + +**실행 방법:** +``` +✅ Phase 2 재현성: + git log --oneline -- src/ # 모든 변경 이력 + git show :src/QueryPBO.sql # 특정 시점의 쿼리 + +✅ Phase 3 재현성: + git tag deploy-2026-11-20 # 배포 버전 태그 + git show deploy-2026-11-20:deploy.sh # 배포 스크립트 +``` + +--- + +### 15. 이력성 (Traceability) + +**로드맵 적용:** +``` +Phase 1 ~ Phase 4: 모든 변경을 git에 기록 +- Commit message: DEBT-{id}, correlation ID +- Tag: Phase별 마일스톤 (Phase-1-Complete, etc.) +- Branch: 기능별 (feature/debt-014, etc.) + +TECH_DEBT_REGISTER.md 유지: +- 매월 DEBT 결제 기록 +- 미결제 DEBT 이유 문서화 + +모니터링 이벤트 로깅: +- operation_audit_trail (자동) +- outbox/inbox 이벤트 (자동) +``` + +**실행 방법:** +``` +✅ Phase 2 이력성: + git log --format="%h %an %ai %s" --grep="DEBT" + # DEBT-014, DEBT-029 등 모든 기록 조회 + +✅ 매월 검증: + grep "2026-11" TECH_DEBT_REGISTER.md + # 이번 달 DEBT 결제 기록 확인 +``` + +--- + +### 16. 안정성 (Reliability & Crash Recovery) + +**로드맵 적용:** +``` +Phase 1: 자동 복구 검증 (자동) +- Job 3227 실패 시 재시도 +- DB 연결 끊김 시 재연결 +- Crash recovery (4/4 시나리오) 자동 검증 + +Phase 2: 안정성 검증 리포트 +- Phase 1 기간 중 재시도 횟수 +- 실패율 (목표: < 0.1%) +- Crash recovery 성공률 (목표: 100%) + +Phase 3: 배포 안정성 +- Rollback 계획 사전 테스트 +- Monitoring 시스템 구성 +- SLA 정의 (99.5%) + +Phase 4: 지속 모니터링 +- 에러율 추적 (< 0.1%) +- 재시도 로그 분석 (월 1회) +- 장애 원인 분석 (RCA) +``` + +**실행 방법:** +``` +✅ Phase 1 검증: + select event_type, count(*) from compliance.operation_audit_trail + where event_type = 'JOB_RETRY' group by event_type; + +✅ Phase 2 검증: + - Retry 로그 분석 + - Crash recovery 동작 확인 + - 실패 이유 카테고리화 +``` + +--- + +### 17. 고도화 (Evolutionary Architecture) + +**로드맵 적용:** +``` +Phase 1 ~ Phase 3: 현재 아키텍처 고정 +- 새로운 패턴 도입 금지 +- 마이크로서비스 검토 금지 + +Phase 4: 진화적 개선 +- 분기별 1-2개 아키텍처 개선 +- A/B 테스트로 변경 검증 +- Feature flag로 점진적 배포 + +예시: +- Q1 2027: Read replica for metrics (성능 개선) +- Q2 2027: Event sourcing for audit (확장성) +- Q3 2027: API gateway for rate limiting (보안) +``` + +**실행 방법:** +``` +✅ Phase 4 계획: + - 아키텍처 결정 기록 (ADR) + - 변경 영향 분석 (dependency map) + - 회귀 테스트 계획 +``` + +--- + +### 18. 컴포넌트화 (Modularity) + +**로드맵 적용:** +``` +Phase 1 ~ Phase 3: 기존 모듈 구조 유지 +- AuditTrailConsumer (DEBT-029) +- MetricsSql (DEBT-014) +- PBO/DSR/OOS 계산 (Phase 2) + +Phase 4: 모듈 분리 검토 +- 각 메트릭을 독립 서비스로? (아니면 이대로) +- 감사 로깅을 별도 db로? (아니면 이대로) +- 결정: 분기별 1회 검토, 필요시만 분리 +``` + +**실행 방법:** +``` +✅ Phase 2 검증: + grep -r "interface I" src/KArtSell.Host/ + # 각 컴포넌트의 contract 확인 + +✅ Phase 4 계획: + - 컴포넌트 간 의존성 맵 그리기 + - 긴밀한 결합도(coupling) 식별 + - 분기별 1개씩 리팩토링 +``` + +--- + +### 19. 정공법 (Right Way, No Shortcuts) + +**로드맵 적용:** +``` +모든 Phase: +- --no-verify 금지 (git hooks 실행) +- force push 금지 +- hardcoded 값 금지 +- TODO 주석만 허용 (FIXME, XXX 금지) +- 근본 원인 분석 (band-aid 금지) + +Phase 2 검증: +- 모든 버그 수정이 근본 원인 해결인지 확인 +- 임시 패치 금지 + +Phase 3 배포: +- 배포 체크리스트 모두 완료할 때까지 진행 금지 +- 문제 발생 시 rollback (workaround 금지) +``` + +**실행 방법:** +``` +✅ Pre-commit hook 확인: + cat .git/hooks/pre-commit + # 테스트 자동 실행 여부 확인 + +✅ PR 승인 기준: + - 커밋 메시지 명확한지 + - 테스트 추가되었는지 + - 문서 업데이트되었는지 +``` + +--- + +### 20. 기술부채 관리 (20% Monthly Paydown) + +**로드맵 적용:** +``` +Phase 1: 부채 현황 파악 +- 현재 DEBT-014/029/030/032/016/024 결제 상태 확인 +- 누적 부채 점수 계산 + +Phase 2: 부채 정리 +- 미결제 부채 식별 +- 우선순위 결정 (Impact × Effort) + +Phase 3: 부채 동결 +- 배포 전 추가 부채 금지 +- 배포 후 모니터링 중에만 결제 + +Phase 4: 월별 20% 결제 +- 첫 달(11월): 20% 결제 +- 둘째 달(12월): 추가 20% 결제 +- 2027+: 월별 지속 (quarterly 목표 = 60%) +``` + +**실행 방법:** +``` +✅ 매월 이행: + git log --oneline --grep="DEBT" --since="2026-11-01" + # DEBT 관련 커밋 확인 + + grep "2026-11" TECH_DEBT_REGISTER.md + # 월별 결제 기록 확인 +``` + +--- + +## 🎯 최적 실행을 위한 체크리스트 + +### Phase 별 Go/No-Go 기준 + +#### Phase 1 → Phase 2 (Go-Live 승인) +``` +□ Job 3227 50+ 일 실행 (자동) +□ 일일 메트릭 안정적 계산 +□ 감사 로그 정상 기록 (DEBT-014/029) +□ 에러율 < 0.1% +→ Go Phase 2 +``` + +#### Phase 2 → Phase 3 (배포 승인) +``` +□ PBO < 20% ✅ +□ DSR > 0.5 ✅ +□ OOS 드리프트 < 2.5% ✅ +□ 감사 이벤트 정상 ✅ +□ 기술부채 20% 결제 ✅ +□ 배포 체크리스트 100% ✅ +→ Go Phase 3 +``` + +#### Phase 3 → Phase 4 (운영 모드) +``` +□ 배포 성공 ✅ +□ 72시간 모니터링 SLA 99.5% 달성 ✅ +□ 에러율 < 0.1% ✅ +□ 응답 시간 < 500ms (p95) ✅ +□ 경영진 최종 승인 ✅ +→ Go Phase 4 +``` + +--- + +## 📊 우선순위 매트릭스 (Phase 2) + +| 메트릭 | Impact | Effort | 우선순위 | 병렬화 | +|--------|--------|--------|---------|--------| +| PBO 검증 | 높음 | 중간 | 1순위 | 가능 | +| DSR 검증 | 높음 | 중간 | 1순위 | 가능 | +| OOS 검증 | 높음 | 높음 | 1순위 | 가능 | +| 감사 로그 | 중간 | 낮음 | 2순위 | 가능 | +| DEBT 검토 | 중간 | 중간 | 2순위 | 가능 | + +→ **모든 Phase 2 작업 병렬 가능** (의존성 없음) + +--- + +## 🚀 리스크 경감 전략 + +| 리스크 | 발생 시 조치 | 백업 계획 | +|--------|------------|---------| +| Phase 1 조기 완료 | 배포 앞당김 | 연일 모니터링 강화 | +| Phase 1 지연 | 스케줄 연장 | 우선순위 조정 | +| PBO 임계값 미충족 | Phase 3 연기 | 모델 재조정 및 재검증 | +| 배포 중 장애 | 즉시 롤백 | 근본 원인 분석 후 재배포 | +| SLA 미달 | 72시간 연장 | 성능 최적화 후 재검증 | + +--- + +**Version:** 1.0 +**Last Updated:** 2026-08-11 +**Owner:** CTO +**Status:** ACTIVE - READY FOR EXECUTION diff --git a/WBS_MASTER.md b/WBS_MASTER.md new file mode 100644 index 00000000..2067bcd2 --- /dev/null +++ b/WBS_MASTER.md @@ -0,0 +1,423 @@ +# WBS (Work Breakdown Structure): K-ArtSell Aegis v16.0 배포 로드맵 + +**목표:** 90% → 100% 프로덕션 배포 (2026-08-11 ~ 2026-12-31) + +--- + +## 1️⃣ PHASE 1: Shadow Run & Validation (자동 진행) + +### 1.1 자동 실행 (Hangfire Job 3227) +**일정:** 2026-08-11 ~ 2026-10-31 (50-90일) +**담당:** 자동화 시스템 +**상태:** 🟢 진행 중 + +``` +1.1.1 252+ Trading Day Execution + └─ [진행중] Daily PBO/DSR 계산 + └─ [진행중] Daily OOS 드리프트 검증 + └─ [진행중] Crash Recovery (4/4 시나리오) + └─ [진행중] Duplicate Detection 로깅 (DEBT-014) + └─ [진행중] Event Audit Trail (DEBT-029) + +1.1.2 메트릭 자동 계산 + └─ [일일] PBO (Probability of Backtest Overfit) + └─ [일일] DSR (Daily Sharpe Ratio) + └─ [일일] OOS (Out-of-Sample) 드리프트 + └─ [주간] 누적 성과 리포트 + +1.1.3 감사 기록 + └─ [실시간] operation_audit_trail 로깅 + └─ [실시간] outbox/inbox 이벤트 처리 + └─ [주간] 데이터 정합성 검증 +``` + +**산출물:** +- Job 3227 실행 로그 +- 일일 메트릭 데이터 +- 주간 진행 보고서 + +--- + +## 2️⃣ PHASE 2: Evidence Collection & Verification + +### 2.1 PBO 메트릭 검증 +**일정:** 2026-11-01 ~ 2026-11-08 +**담당:** 데이터 팀 +**상태:** ⏳ 대기 + +``` +2.1.1 PBO 계산 검증 + ├─ [Task] Phase 1 마지막 데이터 수집 + ├─ [Task] PBO 공식 적용 (confidence interval) + └─ [검증] PBO < 20% threshold 확인 + └─ PASS → Phase 3 진행 + └─ FAIL → 모델 재조정 (리스크) + +2.1.2 PBO 리포트 작성 + ├─ [Report] 계산 방법론 문서화 + ├─ [Report] 결과 해석 (signal strength) + └─ [Approval] 기술 리더 검토 & 승인 +``` + +**성공 기준:** +- PBO < 20% (probability < 20%) +- 계산 재현 가능 (git 추적) +- 리더 승인 문서 + +--- + +### 2.2 DSR 메트릭 검증 +**일정:** 2026-11-01 ~ 2026-11-08 +**담당:** 퀀트 팀 +**상태:** ⏳ 대기 + +``` +2.2.1 DSR 계산 검증 + ├─ [Task] 252+ 트레이딩 데이 DSR 누적 계산 + ├─ [Task] 월별/분기별 DSR 추이 분석 + └─ [검증] DSR > 0.5 threshold 확인 + └─ PASS → Phase 3 진행 + └─ FAIL → 전략 재평가 (리스크) + +2.2.2 DSR 리포트 작성 + ├─ [Report] Sharpe ratio 방법론 + ├─ [Report] 리스크 조정 성과 분석 + └─ [Approval] CFO 검토 & 승인 +``` + +**성공 기준:** +- DSR > 0.5 (risk-adjusted return) +- 월별 일관성 (< 20% 변동) +- CFO 승인 + +--- + +### 2.3 OOS (Out-of-Sample) 드리프트 검증 +**일정:** 2026-11-01 ~ 2026-11-10 +**담당:** 모델 팀 +**상태:** ⏳ 대기 + +``` +2.3.1 OOS 드리프트 분석 + ├─ [Task] In-sample vs Out-of-sample 성과 비교 + ├─ [Task] 일일 드리프트 계산 (Phase 1 기간) + └─ [검증] OOS 드리프트 < 2.5% 확인 + └─ PASS → Phase 3 진행 + └─ FAIL → 모델 튜닝 (리스크) + +2.3.2 드리프트 분석 보고서 + ├─ [Report] 시간대별 드리프트 추이 + ├─ [Report] 시장 조건별 드리프트 (bull/bear/sideways) + └─ [Approval] 리스크 위원회 검토 +``` + +**성공 기준:** +- OOS 드리프트 < 2.5% +- 모든 시장 조건에서 안정성 입증 +- 위원회 승인 + +--- + +### 2.4 감시 이벤트 로그 검토 +**일정:** 2026-11-01 ~ 2026-11-12 +**담당:** 감사 팀 +**상태:** ⏳ 대기 + +``` +2.4.1 DEBT-014: Operation Audit Trail + ├─ [Task] 252일 기간 duplicate detection 로그 분석 + ├─ [Task] 중복 이벤트 발생률 검증 + └─ [검증] False positive rate < 0.1% 확인 + +2.4.2 DEBT-029: Event Audit Logging + ├─ [Task] outbox/inbox 이벤트 일관성 검증 + ├─ [Task] 재처리 안전성 (idempotency) 검증 + └─ [검증] 모든 이벤트 정상 처리 확인 + +2.4.3 감시 보고서 + ├─ [Report] 감지된 이상 사항 요약 + ├─ [Report] 시스템 안정성 인증 + └─ [Approval] Compliance 팀 서명 +``` + +**성공 기준:** +- Duplicate detection: < 0.1% false positive +- Event processing: 100% success rate +- Compliance 승인 + +--- + +### 2.5 기술부채 최종 검토 +**일정:** 2026-11-10 ~ 2026-11-15 +**담당:** 아키텍처 팀 +**상태:** ⏳ 대기 + +``` +2.5.1 DEBT 현황 검토 + ├─ [Task] DEBT-014/029/030/032/016/024 결제 확인 + ├─ [Task] 미결제 DEBT 식별 및 우선순위 + └─ [검증] 월별 20% 결제 목표 달성 확인 + +2.5.2 DEBT 정리 + ├─ [Task] 미결제 DEBT → 다음 분기 로드맵 이관 + ├─ [Task] TECH_DEBT_REGISTER.md 업데이트 + └─ [Report] DEBT 관리 정책 문서화 + +2.5.3 기술부채 승인 + ├─ [Approval] CTO 최종 검토 + └─ [Approval] Phase 3 진행 승인 서명 +``` + +**성공 기준:** +- 275% DEBT 결제 이력 확인 +- 모든 미결제 DEBT 문서화 +- CTO 서명 + +--- + +## 3️⃣ PHASE 3: Production Deployment + +### 3.1 배포 전 준비 +**일정:** 2026-11-16 ~ 2026-11-19 +**담당:** DevOps 팀 +**상태:** ⏳ 대기 + +``` +3.1.1 환경 준비 + ├─ [Setup] kartsell.taxbaik.com 서버 준비 + ├─ [Setup] PostgreSQL 마이그레이션 계획 + ├─ [Setup] API keys 및 secrets 확보 + └─ [Verify] Sandbox 테스트 완료 + +3.1.2 배포 체크리스트 + ├─ [Checklist] .NET 10 runtime 설치 확인 + ├─ [Checklist] 데이터베이스 백업 계획 + ├─ [Checklist] 롤백 계획 수립 + ├─ [Checklist] 모니터링 대시보드 준비 + └─ [Checklist] Nginx 설정 검증 + +3.1.3 팀 준비 + ├─ [Briefing] 배포 팀 교육 + ├─ [Briefing] 긴급 연락망 확인 + └─ [Briefing] 일정 최종 확인 +``` + +**산출물:** +- 배포 체크리스트 (모두 체크됨) +- 롤백 계획 문서 +- 팀 교육 기록 + +--- + +### 3.2 데이터베이스 마이그레이션 +**일정:** 2026-11-19 (야간) +**담당:** DBA 팀 +**상태:** ⏳ 대기 + +``` +3.2.1 마이그레이션 실행 (야간 진행) + ├─ [Step 1] 기존 DB 전체 백업 + ├─ [Step 2] 0041_create_operation_audit_trail 실행 + ├─ [Step 3] 마이그레이션 검증 (모든 테이블 확인) + └─ [Step 4] Idempotency 재테스트 + +3.2.2 마이그레이션 롤백 준비 + ├─ [Rollback] 백업에서 복구 계획 + ├─ [Rollback] 복구 예상 시간: 30분 + └─ [Verify] 롤백 테스트 (sandbox) + +3.2.3 마이그레이션 로그 + ├─ [Log] 모든 SQL 문 기록 + ├─ [Log] 실행 시간 기록 + └─ [Log] 에러 로그 (있으면) 기록 +``` + +**성공 기준:** +- 마이그레이션 완료 +- 모든 테이블 존재 확인 +- 데이터 무결성 검증 (row count match) + +--- + +### 3.3 애플리케이션 배포 +**일정:** 2026-11-20 (오전 업무 외 시간) +**담당:** DevOps + Engineering +**상태:** ⏳ 대기 + +``` +3.3.1 배포 실행 + ├─ [Deploy] 기존 서비스 중지 + ├─ [Deploy] 새 바이너리 배치 + ├─ [Deploy] 환경 변수 설정 (API keys, DB conn) + ├─ [Deploy] Nginx 재구성 + └─ [Deploy] 새 서비스 시작 + +3.3.2 배포 후 검증 (Smoke Test) + ├─ [Test] HTTP 상태 코드 확인 (200) + ├─ [Test] 인증 엔드포인트 테스트 + ├─ [Test] Shadow Run API 테스트 + ├─ [Test] 데이터베이스 연결 확인 + └─ [Test] 로그 정상 기록 확인 + +3.3.3 배포 로그 + ├─ [Log] 배포 시간 + ├─ [Log] 배포 담당자 + ├─ [Log] 모든 에러 기록 + └─ [Log] 모니터링 메트릭 스냅샷 +``` + +**성공 기준:** +- 서비스 정상 가동 (99.5% uptime) +- API 응답 시간 < 500ms +- 에러율 < 0.1% + +--- + +### 3.4 배포 후 모니터링 (72시간) +**일정:** 2026-11-20 ~ 2026-11-23 +**담당:** SRE 팀 +**상태:** ⏳ 대기 + +``` +3.4.1 실시간 모니터링 (24/7) + ├─ [Monitor] 에러율 추적 + ├─ [Monitor] 응답 시간 추적 + ├─ [Monitor] CPU/메모리 사용률 + ├─ [Monitor] 데이터베이스 연결 풀 + └─ [Monitor] API 호출률 + +3.4.2 매시간 보고서 + ├─ [Report] SLA 준수 여부 + ├─ [Report] 이상 사항 식별 + └─ [Action] 필요 시 즉시 조치 + +3.4.3 문제 해결 (필요시) + ├─ [If Issue] 로그 분석 + ├─ [If Issue] 패치 준비 + └─ [If Issue] 롤백 또는 핫픽스 + +3.4.4 72시간 보고서 + ├─ [Report] 전체 안정성 검증 + ├─ [Report] 성능 메트릭 요약 + └─ [Approval] Go-Live 최종 승인 +``` + +**성공 기준:** +- 99.5% SLA 달성 +- 에러율 < 0.1% +- 응답 시간 < 500ms (p95) +- 최고 경영진 승인 + +--- + +## 4️⃣ PHASE 4: Operations & Continuous Improvement + +### 4.1 월별 기술부채 관리 (첫 달: 2026-11월) +**일정:** 2026-11-24 ~ 2026-11-30 +**담당:** Engineering Lead +**상태:** ⏳ 대기 + +``` +4.1.1 DEBT 식별 + ├─ [Task] 이전 월 DEBT 리스트 검토 + ├─ [Task] 이 달 새로운 DEBT 식별 + └─ [Task] TECH_DEBT_REGISTER.md 업데이트 + +4.1.2 DEBT 결제 (20% 목표) + ├─ [Task] High Impact / Low Effort DEBT 우선 + ├─ [Task] 월별 20% (점수 기준) 결제 실행 + └─ [Verify] 결제 커밋 기록 (git log) + +4.1.3 DEBT 리뷰 회의 + ├─ [Meeting] 완료된 DEBT 리뷰 + ├─ [Meeting] 다음 월 계획 수립 + └─ [Report] 월간 DEBT 리포트 작성 +``` + +**성공 기준:** +- 20% DEBT 결제 달성 +- 모든 DEBT git에 기록됨 +- 리더 승인 + +--- + +### 4.2 분기별 성과 검토 (Q4 2026: 12월) +**일정:** 2026-12-01 ~ 2026-12-31 +**담당:** CTO + 팀 리더 +**상태:** ⏳ 대기 + +``` +4.2.1 성과 지표 수집 + ├─ [Metric] 가용성 (99.5% SLA) + ├─ [Metric] 성능 (응답 시간, throughput) + ├─ [Metric] 품질 (테스트 커버리지, 버그율) + ├─ [Metric] 기술부채 (월별 20% 결제) + └─ [Metric] 비즈니스 (모델 정확도, ROI) + +4.2.2 리스크 평가 + ├─ [Risk] 모니터링 이상 (드리프트, 이상) + ├─ [Risk] 보안 문제 (알려진 CVE) + └─ [Risk] 기술부채 누적 + +4.2.3 Q1 2027 계획 수립 + ├─ [Planning] 새 기능 (auto-learning 검토) + ├─ [Planning] 최적화 (성능, 비용) + └─ [Planning] 운영 개선 (모니터링, 자동화) + +4.2.4 분기별 리포트 + ├─ [Report] 성과 요약 + ├─ [Report] 리스크 및 완화 방안 + ├─ [Report] 개선 기회 + └─ [Approval] 경영진 검토 & 승인 +``` + +**성공 기준:** +- SLA 99.5% 달성 +- DEBT 60% 결제 (3개월) +- 0건의 critical incident +- Q1 계획 수립 완료 + +--- + +## 📊 WBS 요약 (Task Count) + +| Phase | 작업수 | 상태 | 담당 | +|-------|--------|------|------| +| **P1: Execution** | 5 | 🟢 진행중 | 자동화 | +| **P2: Verification** | 16 | ⏳ 대기 | Engineering | +| **P3: Deployment** | 11 | ⏳ 대기 | DevOps | +| **P4: Operations** | 8+ | ⏳ 대기 | SRE | +| **Total** | **40+** | - | - | + +--- + +## 🎯 Critical Path (병렬화 불가) + +``` +Phase 1 (자동, 50-90일) + ↓ +Phase 2 (15일, 병렬 가능) + ├─ 2.1 PBO 검증 + ├─ 2.2 DSR 검증 + ├─ 2.3 OOS 검증 + ├─ 2.4 감시 로그 + └─ 2.5 DEBT 검토 + ↓ +Phase 3 (2일) + ├─ 3.1 배포 준비 + ├─ 3.2 DB 마이그레이션 + ├─ 3.3 앱 배포 + └─ 3.4 모니터링 (72시간) + ↓ +Phase 4 (지속, 월별/분기별) +``` + +**최단 시간:** 50 + 15 + 2 = **67일** (2026-08-11 ~ 2026-10-17) +**최장 시간:** 90 + 15 + 2 = **107일** (2026-08-11 ~ 2026-11-25) + +--- + +**Version:** 1.0 +**Last Updated:** 2026-08-11 +**Owner:** Program Manager +**Status:** ACTIVE