summaryrefslogtreecommitdiff
path: root/docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md
diff options
context:
space:
mode:
authorTheSiahxyz <164138827+TheSiahxyz@users.noreply.github.com>2026-04-02 10:26:52 +0900
committerTheSiahxyz <164138827+TheSiahxyz@users.noreply.github.com>2026-04-02 10:26:52 +0900
commit53cadcf7e34f05f77082e84f0696b56bcbcbae36 (patch)
treee02650e10c4d5727bc1e32e27788c17327fa46f7 /docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md
parentf5521da2876a2c19afc24f370b3258f2be95f81a (diff)
refactor: remove all crypto/Binance code, update to US stock symbols
Diffstat (limited to 'docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md')
-rw-r--r--docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md374
1 files changed, 0 insertions, 374 deletions
diff --git a/docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md b/docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md
deleted file mode 100644
index aa32eb4..0000000
--- a/docs/superpowers/specs/2026-04-01-crypto-trading-platform-design.md
+++ /dev/null
@@ -1,374 +0,0 @@
-# Crypto Trading Platform — Design Spec
-
-## Overview
-
-Binance 현물 암호화폐 자동매매 플랫폼. 마이크로서비스 아키텍처 기반으로 데이터 수집, 전략 실행, 주문 처리, 포트폴리오 관리, 백테스팅을 독립 서비스로 운영한다. CLI로 제어하며, 전략은 플러그인 방식으로 확장 가능하다.
-
-- **시장:** 암호화폐 (Binance 현물)
-- **언어:** Python
-- **인터페이스:** CLI (Click)
-- **아키텍처:** 마이크로서비스 (Docker Compose)
-
----
-
-## Architecture
-
-### 서비스 구성
-
-```
-┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐
-│ Data │───▶│ Message Broker │◀──│ Strategy │
-│ Collector │ │ (Redis Streams) │ │ Engine │
-└─────────────┘ └──────────────────┘ └─────────────────┘
- │ ▲ │
- ▼ │ ▼
- ┌──────────────────┐ ┌─────────────────┐
- │ Backtester │ │ Order │
- │ │ │ Executor │
- └──────────────────┘ └─────────────────┘
- │
- ┌────────────────────────┘
- ▼
- ┌──────────────────┐
- │ Portfolio │
- │ Manager │
- └──────────────────┘
-
- CLI ──────▶ 각 서비스에 명령 전달
-```
-
-| 서비스 | 역할 | 상시 실행 |
-|--------|------|-----------|
-| **data-collector** | Binance WebSocket/REST로 시세 수집, DB 저장 | Yes |
-| **strategy-engine** | 플러그인 전략 로드 및 시그널 생성 | 봇 실행 시 |
-| **order-executor** | 시그널 받아 실제 주문 실행 + 리스크 관리 | 봇 실행 시 |
-| **portfolio-manager** | 잔고, 손익, 포지션 추적 | Yes |
-| **backtester** | 과거 데이터로 전략 검증 | 요청 시 |
-| **shared** | 공통 모델, 이벤트 정의, 유틸리티 (라이브러리) | — |
-| **cli** | 사용자 인터페이스, 각 서비스 제어 | — |
-
-### 통신 흐름
-
-```
-[Binance WS]
- │
- ▼
-data-collector ──publish──▶ Redis Stream: "candles.{symbol}"
- │
- ┌───────────────┤
- ▼ ▼
- strategy-engine backtester (과거 데이터는 DB에서)
- │
- ▼
- Redis Stream: "signals"
- │
- ▼
- order-executor
- │
- ┌───────┴───────┐
- ▼ ▼
- [Binance API] Redis Stream: "orders"
- │
- ▼
- portfolio-manager
-```
-
----
-
-## Project Structure
-
-```
-trading/
-├── services/
-│ ├── data-collector/
-│ │ ├── src/
-│ │ │ ├── __init__.py
-│ │ │ ├── main.py # 서비스 진입점
-│ │ │ ├── binance_ws.py # WebSocket 실시간 시세
-│ │ │ ├── binance_rest.py # REST 과거 데이터 수집
-│ │ │ ├── storage.py # DB 저장 로직
-│ │ │ └── config.py
-│ │ ├── tests/
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ │
-│ ├── strategy-engine/
-│ │ ├── src/
-│ │ │ ├── __init__.py
-│ │ │ ├── main.py
-│ │ │ ├── engine.py # 전략 로더 + 실행기
-│ │ │ ├── plugin_loader.py # 플러그인 동적 로드
-│ │ │ └── config.py
-│ │ ├── strategies/ # 플러그인 전략 디렉토리
-│ │ │ ├── base.py # 전략 추상 클래스
-│ │ │ ├── rsi_strategy.py # 예시: RSI 전략
-│ │ │ └── grid_strategy.py # 예시: 그리드 전략
-│ │ ├── tests/
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ │
-│ ├── order-executor/
-│ │ ├── src/
-│ │ │ ├── __init__.py
-│ │ │ ├── main.py
-│ │ │ ├── executor.py # 주문 실행 로직
-│ │ │ ├── risk_manager.py # 리스크 관리 (손절/익절)
-│ │ │ └── config.py
-│ │ ├── tests/
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ │
-│ ├── portfolio-manager/
-│ │ ├── src/
-│ │ │ ├── __init__.py
-│ │ │ ├── main.py
-│ │ │ ├── portfolio.py # 잔고/포지션 추적
-│ │ │ ├── pnl.py # 손익 계산
-│ │ │ └── config.py
-│ │ ├── tests/
-│ │ ├── Dockerfile
-│ │ └── pyproject.toml
-│ │
-│ └── backtester/
-│ ├── src/
-│ │ ├── __init__.py
-│ │ ├── main.py
-│ │ ├── engine.py # 백테스팅 엔진
-│ │ ├── simulator.py # 가상 주문 시뮬레이터
-│ │ ├── reporter.py # 결과 리포트 생성
-│ │ └── config.py
-│ ├── tests/
-│ ├── Dockerfile
-│ └── pyproject.toml
-│
-├── shared/
-│ ├── src/shared/
-│ │ ├── __init__.py
-│ │ ├── models.py # 공통 데이터 모델
-│ │ ├── events.py # 이벤트 타입 정의
-│ │ ├── broker.py # Redis Streams 클라이언트
-│ │ ├── db.py # DB 연결 (PostgreSQL)
-│ │ └── config.py # 공통 설정
-│ ├── tests/
-│ └── pyproject.toml
-│
-├── cli/
-│ ├── src/
-│ │ ├── __init__.py
-│ │ ├── main.py # Click 기반 CLI 진입점
-│ │ ├── commands/
-│ │ │ ├── data.py # 데이터 수집 명령
-│ │ │ ├── trade.py # 매매 시작/중지
-│ │ │ ├── backtest.py # 백테스팅 실행
-│ │ │ ├── portfolio.py # 포트폴리오 조회
-│ │ │ └── strategy.py # 전략 관리
-│ │ └── config.py
-│ ├── tests/
-│ └── pyproject.toml
-│
-├── docker-compose.yml # 전체 서비스 오케스트레이션
-├── .env.example # 환경변수 템플릿
-├── Makefile # 공통 명령어
-└── README.md
-```
-
----
-
-## Tech Stack
-
-| 용도 | 라이브러리 |
-|------|-----------|
-| 거래소 API | **ccxt** |
-| 메시지 브로커 | **Redis Streams** |
-| DB | **PostgreSQL** + **asyncpg** |
-| CLI | **Click** |
-| 데이터 분석 | **pandas**, **numpy** |
-| 기술 지표 | **pandas-ta** |
-| 비동기 처리 | **asyncio** + **aiohttp** |
-| 설정 관리 | **pydantic-settings** |
-| 컨테이너 | **Docker** + **docker-compose** |
-| 테스트 | **pytest** + **pytest-asyncio** |
-
----
-
-## Data Models
-
-### Core Models (shared/models.py)
-
-```python
-class Candle:
- symbol: str # "BTCUSDT"
- timeframe: str # "1m", "5m", "1h"
- open_time: datetime
- open: Decimal
- high: Decimal
- low: Decimal
- close: Decimal
- volume: Decimal
-
-class Signal:
- strategy: str # "rsi_strategy"
- symbol: str
- side: "BUY" | "SELL"
- price: Decimal
- quantity: Decimal
- reason: str # 시그널 발생 근거
-
-class Order:
- id: str
- signal_id: str # 추적용
- symbol: str
- side: "BUY" | "SELL"
- type: "MARKET" | "LIMIT"
- price: Decimal
- quantity: Decimal
- status: "PENDING" | "FILLED" | "CANCELLED" | "FAILED"
- created_at: datetime
- filled_at: datetime | None
-
-class Position:
- symbol: str
- quantity: Decimal
- avg_entry_price: Decimal
- current_price: Decimal
- unrealized_pnl: Decimal
-```
-
-### PostgreSQL Tables
-
-| 테이블 | 용도 |
-|--------|------|
-| `candles` | 시세 이력 (파티셔닝: symbol + timeframe) |
-| `signals` | 전략 시그널 이력 |
-| `orders` | 주문 이력 |
-| `trades` | 체결 이력 |
-| `positions` | 현재 포지션 |
-| `portfolio_snapshots` | 일별 포트폴리오 스냅샷 |
-
-### Storage Strategy
-
-- **실시간 시세:** Redis 캐싱 + PostgreSQL 영구 저장
-- **주문/체결:** PostgreSQL 즉시 기록
-- **백테스팅 데이터:** PostgreSQL에서 bulk read (pandas DataFrame)
-
----
-
-## Strategy Plugin System
-
-### Base Interface
-
-```python
-from abc import ABC, abstractmethod
-from shared.models import Candle, Signal
-
-class BaseStrategy(ABC):
- @abstractmethod
- def on_candle(self, candle: Candle) -> Signal | None:
- """캔들 데이터 수신 시 시그널 반환"""
- pass
-
- @abstractmethod
- def configure(self, params: dict) -> None:
- """전략 파라미터 설정"""
- pass
-```
-
-새 전략 추가 = `BaseStrategy` 상속 파일 하나 작성 후 `strategies/` 디렉토리에 배치.
-
-### 예시 전략
-
-- **RSI Strategy:** RSI 과매도 시 매수, 과매수 시 매도
-- **Grid Strategy:** 가격 구간을 나눠 자동 매수/매도 주문 배치
-
----
-
-## CLI Interface
-
-```bash
-# 데이터 수집
-trading data collect --symbol BTCUSDT --timeframe 1m
-trading data history --symbol BTCUSDT --from 2025-01-01
-trading data list
-
-# 자동매매
-trading trade start --strategy rsi --symbol BTCUSDT
-trading trade stop --strategy rsi
-trading trade status
-
-# 수동매매
-trading order buy --symbol BTCUSDT --quantity 0.01
-trading order sell --symbol BTCUSDT --price 70000
-trading order cancel --id abc123
-
-# 백테스팅
-trading backtest run --strategy rsi --symbol BTCUSDT \
- --from 2025-01-01 --to 2025-12-31
-trading backtest report --id latest
-
-# 포트폴리오
-trading portfolio show
-trading portfolio history --days 30
-
-# 전략 관리
-trading strategy list
-trading strategy info --name rsi
-
-# 서비스 관리
-trading service up
-trading service down
-trading service logs --name strategy-engine
-```
-
----
-
-## Risk Management
-
-### Risk Check Pipeline (order-executor)
-
-시그널 수신 시 다음 체크를 순서대로 통과해야 주문 실행:
-
-1. 최대 포지션 크기 초과 여부
-2. 일일 최대 손실 한도 도달 여부
-3. 동일 심볼 중복 주문 방지
-4. 주문 금액 < 가용 잔고 확인
-5. 가격 급변 감지 (슬리피지 보호)
-
-### Safety Mechanisms
-
-| 장치 | 설명 |
-|------|------|
-| **긴급 정지 (Kill Switch)** | `trading trade stop-all` — 모든 봇 중지, 미체결 주문 전량 취소 |
-| **일일 손실 한도** | 설정 비율 초과 시 자동 매매 중단 |
-| **최대 포지션 제한** | 총 자산 대비 단일 심볼 비율 제한 |
-| **연결 끊김 대응** | Binance 연결 끊기면 신규 주문 중단, 재연결 시도 |
-| **드라이런 모드** | 실제 주문 없이 시그널만 생성 — 전략 검증용 |
-
----
-
-## Configuration (.env)
-
-```
-BINANCE_API_KEY=
-BINANCE_API_SECRET=
-REDIS_URL=redis://localhost:6379
-DATABASE_URL=postgresql://user:pass@localhost:5432/trading
-LOG_LEVEL=INFO
-RISK_MAX_POSITION_SIZE=0.1
-RISK_STOP_LOSS_PCT=5
-RISK_DAILY_LOSS_LIMIT_PCT=10
-DRY_RUN=true
-```
-
----
-
-## Docker Compose Services
-
-```yaml
-services:
- redis: # 메시지 브로커 (항상 실행)
- postgres: # 데이터 저장소 (항상 실행)
- data-collector: # 시세 수집 (항상 실행)
- strategy-engine: # 전략 엔진 (봇 실행 시)
- order-executor: # 주문 실행 (봇 실행 시)
- portfolio-manager: # 포트폴리오 (항상 실행)
-```