docs: Add comprehensive refactoring plan
This commit is contained in:
276
REFACTORING_PLAN.md
Normal file
276
REFACTORING_PLAN.md
Normal file
@@ -0,0 +1,276 @@
|
|||||||
|
# AutoStock 리팩토링 마스터 플랜
|
||||||
|
|
||||||
|
> **목표**: 현재 엉망진창인 구조를 유지보수 가능한 모듈형 아키텍처로 전환
|
||||||
|
> **원칙**: 기존 코드는 버리지 않고 재배치 + 추상화 레이어 추가
|
||||||
|
> **일정**: 2026년 3월 ~ 4월 (단계별 점진적 리팩토링)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 현재 구조의 문제점
|
||||||
|
|
||||||
|
### 1. 거대 파일 문제
|
||||||
|
- `main.py` (30KB) - FastAPI 라우터 + 매매 로직 + WebSocket이 모두 혼재
|
||||||
|
- `portfolio.py` (58KB) - API 엔드포인트에 비즈니스 로직 직접 구현
|
||||||
|
- `korea_investment_api.py` (49KB) - KIS API 전체가 한 파일
|
||||||
|
|
||||||
|
### 2. 역할 분리 미흡
|
||||||
|
```
|
||||||
|
현재 services/
|
||||||
|
├── KIS API 관련 (korea_investment_api.py, kis_realtime_stream.py)
|
||||||
|
├── 전략 관련 (day_trading_strategy.py, mean_reversion_strategy.py)
|
||||||
|
├── 리스크 관련 (loss_tracker.py, mdd_manager.py)
|
||||||
|
├── ML 관련 (ml_ensemble.py, tensorflow_predictor.py)
|
||||||
|
└── 기타 (market_analyzer.py, technical_indicators.py)
|
||||||
|
→ 모두 services/ 에 flat하게 존재
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 배치 스크립트 분산
|
||||||
|
- `batch_daily_analysis.py` (22KB)
|
||||||
|
- `batch_intraday_analysis.py` (19KB)
|
||||||
|
- `collect_krx_data.py` (14KB)
|
||||||
|
→ 루트에 독립 파일로 흩어져 있음
|
||||||
|
|
||||||
|
### 4. 설정 관리 방식
|
||||||
|
- `trading_rules_config.json` - 전략 설정이 파일
|
||||||
|
- DB에 있어야 할 데이터가 파일로 관리됨
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 목표 구조
|
||||||
|
|
||||||
|
```
|
||||||
|
backend/app/
|
||||||
|
│
|
||||||
|
├── api/endpoints/ # REST API 라우터만 (얇은 레이어)
|
||||||
|
│ ├── portfolio.py # 포트폴리오 조회/수정
|
||||||
|
│ ├── trades.py # 거래 이력
|
||||||
|
│ ├── strategy_config.py # 전략 설정 CRUD
|
||||||
|
│ ├── risk_management.py # 리스크 설정
|
||||||
|
│ ├── market_data.py # 시세 데이터
|
||||||
|
│ └── recommendations.py # AI 추천
|
||||||
|
│
|
||||||
|
├── trading/ # 매매 실행 엔진 (신규)
|
||||||
|
│ ├── engine.py # 메인 매매 루프 (asyncio)
|
||||||
|
│ ├── kis_client.py # KIS REST API 전체
|
||||||
|
│ ├── ws_client.py # KIS WebSocket 실시간 시세
|
||||||
|
│ ├── order_manager.py # 주문 실행·취소·조회
|
||||||
|
│ ├── ws_manager.py # WebSocket 연결 관리
|
||||||
|
│ └── scheduler.py # 장 스케줄 (batch 통합)
|
||||||
|
│
|
||||||
|
├── strategy/ # 전략 엔진 (신규)
|
||||||
|
│ ├── base_strategy.py # 전략 추상 클래스
|
||||||
|
│ ├── signal.py # Signal 데이터 클래스
|
||||||
|
│ ├── strategy_manager.py # 전략 등록·실행·관리
|
||||||
|
│ ├── indicators.py # 보조지표 (MA, RSI, MACD 등)
|
||||||
|
│ ├── scanner.py # 종목 스캔
|
||||||
|
│ ├── market_analyzer.py # 시장 분석
|
||||||
|
│ ├── feature_engineering.py # ML 피처
|
||||||
|
│ └── strategies/
|
||||||
|
│ ├── day_trading.py
|
||||||
|
│ ├── mean_reversion.py
|
||||||
|
│ ├── short_term.py
|
||||||
|
│ └── ml/
|
||||||
|
│ ├── ensemble.py
|
||||||
|
│ └── tf_predictor.py
|
||||||
|
│
|
||||||
|
├── risk/ # 리스크 관리 (신규)
|
||||||
|
│ ├── risk_manager.py # 통합 리스크 관리
|
||||||
|
│ ├── loss_tracker.py # 손실 추적
|
||||||
|
│ └── mdd_manager.py # MDD 관리
|
||||||
|
│
|
||||||
|
├── db/ # 데이터베이스 레이어 (신규)
|
||||||
|
│ ├── repository.py # DB CRUD 통합
|
||||||
|
│ └── watchlist.py # 감시종목
|
||||||
|
│
|
||||||
|
├── mq/ # RabbitMQ 연동 (신규)
|
||||||
|
│ ├── producer.py # 신호 발행
|
||||||
|
│ └── consumer.py # 주문 수신
|
||||||
|
│
|
||||||
|
├── cache/ # Redis 캐시 (신규)
|
||||||
|
│ ├── price_cache.py # 실시간 시세 캐시
|
||||||
|
│ └── token_cache.py # KIS 토큰 캐시
|
||||||
|
│
|
||||||
|
├── models/ # DB 모델 (현재 유지)
|
||||||
|
├── core/ # 설정·의존성 (현재 유지)
|
||||||
|
└── main.py # FastAPI 진입점 (대폭 축소)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 리팩토링 로드맵
|
||||||
|
|
||||||
|
### Phase 1: Trading Engine 분리 (Week 1-2)
|
||||||
|
|
||||||
|
**목표**: KIS API 관련 코드를 `trading/` 폴더로 독립
|
||||||
|
|
||||||
|
| 작업 | 현재 파일 | 새 위치 | 변경사항 |
|
||||||
|
|------|----------|---------|---------|
|
||||||
|
| 1.1 | `korea_investment_api.py` (49KB) | `trading/kis_client.py` | 클래스 단위 분리 |
|
||||||
|
| 1.2 | `kis_realtime_stream.py` (25KB) | `trading/ws_client.py` | WebSocket 전용 |
|
||||||
|
| 1.3 | `trade_executor.py` (28KB) | `trading/order_manager.py` | 주문 실행만 |
|
||||||
|
| 1.4 | `websocket_manager.py` (5KB) | `trading/ws_manager.py` | 연결 관리 |
|
||||||
|
| 1.5 | batch 파일들 | `trading/scheduler.py` | APScheduler 통합 |
|
||||||
|
|
||||||
|
**체크포인트**:
|
||||||
|
- [ ] `trading/kis_client.py` 테스트 통과
|
||||||
|
- [ ] WebSocket 실시간 시세 정상 수신
|
||||||
|
- [ ] 모의투자 주문 성공
|
||||||
|
- [ ] 기존 API 엔드포인트 정상 동작
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Strategy Engine 구축 (Week 3-4)
|
||||||
|
|
||||||
|
**목표**: 전략 추상화 + 기존 전략들 재배치
|
||||||
|
|
||||||
|
| 작업 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| 2.1 | `strategy/base_strategy.py` 작성 (추상 클래스) |
|
||||||
|
| 2.2 | `strategy/signal.py` 작성 (Signal 데이터 클래스) |
|
||||||
|
| 2.3 | `day_trading_strategy.py` → `strategies/day_trading.py` 이전 + 리팩토링 |
|
||||||
|
| 2.4 | `mean_reversion_strategy.py` → `strategies/mean_reversion.py` 이전 |
|
||||||
|
| 2.5 | `short_term_strategy.py` → `strategies/short_term.py` 이전 |
|
||||||
|
| 2.6 | `technical_indicators.py` → `strategy/indicators.py` 이전 |
|
||||||
|
| 2.7 | `strategy_config_service.py` → `strategy/strategy_manager.py` 이전 |
|
||||||
|
|
||||||
|
**체크포인트**:
|
||||||
|
- [ ] 최소 1개 전략이 새 구조로 동작
|
||||||
|
- [ ] 신호 생성 → 주문 실행 파이프라인 확인
|
||||||
|
- [ ] 전략 ON/OFF 동적 전환 가능
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Risk Management 통합 (Week 5)
|
||||||
|
|
||||||
|
**목표**: 리스크 관리 로직 통합 + 3단계 레이어 구현
|
||||||
|
|
||||||
|
| 작업 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| 3.1 | `risk/risk_manager.py` 신규 작성 (Account/Position/Order 레벨) |
|
||||||
|
| 3.2 | `loss_tracker.py` 이전 |
|
||||||
|
| 3.3 | `mdd_manager.py` 이전 |
|
||||||
|
| 3.4 | Circuit Breaker 구현 |
|
||||||
|
| 3.5 | 손절·익절·트레일링 스탑 통합 |
|
||||||
|
|
||||||
|
**체크포인트**:
|
||||||
|
- [ ] 일일 손실 한도 테스트 성공
|
||||||
|
- [ ] 손절가 도달 시 자동 청산
|
||||||
|
- [ ] Circuit Breaker 발동 확인
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 4: API Layer 다이어트 (Week 6)
|
||||||
|
|
||||||
|
**목표**: API 엔드포인트에서 비즈니스 로직 제거
|
||||||
|
|
||||||
|
현재 `portfolio.py` (58KB) 예시:
|
||||||
|
```python
|
||||||
|
# 현재 (BAD)
|
||||||
|
@router.get("/portfolio")
|
||||||
|
async def get_portfolio():
|
||||||
|
# 50줄의 비즈니스 로직...
|
||||||
|
return result
|
||||||
|
|
||||||
|
# 목표 (GOOD)
|
||||||
|
@router.get("/portfolio")
|
||||||
|
async def get_portfolio():
|
||||||
|
return await portfolio_service.get_summary()
|
||||||
|
```
|
||||||
|
|
||||||
|
**체크포인트**:
|
||||||
|
- [ ] 모든 API 파일 < 200줄
|
||||||
|
- [ ] 비즈니스 로직은 service 레이어에만 존재
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 5: Async 실행 흐름 통합 (Week 7)
|
||||||
|
|
||||||
|
**목표**: `main.py`를 얇게 만들고 asyncio 태스크 통합
|
||||||
|
|
||||||
|
```python
|
||||||
|
# main.py 최종 목표
|
||||||
|
async def startup_event():
|
||||||
|
await init_db()
|
||||||
|
await init_redis()
|
||||||
|
await init_rabbitmq()
|
||||||
|
|
||||||
|
# 백그라운드 태스크 시작
|
||||||
|
asyncio.create_task(trading_engine.run())
|
||||||
|
asyncio.create_task(risk_monitor.run())
|
||||||
|
asyncio.create_task(scheduler.run())
|
||||||
|
```
|
||||||
|
|
||||||
|
**체크포인트**:
|
||||||
|
- [ ] `main.py` < 300줄
|
||||||
|
- [ ] 4개 독립 태스크 정상 동작
|
||||||
|
- [ ] 태스크 간 Queue 통신 확인
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 6: DB + Cache + MQ 레이어 추가 (Week 8)
|
||||||
|
|
||||||
|
**목표**: Redis, RabbitMQ 활용 구조 완성
|
||||||
|
|
||||||
|
| 작업 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| 6.1 | `cache/price_cache.py` - Redis에 실시간 시세 캐싱 |
|
||||||
|
| 6.2 | `cache/token_cache.py` - KIS 토큰 Redis 저장 |
|
||||||
|
| 6.3 | `mq/producer.py` - 신호 → RabbitMQ 발행 |
|
||||||
|
| 6.4 | `mq/consumer.py` - RabbitMQ → 주문 실행 |
|
||||||
|
| 6.5 | `db/repository.py` - DB CRUD 통합 |
|
||||||
|
|
||||||
|
**체크포인트**:
|
||||||
|
- [ ] Redis에서 실시간 시세 조회 가능
|
||||||
|
- [ ] RabbitMQ로 신호 전달 확인
|
||||||
|
- [ ] DB 트랜잭션 정상
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 마이그레이션 체크리스트
|
||||||
|
|
||||||
|
각 Phase 완료 시 반드시 확인:
|
||||||
|
|
||||||
|
- [ ] 기존 API 엔드포인트 모두 정상 응답
|
||||||
|
- [ ] Docker Compose 정상 실행
|
||||||
|
- [ ] 모의투자 환경에서 주문 성공
|
||||||
|
- [ ] Frontend 대시보드 정상 표시
|
||||||
|
- [ ] 테스트 커버리지 유지 (최소 현재 수준)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 롤백 전략
|
||||||
|
|
||||||
|
각 Phase마다 Git Branch 분리:
|
||||||
|
```
|
||||||
|
main
|
||||||
|
├── feature/refactor-phase1-trading
|
||||||
|
├── feature/refactor-phase2-strategy
|
||||||
|
├── feature/refactor-phase3-risk
|
||||||
|
└── ...
|
||||||
|
```
|
||||||
|
|
||||||
|
Phase 완료 시 main에 merge, 문제 발생 시 이전 브랜치로 revert
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 참고 문서
|
||||||
|
|
||||||
|
- [ARCHITECTURE.md](./docs/ARCHITECTURE.md) - 최종 아키텍처 다이어그램
|
||||||
|
- [CLAUDE.md](./CLAUDE.md) - AI MCP 연동 가이드
|
||||||
|
- [RISK_MANAGEMENT_API.md](./RISK_MANAGEMENT_API.md) - 리스크 API 명세
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 진행 현황
|
||||||
|
|
||||||
|
- [ ] Phase 1: Trading Engine 분리
|
||||||
|
- [ ] Phase 2: Strategy Engine 구축
|
||||||
|
- [ ] Phase 3: Risk Management 통합
|
||||||
|
- [ ] Phase 4: API Layer 다이어트
|
||||||
|
- [ ] Phase 5: Async 실행 흐름 통합
|
||||||
|
- [ ] Phase 6: DB + Cache + MQ 레이어
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated**: 2026-03-06
|
||||||
|
**Author**: 서영우
|
||||||
Reference in New Issue
Block a user