이 파일은 Backend 프로젝트 작업 시 Claude Code가 참고하는 가이드입니다.
Sign in to like and favorite skills
이 파일은 Backend 프로젝트 작업 시 Claude Code가 참고하는 가이드입니다.
Backend는 2개의 서비스로 구성됩니다:
cd quant-jump-stock-core # 개발 서버 실행 ./gradlew bootRun # 빌드 (테스트 제외) ./gradlew build -x test # 테스트 실행 ./gradlew test # 클린 빌드 ./gradlew clean build
cd quant-jump-stock-data-engine # Poetry로 의존성 설치 poetry install # 개발 서버 실행 python src/main.py # 또는 uvicorn src.main:app --reload --port 10020
make local # .env.local로 Docker 서비스 시작 make prod # .env.prod로 Docker 서비스 시작 make logs # 로그 확인 make down # 서비스 종료 make clean # 볼륨 포함 전체 삭제
src/main/kotlin/com/quantjumpstock/core/ ├── adapter/ # 어댑터 레이어 (외부 연동) │ ├── input/ # 인바운드 어댑터 │ │ ├── api/ # 내부 API 인터페이스 │ │ ├── rest/ # REST 컨트롤러 ⭐ 신규 API는 여기에 │ │ │ ├── admin/ # 관리자 API │ │ │ ├── analysis/ # 주식 분석 API │ │ │ ├── auth/ # 인증 API │ │ │ ├── category/ # 카테고리 API │ │ │ ├── economic/ # 경제 지표 API │ │ │ ├── marketplace/ # 마켓플레이스 API │ │ │ ├── ml/ # ML 모델 API │ │ │ ├── prediction/ # 예측 API │ │ │ ├── scheduler/ # 스케줄러 API │ │ │ ├── strategy/ # 전략 API │ │ │ ├── user/ # 사용자 API │ │ │ └── vertexai/ # Vertex AI API │ │ ├── messaging/ # Kafka 컨슈머 │ │ └── scheduler/ # Quartz 잡 스케줄러 │ └── output/ # 아웃바운드 어댑터 │ ├── persistence/ │ │ ├── jpa/ # PostgreSQL (JPA Entity/Repository) │ │ └── mongodb/ # MongoDB Repository │ ├── external/ # 외부 API 클라이언트 (KIS, FRED) │ ├── gcp/ # GCP 서비스 │ │ └── vertexai/ # Vertex AI 클라이언트 │ ├── messaging/ # Kafka 프로듀서 │ └── notification/ # Slack 알림 │ ├── application/ # 애플리케이션 레이어 (유스케이스) │ ├── admin/ # 관리자 서비스 │ ├── analysis/ # 분석 서비스 │ ├── auth/ # 인증 서비스 │ ├── balance/ # 잔고 서비스 │ ├── category/ # 카테고리 서비스 │ ├── economic/ # 경제 지표 서비스 │ ├── marketplace/ # 마켓플레이스 서비스 │ ├── ml/ # ML 서비스 │ ├── prediction/ # 예측 서비스 │ ├── scheduler/ # 스케줄러 서비스 │ ├── stock/ # 주식 데이터 서비스 │ ├── strategy/ # 전략 서비스 │ ├── trading/ # 트레이딩 서비스 │ ├── user/ # 사용자 서비스 │ └── vertexai/ # Vertex AI 서비스 │ ├── domain/ # 도메인 레이어 (비즈니스 로직) │ ├── model/ # 핵심 도메인 엔티티 │ ├── port/ # 포트 인터페이스 (헥사고날 아키텍처) │ ├── analysis/ # 분석 도메인 │ ├── economic/ # 경제 도메인 │ ├── ml/ # ML 도메인 │ ├── prediction/ # 예측 도메인 │ ├── scheduler/ # 스케줄러 도메인 │ ├── trading/ # 트레이딩 도메인 │ └── vertexai/ # Vertex AI 도메인 │ ├── config/ # Spring 설정 ├── events/ # 이벤트 정의 ├── infrastructure/ # 인프라 공통 유틸 └── scheduler/ # Quartz 설정
quant-jump-stock-data-engine/src/ ├── main.py # FastAPI 진입점 ├── core/ # 핵심 유틸리티 ├── events/ # 이벤트 핸들러 ├── features/ # 피처 모듈 └── services/ # 비즈니스 서비스
adapter/output/persistence/jpa/src/main/resources/db/migration/stock_trading{ "date": "2025-02-05", "stocks": { "AAPL": { "close_price": 231.42 }, "NVDA": { "close_price": 124.79 }, ... }, "yfinance_indicators": { "S&P 500 ETF": 597.20, ... }, "fred_indicators": { ... } }
adapter/output/persistence/mongodb/V{버전}__설명.sql 예: V12__Create_User_Subscription_Table.sql
✅ adapter → application → domain ❌ domain → adapter (의존성 역전 위반) ❌ adapter.input → adapter.output 직접 참조
adapter/input/rest/{도메인}/application/{도메인}/domain/model/adapter/output/persistence/jpa/@Entity @Table(name = "table_name") class EntityName( @Id @GeneratedValue(strategy = GenerationType.IDENTITY) val id: Long? = null, // 다른 필드들... )
| 서비스 | 용도 | 설정 위치 |
|---|---|---|
| KIS API | 한국투자증권 실시간 시세 | |
| FRED API | 미국 경제 지표 | |
| Vertex AI | AI 예측 모델 | |
| Slack | 알림 전송 | |
| Kafka | 이벤트 스트리밍 | |
scheduler/adapter/input/scheduler/V3__Create_Quartz_Tables.sql상세: TESTING_RULES.md 참조
cd quant-jump-stock-core && ./gradlew test.env.local.env.example# 필수 FRED_API_KEY= KIS_APP_KEY= KIS_APP_SECRET= DB_HOST=localhost DB_PORT=5432 MONGODB_URI= # 선택 SLACK_WEBHOOK_URL_TRADING= GCP_ENABLED=false
Backend 아키텍처 개선을 위한 상세 문서가 준비되어 있습니다:
| 항목 | 현재 | 목표 |
|---|---|---|
| ArchUnit 위반 | ~27건 | 0건 |
| 단위 테스트 커버리지 | 0% | 80%+ |
| Application → JPA 의존성 | 11개 서비스 | 0개 |
| Domain 모델 오염 | 5개 파일 | 0개 |