auto-stock/docs/REFACTORING_PLAN.md

AutoStock 리팩토링 마스터 플랜

⚠️ 폐기됨 (2026-09-27) 이 계획이 목표로 삼은 app/strategy/ 패키지(strategy_manager, base_strategy, signal, indicators, scanner, strategies/)는 어디서도 import되지 않는 죽은 코드로 확인되어 삭제되었습니다. short_term_strategy.py, kosdaq_scanner.py 도 함께 제거되었습니다(2.5 항목 무효). 아래 내용은 이력 참고용이며, 현재 구조는 CLAUDE.md §2 를 따릅니다. 전략 구조를 다시 손대려면 CLAUDE.md §8.5(미해결 항목)부터 확인하십시오.

---

목표: 현재 엉망진창인 구조를 유지보수 가능한 모듈형 아키텍처로 전환
원칙: 기존 코드는 버리지 않고 재배치 + 추상화 레이어 추가
일정: 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) 예시:

# 현재 (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 태스크 통합

# 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 - 최종 아키텍처 다이어그램
• CLAUDE.md - AI MCP 연동 가이드
• 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: 서영우