AIBE5-Team2 · 최종 프로젝트 — AI 기반 퀀트 투자 워크스페이스
자연어 프롬프트로 전략을 구성하고, 6종 백테스트 → QuantStats Tearsheet → MOCK/REAL 주문 제안(OrderProposal) 큐 → 한국투자증권(KIS) 실주문까지 한 흐름으로 연결합니다.
| 영역 | 설명 |
|---|---|
| 구독 플랜 | FREE / STANDARD(9,900원/월) / PREMIUM(19,900원/월) / EXPERT(준비중) — Toss Payments v1 결제창 연동. 테스트 키(샌드박스)로 실제 청구 없이 전체 결제 흐름 검증 가능. |
| Alpha Workspace | 탭 분리 레이아웃(Chat / Config / Report / Regime / Trust / Briefing / Log). 사용자별 다중 워크스페이스. |
| 백테스트 엔진 | 6 전략(buy_and_hold, sma_cross, rsi_meanrev, macd, momentum_12_1, vix_risk_off) + 무한매수법(infinite_buying) — vectorbt 기반. 수수료 0.25% + 슬리피지 0.1% 반영. |
| Tearsheet | quantstats HTML 리포트 자동 생성, /reports/{file}.html 정적 서빙. |
| AI 신호 | XGBoost up-probability + SHAP 설명 + Walk-Forward / 5-State Regime / Trust Score 파라미터 섭동. |
| OrderProposal 큐 | 일일 시그널 → 사용자 승인 큐. HMAC 서명 승인 링크, TTL 만료 잡 자동 정리. |
| MOCK → REAL 게이트 | 모든 주문은 MOCK 선행. 사용자 명시 승인 후에만 KIS 실주문 전송. 글로벌 Kill-Switch 지원. |
| KIS 브로커 연동 | 모의/실거래 계좌 등록, AES-GCM 암호화 저장, 토큰 자동 갱신, 잔고/현재가/주문 API. |
| Living Briefing | 일일 시장 요약 + 사용자 포트폴리오 코멘트 (Gemini 2.5-flash, 쿼터 관리 AiGatewayService 통합). |
| 알림 센터 | 시그널/체결/만료 알림 — Zustand persist + BE /api/notifications/*. |
| Rate Limiting | AI 채팅 20 req/hour/user (Bucket4j). JWT 만료 시 자동 localStorage 클리어. |
| Flyway 마이그레이션 | ddl-auto=validate + Flyway 자동 스키마 관리. APP_CRYPTO_KEY 기본값 없음 — 환경변수 필수. |
| Circuit Breaker | Analytics 사이드카 Resilience4j CB + Retry. XGBoost 일일 22:30 KST 자동 재학습 스케줄러. |
※ 본 저장소는 DevBridge(파트너-클라이언트 매칭 플랫폼) 기반 위에 Alpha-Helix 모듈이 얹힌 형태입니다. 매칭/포트폴리오/채팅 기능 일부가 함께 포함되어 있습니다.
| 레이어 | 스택 |
|---|---|
| Frontend | React 18 · Vite 7 · Tailwind 4 · Zustand (persist) · Axios · React Router v7 · FullCalendar · Stream Chat |
| Backend | Spring Boot 4.0 · Java 21 · JPA/Hibernate · Flyway · Resilience4j · Bucket4j · JJWT(HS256) · Spring Mail · Gradle 9 |
| Analytics | Python 3.11 · FastAPI 0.115 · vectorbt 0.26 · quantstats 0.0.62 · xgboost 2.1 · SHAP 0.46 · yfinance (→ Polygon.io 예정) |
| DB | MySQL 8 (alphahelix_db) |
| AI | Google Gemini 2.5-flash · AiGatewayService(쿼터+로그 통합) · 선택적으로 Anthropic / OpenAI / Perplexity |
| Broker | 한국투자증권 OpenAPI (모의/실거래) — AES-GCM 키 보관, HMAC 승인 링크 |
| Infra | EC2 + Nginx + systemd (who-a-backend.service / who-a-analytics.service) |
- JDK 17, Node 20+, Python 3.11, MySQL 8
backend/src/main/resources/application-local.properties생성(템플릿:application.properties참고)analytics/.env생성(템플릿:analytics/.env.example)
mysql -uroot -p1234 -e "CREATE DATABASE alphahelix_db CHARACTER SET utf8mb4;"./gradlew bootRuncd analytics
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --port 8001 --reloadcd frontend
npm install
npm run dev- 프론트: http://localhost:5173
- 백엔드 API: http://localhost:8080/api
- Analytics: http://localhost:8001 (백엔드가 내부 토큰으로만 호출)
| 키 | 용도 |
|---|---|
DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, DB_PASSWORD |
MySQL 연결 |
JWT_SECRET |
JWT HS256 서명 (32+ bytes) |
APP_CRYPTO_KEY |
KIS 키 AES-GCM 암호화 (Base64 32 bytes) |
APPROVAL_HMAC_SECRET |
OrderProposal 승인 링크 서명 |
GEMINI_API_KEY |
Gemini AI (미설정 시 룰베이스 폴백) |
ANALYTICS_BASE_URL / ANALYTICS_INTERNAL_TOKEN |
BE → Analytics 사이드카 |
MAIL_USERNAME / MAIL_PASSWORD |
Gmail SMTP (앱 비밀번호) |
TOSS_SECRET_KEY |
토스 결제 시크릿 키. 반드시 클라이언트 키와 동일 계정 키쌍 사용. 테스트: test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R / 운영: 토스 개발자센터 라이브 키 |
TOSS_WEBHOOK_SECRET |
토스 웹훅 서명 검증 (옵션) |
TRADING_KILL_SWITCH |
true 시 모든 KIS 실주문 차단 |
.
├── backend/ Spring Boot — 매칭 + Alpha-Helix REST API
│ └── src/main/java/com/DevBridge/devbridge/
│ ├── controller/ AlphaHelix · BrokerAccount · BrokerOrder · OrderProposal · ...
│ ├── service/ DailySignalGenerator · AnalyticsClient · CryptoService · broker/Kis*
│ ├── entity/ AlphaWorkspace · OrderProposal · BrokerAccount · ...
│ └── security/ JWT 쿠키 필터 · AuthContext
├── analytics/ Python FastAPI 사이드카
│ └── app/
│ ├── backtest/ vbt_engine · infinite_buying
│ ├── metrics/ quantstats_report
│ ├── models/ xgb_signal
│ ├── explain/ shap_explainer
│ └── robust/ walkforward · regime · trust_score
├── frontend/ React + Vite
│ └── src/
│ ├── alpha/ Workspace · Account · Proposals · OrderConfirmModal · ChatDock
│ ├── pages/ Home · Login · Mypage · NotificationsPage · VisionBoard · ...
│ ├── store/ Zustand (auth · notifications · ...)
│ └── i18n/ translations.js
└── deploy/ systemd units · nginx conf · cloud-init · DEPLOY_FROM_SCRATCH.md
- JWT HttpOnly 쿠키 —
Set-Cookie: HttpOnly; Secure(prod); SameSite=Lax(XSS 토큰 탈취 방지). Authorization 헤더는 레거시 fallback. - KIS 자격증명 AES-GCM 암호화 — DB 평문 저장 금지. 키는
APP_CRYPTO_KEY환경변수. - 승인 링크 HMAC 서명 + TTL — 이메일/링크로 노출되는 OrderProposal 승인 토큰 위조 차단.
OrderProposalExpiryJob이 만료 큐 정리. - MOCK → REAL 명시 게이트 — DailySignalGenerator는 항상 MOCK 제안 먼저, 실주문은 별도 승인 단계.
- 글로벌 Kill-Switch —
app.trading.kill-switch=true시 KIS 어댑터가 모든 실주문 거부. - 파일 업로드 — multipart 50MB 제한, path traversal 방지.
- 로깅 — 시크릿 마스킹,
application-prod.properties에서ddl-auto=validate+ actuator 노출 최소화.
- 단일 EC2(
who-a) 위에 nginx + 3 systemd 유닛(backend 8080, analytics 8001, frontend dist). - 상세 절차:
deploy/DEPLOY_FROM_SCRATCH.md - 환경 템플릿:
deploy/ENV_TEMPLATE.txt
- 회원가입 → 로그인 (JWT 쿠키 세팅 확인)
- 마이페이지 → KIS 모의계좌 등록 (
appkey/appsecret입력) - Alpha Workspace 생성 → 전략 선택 → 백테스트 → Tearsheet 확인
- 데일리 시그널 트리거 → Proposals 페이지에서 MOCK 주문 승인 → 만료/체결 알림 수신
- (옵션) Kill-Switch off + 실거래 계좌 → REAL 주문 게이트 통과
AIBE5 — Team2 (Alpha-Helix)
본 리포지토리는 교육·발표 목적의 비공개 팀 프로젝트입니다.