fix: 매매 파라미터 3중 소스 정합 + 리스크 가드 복원 + 죽은 코드 2,695줄 제거

## 배경 "전략이 혼란스럽고 현재와 맞지 않는다"를 조사한 결과, 전략 설계가 아니라 전략을 검증했다는 도구와 파라미터 소스가 어긋나 있었다. ## 파라미터 소스 단일화 - 우선순위가 adaptive > strategy_cfg(DB) > config.py 인데 문서는 맨 마지막인 config.py 를 기술하고 있었다. 11곳이 불일치(BULL RSI 46 vs DB 30, SL -7% vs -6%). - DEFAULT_PARAMS 를 config.py 에 정합 + alembic 0012 로 기존 DB 행 갱신 (운영자가 UI 로 바꾼 값은 보존, 옛 기본값과 같은 행만 갱신, 테이블 가드·멱등) ## 백테스트를 실전 로직에 정합 - calculate_adx_simple 이 정확히 period 배(14.0×) 발산 → Aggressive 게이트 `ADX>25` 가 전 레짐 100% 통과. 전환 빈도 5.6%→2.0%(-65%), 성과 상방 편향 - 백테스트 RSI 는 SMA, 실전은 Wilder → 진입 판정 10~11% 불일치 - us_backtest_engine RSI 1봉 지연 제거 (룩어헤드 없음을 절단 테스트로 증명) - backend/backtest_results/ 25건은 폐기 대상 (§8.4) ## 리스크 가드 복원 - 4% 절대 상한이 try 블록 안에 있어 예외 시 적응형 6~7% 가 통과 → try 밖으로 - 청산을 매수보다 먼저 평가 (보유 종목이 추천에 들면 손절 대신 물타기가 나갔다) - 리스크 가드 4개를 매수 전용화 → MDD -10%·보유한도 도달 시에도 손절 작동 - MDD 갱신 5회 연속 실패 시 신규 진입 차단 fail-safe (청산은 계속 허용) - 스윙 청산이 DT 보유분까지 매도하던 문제, sell_pct 기준 혼재 정정 ## 죽은 코드 제거 (2,695줄) - short_term_strategy, kosdaq_scanner, app/strategy/ 패키지 - app/trading/ + korea_investment_api_adapter (real_market_api 정본은 korea_investment_api.py:1482, adapter 는 import 0건) ## 지표·사이징 단일화 (수치 무변경 증명) - indicators_core.py: 3,274건 비교 최대 오차 0.000e+00 - sizing_core.py: 42,105건 비교 불일치 0 - 미국 전략 상수 13개 config 편입 (hex 까지 동일, 3,168 케이스 전수 비교) ## 테스트 안전 (실 KIS 호출 차단) - 유닛 테스트가 실제 KIS 에 매도 주문을 2회 전송하고 있었다. 리팩터링이 close_stale_positions 의 대상을 _execute_exit → _execute_exit_stale 로 바꿨는데 목이 전자에 걸려 빗나갔다. test_api_endpoints 도 캡처된 싱글톤 참조 누수로 실제 잔고 조회를 타 141초를 소비했다. - backend/tests/conftest.py 신설: 주문·토큰·시세·잔고를 호출 즉시 예외로 차단. 예외는 BaseException 파생(프로덕션 except Exception 폴백에 삼켜지지 않게), 클래스 메서드에 적용(캡처된 참조까지 덮음), DATABASE_URL `_test` 가드 강제 - 전체 유닛 스위트: 365초/6 failed → 11.8초/0 failed (소켓 차단 하 559 passed) ## 신규 (둘 다 플래그 OFF, 백테스트 미검증) - range_trading_strategy.py — SIDEWAYS 담당 전략이 없던 빈 칸. 미배선 - check_bear_buy_signal_v2 — BEAR 4중 AND(발화율 2.3%) → 점수제(12.4%) ## 문서 - CLAUDE.md 를 실제 코드 기준으로 재작성. §0 파라미터 우선순위, §4.1 테스트 규약, §6.4 문서화되지 않았던 진입 차단 게이트 9종, §8.4 백테스트 폐기 근거, §8.5 미해결 19항목 - 루트 md 6개 → 2개(docs/ 이동), 중복 배치 문서 병합, 스테일 worktree 제거 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-28 08:58:18 +09:00
parent b4608e5abf
commit 1b9257c4d2
71 changed files with 5510 additions and 3685 deletions
--- a/docs/REFACTORING_PLAN.md
+++ b/docs/REFACTORING_PLAN.md
@@ -0,0 +1,286 @@
+# 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) 예시:
+```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**: 서영우