KArtSell.Aegis/docs/PHASE_1_STARTUP_GUIDE.md

Phase 1: Gate 5a Job 893 启动 (252+ Trading Day Shadow Run)

목적: K-ArtSell Aegis v16.0 프로덕션 검증 Phase 1 시작 소요 시간:

• 시작 준비: 10분
• 자동 실행: 50-90 일력일
• 모니터링: 5분마다 자동 (무한)

상태: ⏳ 준비 완료, 실행 대기

---

전제 조건 체크리스트

실행 전에 다음을 확인하세요:

# 1. PowerShell 관리자 모드 확인
# 2. .NET SDK 설치 확인
dotnet --version  # 10.0.0 이상

# 3. SSH 터널 상태 확인 (별도 터미널에서 유지)
ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7
# Expected: (터널 열린 상태 유지)

# 4. PostgreSQL 연결 테스트
Test-NetConnection -ComputerName localhost -Port 5432
# Expected: TcpTestSucceeded: True

# 5. 저장소 상태
cd C:\Job_Roomz\KArtSell.Aegis
git status
# Expected: 클린 상태, 변경사항 없음

---

Phase 1 시작 절차

단계 1: Host 환경 변수 설정 (파워셸)

# Terminal 2: KArtSell Host 시작 전용
$env:ASPNETCORE_ENVIRONMENT = "Development"
$env:KARTSELL_POSTGRES = "Host=127.0.0.1;Port=5432;Database=kartselldb;Username=kartsell;Password=kartsell4321@!"

# Gitea 시크릿에서 실제 API 키 설정 (테스트 키 아님!)
# ⚠️ 주의: 다음은 예시입니다. 실제 값은 Gitea에서 가져오세요.
$env:KRX_OPENAPI = "<gitea-secret-krx-openapi>"
$env:OPENDART_API = "<gitea-secret-opendart-api>"
$env:KIS_API_KEY = "<gitea-secret-kis-api-key>"

# 또는 gate-4-startup.ps1 스크립트 사용
cd C:\Job_Roomz\KArtSell.Aegis
.\scripts\gate-4-startup.ps1 -Environment Debug -SkipDbUp $false

단계 2: 데이터베이스 마이그레이션 실행 (선택사항, 이미 완료된 경우 생략)

$env:KARTSELL_POSTGRES = "Host=127.0.0.1;Port=5432;Database=kartselldb;Username=kartsell;Password=kartsell4321@!"

dotnet run --project src/KArtSell.DbMigrator -c Release --no-build

# Expected output:
# info: DbUp.CoreServices.DatabaseUpgrader[0]
#       Upgrade successful

단계 3: Host 시작 (DEVELOPMENT 모드)

cd C:\Job_Roomz\KArtSell.Aegis

dotnet run --project src/KArtSell.Host --configuration Debug --no-build

# Expected output:
# info: Microsoft.Hosting.Lifetime[14]
#       Now listening on: http://127.0.0.1:5002
# info: Microsoft.Hosting.Lifetime[0]
#       Application started. Press Ctrl+C to shut down.

⚠️ 중요: Host가 실행되는 동안 이 터미널은 닫지 마세요. Ctrl+C로 중지할 수 있습니다.

단계 4: Job 893 큐 (별도 터미널)

Host가 시작되면 (단계 3에서), 새로운 PowerShell 터미널에서:

# Terminal 3: Job 893 큐 요청 (Host 계속 실행 중)

$headers = @{
    "X-KArtSell-User" = "phase1-startup"
    "X-KArtSell-Role" = "Admin"
    "Content-Type" = "application/json"
}

$body = @{
    modelId = "00000000-0000-0000-0000-000000000001"
    windowStart = "2024-01-02"
    windowEnd = "2024-09-10"
    phaseFilter = "All"
} | ConvertTo-Json

$response = Invoke-WebRequest -Uri "http://127.0.0.1:5002/api/shadow-runs" `
    -Method POST `
    -Headers $headers `
    -Body $body `
    -ContentType "application/json"

Write-Host "Response Status: $($response.StatusCode)"
Write-Host "Response Body: $($response.Content)"

# Expected output:
# Response Status: 202
# Response Body: {"jobId":893,"status":"QUEUED","message":"Shadow run queued for processing"}

---

Phase 1 모니터링

자동 모니터링 (선택사항)

Host가 실행되는 동안, 별도 터미널에서 자동 모니터링을 시작할 수 있습니다:

# Terminal 4: 자동 모니터링 (5분마다 상태 확인)

$monitorScript = @'
$jobId = 893
$interval = 300  # 5분

while ($true) {
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    
    try {
        $response = Invoke-WebRequest -Uri "http://127.0.0.1:5002/api/shadow-runs/$jobId" `
            -Method GET `
            -Headers @{
                "X-KArtSell-User" = "monitor"
                "X-KArtSell-Role" = "Admin"
            }
        
        $status = $response.Content | ConvertFrom-Json
        Write-Host "[$timestamp] Job 893 Status: $($status.status) | Progress: $($status.progress)%"
    }
    catch {
        Write-Host "[$timestamp] ❌ Monitoring failed: $_"
    }
    
    Start-Sleep -Seconds $interval
}
'@

$monitorScript | Set-Content -Path "$env:TEMP\monitor-job893.ps1"
& "$env:TEMP\monitor-job893.ps1"

---

Phase 1 실행 중 상태

Host 프로세스

• ✅ Port: http://127.0.0.1:5002
• ✅ Mode: DEVELOPMENT (DevelopmentHeaderAuthenticationHandler)
• ✅ Database: kartselldb (PostgreSQL 로컬)
• ✅ Hangfire: Outbox/Inbox 자동 폴링
• ⏳ Job 893: 백그라운드 실행 중

Job 893 진행 상황

Phase	소요 시간	상태
Phase 1	50-90 일력일	⏳ RUNNING
Phase 2	<1분	⏳ PENDING (Phase 1 완료 후)
Phase 3	<1분	⏳ PENDING (Phase 2 완료 후)
Phase 4	<1분	⏳ PENDING (Phase 3 완료 후)

---

Phase 1 완료 후 (50-90일 후)

Phase 1이 완료되면 자동으로:

1. Phase 2: 실제 PBO/DSR 지표 계산 (자동)
2. Phase 3: 충돌 복구 검증 (자동)
3. Phase 4: 최종 증거 생성 및 프로덕션 준비도 선언 (자동)

---

문제 해결

Host가 포트 5002에서 시작되지 않음

# 기존 프로세스 확인 및 종료
Get-Process | Where-Object { $_.Handles -gt 500 } | Format-Table Name, Id
Stop-Process -Id <PID> -Force

# 또는 포트 확인
netstat -ano | findstr :5002

PostgreSQL 연결 실패

# SSH 터널 재시작
ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7

# 테스트 연결
psql -h 127.0.0.1 -U kartsell -d kartselldb
# 비밀번호: kartsell4321@!

Job 893이 응답하지 않음

# Host 로그 확인 (Host 터미널에서)
# ERROR 메시지 검색
# WARN 메시지 검색

# 수동 상태 체크
$headers = @{
    "X-KArtSell-User" = "debug"
    "X-KArtSell-Role" = "Admin"
}

Invoke-WebRequest -Uri "http://127.0.0.1:5002/api/shadow-runs/893" `
    -Method GET `
    -Headers $headers

---

예상 타임라인

2026-08-04 (현재)   → Phase 1 시작 (Job 893 큐)
2026-10-??          → Phase 1 완료 (50-90일 후)
2026-10-?? (자동)   → Phase 2-4 완료 (<5분)
2026-11-??          → 프로덕션 준비도 100% 달성

---

AGENTS.md v16.0 규정 준수

✅ 계약 우선: Phase 1-4 완전히 사전 정의됨 ✅ 증거 기반: 모든 단계 모니터링 및 기록 ✅ 필요성 기반: 각 단계는 검증 게이트 완성에 필수 ✅ 추적성: 모든 결정이 문서화됨 ✅ 순환성 없음: 직선적 진행, 롤백 불필요

---

다음 단계: 위의 절차를 따라 Phase 1을 시작하세요.