kjh2064/QuantEngineByItz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: root 경로의 미사용/과거 문서 및 스크립트를 docs/ 하위로 정리 격리
WBS-9.3 - NULL Policy CI Gate / NULL Policy Validation (pull_request) Failing after 4s
Details
Quant Engine CI/CD Pipeline / validate-core (pull_request) Failing after 2m15s
Details
Quant Engine CI/CD Pipeline / validate-ui-and-storage (pull_request) Has been skipped
Details

Browse Source
This commit is contained in:
김재현
2026-06-26 11:35:42 +09:00
parent 6051338367
commit 15c7971018
16 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/archive/CI_CD_PIPELINE.md
+471
View File
@@ -0,0 +1,471 @@
# 🚀 Quant Engine CI/CD Pipeline
**버전**: v9 Hardening Release
**CI/CD 시스템**: Gitea Actions
**배포 대상**: 178.104.200.7 (production)
**배포 브랜치**: `main`
---
## 📋 파이프라인 구조
```
┌─────────────────────────────────────────────────────────────┐
│ 1. Code Push to main Branch │
│ (또는 workflow_dispatch 수동 실행) │
└────────────────────┬────────────────────────────────────────┘
↓
┌───────────────────────┐
│ CI: build-and-test │
├───────────────────────┤
│ ✓ Checkout code │
│ ✓ Setup .NET 10 │
│ ✓ Run validations │
│ ✓ Restore deps │
│ ✓ Build Release │
│ ✓ Run unit tests │
│ ✓ Publish package │
│ ✓ Create archive │
│ ✓ Upload artifact │
└───────────┬───────────┘
│ (성공 시)
↓
┌───────────────────────┐
│ CD: deploy-to-prod │
├───────────────────────┤
│ ✓ Download artifact │
│ ✓ Setup SSH │
│ ✓ Create backup │
│ ✓ Deploy package │
│ ✓ Extract/install │
│ ✓ Restart services │
│ ✓ Health check │
│ ✓ Verify deployment │
│ ✓ Generate report │
└───────────┬───────────┘
│ (성공 시)
↓
┌───────────────────────┐
│ Post-Deployment │
├───────────────────────┤
│ ✓ Performance check │
│ ✓ Create checklist │
│ ✓ Notify (Slack) │
└───────────────────────┘
```
---
## 🔄 워크플로우 상세
### Step 1: CI Build and Test
**파일**: `.gitea/workflows/ci.yml` (기존)
**실행 조건**: `push main` 또는 `pull_request main`
```yaml
# 자동 실행 트리거
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
# 검증 항목
- Python spec validation
- Formula registry validation
- Golden case coverage
- Harness coverage audit
- Qualitative sell strategy validation
```
---
### Step 2: CD Deploy to Production
**파일**: `.gitea/workflows/deploy-prod.yml` (신규)
**실행 조건**: `push main` (CI 통과 후)
#### 2.1 Build Release Package
```yaml
- Setup .NET 10.0.x
- Run core validations (CI 게이트)
- Restore dependencies
- Build Release (-c Release)
- Run unit tests
- Publish package
- Create .tar.gz archive
```
**산출물**: `quant-engine-release-{run_number}.tar.gz` (24MB)
#### 2.2 Deploy to Production
```yaml
- Setup SSH authentication
- Create backup (/var/www/quant_backup/)
- Transfer archive via SCP
- Extract to /var/www/quant/publish
- Set permissions (www-data:www-data)
- Restart nginx service
```
#### 2.3 Health Check & Verification
```yaml
- HTTP 200 OK 확인
- MudBlazor 리소스 로드 확인
- Page title 검증
- 배포 리포트 생성
```
#### 2.4 Post-Deployment
```yaml
- Performance metrics 수집
- Page load time 측정
- Deployment checklist 생성
- Slack 알림 (옵션)
```
---
## 🔐 Secrets & Environment Variables
### 필수 Gitea Secrets
```yaml
SSH_PRIVATE_KEY:
- 설명: SSH 개인 키 (id_ed25519)
- 형식: PEM format
- 권한: 600
- 생성: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
SLACK_WEBHOOK (선택사항):
- 설명: Slack 배포 알림
- 형식: https://hooks.slack.com/services/...
- 용도: 배포 완료 알림
```
### 환경 변수
```yaml
DEPLOY_HOST: 192.168.123.100
# 설명: 운영서버 내부 IP (Gitea와 같은 원격 서버)
# Gitea에서 배포할 때는 내부 IP로 SSH 연결
# 외부 사용자는 178.104.200.7 (공인 IP)로 접속
DEPLOY_USER: kjh2064
DEPLOY_PATH: /var/www/quant
DOTNET_VERSION: 10.0.x
```
### 네트워크 구조
```
원격 서버 (178.104.200.7)
┌──────────────────────────────────────────────┐
│ 내부 네트워크: 192.168.123.100 │
│ ┌────────────────────────────────────────┐ │
│ │ ├─ Gitea (CI/CD) │ │
│ │ └─ 운영서버 (nginx, 웹 서비스) │ │
│ │ └─ /var/www/quant/publish │ │
│ └────────────────────────────────────────┘ │
│ 포트포워딩: 80/443 → 내부:80 │
└──────────────────────────────────────────────┘
↑
│
공인 IP 178.104.200.7
↑
인터넷 (사용자)
CI/CD 배포 경로:
Gitea (192.168.123.100)
→ SSH (내부, 안전 & 빠름)
→ 운영서버 (192.168.123.100)
외부 사용자 접속:
브라우저 → 178.104.200.7
→ nginx 포트포워딩
→ localhost:80 → /var/www/quant/publish/quant/
```
---
## 📊 배포 프로세스 상세 (시간별)
```
┌─────────────┬──────────┬────────────────────────────────────┐
│ 단계 │ 소요시간 │ 설명 │
├─────────────┼──────────┼────────────────────────────────────┤
│ CI 검증 │ ~3분 │ Spec/Registry/Coverage 검증 │
│ 빌드 │ ~2분 │ Release 빌드 (.NET) │
│ 테스트 │ ~1분 │ Unit tests 실행 │
│ 패키징 │ <1분 │ Archive 생성 (24MB) │
├─────────────┼──────────┼────────────────────────────────────┤
│ SSH 준비 │ <1분 │ SSH 키 설정 │
│ 백업 생성 │ ~1분 │ /var/www/quant_backup/ 생성 │
│ 파일 전송 │ ~2분 │ rsync (24MB) │
│ 추출/설치 │ <1분 │ tar 추출, 권한 설정 │
│ 재시작 │ ~3초 │ nginx restart │
│ 헬스 체크 │ ~5초 │ HTTP 200 OK 확인 (최대 60초) │
├─────────────┼──────────┼────────────────────────────────────┤
│ 총 소요시간 │ ~10분 │ CI부터 배포 완료까지 │
└─────────────┴──────────┴────────────────────────────────────┘
```
---
## ✅ 배포 체크리스트
### 배포 전 (개발자)
```
[ ] 모든 변경사항 커밋
[ ] main 브랜치에 push
[ ] CI 검증 통과 대기 (~5분)
```
### 배포 중 (자동화)
```
Gitea Actions:
[ ] build-and-test job 실행
[ ] 모든 검증 통과
[ ] Release 빌드 생성 (24MB)
[ ] 아티팩트 저장
[ ] deploy-to-prod job 시작
[ ] SSH 연결 성공
[ ] 백업 생성
[ ] 파일 전송
[ ] 권한 설정
[ ] 서비스 재시작
[ ] 헬스 체크 통과
```
### 배포 후 (운영자)
```
[ ] Dashboard 접속 확인 (http://178.104.200.7/quant/)
[ ] KPI 카드 렌더링 확인
[ ] MudBlazor 스타일 적용 확인
[ ] 모든 테이블 표시 확인
[ ] 로그 에러 없음 확인 (nginx)
[ ] 성능 메트릭 양호 확인
```
---
## 🔄 배포 프로세스 트리거
### 자동 배포 (권장)
```bash
# main 브랜치에 push
git push origin feature/dotnet-migration:main
# → Gitea Actions 자동 실행
# → CI/CD 파이프라인 시작
# → ~10분 후 배포 완료
```
### 수동 배포 (긴급)
```bash
# Gitea 웹 UI에서:
# Actions → deploy-prod → Run workflow
# 또는 CLI:
# (Gitea CLI 설정 필요)
```
---
## 🚨 실패 시 대응
### 빌드 실패
```
원인: 컴파일 오류
해결:
1. Gitea Actions 로그 확인
2. 로컬에서 재현: dotnet build -c Release
3. 오류 수정 및 커밋
4. main에 push
```
### 배포 실패
```
원인: SSH 연결 오류, 디스크 부족 등
해결:
1. SSH 키 확인: secrets.SSH_PRIVATE_KEY
2. 원격 서버 디스크 확인: df -h
3. nginx 상태 확인: systemctl status nginx
4. 필요시 수동 복구 (아래 참고)
```
### 빠른 복구 (롤백)
```bash
# 이전 버전으로 복원
ssh kjh2064@178.104.200.7 << 'EOF'
LATEST=$(ls -t /var/www/quant_backup | head -1)
sudo cp -r /var/www/quant_backup/$LATEST/* /var/www/quant/publish/
sudo systemctl restart nginx
echo "✅ Rolled back to: $LATEST"
EOF
```
---
## 📈 모니터링 & 로깅
### Gitea Actions 로그
```
Gitea 웹 UI:
1. Repository → Actions
2. deploy-prod workflow
3. Latest run 클릭
4. Job 상세 로그 확인
```
### nginx 로그 (실시간)
```bash
# SSH로 접속
ssh kjh2064@178.104.200.7
# 에러 로그
sudo tail -f /var/log/nginx/error.log
# 접근 로그
sudo tail -f /var/log/nginx/access.log
# 상태 확인
sudo systemctl status nginx
```
### 배포 리포트
```
Gitea Actions 아티팩트:
- quant-engine-release-{run}.tar.gz
- deployment-report.txt
- post-deployment-checklist.txt
```
---
## 🔑 SSH 키 설정 (최초 1회)
### 1. 로컬에서 키 생성
```bash
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
```
### 2. 공개 키를 원격 서버에 등록
```bash
ssh-copy-id -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7
```
### 3. Gitea Secrets에 개인 키 등록
```bash
# Gitea 웹 UI:
# Repository → Settings → Secrets → SSH_PRIVATE_KEY
# 내용: cat ~/.ssh/id_ed25519 (전체 복사)
```
### 4. 테스트
```bash
# 비밀번호 없이 접속 확인
ssh kjh2064@178.104.200.7 "echo '✅ SSH 연결 성공'"
```
---
## 📊 배포 통계
```
예상 배포 시간: ~10분
Release 패키지 크기: 24MB
백업 보관 기간: 30일 (최신 5개)
배포 이력: Gitea Actions에서 확인 가능
배포 실패율: < 5% (네트워크 오류 제외)
복구 시간: < 2분 (롤백)
```
---
## 🎯 배포 프로세스 요약
| 단계 | 담당 | 시간 | 상태 |
|------|------|------|------|
| Push to main | 개발자 | 1초 | 수동 |
| CI 검증 | Gitea Actions | 5분 | 자동 |
| Build Release | Gitea Actions | 2분 | 자동 |
| Deploy to Prod | Gitea Actions | 3분 | 자동 |
| Health Check | Gitea Actions | 1분 | 자동 |
| **총계** | | **~10분** | **자동** |
---
## 🔗 관련 파일
```
.gitea/workflows/
├── ci.yml (기존 CI 검증)
└── deploy-prod.yml (신규 배포 파이프라인)
배포 관련 문서:
├── DEPLOYMENT_GUIDE.md
├── DEPLOYMENT_STEPS.md
└── DEPLOYMENT_CHECKLIST.md
```
---
## ✨ 주요 기능
### 자동화
- ✅ 코드 푸시 → 자동 빌드/테스트/배포
- ✅ 실패 시 자동 알림 (Slack)
- ✅ 자동 백업 및 롤백 준비
### 안전성
- ✅ SSH 키 기반 인증
- ✅ 자동 백업 (5개 유지)
- ✅ 롤백 명령어 제공
- ✅ 헬스 체크 (최대 60초)
### 가시성
- ✅ Gitea Actions 로그
- ✅ 배포 리포트 생성
- ✅ Post-deployment 체크리스트
- ✅ Slack 알림 (옵션)
---
## 🚀 배포 시작
### 시작 방법
```bash
# 1. 로컬 변경사항 커밋
git add .
git commit -m "feat: v9 hardening release with CI/CD"
# 2. main 브랜치에 푸시
git push origin feature/dotnet-migration:main
# 3. Gitea Actions 자동 실행
# → 약 10분 후 배포 완료
# → http://178.104.200.7/quant/ 접속 가능
```
---
**배포는 이제 CI/CD를 통해서만 수행됩니다.**
모든 배포가 자동화되고, Gitea Actions에서 전체 프로세스가 추적됩니다. 🎉
docs/archive/DEPLOYMENT_CHECKLIST.md
+292
View File
@@ -0,0 +1,292 @@
# 🚀 Quant Engine v9 Deployment Checklist
**상태**: 2026-06-25 배포 준비 완료
**목표**: honest_proof_score 56.57 → 95.0
**기간**: 6주 (2026-06-25 ~ 2026-08-10)
---
## ✅ Phase 0: 사전 준비 (완료)
### 코드 구현
- [x] **P3 손절 체계** — `spec/exit/stop_loss.yaml`
- calcAbsoluteRiskStopV1_
- calcRelativeUnderperfAlertV1_
- calcStopActionLadderV1_
- [x] **P4 라우팅** — `spec/xx_routing_contract.yaml`
- buildRoutePacket_ (SCALP/SWING/MOMENTUM/POSITION)
- [x] **P5 뒷북 차단** — `spec/exit/pre_distribution_gate.yaml`
- calcAlphaLeadV1_
- calcDistributionRiskV1_
- [x] **P6 현금확보** — `spec/exit/cash_recovery.yaml`
- calcCashRecoveryOptimizerV1_
### UI/UX
- [x] MudBlazor 6.10.0 추가 (QuantEngine.Web.csproj)
- [x] Dashboard.razor — Material Design 레이아웃
- [x] MainLayout.razor — 반응형 AppBar + Drawer
- [x] NavMenu.razor — Material Icons 네비게이션
- [x] App.razor — MudThemeProvider 통합
### 빌드
- [x] Release 빌드: `dotnet publish -c Release`
- [x] 결과: `src/dotnet/QuantEngine.Web/publish/` (24MB, 172개 파일)
- [x] 모든 컴파일 에러 해결
---
## 🚀 Phase 1: 배포 (지금 진행)
### 1.1 웹 서버 배포
```bash
# 실행 방법
chmod +x deploy.sh
./deploy.sh
```
**배포 스크립트 단계:**
- [ ] SSH 연결 확인 (178.104.200.7)
- [ ] 원격 백업 생성 (`/var/www/quant_backup_*`)
- [ ] 파일 전송 (rsync, 24MB)
- [ ] 권한 설정 (www-data:www-data)
- [ ] nginx 재시작
- [ ] HTTP 상태 확인 (200 OK)
**확인 URL:**
```
http://178.104.200.7/quant/
```
### 1.2 GAS 배포
#### Step 1: Google Apps Script 프로젝트 생성
```
1. Google Drive → 새로 만들기 → Google Apps Script
2. 프로젝트명: "Quant Engine Data Feed"
3. 스크립트 저장
```
#### Step 2: 함수 추가
```javascript
// 다음 파일들의 내용을 복사해서 GAS에 붙여넣기:
// - src/google_apps_script/gas_data_feed.gs (P3~P6 함수)
// - src/google_apps_script/live_outcome_ledger.gs (신호 추적)
```
#### Step 3: 스프레드시트 연동
```
1. 새 스프레드시트 생성: "live_outcome_ledger"
2. LEDGER_SHEET_ID 변수 업데이트 (live_outcome_ledger.gs)
3. initializeLedger_() 실행 → 헤더 자동 생성
```
#### Step 4: 테스트
```javascript
// GAS 콘솔에서 실행
testLiveOutcomeLedger();
// 또는 개별 테스트
testP3Functions();
```
**체크리스트:**
- [ ] GAS 프로젝트 생성 완료
- [ ] gas_data_feed.gs 파일 추가 (7개 함수)
- [ ] live_outcome_ledger.gs 파일 추가 (신호 추적)
- [ ] LEDGER_SHEET_ID 설정 (스프레드시트 ID)
- [ ] initializeLedger_() 실행
- [ ] 테스트 함수 통과
### 1.3 데이터베이스 연결 확인
```bash
# SSH 접속 후
ssh kjh2064@178.104.200.7
# PostgreSQL 연결 확인
psql -h 127.0.0.1 -U gitea -d giteadb
```
**체크리스트:**
- [ ] PostgreSQL 실행 중
- [ ] giteadb 데이터베이스 존재
- [ ] quantengine schema 존재
---
## 📊 Phase 2: 실전 운영 (6주)
### Week 1-2: 기초 구축 (2026-06-25 ~ 2026-07-08)
**목표**: 6-8개 신호 수집
**매일 해야 할 일:**
- [ ] 신호 발생 → `addSignal_(signal)` 호출
- [ ] 또는 스프레드시트 "live_outcome_ledger"에 직접 입력
**주간 금요일 (매주):**
- [ ] `calculateStats_()` 실행
- [ ] win_rate 확인 (목표: >= 60%)
- [ ] 주간 리포트 작성 (docs/DAILY_SIGNAL_TRACKING.md 참고)
**체크리스트:**
- [ ] Week 1: 3-4개 신호
- [ ] Week 2: 3-4개 신호 (누적 6-8개)
- [ ] 승률 >= 50% 유지
### Week 3-4: T+20 수집 (2026-07-09 ~ 2026-07-22)
**목표**: 추가 8-10개 신호 + T+20 데이터 수집 시작
**매일:**
- [ ] 신규 신호 기록
- [ ] T+20 도달한 신호 `updatePriceT20_(signalId, priceT20)` 호출
**T+20 가격 수집:**
```python
# KIS API, Yahoo Finance 등에서 자동 수집
# 또는 수동으로 스프레드시트 입력
# 자동으로 계산됨:
# - return_pct_t20
# - outcome (WIN/LOSS/BREAKEVEN)
# - win_margin
# - validation_status: PROVISIONAL
```
**체크리스트:**
- [ ] Week 3: 4-5개 신호
- [ ] Week 4: 4-5개 신호 (누적 14-18개)
- [ ] T+20 데이터 6-8개 수집
- [ ] 완료된 신호 승률 >= 60%
### Week 5-6: 데이터 수렴 (2026-07-23 ~ 2026-08-05)
**목표**: 추가 8-10개 신호 + 30개 근처
**매일:**
- [ ] 신규 신호 기록
- [ ] T+20 데이터 입력 (완료)
**대량 수렴:**
```javascript
// 주간 실행
stats = calculateStats_();
Logger.log(`승률: ${stats.win_rate}%, 완료: ${stats.completed}/30`);
```
**체크리스트:**
- [ ] Week 5: 4-5개 신호
- [ ] Week 6: 4-5개 신호 (누적 22-28개)
- [ ] 전체 승률 >= 60%
### Week 7: CALIBRATED 전환 (2026-08-06 ~ 2026-08-10)
**목표**: 30개 완료 + CALIBRATED 전환
**최종 신호:**
- [ ] 마지막 2-8개 신호 수집
- [ ] T+20 데이터 완료
**CALIBRATED 전환 실행:**
```javascript
// 조건 확인
check = checkCalibrationReady_();
Logger.log(JSON.stringify(check, null, 2));
// 조건 충족 시
calibrateIfReady_();
```
**체크리스트:**
- [ ] 신호 누적: 30개 완료
- [ ] 승률: >= 60% (30개 중 최소 18개 WIN)
- [ ] avg_win_margin >= 2.0%
- [ ] PROVISIONAL → CALIBRATED 전환
- [ ] honest_proof_score 업데이트 (95.0 달성)
---
## 🎯 최종 목표
### honest_proof_score 개선
```
현재: 56.57
├─ P0 완료: +10점 → 66.57
├─ P2 샘플: +20점 → 86.57
└─ P3~P6: +8점 → 94.57 ≈ 95.0 ✅
```
### 배포 완료 조건
- [x] Release 빌드 성공
- [x] 명세 파일 (P3~P6 YAML)
- [x] GAS 함수 구현 (7개)
- [x] 배포 스크립트 작성
- [x] 신호 추적 시스템 (GAS)
- [ ] 웹 서버 배포 실행
- [ ] GAS 프로젝트 배포 실행
- [ ] 30개 신호 수집 (6주)
- [ ] CALIBRATED 전환
- [ ] honest_proof_score 95.0 달성
---
## 📝 추가 작업
### 배포 후 확인
```bash
# 웹사이트 접속
curl -I http://178.104.200.7/quant/
# 로그 모니터링
ssh kjh2064@178.104.200.7
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log
# 백업 위치
/var/www/quant_backup_YYYYMMDD_HHMMSS/
```
### 문제 해결
| 문제 | 해결법 |
|------|--------|
| HTTP 503 | 앱이 시작 중. 몇 초 후 재시도 |
| HTTP 404 | nginx 설정 확인 (`/etc/nginx/sites-available/quant`) |
| SSH 연결 실패 | SSH 키 확인 (`~/.ssh/id_ed25519`) |
| 성능 저하 | 데이터베이스 연결 확인, 로그 분석 |
### 모니터링
```bash
# 일일 헬스 체크 (cron)
0 9 * * * curl http://178.104.200.7/quant/ > /dev/null 2>&1
# 주간 리포트 (GAS 자동화)
# 매주 금요일 18:00 실행:
# - calculateStats_()
# - 이메일 발송
```
---
## 🔗 관련 문서
- `V9_HARDENING_IMPLEMENTATION_ROADMAP.md` — 전체 로드맵
- `docs/DAILY_SIGNAL_TRACKING.md` — 일일 추적 가이드
- `deploy.sh` — 배포 스크립트
- `src/google_apps_script/gas_data_feed.gs` — GAS 함수
- `src/google_apps_script/live_outcome_ledger.gs` — 신호 추적
---
**작성일**: 2026-06-25
**최후 수정**: 2026-06-25
**다음 체크**: 2026-07-04 (Phase 2 Week 1 마감)
docs/archive/DEPLOYMENT_GUIDE.md
+374
View File
@@ -0,0 +1,374 @@
# 🚀 Quant Engine Deployment Guide
**생성**: 2026-06-25
**버전**: v9 Hardening Release
**패키지 크기**: 24MB
**배포 대상**: 178.104.200.7 (원격) 또는 로컬
---
## 📦 배포 전 체크리스트
### ✅ 준비된 항목
```
[x] Release 빌드 완료 (24MB)
[x] MudBlazor UI 완성 (91/100 평가)
[x] Dashboard 고도화 (KPI + 시장현황 + 성과 + 알고리즘 + 신호)
[x] Program.cs 수정 (AddMudServices 추가)
[x] 배포 스크립트 준비 (deploy.sh)
[x] Playwright 테스트 통과
[x] git 커밋 완료
```
### 📍 배포 패키지
```
위치: src/dotnet/QuantEngine.Web/publish/
크기: 24MB
파일: 172개
구성:
├── DLL 파일 (10개)
│ ├── QuantEngine.Web.dll (60KB)
│ ├── QuantEngine.Core.dll (28KB)
│ ├── QuantEngine.Application.dll (4KB)
│ ├── QuantEngine.Infrastructure.dll (61KB)
│ ├── MudBlazor.dll (8.7MB) ✨
│ ├── Npgsql.dll (1.5MB)
│ ├── Dapper.dll (242KB)
│ └── 기타
├── 정적 자산 (wwwroot/)
│ ├── CSS (MudBlazor)
│ ├── JS (Blazor Runtime)
│ └── 이미지/폰트
└── 설정 파일
├── appsettings.json
├── runtimeconfig.json
└── deps.json
```
---
## 🌐 배포 옵션
### Option 1: 원격 배포 (권장)
#### 전제 조건
```
✓ SSH 키: ~/.ssh/id_ed25519
✓ 원격 서버: 178.104.200.7
✓ 사용자: kjh2064
✓ nginx 설치 완료
```
#### 실행 명령
```bash
cd /c/Temp/data_feed
chmod +x deploy.sh
./deploy.sh
```
#### 배포 과정
```
1. SSH 연결 확인 (10초)
2. 원격 백업 생성 (/var/www/quant_backup_*)
3. 파일 전송 (rsync, 24MB ~ 1분)
4. 권한 설정 (www-data:www-data)
5. nginx 재시작
6. 헬스 체크 (HTTP 200 확인)
```
#### 성공 시 접속
```
URL: http://178.104.200.7/quant/
```
---
### Option 2: 로컬 배포 (개발/테스트)
#### 웹 서비스 실행
```bash
cd src/dotnet/QuantEngine.Web
dotnet QuantEngine.Web.exe
```
#### 접속
```
URL: http://localhost:5265
```
---
### Option 3: IIS 배포 (Windows 전용)
#### 1단계: 호스팅 번들 설치
```
.NET 10.0 Hosting Bundle for IIS
다운로드: https://dotnet.microsoft.com/download/dotnet
```
#### 2단계: IIS 사이트 생성
```
Site Name: Quant Engine
Physical Path: C:\var\www\quant\publish
Protocol: HTTP
Port: 80
```
#### 3단계: 응용 프로그램 풀 설정
```
.NET 런타임 버전: 10.0
파이프라인 모드: Integrated
관리 사용자: ApplicationPoolIdentity
```
#### 4단계: 배포 패키지 복사
```powershell
Copy-Item -Path "src/dotnet/QuantEngine.Web/publish/*" `
-Destination "C:\var\www\quant\publish" `
-Recurse -Force
```
#### 5단계: IIS 재시작
```powershell
net stop IISADMIN
net start IISADMIN
```
---
## 🔧 배포 후 확인
### 1. 웹 서비스 상태
```bash
# HTTP 상태 확인
curl -I http://178.104.200.7/quant/
# 기대 결과:
# HTTP/1.1 200 OK
# Content-Type: text/html
```
### 2. 로그 모니터링
```bash
# SSH 접속
ssh kjh2064@178.104.200.7
# nginx 에러 로그
sudo tail -f /var/log/nginx/error.log
# nginx 접근 로그
sudo tail -f /var/log/nginx/access.log
# 애플리케이션 로그 (있으면)
sudo journalctl -u quant-engine -f
```
### 3. 성능 테스트
```bash
# 페이지 로드 시간
time curl http://178.104.200.7/quant/ > /dev/null
# 동시 연결 테스트 (100 users)
ab -n 100 -c 10 http://178.104.200.7/quant/
```
### 4. 기능 검증
```
✓ Dashboard 페이지 로드
✓ KPI 카드 표시
✓ 성과 메트릭 렌더링
✓ 알고리즘 테이블 표시
✓ 신호 피드 업데이트
✓ MudBlazor 스타일 적용
✓ 반응형 레이아웃 (모바일/태블릿/데스크톱)
```
---
## 📊 배포 체크리스트
### 전 배포
```
[ ] Release 빌드 성공 확인
[ ] appsettings.json 데이터베이스 연결 확인
[ ] SSH 키 권한 확인 (chmod 600)
[ ] nginx 설정 확인
[ ] 방화벽 포트 확인 (HTTP 80, HTTPS 443)
[ ] SSL 인증서 확인 (필요시)
```
### 배포 중
```
[ ] deploy.sh 실행
[ ] 파일 전송 진행 상황 모니터링
[ ] 권한 설정 확인
[ ] nginx 재시작 확인
```
### 배포 후
```
[ ] 웹 서비스 접속 확인
[ ] HTTP 상태 200 확인
[ ] 로그 에러 확인
[ ] 성능 메트릭 확인
[ ] 기능 테스트 완료
[ ] 모바일 반응형 확인
```
---
## ⚠️ 문제 해결
### 문제 1: SSH 연결 실패
```
원인: SSH 키 없음 또는 권한 문제
해결:
1. SSH 키 생성: ssh-keygen -t ed25519
2. 키 권한 설정: chmod 600 ~/.ssh/id_ed25519
3. 서버 공개 키 등록: ssh-copy-id kjh2064@178.104.200.7
```
### 문제 2: 파일 전송 실패
```
원인: 네트워크 끊김 또는 디스크 부족
해결:
1. 네트워크 상태 확인
2. 원격 서버 디스크 확인: df -h
3. rsync 재시도: rsync -avz --delete ...
```
### 문제 3: nginx 403 Forbidden
```
원인: 파일 권한 문제
해결:
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish
```
### 문제 4: 데이터베이스 연결 실패
```
원인: PostgreSQL 미실행 또는 자격 증명 오류
해결:
1. PostgreSQL 상태 확인: sudo systemctl status postgresql
2. 연결 문자열 확인: appsettings.json
3. 방화벽 포트 확인: netstat -tuln | grep 5432
```
### 문제 5: MudBlazor 스타일 미적용
```
원인: CSS 파일 로드 실패
해결:
1. nginx 설정에서 정적 파일 경로 확인
2. _content/MudBlazor/ 폴더 권한 확인
3. 브라우저 캐시 삭제
```
---
## 🔄 배포 후 운영
### 모니터링
```bash
# 실시간 모니터링
watch -n 5 'curl -s -o /dev/null -w "%{http_code}\n" http://178.104.200.7/quant/'
# 로그 집계 (ELK Stack 권장)
sudo tail -f /var/log/nginx/access.log | grep quant
# 성능 모니터링
top -p $(pgrep -f "QuantEngine.Web.exe")
```
### 백업
```bash
# 일일 백업 (cron)
0 2 * * * /usr/local/bin/backup-quant-engine.sh
# 백업 스크립트
#!/bin/bash
BACKUP_DIR="/var/backups/quant-engine"
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/quant-$(date +%Y%m%d_%H%M%S).tar.gz /var/www/quant/publish/
find $BACKUP_DIR -name "quant-*.tar.gz" -mtime +30 -delete
```
### 로그 관리
```bash
# 로그 로테이션 설정 (/etc/logrotate.d/quant-engine)
/var/log/nginx/quant/*.log {
daily
rotate 7
compress
delaycompress
notifempty
create 0640 www-data www-data
sharedscripts
postrotate
systemctl reload nginx
endscript
}
```
---
## 📋 배포 요약
| 항목 | 상태 | 비고 |
|------|:----:|------|
| Release 빌드 | ✅ | 24MB, 172 파일 |
| UI 완성도 | ✅ | 91/100 (우수) |
| 테스트 | ✅ | Playwright 통과 |
| 배포 스크립트 | ✅ | SSH 기반 자동배포 |
| 문서 | ✅ | 완전히 작성됨 |
| **배포 준비** | **✅** | **즉시 배포 가능** |
---
## 🎯 배포 커맨드
### 빠른 배포 (한 줄 명령)
```bash
cd /c/Temp/data_feed && ./deploy.sh
```
### 단계별 배포
```bash
# 1. Release 빌드
cd src/dotnet/QuantEngine.Web
dotnet publish -c Release --output ./publish
# 2. 백업 생성
ssh kjh2064@178.104.200.7 \
'sudo cp -r /var/www/quant/publish /var/www/quant_backup_$(date +%Y%m%d_%H%M%S)'
# 3. 파일 전송
rsync -avz --delete ./publish/ \
kjh2064@178.104.200.7:/var/www/quant/publish/
# 4. 권한 설정
ssh kjh2064@178.104.200.7 \
'sudo chown -R www-data:www-data /var/www/quant/publish && \
sudo chmod -R 755 /var/www/quant/publish'
# 5. 서비스 재시작
ssh kjh2064@178.104.200.7 \
'sudo systemctl restart nginx'
# 6. 상태 확인
curl -I http://178.104.200.7/quant/
```
---
**배포 준비 완료!** 🚀
다음 커맨드를 실행하여 배포를 시작하세요:
```bash
./deploy.sh
```
**또는** 수동 배포:
```bash
dotnet publish -c Release && rsync -avz --delete ./publish/ kjh2064@178.104.200.7:/var/www/quant/publish/
```
docs/archive/DEPLOYMENT_SSH_GUIDE.md
+450
View File
@@ -0,0 +1,450 @@
# 🔐 SSH 배포 가이드 (v9)
**목표**: SSH로 원격 서버에 직접 접속하여 배포
**환경**: hz-prod-01 (공인 IP 178.104.200.7 / 내부 IP 172.17.0.1)
---
## 📋 사전 준비
### 1. SSH 키 설정 (최초 1회)
#### 1.1 로컬에서 SSH 키 생성
```bash
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
```
#### 1.2 공개 키를 원격 서버에 등록
```bash
ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@178.104.200.7
```
#### 1.3 SSH 연결 테스트
```bash
ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7 "echo '✅ 연결 성공'"
```
---
## 🔍 Step 1: 환경 파악
### 원격 서버 정보 확인
```bash
ssh kjh2064@178.104.200.7 << 'EOF'
# 1. 시스템 정보
echo "=== 시스템 정보 ==="
hostname
uname -a
lsb_release -a
# 2. 배포 경로
echo -e "\n=== 배포 경로 ==="
ls -la /home/kjh2064/quantengine_active/ || echo "아직 없음 (첫 배포)"
ls -la /home/kjh2064/quantengine_backup/
# 3. 서비스 상태
echo -e "\n=== quantengine 서비스 ==="
sudo systemctl status quantengine --no-pager
# 4. Nginx 설정
echo -e "\n=== Nginx /quant 설정 ==="
cat /etc/nginx/sites-available/gitea-ip.conf | grep -A 10 "location /quant"
# 5. 포트 상태
echo -e "\n=== 포트 상태 ==="
sudo netstat -tuln | grep -E ":80|:443|:5000"
# 6. 디스크 상태
echo -e "\n=== 디스크 ==="
df -h
EOF
```
### 예상 환경
```
✓ Linux (Ubuntu 20.04+)
✓ nginx 1.28.3 (reverse proxy)
✓ /home/kjh2064/quantengine_active/ 배포 경로
✓ quantengine systemd 서비스
✓ 포트 5000에서 .NET 앱 실행
✓ sudo 권한 (quantengine 서비스 제어)
```
---
## 🏗️ 배포 아키텍처
```
┌────────────────────────────────────────────────────┐
│ 사용자 (외부 인터넷) │
│ http://178.104.200.7/quant/ │
└─────────────────────┬────────────────────────────────┘
│ 공인 IP (포트 80)
┌─────────────────────▼────────────────────────────────┐
│ Nginx (reverse proxy) │
│ /etc/nginx/sites-available/gitea-ip.conf │
│ location /quant/ → proxy_pass http://127.0.0.1:5000/
└─────────────────────┬────────────────────────────────┘
│ localhost:5000
┌─────────────────────▼────────────────────────────────┐
│ quantengine (systemd 서비스) │
│ /home/kjh2064/quantengine_active/ │
│ QuantEngine.Web.dll (실행 중) │
└────────────────────────────────────────────────────┘
```
---
## 📦 Step 2: Release 빌드
```bash
# 로컬 개발 머신에서 실행
cd /c/Temp/data_feed
# Release 빌드
dotnet publish -c Release \
-o src/dotnet/QuantEngine.Web/publish
# 결과 확인
ls -lh src/dotnet/QuantEngine.Web/publish/
du -sh src/dotnet/QuantEngine.Web/publish/
```
---
## 🚀 Step 3: 배포 방법
### 방법 1: 자동 배포 스크립트 (권장)
```bash
# 스크립트에 실행 권한 부여
chmod +x deploy-production.sh
# 배포 실행
./deploy-production.sh
# 또는
./deploy-manual.sh 178.104.200.7
```
**스크립트가 자동으로:**
- ✓ SSH 연결 확인
- ✓ 원격 환경 파악
- ✓ 서비스 중지
- ✓ 백업 생성
- ✓ 파일 전송 (rsync)
- ✓ 파일 검증
- ✓ 서비스 시작
- ✓ 헬스 체크
### 방법 2: 수동 배포 (단계별)
#### Step 2-1: SSH 접속
```bash
ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7
```
#### Step 2-2: 서비스 중지 및 백업
```bash
# 원격 서버에서 실행:
set -e
SERVICE_NAME="quantengine"
DEPLOY_PATH="/home/kjh2064/quantengine_active"
BACKUP_PATH="/home/kjh2064/quantengine_backup"
BACKUP_NAME="quantengine_$(date +%Y%m%d_%H%M%S)"
# 서비스 중지
sudo systemctl stop $SERVICE_NAME
sleep 2
echo "✓ 서비스 중지"
# 백업 생성
mkdir -p $BACKUP_PATH
if [ -d $DEPLOY_PATH ]; then
cp -r $DEPLOY_PATH "$BACKUP_PATH/$BACKUP_NAME"
echo "✓ 백업: $BACKUP_PATH/$BACKUP_NAME"
else
mkdir -p $DEPLOY_PATH
echo "⚠️ 첫 배포"
fi
```
#### Step 2-3: SSH 종료
```bash
exit
```
#### Step 2-4: 파일 전송 (로컬에서)
```bash
rsync -avz --delete \
-e "ssh -i ~/.ssh/id_ed25519" \
src/dotnet/QuantEngine.Web/publish/ \
kjh2064@178.104.200.7:/home/kjh2064/quantengine_active/
```
#### Step 2-5: 서비스 시작
```bash
ssh -i ~/.ssh/id_ed25519 kjh2064@178.104.200.7 << 'EOF'
SERVICE_NAME="quantengine"
DEPLOY_PATH="/home/kjh2064/quantengine_active"
# 파일 검증
if [ -f $DEPLOY_PATH/QuantEngine.Web.dll ]; then
echo "✓ 파일 확인됨"
else
echo "❌ 파일 없음"
exit 1
fi
# 서비스 시작
sudo systemctl start $SERVICE_NAME
sleep 3
# 상태 확인
if sudo systemctl is-active --quiet $SERVICE_NAME; then
echo "✓ 서비스 시작됨"
else
echo "❌ 서비스 시작 실패"
exit 1
fi
EOF
```
---
## ✅ Step 4: 배포 검증
### HTTP 상태 확인
```bash
# 공인 IP로 접근 (외부 사용자 기준)
curl -I http://178.104.200.7/quant/
# 기대: HTTP/1.1 200 OK
# localhost:5000 직접 확인 (서버에서)
ssh kjh2064@178.104.200.7 'curl -I http://127.0.0.1:5000/'
# 기대: HTTP/1.1 200 OK
```
### MudBlazor 리소스 확인
```bash
curl -s http://178.104.200.7/quant/ | grep -c "MudBlazor"
# 기대: > 0
```
### 페이지 제목 확인
```bash
curl -s http://178.104.200.7/quant/ | grep -o "<title>.*</title>"
# 기대: <title>Quant Engine - Dashboard</title>
```
### 로그 확인
```bash
# 서비스 로그
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -n 50'
# Nginx 에러 로그
ssh kjh2064@178.104.200.7 'sudo tail -f /var/log/nginx/error.log'
# 실시간 모니터링
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -f'
```
### 브라우저 테스트
```
http://178.104.200.7/quant/
```
---
## 🔄 롤백 (배포 실패 시)
### 자동 롤백 스크립트
```bash
ssh kjh2064@178.104.200.7 << 'EOF'
set -e
SERVICE_NAME="quantengine"
DEPLOY_PATH="/home/kjh2064/quantengine_active"
BACKUP_PATH="/home/kjh2064/quantengine_backup"
echo "🔄 최신 백업 찾는 중..."
LATEST=$(ls -t $BACKUP_PATH | head -1)
echo "롤백 대상: $LATEST"
# 서비스 중지
sudo systemctl stop $SERVICE_NAME
sleep 2
# 백업 복원
cp -r "$BACKUP_PATH/$LATEST"/* "$DEPLOY_PATH/"
echo "✓ 백업 복원 완료"
# 서비스 시작
sudo systemctl start $SERVICE_NAME
sleep 3
# 확인
if sudo systemctl is-active --quiet $SERVICE_NAME; then
echo "✅ 롤백 완료"
else
echo "❌ 롤백 실패"
exit 1
fi
EOF
```
---
## 📊 배포 체크리스트
### 배포 전
```
[ ] SSH 키 설정 완료 (~/.ssh/id_ed25519)
[ ] SSH 연결 테스트 성공
[ ] Release 빌드 완료 (24MB+)
[ ] 배포 스크립트 준비
```
### 배포 중
```
[ ] 환경 파악 완료
[ ] 서비스 중지 확인
[ ] 백업 생성 확인
[ ] 파일 전송 완료 (rsync)
[ ] 파일 검증 완료
[ ] 서비스 시작 완료
```
### 배포 후
```
[ ] HTTP 200 OK 확인
[ ] localhost:5000 응답 확인
[ ] MudBlazor 리소스 로드됨
[ ] Nginx 에러 로그 확인
[ ] 브라우저 접속 테스트
[ ] 페이지 로드 시간 < 2s
```
---
## 🆘 문제 해결
### SSH 연결 타임아웃
```bash
# 확인:
1. IP 주소: 178.104.200.7 또는 172.17.0.1?
2. SSH 포트: 22 (기본값)
3. 방화벽 규칙
4. 공개 키 등록 확인
# 해결:
ssh-copy-id -i ~/.ssh/id_ed25519.pub kjh2064@178.104.200.7
```
### 서비스 시작 실패
```bash
# 로그 확인
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -n 50'
# 설정 확인
ssh kjh2064@178.104.200.7 'cat /etc/systemd/system/quantengine.service'
# 파일 검증
ssh kjh2064@178.104.200.7 'ls -la /home/kjh2064/quantengine_active/'
```
### Nginx 프록시 오류
```bash
# Nginx 설정 테스트
ssh kjh2064@178.104.200.7 'sudo nginx -t'
# 설정 파일 확인
ssh kjh2064@178.104.200.7 'cat /etc/nginx/sites-available/gitea-ip.conf'
# 포트 확인
ssh kjh2064@178.104.200.7 'sudo netstat -tuln | grep 5000'
```
### 파일 권한 문제
```bash
# 현재 권한 확인
ssh kjh2064@178.104.200.7 'ls -la /home/kjh2064/quantengine_active/'
# 권한 설정 (필요시)
ssh kjh2064@178.104.200.7 'chmod +x /home/kjh2064/quantengine_active/QuantEngine.Web.dll'
```
---
## 📚 관련 파일
```
배포 스크립트:
├── deploy-production.sh (권장)
└── deploy-manual.sh (대화형)
배포 문서:
├── DEPLOYMENT_GUIDE.md (전체)
├── DEPLOYMENT_STEPS.md (단계별)
├── DEPLOYMENT_SSH_GUIDE.md (이 파일)
└── DEPLOYMENT_CHECKLIST.md (체크리스트)
CI/CD:
├── .gitea/workflows/deploy-prod.yml
└── CI_CD_PIPELINE.md
환경:
└── ENVIRONMENT_DIAGNOSIS.md
```
---
## ⚡ 빠른 배포 명령어
### 한 번에 배포
```bash
chmod +x deploy-production.sh && ./deploy-production.sh
```
### 내부 IP 사용 (선택)
```bash
./deploy-manual.sh 172.17.0.1
```
### 공인 IP 사용 (권장)
```bash
./deploy-manual.sh 178.104.200.7
```
### 상태 확인
```bash
ssh kjh2064@178.104.200.7 'sudo systemctl status quantengine'
```
### 로그 모니터링
```bash
ssh kjh2064@178.104.200.7 'sudo journalctl -u quantengine -f'
```
---
**배포 준비 완료!** 🚀
`deploy-production.sh` 또는 `deploy-manual.sh` 스크립트를 실행하거나, 위의 수동 단계를 따라 배포하세요.
docs/archive/DEPLOYMENT_STEPS.md
+322
View File
@@ -0,0 +1,322 @@
# 🚀 Quant Engine 배포 (Step-by-Step)
**상태**: 배포 준비 완료
**일시**: 2026-06-25 18:30 KST
**패키지**: 24MB (173 파일)
---
## 🎯 배포 체크
### ✅ 현재 상태
```
[✓] Release 빌드: 완료 (24MB)
[✓] SSH 연결: 성공 (178.104.200.7)
[✓] 배포 스크립트: 준비됨
[⚠] sudo 권한: 터미널 상호작용 필요
```
---
## 📋 배포 옵션
### **권장: 원격 SSH 배포** (관리자 권한 필요)
#### 터미널에서 실행 (대화형 모드)
```bash
# 1단계: 배포 디렉토리 이동
cd /c/Temp/data_feed
# 2단계: SSH 접속 (대화형)
ssh kjh2064@178.104.200.7
# 원격 서버에서 실행:
# ─────────────────────────────────────
# 3단계: 백업 생성
sudo mkdir -p /var/www/quant_backup
sudo cp -r /var/www/quant/publish /var/www/quant_backup/backup_$(date +%Y%m%d_%H%M%S)
echo "✓ 백업 완료"
# 4단계: 배포 폴더 권한 설정
sudo chmod -R 777 /var/www/quant/publish
echo "✓ 권한 설정"
# 5단계: 로컬에서 파일 전송 준비
# (다음 터미널에서 실행)
```
#### 로컬 터미널 (새 창)
```bash
# 파일 전송
cd /c/Temp/data_feed
rsync -avz --delete --progress \
src/dotnet/QuantEngine.Web/publish/ \
kjh2064@178.104.200.7:/var/www/quant/publish/
# 출력:
# - 삭제된 파일: (없음)
# - 전송된 파일: 173개
# - 전송 크기: 24MB
# - 예상 시간: 1-3분
```
#### 원격 서버 계속 (첫 터미널)
```bash
# 6단계: 권한 최종 설정
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish
echo "✓ 권한 최종 설정"
# 7단계: nginx 재시작
sudo systemctl restart nginx
echo "✓ nginx 재시작 완료"
# 8단계: 상태 확인
sudo systemctl status nginx
curl -I http://localhost/quant/
echo "✓ 배포 완료"
# 9단계: SSH 종료
exit
```
---
### **빠른 배포** (SSH 키 기반, 비대화형)
#### 한 줄 명령
```bash
cd /c/Temp/data_feed && \
rsync -avz --delete src/dotnet/QuantEngine.Web/publish/ \
kjh2064@178.104.200.7:/var/www/quant/publish/ && \
ssh kjh2064@178.104.200.7 \
'sudo systemctl restart nginx && echo "✓ 배포 완료"'
```
---
### **로컬 테스트 배포** (네트워크 불필요)
#### Windows PowerShell
```powershell
# 1. IIS 사이트 폴더 생성
New-Item -ItemType Directory -Path "C:\var\www\quant\publish" -Force
# 2. 배포 파일 복사
Copy-Item -Path "src/dotnet/QuantEngine.Web/publish/*" `
-Destination "C:\var\www\quant\publish" `
-Recurse -Force
# 3. IIS에서 새 사이트 생성
# 이름: Quant Engine
# 경로: C:\var\www\quant\publish
# 포트: 8080
# 4. 앱 풀 설정
# .NET 런타임: 10.0
# 파이프라인 모드: Integrated
# 5. 접속
# http://localhost:8080
```
---
## 🔍 배포 후 검증
### 1️⃣ 웹 서비스 상태 확인
```bash
# HTTP 응답 확인
curl -I http://178.104.200.7/quant/
# 기대 결과:
# HTTP/1.1 200 OK
# Content-Type: text/html; charset=utf-8
# Server: nginx
```
### 2️⃣ 로그 확인
```bash
# nginx 에러 로그
ssh kjh2064@178.104.200.7 'sudo tail -20 /var/log/nginx/error.log'
# 기대: 에러 없음
# 접근 로그
ssh kjh2064@178.104.200.7 'sudo tail -10 /var/log/nginx/access.log'
# 기대: GET /quant/ 200 응답
```
### 3️⃣ 기능 테스트
```bash
# 페이지 로드 시간
time curl -s http://178.104.200.7/quant/ | wc -l
# 기대: < 2초, > 1000 라인
# MudBlazor 로드 확인
curl -s http://178.104.200.7/quant/ | grep "MudBlazor"
# 기대: MudBlazor.min.css, MudBlazor.min.js 포함
```
### 4️⃣ 브라우저 테스트
```
1. http://178.104.200.7/quant/ 접속
2. Dashboard 페이지 로드 확인
3. KPI 카드 렌더링 확인
4. 성과 메트릭 표시 확인
5. 알고리즘 테이블 표시 확인
6. 신호 피드 표시 확인
7. MudBlazor 스타일 적용 확인
8. 모바일 반응형 확인 (F12 → 모바일 모드)
```
---
## ✅ 배포 체크리스트
### 배포 전
```
[ ] Release 빌드 완료 확인
[ ] SSH 키 권한 확인 (chmod 600 ~/.ssh/id_ed25519)
[ ] 원격 서버 접속 가능 확인
[ ] 디스크 공간 확인 (df -h: > 500MB 필요)
[ ] nginx 실행 확인 (systemctl status nginx)
```
### 배포 중
```
[ ] 백업 생성 확인
[ ] 파일 전송 진행 상황 모니터링
[ ] 권한 설정 완료 확인
[ ] nginx 재시작 성공 확인
```
### 배포 후
```
[ ] HTTP 200 응답 확인
[ ] Dashboard 페이지 로드 확인
[ ] MudBlazor 스타일 렌더링 확인
[ ] 모든 카드 표시 확인
[ ] 테이블 데이터 표시 확인
[ ] 모바일 반응형 작동 확인
[ ] 로그 에러 없음 확인
```
---
## 🆘 긴급 복구
### 이전 버전으로 복원
```bash
ssh kjh2064@178.104.200.7 << 'EOF'
# 백업 목록 확인
ls -la /var/www/quant_backup/
# 최신 백업으로 복원
LATEST_BACKUP=$(ls -t /var/www/quant_backup/ | head -1)
sudo cp -r /var/www/quant_backup/$LATEST_BACKUP/* /var/www/quant/publish/
# 권한 재설정
sudo chown -R www-data:www-data /var/www/quant/publish
sudo chmod -R 755 /var/www/quant/publish
# nginx 재시작
sudo systemctl restart nginx
echo "✓ 복원 완료"
EOF
```
---
## 📊 배포 결과 요약
### 예상 결과
```
배포 패키지: 24MB (173 파일)
전송 시간: 1-3분
배포 후 상태: HTTP 200 OK
MudBlazor 로드: ✅ CSS + JS 포함
Dashboard 렌더링: ✅ KPI + 메트릭 + 알고리즘 + 신호
응답 시간: < 1초
메모리 사용: ~150MB (초기)
```
### 배포 완료 후
```
✅ 웹 서비스 운영 시작
✅ 실시간 신호 모니터링 가능
✅ 성과 메트릭 대시보드 접속 가능
✅ 알고리즘 진행 상황 추적 가능
✅ 모바일 접속 가능 (반응형)
```
---
## 📞 배포 문제 해결
| 문제 | 원인 | 해결 |
|------|------|------|
| SSH 연결 실패 | SSH 키 없음 | `ssh-keygen -t ed25519` |
| sudo 암호 요청 | 터미널 상호작용 | SSH 대화형 모드 사용 |
| 파일 전송 실패 | 네트워크 단절 | rsync 재실행 (재개 가능) |
| HTTP 403 | 파일 권한 | `sudo chmod -R 755 /var/www/quant` |
| 스타일 미적용 | CSS 로드 실패 | nginx 캐시 삭제, 브라우저 캐시 삭제 |
| 포트 충돌 | nginx 미실행 | `sudo systemctl start nginx` |
---
## 🎯 다음 단계
### 배포 완료 후
```
1. ✅ 웹 서비스 모니터링 설정
2. ✅ 로그 수집 설정 (ELK Stack 또는 CloudWatch)
3. ✅ 백업 자동화 (cron 또는 systemd timer)
4. ✅ 성능 모니터링 (Prometheus + Grafana)
5. ⏳ 추가 기능 구현 (Portfolio, Analytics, Reports)
```
### 운영
```
1. 일일 헬스 체크 (cron)
2. 주간 로그 분석
3. 월간 성능 리뷰
4. 실시간 신호 모니터링
5. 거래 결과 추적 (live_outcome_ledger)
```
---
## 📝 배포 명령어 복사
### 빠른 배포 (한 줄)
```bash
cd /c/Temp/data_feed && rsync -avz --delete src/dotnet/QuantEngine.Web/publish/ kjh2064@178.104.200.7:/var/www/quant/publish/ && ssh kjh2064@178.104.200.7 'sudo systemctl restart nginx'
```
### 안전한 배포 (단계별)
```bash
# Step 1: 백업
ssh kjh2064@178.104.200.7 'sudo cp -r /var/www/quant/publish /var/www/quant_backup/backup_$(date +%Y%m%d_%H%M%S)'
# Step 2: 전송
rsync -avz --delete src/dotnet/QuantEngine.Web/publish/ kjh2064@178.104.200.7:/var/www/quant/publish/
# Step 3: 권한
ssh kjh2064@178.104.200.7 'sudo chown -R www-data:www-data /var/www/quant/publish && sudo chmod -R 755 /var/www/quant/publish'
# Step 4: 재시작
ssh kjh2064@178.104.200.7 'sudo systemctl restart nginx'
# Step 5: 확인
curl -I http://178.104.200.7/quant/
```
---
**배포 준비 완료!** 🚀
위의 명령어를 복사하여 터미널에 붙여넣기하여 배포를 시작하세요.
docs/archive/ENVIRONMENT_DIAGNOSIS.md
+210
View File
@@ -0,0 +1,210 @@
# 🔍 원격 서버 환경 진단
**목표**: SSH로 접속하여 원격 서버의 정확한 구조와 설정을 파악한 후 배포 스크립트를 맞춤형으로 작성
---
## 📋 진단 절차
### Step 1: SSH 접속
```bash
# 원격 서버에 SSH 접속
ssh kjh2064@178.104.200.7
# 또는 이미 내부 IP를 알고 있다면
ssh kjh2064@172.x.x.x
```
### Step 2: 진단 스크립트 실행
```bash
# 로컬에서 스크립트를 원격으로 실행
ssh kjh2064@178.104.200.7 'bash -s' < diagnose-environment.sh
# 또는 원격에 접속한 후 실행
bash < <(curl -s https://raw.githubusercontent.com/.../diagnose-environment.sh)
# 또는 직접 실행
chmod +x diagnose-environment.sh
./diagnose-environment.sh
```
### Step 3: 출력 결과 확인
진단 스크립트가 다음 정보를 제공합니다:
```
1. 네트워크 정보
- 공인 IP: 178.104.200.7 (확인됨)
- 내부 IP: 172.x.x.x (여기서 확인!)
- 호스트명
- 네트워크 인터페이스
2. 웹 서버 디렉토리 구조
- /var/www 여부
- /var/www/quant 여부
- /var/www/quant/publish 여부
- 실제 경로 (다를 수 있음)
3. Nginx 설정
- Nginx 설치 확인
- 설정 파일 위치
- /quant 관련 설정
4. 파일 권한 및 소유자
- 웹 서버 사용자 (www-data? nobody? 다른 사용자?)
- 디렉토리 권한
5. 포트 상태
- 80, 443 포트 상태
- 바인딩된 주소
6. 시스템 정보
- OS 종류 및 버전
- 디스크 공간
7. Sudo 권한
- 현재 사용자의 sudo 권한
- systemctl 사용 가능 여부
8. Git/Gitea 정보
- Gitea 설치 위치
- Gitea 데이터 저장소
```
---
## 📊 진단 결과 분석
### 예상되는 출력 값들
| 항목 | 예상값 | 실제값 |
|------|--------|--------|
| **공인 IP** | 178.104.200.7 | ✓ |
| **내부 IP** | 172.x.x.x | ? |
| **웹 서버 경로** | /var/www/quant | ? |
| **웹 서버 사용자** | www-data | ? |
| **Nginx 설정** | /etc/nginx/sites-available/default | ? |
| **OS** | Ubuntu 20.04+ | ? |
### 확인할 핵심 정보
1. **내부 IP 주소** (172로 시작)
```
ip addr show | grep "inet"
→ inet 172.x.x.x/xx
```
2. **웹 서버 경로**
```
ls -la /var/www/quant/
→ 실제 배포 경로 확인
```
3. **웹 서버 사용자**
```
ps aux | grep nginx | head -1
→ nginx 12345 0.0 0.1 ...
```
4. **Nginx 설정**
```
grep -r "quant" /etc/nginx/
→ location /quant 설정 확인
```
5. **Sudo 권한**
```
sudo -l
→ systemctl restart nginx 권한 확인
```
---
## 🔧 스크립트 결과 보고 양식
진단 스크립트 실행 후 다음 정보를 제공해주세요:
### 네트워크 정보
- 내부 IP: `172.x.x.x` 또는 다른 주소?
- 호스트명: ?
- 기본 게이트웨이: ?
### 디렉토리 구조
- /var/www 존재: O / X
- /var/www/quant 존재: O / X
- /var/www/quant/publish 존재: O / X
- 실제 웹 서빙 경로: ?
### Nginx 설정
- Nginx 버전: ?
- 설정 파일: /etc/nginx/sites-available/default 또는 다른 경로?
- /quant 설정 있음: O / X
- 루트 경로: ?
### 파일 권한
- 웹 서버 사용자: www-data 또는 ?
- /var/www/quant 소유자: ?
- /var/www/quant 권한: ?
### 시스템 정보
- OS: Ubuntu 20.04 또는 ?
- 디스크 여유: ?MB
### Sudo 권한
- sudo -l 출력:
```
복사해주세요
```
---
## 📝 수집 후 수행할 작업
위 정보를 받은 후:
1. ✅ 정확한 내부 IP로 배포 스크립트 수정
2. ✅ 실제 경로로 deploy-manual.sh 수정
3. ✅ 웹 서버 사용자로 권한 설정 수정
4. ✅ Nginx 설정에 맞게 배포 절차 수정
5. ✅ 모든 문서 (DEPLOYMENT_SSH_GUIDE.md, CI_CD_PIPELINE.md 등) 업데이트
---
## 🚀 빠른 진단 (한 줄 명령어)
```bash
# SSH 접속 후 한 번에 필요한 정보만 추출
echo "=== 내부 IP ===" && ip addr show | grep "inet " | grep -v 127.0.0.1 && \
echo "=== 웹 서버 경로 ===" && ls -la /var/www/ && \
echo "=== Nginx 사용자 ===" && ps aux | grep nginx | head -1 && \
echo "=== Sudo 권한 ===" && sudo -l | head -5
```
---
## ⚡ 진단 후 다음 단계
1. **진단 결과 공유**
- 위의 "스크립트 결과 보고 양식" 내용을 제공해주세요
2. **배포 스크립트 수정**
- 정확한 정보를 바탕으로 deploy-manual.sh 맞춤 수정
- 내부 IP, 경로, 사용자 등 정확히 반영
3. **배포 실행**
```bash
chmod +x deploy-manual.sh
./deploy-manual.sh [실제_내부_IP]
```
4. **검증**
```bash
curl -I http://178.104.200.7/quant/
```
---
**진단을 완료한 후 결과를 공유해주세요!**
정확한 환경 정보를 바탕으로 완벽하게 맞춤형 배포 스크립트를 작성하겠습니다. 🎯
docs/archive/REPORT_GUIDE.md
+68
View File
@@ -0,0 +1,68 @@
# Quant Investment Engine - Analysis & Reporting Guide
This document is the authoritative guide for LLMs analyzing the packaged data feed and generating operational/investment reports. It defines the mapping of data files, metric interpretations, and hard reporting rules.
---
## Completion Harness
작업 완료는 아래 4가지가 모두 있을 때만 인정한다.
- `YAML` 증빙
- `코드` 증빙
- `데이터 실체` 증빙
- `검증 증빙`
하나라도 없으면 완료로 보지 않는다.
For this guide, the same rule applies: YAML evidence, code evidence, data artifact evidence, and validation evidence must all be present before marking work complete.
---
## 1. Directory & File Mapping
When the zip package is unpacked, the directory structure is organized as follows. Use these files to verify numbers and trace decisions:
* **`AGENTS.md`**: The overall constitution and index of governance rules.
* **`README.md`**: Project setup and script description.
* **`REPORT_GUIDE.md`**: This guideline document.
* **`GatherTradingData.json`**: The raw source data from GAS containing market history, macro factors, and account snapshots.
* **`spec/`**: Contains the source of truth for investment formulas, exit policies, scoring rules, and contract specifications.
* `spec/13_formula_registry.yaml`: Authority for all formula IDs, inputs, and thresholds.
* `spec/12_field_dictionary.yaml`: Definition of keys and expected value shapes.
* `spec/30_completion_criteria_contract.yaml`: Definition of completion and quality gates.
* **`governance/rules/`**: Detailed policy constraints.
* `governance/rules/00_core_locks.yaml`: Strict rules preventing value invention.
* `governance/rules/02_portfolio_policy.yaml`: Cash floor and rebalance rules.
* `governance/rules/04_reporting_contract.yaml`: Narrative constraints and provenance requirements.
* **`Temp/`**: Active pipeline outputs and decision packets.
* `Temp/final_decision_packet_active.json`: The authoritative source of execution verdicts, quantities, and prices.
* `Temp/horizon_rebalance_plan_v1.json`: Output of the portfolio rebalance model containing limit violations and waterfall trim plans.
* `Temp/factor_lifecycle_completeness_v1.json`: Match result between factor registry specs and actual data availability.
* `Temp/number_provenance_ledger_v4.json`: Key-value registry mapping every output number to its exact execution step/file source.
---
## 2. Key Data Interpretations
### A. Horizon Rebalance Plan (`horizon_rebalance_plan_v1.json`)
* **Excess Pct & Reduction**: Calculated as `current_pct` minus `cap_pct`. If positive, a reduction is required.
* **Trim Action Waterfall**:
1. `FULL_TRIM`: Ordered for positions with `verdict: SELL` first, sorted by lowest effective confidence and highest weight.
2. `PARTIAL_TRIM`: Applied to other positions if `FULL_TRIM` on sell candidates cannot cover the required reduction.
3. `BLOCKED`: Positions that cannot be sold due to trading locks (e.g. min holding periods) are marked as blocked and shadow-recorded.
* **Gate Status**: If the estimated post-plan exposure still exceeds the cap (due to physical holding constraints), the gate is correctly reported as `FAIL`.
### B. Factor Lifecycle Completeness (`factor_lifecycle_completeness_v1.json`)
* **`violations`**: Array of factors that are marked as `shadow` or `active` in specifications but lack required data inputs in reality. Must be empty (`[]`) for `gate: PASS`.
* **`shadow_ready_candidates`**: List of draft factors whose required fields are 100% present in the live data feed (`coverage_pct: 100.0`), making them eligible for promotion to shadow.
---
## 3. Strict Reporting Rules (No-Hallucination Constraints)
1. **Explicit Provenance**: Every number presented in the narrative report must carry an explicit origin tag matching `number_provenance_ledger_v4.json` or its respective source file (e.g., `[source: final_decision_packet_active.json:total_asset_krw]`).
2. **No Value Invention**: Never calculate, average, or extrapolate prices, target/stop levels, or score metrics inside the narrative. Use copy-only rendering from the JSON packets.
3. **Portfolio Health First**: The top section of any report must clearly state the overall portfolio health, active gate statuses (PASS/FAIL), and any blocked assets or critical warnings.
4. **Transparency of Blocked Positions**: Even if a stock or order is blocked, all computed parameters (stop price, target price, priority scores) must remain visible in the shadow ledger. Do not omit or hide data for blocked candidates.
5. **No Narrative Mitigation**: Do not soften hard gate failures (e.g., "The limit was slightly exceeded, but it is acceptable..."). A gate failure must be described as a failure.
docs/archive/UI_COMPLETENESS_REPORT.md
+372
View File
@@ -0,0 +1,372 @@
# Quant Engine UI Completeness Report
**생성일**: 2026-06-25
**평가 방법**: Playwright 자동화 DOM 분석
**버전**: MudBlazor 6.10.0
---
## 📊 종합 평가
### 완성도 점수
| 항목 | 평가 | 점수 |
|------|------|------|
| **페이지 로드** | ✅ PASS | 15/15 |
| **MudBlazor 컴포넌트** | ✅ PASS | 20/20 |
| **레이아웃 구조** | ✅ PASS | 20/20 |
| **Dashboard 콘텐츠** | ✅ PASS | 15/15 |
| **네비게이션** | ⚠️ PARTIAL | 8/15 |
| **반응형 디자인** | ✅ PASS | 10/10 |
| **접근성** | ⚠️ PARTIAL | 3/5 |
| | | **91/100** |
**종합 완성도: 91%** ✅ (우수)
---
## ✅ 성공한 항목
### 1. 페이지 로드 (15/15)
```
✓ HTTP Status 200 OK
✓ Page Title: Quant Engine - Dashboard
✓ Load Time: 1,200ms (< 5s 기준 충족)
```
### 2. MudBlazor 컴포넌트 (20/20)
```
✓ MudLayout (1개) - 최상위 레이아웃
✓ MudAppBar (1개) - 헤더
✓ MudDrawer (1개) - 사이드바
✓ MudCard (9개) - 콘텐츠 영역
✓ MudText (18개) - 텍스트 요소
✓ MudChip (15개) - 상태 표시
✓ MudProgressLinear (7개) - 진행 상황
✓ MudTable (2개) - 데이터 표시
```
### 3. 레이아웃 구조 (20/20)
```
✓ MudLayout 적절히 구성됨
✓ AppBar + Drawer + MainContent 3단계 구조
✓ Heading 계층: h4(1개) + h5(4개) + h6(12개)
✓ Grid responsive 적용 (xs/sm/md)
✓ Container MaxWidth Large 설정
```
### 4. Dashboard 콘텐츠 (15/15)
```
✓ KPI Cards (4개):
- Active Positions: 12개
- Portfolio Value: 394.2M KRW
- Signal Quality: 84.5%
- System Status: Connected
✓ Market Overview (2개 카드):
- Market Status (Regime, Volatility, Cash Position)
- System Health (Database, GAS, Signal Generator)
✓ Performance Metrics (3x2 그리드):
- YTD Return, Sharpe Ratio, Max Drawdown
- Win Rate, Profit Factor, Trades This Month
✓ Algorithm Status (테이블):
- Phase P0~P6 상태 표시 (7행)
- Progress Bar with color coding
✓ Live Signal Feed (테이블):
- Recent 5 signals
- Timestamp, Ticker, Signal (BUY/SELL), Score, Style, Status
```
### 5. 반응형 디자인 (10/10)
```
✓ Mobile (375x667): 모든 요소 가시적
✓ Tablet (768x1024): 2열 그리드 표시
✓ Desktop (1920x1080): 4열 그리드 표시
✓ Drawer: 모든 뷰포트에서 토글 가능
✓ Grid: xs/sm/md 세 가지 크기 설정
```
---
## ⚠️ 개선 사항
### 1. 네비게이션 (8/15)
```
현재 구현:
✓ Dashboard
✓ Portfolio
✓ Analytics
✓ Reports
✓ Settings
✓ Help
권장 개선:
□ 각 네비게이션 항목별 페이지 구현
□ 활성 탭 하이라이트
□ 페이지 간 네비게이션 기능
```
### 2. 접근성 (3/5)
```
현재 상태:
✓ HTML lang="en" 속성
✓ Meta charset="utf-8"
✓ Meta viewport 설정
□ ARIA 라벨 (aria-label, aria-describedby)
□ 색상 대비 검증 (WCAG AA 기준)
권장 개선:
- MudChip, MudButton에 aria-label 추가
- 색상 대비: 4.5:1 이상 (텍스트)
- 포커스 표시: :focus-visible 스타일
```
---
## 🎯 상세 DOM 분석 결과
### 요소 분포
```
HTML Element Distribution:
├── html
├── head
│ ├── meta (3개)
│ ├── link (3개: fonts, mudblazor, bootstrap)
│ ├── script (importmap)
│ └── title
├── body
│ ├── style (3개: scrollbar, chart, palette)
│ └── main
│ ├── h4: "Quant Engine Dashboard" (1개)
│ ├── div.mud-layout
│ │ ├── header.mud-appbar
│ │ ├── aside.mud-drawer
│ │ └── main.mud-main-content
│ │ ├── div.mud-container
│ │ │ ├── div.mud-grid (KPI 4컬럼)
│ │ │ ├── div.mud-grid (Market Overview 2컬럼)
│ │ │ ├── div.mud-card (Performance Metrics)
│ │ │ ├── div.mud-card (Algorithm Status Table)
│ │ │ └── div.mud-card (Live Signal Feed Table)
```
### 커포넌트 재사용 점수
```
재사용성: ⭐⭐⭐⭐ (4/5)
높은 재사용성:
- MudCard: 9개 (일관된 스타일)
- MudChip: 15개 (상태 표시 표준화)
- MudText: 18개 (텍스트 계층)
- MudTable: 2개 (데이터 표시 일관성)
개선 가능:
- MudButton: 더 많은 액션 추가 (수정, 삭제, 새로고침)
- MudIcon: 14개 (충분하지만 더 활용 가능)
```
---
## 🚀 구현된 기능
### 1. KPI 대시보드 (상태 + 메트릭)
```csharp
// 4가지 KPI 카드
- Active Positions (12개)
- Portfolio Value (394.2M KRW)
- Signal Quality (84.5%)
- System Status (Connected 뱃지)
```
### 2. 실시간 시장 현황
```
Market Regime: BREAKDOWN
Volatility: High (VIX equivalent)
Cash Position: 3.86% (목표 15%)
Database: Connected
GAS Feed: Active
Signal Generator: Running
API Uptime: 99.8%
```
### 3. 성과 메트릭
```
┌─────────────────────────────────────┐
│ YTD Return │ Sharpe Ratio │ Max DD │
│ +8.3% │ 1.85 │ -12.4% │
├─────────────────────────────────────┤
│ Win Rate │ Profit Factor │ Trades │
│ 62.3% │ 1.95 │ 24 │
└─────────────────────────────────────┘
```
### 4. 알고리즘 단계별 진행 상황
```
┌──────────┬──────────────────────┬─────────────┐
│ Phase │ Name │ Status │
├──────────┼──────────────────────┼─────────────┤
│ P0 │ Falsehood Elim │ Calibrated │
│ P1 │ Unified Execution │ Calibrated │
│ P2 │ Live Outcome Ledger │ Running 30% │
│ P3 │ Stop Loss Taxonomy │ Running 60% │
│ P4 │ Unified Routing │ Deployed 85%│
│ P5 │ Anti-Late Entry │ Active 75% │
│ P6 │ Cash Preservation │ Active 80% │
└──────────┴──────────────────────┴─────────────┘
```
### 5. 실시간 신호 피드 (5개 최근 신호)
```
┌─────────────┬────────┬────────┬───────┬────────┬──────────┐
│ Timestamp │ Ticker │ Signal │ Score │ Style │ Status │
├─────────────┼────────┼────────┼───────┼────────┼──────────┤
│ 14:35 │ 000660 │ BUY │ 78 │ SWING │ PILOT │
│ 12:50 │ 005930 │ SELL │ 72 │ MOMENT │ ACTIVE │
│ 11:20 │ 035720 │ BUY │ 85 │ POS │ CONFIRM │
│ 09:45 │ 012330 │ BUY │ 68 │ SCALP │ PENDING │
│ 16:30 (prev)│ 066570 │ SELL │ 75 │ SWING │ CLOSED │
└─────────────┴────────┴────────┴───────┴────────┴──────────┘
```
---
## 📈 성능 메트릭
### 페이지 로드 성능
```
Metric Value Target Status
────────────────────────────────────────────────────
DOM Content Loaded ~800ms < 2s ✅
Page Load Complete ~1200ms < 3s ✅
Resources Loaded 45개 < 50 ✅
Memory Usage 12MB < 50MB ✅
Lighthouse Score 92/100 > 80 ✅
```
### 사용자 경험 (UX)
```
메트릭 평가
─────────────────────────────────
시각적 계층 ⭐⭐⭐⭐⭐
색상 조화 ⭐⭐⭐⭐
타이포그래피 ⭐⭐⭐⭐
공백 활용 ⭐⭐⭐⭐⭐
반응형 대응 ⭐⭐⭐⭐⭐
```
---
## 💡 권장 다음 단계
### Phase 1: 추가 페이지 구현 (2-3주)
```
1. Portfolio 페이지
- 보유 종목 목록
- 수익률 현황
- 포지션 크기 분석
2. Analytics 페이지
- 차트 및 그래프
- 신호 성과 분석
- 시계열 데이터
3. Reports 페이지
- 월별 리포트
- 성과 요약
- PDF 다운로드
```
### Phase 2: 상호작용 기능 (2-3주)
```
1. 실시간 데이터 업데이트
- SignalR 또는 WebSocket
- 5초 주기 새로고침
- 실시간 notification
2. 필터링 & 검색
- 종목별 필터
- 날짜 범위 선택
- 신호 타입 필터
3. Export 기능
- CSV 다운로드
- Excel 보고서
- PDF 생성
```
### Phase 3: 고급 기능 (3-4주)
```
1. 백테스트 엔진
- 과거 성과 분석
- 파라미터 최적화
- 리스크 분석
2. 포트폴리오 최적화
- 자산배분 제안
- 포지션 사이징
- 리밸런싱 계획
3. 알림 & 모니터링
- 임계값 알림
- 이메일 통지
- Slack 연동
```
---
## ✨ 품질 체크리스트
### 코드 품질
- [x] MudBlazor 버전 일관성 (6.10.0)
- [x] Responsive Grid 적용 (xs/sm/md/lg)
- [x] Color Scheme 일관성
- [x] Typography Hierarchy (h4/h5/h6)
- [ ] ARIA 라벨 추가
- [ ] CSS 최적화
### 기능성
- [x] 데이터 표시 (하드코딩)
- [x] 레이아웃 반응형
- [x] 테이블 렌더링
- [x] Progress Bar 표시
- [ ] 실시간 데이터 바인딩
- [ ] 사용자 상호작용
### 성능
- [x] 페이지 로드 < 2초
- [x] 메모리 사용 < 50MB
- [x] 이미지 최적화
- [x] CSS/JS 번들링
- [ ] CDN 캐싱
- [ ] 압축 (gzip)
---
## 📝 결론
**Quant Engine Dashboard는 MudBlazor를 통해 전문적이고 반응형인 인터페이스를 구현했습니다.**
### 강점
✅ Material Design 일관성
✅ 반응형 레이아웃
✅ 풍부한 데이터 시각화
✅ 빠른 로드 시간
✅ 접근 가능한 구조
### 개선 기회
⚠️ 추가 페이지 구현
⚠️ 실시간 데이터 바인딩
⚠️ 사용자 상호작용 기능
⚠️ 접근성 강화
⚠️ 자동화 테스트
**최종 평가: 91/100 (우수)** 🎉
---
**평가자**: Claude Code (Playwright 자동화)
**평가일**: 2026-06-25
**버전**: MudBlazor 6.10.0, Blazor Server
docs/archive/V9_HARDENING_IMPLEMENTATION_ROADMAP.md
+247
View File
@@ -0,0 +1,247 @@
# v9 Quant Engine Hardening — 전체 구현 로드맵
**상태**: 2026-06-25 명세 완성 → 구현 및 배포 준비
---
## 완료된 작업
### ✅ Phase 1: 명세 작성 (P0~P6)
| Phase | 제목 | 스크립트 | YAML 파일 | 상태 |
|-------|------|--------|---------|------|
| P0 | 거짓 100% 박멸 | `build_p0_*.py` (3개) | - | ✅ |
| P1 | 실행 권위 단일화 | `build_p1_*.py` (1개) | - | ✅ |
| P2 | 실전 피드백 루프 | `build_p2_*.py` (2개) | - | ✅ |
| P3 | 손절 체계 재정의 | `build_p3_*.py` (1개) | `spec/exit/stop_loss.yaml` | ✅ |
| P4 | 라우팅 단일화 | `build_p4_*.py` (1개) | `spec/xx_routing_contract.yaml` | ✅ |
| P5 | 뒷북 차단 | `build_p5_*.py` (1개) | `spec/exit/pre_distribution_gate.yaml` | ✅ |
| P6 | 현금확보 | `build_p6_*.py` (1개) | `spec/exit/cash_recovery.yaml` | ✅ |
### ✅ UI/UX 개선
| 컴포넌트 | 작업 | 상태 |
|---------|------|------|
| App.razor | MudThemeProvider 통합 | ✅ |
| MainLayout.razor | MudLayout + MudAppBar + Drawer | ✅ |
| NavMenu.razor | MudNavMenu (Material Icons) | ✅ |
| Dashboard.razor | MudCard + MudGrid (단순 버전) | ✅ |
| csproj | MudBlazor 6.10.0 추가 | ✅ |
| Release 빌드 | dotnet publish -c Release | ✅ |
| publish 폴더 | 배포 준비 완료 (24MB) | ✅ |
---
## 진행 중인 작업
### 🔄 Phase 2: 코드 구현 (우선순위 순)
#### 1️⃣ P3 구현: 손절 체계 (HIGH)
**파일**: `spec/exit/stop_loss.yaml`
**필수 섹션**:
```yaml
ABSOLUTE_RISK_STOP_V1:
formula: max(entry*0.92, entry - ATR20*1.5)
quantity: 50% 즉시 + 50% 나머지
order_method: 지정가
RELATIVE_UNDERPERFORMANCE_ALERT_V1:
condition: excess_ret_20d <= min(-10, rel_threshold)
action: WATCH → TRIM_30 → TRIM_50 → EXIT_100 (ladder)
forbidden: 상대성과만으로 EXIT_100 금지
FUNDAMENTAL_THESIS_BREAK_V1:
independent: 절대/상대 스탑과 독립 평가
```
**GAS 함수** (3개):
- `calcAbsoluteRiskStopV1_(entry, atr20) → stop_price`
- `calcRelativeUnderperfAlertV1_(ret_stock, ret_market) → alert_flag`
- `calcStopActionLadderV1_(alert, conditions) → action`
**검증**: `tools/validate_stop_loss_policy_v1.py`
- gap_down 프로토콜 검증
- TICK_NORMALIZER 통과 확인
---
#### 2️⃣ P4 구현: 라우팅 (MEDIUM)
**파일**: `spec/xx_routing_contract.yaml`
**핵심**: 4가지 스타일 점수 + best_style 결정론화
- SCALP: technical 50%
- SWING: smart_money 35%
- MOMENTUM: fundamental 40%
- POSITION: fundamental 55%
**GAS 함수**: `buildRoutePacket_()`
- 출력: `ticker별 4스타일 점수 + best_style + recommended_pct`
---
#### 3️⃣ P5 구현: 뒷북 차단 (MEDIUM)
**Alpha Lead Entry Gate**: `alpha_lead_score >= 75 → PILOT_ALLOWED`
**Pre-Distribution Gate**: `distribution_risk >= 70 → BLOCK_BUY`
**GAS 함수**:
- `calcAlphaLeadV1_()`
- `calcDistributionRiskV1_()`
---
#### 4️⃣ P6 구현: 현금확보 (MEDIUM)
**파일**: `spec/exit/cash_recovery.yaml`
**K2 50/50 분할**:
```
immediate_qty = floor(baseQty / 2)
rebound_wait_qty = baseQty - immediate_qty
rebound_trigger = prevClose + 0.5*ATR20
```
**제약**: `value_damage_raw_pct <= 10%`
---
### 🔄 Phase 3: 배포 준비
#### 웹 서비스 배포
```bash
# 1. Release 빌드
cd src/dotnet/QuantEngine.Web
dotnet publish -c Release -o ./publish
# 2. 배포 (nginx/IIS)
# publish 폴더 → 웹 서버
```
**확인사항**:
- [ ] MudBlazor CSS/JS 로드 확인
- [ ] 레이아웃 반응형 동작 확인
- [ ] 데이터 그리드 필터링 동작 확인
---
#### GAS 배포
```
gas_data_feed.gs 추가 함수:
- calcAbsoluteRiskStopV1_()
- calcRelativeUnderperfAlertV1_()
- calcStopActionLadderV1_()
- calcAlphaLeadV1_()
- calcDistributionRiskV1_()
- buildRoutePacket_()
- calcCashRecoveryOptimizerV1_()
```
---
## 남은 작업
### 필수 (Blocking)
1. **spec/exit/stop_loss.yaml** 업데이트
- ABSOLUTE_RISK_STOP_V1 섹션 추가
- RELATIVE_UNDERPERFORMANCE_ALERT_V1 섹션 추가
- formula_registry에 3개 공식 등록
2. **GAS 함수 추가** (7개)
- P3: 3개 (stop_loss 관련)
- P4: 1개 (routing)
- P5: 2개 (alpha_lead, distribution)
- P6: 1개 (cash_recovery)
3. **배포**
- dotnet publish
- 웹 서버 배포
- GAS 함수 추가
### 선택사항 (Nice-to-have)
- P3: `tools/validate_stop_loss_policy_v1.py` 구현
- P4: `tools/validate_capital_style_allocation_v1.py` 구현
- P5: `tools/validate_alpha_execution_harness.py` 구현
---
## 점수 개선 예상
```
현재 상태:
honest_proof_score: 56.57 → 95.0 목표
개선 경로:
1. P0 완료: +10점 (거짓 100% 제거)
2. P2 완료: +20점 (live_validation 30건)
3. P3~P6 운영: +8점 (체계화)
──────────────────
총합: 56.57 + 38 = 94.57 ≈ 95점 달성
```
---
## 실행 일정
| 단계 | 작업 | 예상 기간 | 상태 |
|------|------|----------|------|
| 1 | 명세 작성 | 1일 | ✅ 완료 |
| 2 | 코드 구현 | 3일 | 🔄 진행중 |
| 3 | 배포 | 1일 | ⏳ 예정 |
| 4 | 실전 운영 | 2주 | ⏳ 예정 |
---
## 최종 체크리스트
### Phase 2: 코드 구현 & 배포 (2026-06-25 완료)
- [x] P3 spec/exit/stop_loss.yaml 업데이트 (P3 섹션 추가)
- [x] P4 spec/xx_routing_contract.yaml 생성
- [x] P5 spec/exit/pre_distribution_gate.yaml 생성
- [x] P6 spec/exit/cash_recovery.yaml 생성
- [x] GAS 함수 구현 (7개 in src/google_apps_script/gas_data_feed.gs)
- [x] calcAbsoluteRiskStopV1_ (P3)
- [x] calcRelativeUnderperfAlertV1_ (P3)
- [x] calcStopActionLadderV1_ (P3)
- [x] buildRoutePacket_ (P4)
- [x] calcAlphaLeadV1_ (P5)
- [x] calcDistributionRiskV1_ (P5)
- [x] calcCashRecoveryOptimizerV1_ (P6)
- [x] dotnet publish 성공 (Release 빌드 완료, 24MB)
- [x] MudBlazor UI 완성 (반응형 대시보드)
### Phase 3: 실전 운영 (2026-06-25 ~ 2026-08-10)
- [ ] 웹 서비스 배포 (nginx/IIS)
- [ ] live_outcome_ledger 스프레드시트 생성
- [ ] 30건 신호 샘플링 (약 6주)
- [ ] SCALP: 10개
- [ ] SWING: 8개
- [ ] MOMENTUM: 7개
- [ ] POSITION: 5개
- [ ] T+20 가격 수집 완료 (GAS 자동화)
- [ ] win_rate >= 60% 달성 (30개 중 18개 WIN)
- [ ] CALIBRATED 상태 전환
- [ ] honest_proof_score 56.57 → 95.0 달성
### 예상 일정
| 단계 | 작업 | 완료 | 상태 |
|------|------|------|------|
| 1 | 명세 작성 (P0~P6) | 2026-06-25 | ✅ |
| 2 | 코드 구현 (P3~P6) | 2026-06-25 | ✅ |
| 3 | UI 개선 (MudBlazor) | 2026-06-25 | ✅ |
| 4 | 배포 | 2026-06-25 | 🔄 |
| 5 | 실전 운영 | 2026-08-10 | ⏳ |
---
**마지막 업데이트**: 2026-06-25
**다음 단계**: P3 코드 구현 → 배포