QuantFolio

QuantFolio는 전설적인 투자 멘토의 철학을 정량화하여, 하나의 종목을 다각도로 분석하고 합의(Consensus) 결과까지 제시하는 투자 분석 서비스입니다.

이 저장소는 해커톤 제출 가능한 베타 버전을 목표로, 아래 3가지를 빠르게 검증할 수 있도록 설계되어 있습니다.

• 멘토 전략 기반의 멀티팩터 분석
• 사용자 커스텀 페르소나 생성/비교
• 프론트-백 통합 배포 및 공개 도메인 운영

면책: QuantFolio는 교육/연구 목적의 분석 도구이며, 투자 자문이나 매수/매도 권유가 아닙니다.

---

1. 서비스 개요

해결하려는 문제

일반적인 종목 분석은 단일 지표 또는 단일 관점에 치우치기 쉽습니다. QuantFolio는 다음 접근으로 이를 보완합니다.

• 가치/성장/퀄리티 등 서로 다른 철학의 멘토 전략을 동시에 적용
• 전략 간 결과를 합의 엔진으로 통합
• 사용자 성향을 반영한 커스텀 페르소나로 개인화

핵심 사용자 경험

1. 티커 입력 후 분석 실행
2. Graham/Lynch/Munger/Buffett/Custom 결과 비교
3. Radar + Price 차트로 시각화 확인
4. 멘토 프로필에서 철학/공식/핵심지표 이해
5. 커스텀 페르소나 생성 후 즉시 분석 반영

---

2. 현재 베타에서 제공하는 기능

분석 엔진

• 전략 패턴(IInvestmentStrategy) 기반 멘토 전략 모듈화
• 기본 전략 4종 + 사용자 정의 Custom 전략
• 5개 공통 팩터 점수화
  • SafetyMargin, Growth, Profitability, Management, PricingAttractiveness
• 전략별 가중치 기반 총점 계산 및 Verdict 산출(Buy/Hold/Sell)

합의(Consensus) 엔진

• 다수결 우세 의견(DominantVerdict)
• 전략 평균 점수(AverageScore)
• 일치도가 가장 높은 지표 / 괴리가 가장 큰 지표 계산
• 투표 분포(VoteDistribution) 제공

데이터 인프라

• IMarketDataProvider 추상화 + 복합 Provider
  • 1순위 Yahoo Provider 실패 시 Alpha Provider 폴백
• Redis 연결 시 분산 캐시, 미연결 시 메모리 캐시 폴백
• PostgreSQL 연결 시 EF Core DB 사용, 미연결 시 InMemory 폴백

인증/보안

• JWT Access Token + Refresh Token
• Demo 계정 로그인/토큰 재발급 API 제공
• API Rate Limiting(Fixed Window)
• CORS 허용 오리진 정책 적용

비동기 작업

• Hangfire 기반 백그라운드 분석 큐
• 작업 등록/상태 조회 API
• /hangfire 대시보드 노출

프론트엔드 UX

• 다크+골드 테마, 글래스모피즘 스타일
• 랜딩/대시보드/멘토/비교 페이지
• 커스텀 페르소나 생성/삭제 흐름
• 멘토 상세 설명 화면
• 차트 시각화(Recharts)
  • Radar 차트
  • Price Trend 차트
  • 1D, 1W, 1M, 3M, 6M, 1Y, LIVE

참고: 현재 LIVE 차트와 마켓 데이터는 베타용 시뮬레이션 데이터 생성 로직(StockDataGenerator)을 사용합니다.

---

3. 기술 스택

Backend

• .NET 9 Web API
• Entity Framework Core (PostgreSQL / InMemory)
• Hangfire + MemoryStorage
• JWT Bearer Authentication
• Redis Distributed Cache (선택)

Frontend

• React + Vite
• Tailwind CSS
• Recharts
• Axios + React Query
• i18next (ko/en)

운영/배포

• Docker (backend/QuantFolio.Api/Dockerfile)
• 베타 오픈 런북: deploy/BETA_OPEN_60MIN_KR.md
• 스모크 테스트 스크립트: scripts/smoke-beta.sh

---

4. 아키텍처 요약

[React Frontend]
  └─ API 호출 (/analysis, /strategies, /auth)
        ↓
[ASP.NET Core API]
  ├─ AuthService (JWT/Refresh)
  ├─ StockAnalysisService
  │   ├─ MarketDataProvider (Yahoo -> Alpha fallback)
  │   ├─ StrategyFactory (Reflection 등록)
  │   ├─ InvestmentStrategies (Graham/Lynch/Munger/Buffett/Custom)
  │   └─ ConsensusEngine
  ├─ Cache (Redis or Memory)
  ├─ DbContext (PostgreSQL or InMemory)
  └─ Hangfire (Background jobs)

---

5. 디렉토리 구조

.
├─ backend/QuantFolio.Api
│  ├─ Abstractions/          # 핵심 인터페이스
│  ├─ Auth/                  # 인증 모델/서비스 계약
│  ├─ Contracts/             # API 요청/응답 DTO
│  ├─ Controllers/           # HTTP 엔드포인트
│  ├─ Domain/                # 엔터티/도메인 모델
│  ├─ Infrastructure/        # 전략/데이터/보안/캐시/잡
│  ├─ Services/              # 분석/합의/인증 서비스
│  ├─ Dockerfile
│  └─ Program.cs
├─ frontend
│  ├─ src/components         # 공통 UI/차트
│  ├─ src/pages              # 페이지 단위 화면
│  ├─ src/context            # 전역 상태
│  ├─ src/features           # API 훅/비즈니스 로직
│  └─ src/data               # 멘토/프로필 데이터
├─ deploy/BETA_OPEN_60MIN_KR.md
└─ scripts/smoke-beta.sh

---

6. API 요약

Base URL 예: http://localhost:5078

인증

• POST /api/auth/login
• POST /api/auth/refresh

전략/분석

• GET /api/strategies
• POST /api/analysis/run (익명 허용)
• POST /api/analysis/background (인증 필요)
• GET /api/analysis/background/{jobId} (인증 필요)

운영

• GET /api/health (익명 허용)
• GET /api/rankings (인증 필요, 현재 스캐폴드)

분석 요청 예시

{
  "ticker": "AAPL",
  "strategyIds": ["graham", "lynch", "munger"],
  "customWeights": {
    "safetyMargin": 35,
    "growth": 20,
    "profitability": 15,
    "management": 20,
    "pricingAttractiveness": 10
  }
}

---

7. 로컬 실행 방법

사전 요구사항

• .NET SDK 9.x
• Node.js 20+
• (선택) PostgreSQL, Redis

1) Backend 실행

cd backend/QuantFolio.Api
dotnet restore
dotnet run

기본 URL(launch profile 기준)

• http://localhost:5078
• https://localhost:7119 (--launch-profile https)

2) Frontend 실행

cd frontend
npm install
npm run dev

기본 URL

• http://localhost:5173

환경변수 예시 (frontend/.env)

VITE_API_BASE_URL=http://localhost:5078

---

8. 설정값(Environment)

Backend 주요 설정 (appsettings*.json 또는 환경변수)

• Jwt__Issuer
• Jwt__Audience
• Jwt__SigningKey (필수, 32자 이상)
• Jwt__AccessTokenMinutes
• Jwt__RefreshTokenDays
• ConnectionStrings__PostgreSql (없으면 InMemory)
• ConnectionStrings__Redis (없으면 Memory Cache)
• MarketData__YahooFinanceApiKey
• MarketData__AlphaVantageApiKey
• Cors__AllowedOrigins__0

Frontend

• VITE_API_BASE_URL

---

9. 배포(해커톤 베타)

권장 절차는 deploy/BETA_OPEN_60MIN_KR.md 문서를 따릅니다.

배포 후 최소 점검:

chmod +x scripts/smoke-beta.sh
./scripts/smoke-beta.sh https://<your-api-domain>

---

10. 데모 계정

• Email: demo@quantfolio.ai
• Password: P@ssw0rd!

---

11. 검증된 명령

• dotnet build QuantFolio.sln
• npm run lint (frontend)
• npm run build (frontend)

---

12. 알려진 제한사항 (베타)

• 현재 마켓 데이터는 시뮬레이션 생성값 기반
• Rankings/백테스팅은 스캐폴드 단계
• Hangfire 대시보드 접근 제어 강화 필요
• 실서비스 수준 모니터링/APM/알림은 미적용

---

13. 로드맵

1. 실제 시세 API 연동 및 장애 폴백 고도화
2. 백테스팅/소셜 랭킹 실구현
3. Refresh Token 회전/폐기 정책 강화
4. CI/CD + 무중단 배포 체계 구축
5. 실시간 데이터 파이프라인(WebSocket/SSE) 도입