docs: correct WBS tracker and roadmap against verified current state

Both docs were stale relative to 115 commits already on main (VS-03
Approval Workflow, VS-04 Audit Trail, AEG-X-009 live API integration,
Phase 3 J/K/L Sell Decision/Trade Execution/Portfolio Reconciliation),
and repeated an already-corrected false claim that Phase 1 shadow run
was RUNNING.

WBS_PROGRESS_TRACKER.csv:
- AEG-VS-03-01, AEG-VS-04-01: PLANNED/BLOCKED -> COMPLETED, with real
  file paths, commit refs, and isolated test-run counts (20/20, 5/5)
  as evidence.
- AEG-VS-10-01: BLOCKED -> COMPLETED (implementation), with an
  explicit caveat that PBO/DSR production validation is separate and
  still blocked on Phase 1 - not overclaiming past what's verified.
- Added AEG-VS-12-01 (Trade Execution) and AEG-VS-14-01 (Portfolio
  Reconciliation), which had no tracker row at all despite being
  merged to main.
- Flagged a real WBS_ID collision: WBS_MASTER.csv defines VS-03/04/12/14
  as different, unrelated slices (IngestMarketDataPIT, ApplyCorporateActions,
  RankBuyCandidates, GenerateDailyRecommendations). Per user decision,
  kept the tracker's existing IDs and recorded the collision as
  DECISION_REQUIRED on each affected row rather than silently
  renumbering or picking a side.
- Softened AEG-VS-05-01/AEG-X-011/AEG-VS-09-01/AEG-VS-19-01 notes that
  implied Phase 1 was actively counting down ("Job 976, ~50-90 days") -
  corrected to say Phase 1 has not been queued.
- Re-confirmed PHASE-1-SHADOW-RUN unchanged: still no RunId/JobId
  anywhere in this workspace.

CURRENT_ROADMAP.md: full rewrite. Dropped the 2026-08-03 snapshot
content, replaced with what's actually true today, and added a short
"how to re-verify this document" section (check git log divergence,
re-run tests in isolation not just as a full suite, confirm file paths
before writing COMPLETED) aimed at whoever updates this next.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-08-07 23:45:07 +09:00
parent 54b7922167
commit 53be11673c
2 changed files with 72 additions and 268 deletions
+60 -258
View File
@@ -1,285 +1,87 @@
# 🚀 K-ArtSell Aegis v16.0 - 현재 진행 로드맵
**상태:** 95% 완료 (Phase 2-3 구현 완료, Gate 3만 검증 필요)
**마지막 업데이트:** 2026-08-03 02:00 KST
**관리자:** Claude Code + 향후 Codex 연계
**최종 갱신:** 2026-08-07 (이 문서의 이전 버전은 2026-08-03 상태로 정체되어 있었고, 그 사이 병합된 115개 커밋을 반영하지 못했습니다. 이번 갱신은 실제 코드/테스트를 직접 확인한 결과입니다.)
**상태 요약:** VS-03(승인 워크플로우), VS-04(감사 추적), VS-10(매도 결정), VS-12(거래 실행), VS-14(포트폴리오 대사) 백엔드 구현 + 테스트 완료. Phase 1 Shadow Run(Gate 5a, 252+ 거래일 검증)은 **아직 시작되지 않음** (과거 "RUNNING" 기록은 허위였음이 이미 문서로 정정됨). 상세 항목별 상태는 `docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv` 참조.
---
## 📍 Current Sprint (이번 주)
## ⚠️ 알려진 문서 정합성 문제 (DECISION_REQUIRED)
### ✅ 완료 (4개)
#### 1. Idempotency 버그 수정
- **Commit:** 9a2d939
- **파일:** RecommendationReportGenerator.cs, 3x Job classes
- **내용:**
- ADO pattern으로 HasReportBeenSentAsync/MarkReportSentAsync 복구
- Daily/Weekly/Monthly 모든 Job에 idempotency 체크/마크 복구
- CLAUDE.md blocking rule 준수: "No partial success"
- **검증:** Build 0 errors, 모든 Job 테스트됨
#### 2. Serilog Telegram 알림 통합
- **이전 커밋:** (4519fa8)
- **파일:** TelegramSink.cs
- **내용:**
- ERROR/FATAL 로그 → Telegram 자동 발송
- 동기 호출 + 오류 침묵 처리
- Markdown 포맷 + 타임스탬프
#### 3. Daily/Weekly/Monthly Recommendation Reports
- **이전 커밋:** (4519fa8)
- **파일:** 3x Job 클래스 + RecommendationReportGenerator
- **내용:**
- Daily: 09:00 KST 매일
- Weekly: 09:00 KST 토요일 (사용자 요청)
- Monthly: 09:00 KST 1일
- SignalEngine.sell_decisions 집계 + Telegram 발송
#### 4. Phase 1 API 최적화 완료
- **Commit:** eb106d5
- **파일:**
- KrxDataService.cs (exponential backoff)
- TelegramSinkAsync.cs (new, async queue)
- DataBackfiller.cs (30-day batch)
- ApiCallMetricsService.cs (new, 24h metrics)
- Program.cs (TelegramSinkAsync 등록)
- **내용:**
- KRX: 지수 백오프 (100ms → 30s) + X-RateLimit-Remaining 모니터링
- Telegram: 논블로킹 큐, 100ms 간격, 3회 재시도
- DataBackfiller: 252일 → 9회 호출 (97% ↓)
- Metrics: API별 성공/실패/레이턴시/할당량 추적
- **효과:** Shadow run 4분 → 1초 (75% ↓), 신뢰성 ↑
1. **VS 번호 체계 충돌:** `docs/CURRENT/CATALOGS/WBS_MASTER.csv`(원 계획)와 실제 구현/`WBS_PROGRESS_TRACKER.csv`(실행 트래커) 사이에 VS-03/VS-04/VS-12/VS-14 번호가 서로 다른 기능을 가리키는 충돌이 있습니다. 이번 세션에서 발견했고, 사용자 결정에 따라 **기존 트래커 번호를 유지**하고 충돌 사실만 각 행에 명시했습니다. 근본 해결(재번호 부여 또는 WBS_MASTER 공식 대체)은 아직 미결정입니다.
2. **DbUp 마이그레이션 테스트 DB 권한 문제:** `kartsell` DB 사용자가 `kartsell_migration_test` 데이터베이스의 소유자가 아니어서 `DbUpMigrationTests`(12건)가 로컬에서 실패합니다. 코드 문제가 아니라 DBA 조치(소유권 부여)가 필요합니다.
3. **frontend 빌드 산출물 재해시:** `dotnet build`를 실행할 때마다 `pnpm build`가 재실행되어 `wwwroot/assets/*` 해시 파일명이 바뀌고 git에 불필요한 변경이 쌓이는 구조적 문제가 있습니다 (아직 미해결).
---
### ⏳ 진행 중 (1개)
## ✅ 완료 (Backend 구현 + 테스트, 2026-08-07 기준 검증됨)
#### Gate 3: 252+ Trading-Day Shadow Run (리허설)
- **상태:** 🔴 검증 실패 (재시도 필요)
- Run ID: `d14f34ea-2afe-4caf-bbb1-c9a7d74fb582` (생성됨, 미완료)
- Hangfire Job 269: 상태 미확인 (Host 재시작 실패)
- 근본 원인: Hangfire 분산 락 타임아웃 + 가짜 KRX API 키
- **완료된 것:**
- ✅ DB 격리: 테스트 appsettings.Development.json → `kartselldb_test`
- ✅ Host 재시작: Development 환경 (DevelopmentHeaderAuthenticationHandler 활성화)
- ✅ Hangfire 타임아웃 복원력: Program.cs 재시도 로직 추가 (DEBT-015)
- ✅ 실KRX 데이터 서비스: KrxDataService 실연동 (Program.cs 등록)
- ✅ 기술부채 등록: DEBT-009~015 (PBO/DSR/예측/false-exit/타임아웃/감시)
- **현재 제약 사항 (문서화됨):**
- PBO/Sharpe 계산: 간단한 percentile 공식 (정확한 CSCV 방법론 필요 — DEBT-009)
- 모델 예측: 고정 수량 (실제 포지션 사이징 필요 — DEBT-010)
- 비용 2배 시뮬레이션: 선형 공식 (정확한 재시뮬레이션 필요 — DEBT-011)
- False-exit 분석: 미구현 (항상 0 반환 — DEBT-012)
- **필요 조건:**
```bash
# Terminal 1: SSH 터널 (지속)
ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7
# Terminal 2: Host 실행 (Development 환경)
cd D:\JobRoomz\KArtSell.Aegis
$env:ASPNETCORE_ENVIRONMENT = "Development"
dotnet run --project src/KArtSell.Host -c Debug
```
- **실행 단계:**
1. ✅ POST /api/shadow-runs (modelId, windowStart, windowEnd)
2. ✅ 202 Accepted 반환 (Job 269 enqueue)
3. ⏳ Hangfire Worker 처리 중 (Phase 1-5 실행)
4. ⏳ Phase 5 완료 → model_operations.shadow_run 저장
5. ⏳ GET /api/shadow-runs/{runId} → 200 OK (status: Completed)
6. 목적: 데이터 계층 검증 + 실KRX 통합 확인
- **기대 결과 (리허설용):**
- 데이터 파이프라인 동작 확인
- 실KRX 가격 데이터 정상 다운로드
- model_operations.shadow_run 테이블 데이터 쓰기 성공
- 단순화된 분석 메트릭 생성 (프로덕션 검증 아님)
- **순서:** 다음 세션에서 실행
### VS-03: 모델 승인 워크플로우 (Maker-Checker Governance)
- **위치:** `src/KArtSell.Modules.ModelOperations/ApprovalWorkflow/`
- **테스트:** 20/20 PASS (격리 실행 기준)
- **미완료:** 프런트엔드 UI 없음
- **이번 세션에서 발견/수정한 결함:** `ApprovalSql`이 Dapper로 `DateOnly` 파라미터를 바인딩하지 못해 승인 제안서 생성이 실 DB 환경에서 100% 실패하던 버그 — 병합 이후 실 DB로 한 번도 검증되지 않아 발견되지 않고 있었음
### VS-04: 불변 감사 추적 (Audit Trail / GDPR)
- **위치:** `src/KArtSell.Modules.ModelOperations/Compliance/`
- **테스트:** 5/5 PASS (격리 실행 기준)
- **미완료:** 프런트엔드 UI 없음
- **이번 세션에서 발견/수정한 결함:** `ip_address`/`kis_response`류 컬럼의 Dapper 타입 캐스팅 실패, `GdprRetention.RetentionEndsAt``DATE` 컬럼인데 `DateTime`으로 선언되어 있던 문제, 그리고 `KArtSell.BuildingBlocks``[ModuleInitializer]`가 우연히 로드되지 않으면 모든 snake_case 컬럼이 null로 매핑되던 레이스 컨디션
### VS-10: 매도 결정 엔진 (Sell Decision Engine)
- **위치:** `src/KArtSell.Modules.ModelOperations/SellDecision/`, `frontend/src/features/sell-decision/`
- **테스트:** 32/32 PASS (격리 실행 기준)
- **완료도:** Backend + Frontend 모두 존재 (VS-03/04/12/14 중 유일)
- **⚠️ 미검증 사항:** 코드/테스트 완료 ≠ PBO/DSR 프로덕션 검증 완료. 실 시장 데이터 기반 검증은 Phase 1 Shadow Run 완료 후에만 가능
### VS-12: 거래 실행 시스템 (Trade Execution, KIS 연동)
- **위치:** `src/KArtSell.Modules.ModelOperations/TradeExecution/`
- **테스트:** 13/13 PASS (격리 실행 기준)
- **미완료:** 프런트엔드 UI 없음
- **이번 세션에서 발견/수정한 결함 (심각):** `UpdateTradeStatusAsync``status`/`kis_response`/`error_message`만 저장하고 `kis_order_id`, `executed_quantity`, `unit_price`, `commission`, `net_proceeds`, 체결/정산 타임스탬프는 병합 이후 매번 조용히 유실시키던 버그. 거래 체결·정산 데이터가 실제로는 저장되고 있지 않았음
### VS-14: 포트폴리오 대사 (Portfolio Reconciliation)
- **위치:** `src/KArtSell.Modules.ModelOperations/PortfolioReconciliation/`
- **테스트:** 18/18 PASS (격리 실행 기준)
- **미완료:** 프런트엔드 UI 없음
- **참고:** 이 슬라이스가 포함된 PR(#28)이 병합 당일 `model_operations.models` 테이블 누락으로 신규 DB 마이그레이션을 전부 깨뜨리는 채로 병합되었고, 같은 날 별도 PR(#29)로 긴급 수정됨 — 병합 전 fresh-install 리허설이 실제로 이루어지지 않았음을 시사
### AEG-X-009: 외부 데이터 소스 통합 (KRX/OpenDart/KIS)
- **위치:** `src/KArtSell.Modules.ModelOperations/Infrastructure/`, market_data 스키마
- **완료:** 소스 카탈로그/거버넌스 정책(Workstream D/E/F) + 실 API 연동(Workstream G: KRX OpenAPI/OpenDart/KIS 서비스, 일일 스케줄링, 에러 분류, LKG 폴백)
### 그 외 완료 항목 (VS-00 플랫폼 부트스트랩, VS-01/VS-02 슬라이스 스펙, 보안/Outbox/OpenAPI 게이트 등)
상세는 `docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv`의 AEG-X-001~008, AEG-VS-00-01~07, AEG-VS-01-01, AEG-VS-02-01 행 참조.
---
## ✅ 완료됨 (Implemented & Tested)
## 🔴 실제로 블로킹 중인 것 (Phase 1 Shadow Run)
### Phase 2: 중기 최적화
### PHASE-1-SHADOW-RUN: 252+ 거래일 검증 (Gate 5a)
- **상태:** `BLOCKED`**실행 중이 아님**
- **근거:** `docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md`에 이미 정정되어 있음 — 과거 세션들의 "Job 893/976 RUNNING, ~20+시간 경과" 등의 기록은 실제로는 `POST /api/shadow-runs``PostgresException 23514`(check_status 제약조건 위반)로 500 에러를 반환하며 실패한 것이었고, Job이 실제로 시작된 적이 없음
- **차단 사유:** 서버 측 `dataset_manifest`, `model_version_registry`, `evidence_snapshot`, `release_evidence_bundle`에 승인/동결된 행이 없어 RunId/JobId를 생성할 수 없음. 승인된 VersionSet 대기 중
- **재개 절차:** `PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md`의 5단계 참조 (① check_status 제약조건 정합 ② 승인된 테스트 DB에서 fresh/upgrade/재실행/실패복구 리허설 ③ 증거 보존 ④ 명시적 승인 획득 ⑤ 신규 Run ID/Job ID로 재큐잉)
- **이 상태가 바뀌려면:** 실제 RunId/JobId가 존재해야 하며, 문서에 "RUNNING"이라고 다시 적으려면 그 근거를 반드시 명시해야 함 (과거의 허위 기록을 반복하지 말 것)
#### 5. ✅ OpenDart 일일 배치
- **파일:** src/KArtSell.Host/Observability/OpenDartService.cs (186 lines)
- **Job:** OpenDartDailyBatchJob.cs (169 lines)
- **내용:**
- 1,000 req/day 할당량 관리
- 3개월 캐싱 (분기별 재무제표)
- 일 1회 배치 호출만 허용
- **테스트:** 5개 통합 테스트 (OpenDartServiceTests)
- **상태:** ✅ COMPLETE
#### 6. ✅ Gate 4: 승인 워크플로우
- **파일:** GetApprovalQueue/Endpoint.cs, ApproveModel/Handler.cs, RejectModel/Handler.cs
- **내용:**
1. GET /api/approval-queue (대기 중 목록)
2. POST /api/approval/{id}/approve (2명 승인)
3. approved_at / approved_by 타임스탬프 추적
- **테스트:** 32개 통합 테스트
- **상태:** ✅ COMPLETE
#### 7. ✅ KIS Connection Pool
- **파일:** src/KArtSell.Host/Infrastructure/KisConnectionPool.cs (247 lines)
- **내용:**
- 3-5 concurrent connection pool
- OAuth2 token refresh (55분 주기)
- Priority queue (BUY > SELL > CANCEL)
- **테스트:** 2개 통합 테스트 (KisConnectionPoolTests)
- **상태:** ✅ COMPLETE
---
### ✅ Phase 3: 장기 고도화
#### 8. ✅ Central Rate Limiter (모든 API)
- **파일:** src/KArtSell.Host/Infrastructure/RateLimiterService.cs (211 lines)
- **내용:**
- Token bucket pattern (모든 API 통합)
- Per-API quota 추적
- Fairness 보장
- **테스트:** 4개 통합 테스트 (RateLimiterServiceTests)
- **상태:** ✅ COMPLETE
#### 9. ✅ Circuit Breaker Pattern
- **파일:** src/KArtSell.Host/Infrastructure/CircuitBreakerPolicy.cs (180 lines)
- **내용:**
- Polly policy 기반 구현
- 429 에러 3회 → 5분 차단
- 자동 복구 (시간 후)
- **테스트:** 7개 통합 테스트 (CircuitBreakerTests)
- **상태:** ✅ COMPLETE
#### 10. ✅ Gate 5: Observability Dashboard
- **파일:** src/KArtSell.Host/Features/Observability/GetMetricsEndpoint.cs
- **내용:**
- Batch SLA: 작업 완료 시간
- Data quality: 격리된 항목 수
- Duplicate detection: 중복 경고 (DEBT-014)
- Reconciliation: 상태 불일치 (DEBT-014)
- Model drift: OOS 성능 추적
- **테스트:** 6개 통합 테스트 (ObservabilityMetricsTests)
- **상태:** ✅ COMPLETE
---
## 🎯 Production Readiness Gates
| Gate | 항목 | 상태 | 기한 |
|------|------|------|------|
| **1** | DbUp 마이그레이션 (0000-0031) | ✅ PASS | - |
| **2** | Outbox/Inbox Crash-recovery | ✅ PASS | - |
| **3** | 252-day Shadow Run (실KRX) | ⏳ REHEARSAL IN PROGRESS | 오늘 |
| **4** | 승인 워크플로우 | ✅ IMPL (대기) | 이번 주 |
| **5** | 관찰성 대시보드 (메트릭) | ✅ IMPL (대기) | 다음 주 |
**Go-Live 기준:** 모든 Gate PASS + 증거 수집 완료 (≤ 2주)
---
## 📊 진행률
```
Infrastructure: ██████████████████░ 85% (Phase 1 완료, Phase 2-3 진행 중)
Testing: ██████████████████░ 100% (135/135 tests PASS - 5 arch + 95 integration + 35 unit)
Documentation: ████████████░░░░░░░ 60% (로드맵, 계약, ADR, Gate 3 가이드)
Validation Gates: ████████░░░░░░░░░░ 50% (Gate 1-2 PASS, Gate 3 IN PROGRESS, Gate 4-5 준비)
```
---
## 🔄 다음 Iteration
### 이번 루프 (현재, ~60초)
- [ ] Host 준비 확인
- [ ] Agent 1 (Gate 3) 시작 또는 계속 대기
- [ ] Loop 30초마다 상태 모니터링
### Host 준비 후 (오늘, ~30분)
- [ ] Gate 3 Shadow Run 실행
- [ ] 252일 검증 + 메트릭 계산
- [ ] GATE_3_EVIDENCE.md 생성
- [ ] PASS/FAIL 판정
### 다음 주
- [ ] Gate 4: 승인 워크플로우 실행
- [ ] Phase 2: OpenDart + KIS 최적화
- [ ] 증거 수집 완료
### 2주 후
- [ ] Gate 5: 관찰성 대시보드 활성화
- [ ] Production readiness 최종 확인
- [ ] Go-Live 준비
---
## 📝 Codex 연계 방법
### 다른 환경에서 계속하기
1. **현재 커밋 확인**
```bash
git log --oneline -10
# 최신: eb106d5 (Phase 1 API optimization)
# 이전: 9a2d939 (idempotency fix)
# 이전: 4519fa8 (recommendation reports)
```
2. **빌드 & 테스트**
```bash
dotnet build KArtSell.sln -c Release
dotnet test KArtSell.sln -c Release
```
3. **Host 시작 (Gate 3 진행)**
```bash
ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7 # Terminal 1
dotnet run --project src/KArtSell.Host -c Release # Terminal 2
```
4. **Shadow Run 요청**
```bash
curl -X POST http://127.0.0.1:5002/api/shadow-runs \
-H "X-KArtSell-User: gate3-rehearsal" \
-H "X-KArtSell-Role: Researcher" \
-H "Content-Type: application/json" \
-d '{
"modelId": "00000000-0000-0000-0000-000000000001",
"windowStart": "2024-01-02",
"windowEnd": "2024-10-01"
}'
# 폴링 (Analyst 역할 필요)
curl http://127.0.0.1:5002/api/shadow-runs/{runId} \
-H "X-KArtSell-User: gate3-rehearsal" \
-H "X-KArtSell-Role: Analyst"
```
5. **다음 단계로 점프**
- Phase 2 구현 시작 (OpenDart, KIS)
- 로드맵 업데이트
이 게이트는 **달력 시간이 필요한 작업**입니다 (252+ 거래일 시뮬레이션은 컴퓨팅으로 앞당길 수 없음). "최적 전략적으로 빨리 끝내기"의 대상이 될 수 없고, 남은 유일한 실행 가능 조치는 위 재개 절차를 밟아 실제로 큐잉하는 것뿐입니다.
---
## 📚 관련 문서
- **WBS 트래커 (항목별 상세 상태):** `docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv`
- **WBS 원 계획 (번호 충돌 있음, 주의):** `docs/CURRENT/CATALOGS/WBS_MASTER.csv`
- **Phase 1 상태 정정 기록:** `docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md`
- **Architecture:** `docs/03_ARCHITECTURE_BE_FE.md`
- **API Rate Limits:** `docs/API_RATE_LIMIT_STRATEGY.md`
- **Gates:** `PRODUCTION_READINESS.md`
- **Code Guidelines:** `CLAUDE.md`
- **Tech Debt:** `TECH_DEBT_REGISTER.md`
---
## 🔗 Loop 상태
## 📝 이 문서를 다시 갱신할 때
**현재:** `/loop` 30초마다 모니터링 (Host 준비 대기)
**다음:** Host 준비 → Gate 3 자동 시작
**예상:** 오늘 이내 결과
---
**최종 목표:** Production readiness (모든 Gate PASS) ✅
**기한:** 2주 이내 (2026-08-16)
**Status:** ON TRACK 🚀
1. **git log를 먼저 확인하세요.** 이 문서와 `main`이 얼마나 벌어졌는지 (`git log --oneline <이-문서-마지막-커밋>..main`) 확인하지 않고 문서만 읽고 "현재 상태"를 판단하지 마세요.
2. **테스트는 격리 실행으로 확인하세요.** 전체 스위트 실행에서 통과했다고 해서 개별 기능이 안정적으로 통과하는 것은 아닙니다 (이번 세션에서 `AuditSql`이 정확히 이 이유로 놓칠 뻔했습니다 — `--filter`로 단일 클래스만 돌려서 재확인하세요).
3. **"완료"라고 쓰기 전에 실제 파일 경로와 테스트 결과를 직접 확인하세요.** 이 저장소에는 검증 없이 "COMPLETE"/"100%"라고 선언한 문서가 매우 많습니다 (`EXECUTION_COMPLETE_FINAL.md`, `WORK_COMPLETION_CERTIFICATE.md` 등). 그 패턴을 반복하지 마세요.
4. **Phase 1 Shadow Run은 달력 시간 게이트입니다.** 실제로 큐잉되어 진행 중이라는 구체적 증거(RunId/JobId) 없이 "진행 중"이라고 쓰지 마세요.