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분마다 자동 (무한)

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

---

## 전제 조건 체크리스트

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

```powershell
# 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 환경 변수 설정 (파워셸)

```powershell
# 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: 데이터베이스 마이그레이션 실행 (선택사항, 이미 완료된 경우 생략)

```powershell
$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 모드)

```powershell
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 터미널**에서:

```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가 실행되는 동안, 별도 터미널에서 자동 모니터링을 시작할 수 있습니다:

```powershell
# 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에서 시작되지 않음

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

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

### PostgreSQL 연결 실패

```powershell
# 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이 응답하지 않음

```powershell
# 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을 시작하세요.