# Bitget 实盘交易迁移方案

> **目标**: 将当前的模拟交易系统切换到 Bitget 实盘合约交易
>
> **状态**: 方案制定中 - 未实施

---

## 一、当前系统架构分析

### 1.1 模拟交易系统现状

**核心文件**: `backend/app/services/paper_trading_service.py`

**主要功能**:
- ✅ 订单创建 (`create_order_from_signal`)
- ✅ 订单平仓 (`_close_order`, `close_order_manual`)
- ✅ 止盈止损检查 (`check_price_triggers`)
- ✅ 移动止损逻辑
- ✅ 账户余额管理
- ✅ 持仓信息查询

**订单状态管理**:
- `PENDING` - 挂单中（等待入场价格）
- `OPEN` - 已开仓
- `CLOSED` - 已平仓

**配置参数** (`.env`):
```bash
PAPER_TRADING_ENABLED=true                    # 启用模拟交易
PAPER_TRADING_INITIAL_BALANCE=10000           # 初始本金
PAPER_TRADING_LEVERAGE=20                     # 杠杆倍数
PAPER_TRADING_MARGIN_PER_ORDER=1000          # 每单保证金
PAPER_TRADING_MAX_ORDERS=10                   # 最大订单数
PAPER_TRADING_AUTO_CLOSE_OPPOSITE=false      # 自动平反向持仓
PAPER_TRADING_TRAILING_STOP_ENABLED=true     # 移动止损
```

### 1.2 数据流向

```
LLM 分析信号 → PaperTradingService → 数据库记录
                ↓
           本地模拟执行
                ↓
           止盈止损检查（本地价格轮询）
```

---

## 二、实盘交易架构设计

### 2.1 整体方案

**方案 A - 双模式并存** (推荐)
- 保留模拟交易作为回测和测试
- 新增实盘交易服务
- 通过配置开关切换

**方案 B - 完全替换**
- 直接将模拟交易改为实盘
- 风险较高，不推荐

### 2.2 核心组件设计

```
┌─────────────────────────────────────────────────────────────┐
│                      交易服务层                              │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────┐         ┌──────────────────┐         │
│  │ PaperTradingService │         │ RealTradingService │       │
│  │  (模拟交易)        │         │  (实盘交易)        │       │
│  └──────────────────┘         └──────────────────┘         │
│           │                            │                     │
│           └────────────┬───────────────┘                   │
│                        ▼                                     │
│              ┌──────────────────┐                           │
│              │ TradingInterface │ (统一接口)                │
│              └──────────────────┘                           │
│                        │                                     │
│                        ▼                                     │
│           ┌──────────────────────┐                         │
│           │   BitgetTradingAPI   │                         │
│           │   (实盘交易API)       │                         │
│           └──────────────────────┘                         │
└─────────────────────────────────────────────────────────────┘
```

---

## 三、Bitget 实盘 API 需求

### 3.1 需要 API 功能

| 功能 | Bitget API 端点 | 说明 |
|------|----------------|------|
| **下单** | `POST /api/mix/v1/order/placeOrder` | U本位合约下单 |
| **撤单** | `POST /api/mix/v1/order/cancelOrder` | 撤销挂单 |
| **平仓** | `POST /api/mix v1/order/closePosition` | 平仓持仓 |
| **查询持仓** | `GET /api/mix/v1/position/allPosition` | 获取当前持仓 |
| **查询订单** | `GET /api/mix/v1/order/orderInfo` | 获取订单状态 |
| **修改订单** | `POST /api/mix/v1/order/modifyOrder` | 修改挂单价格 |
| **账户余额** | `GET /api/mix/v1/account/account` | 获取账户余额 |
| **设置杠杆** | `POST /api/mix/v1/account/setLeverage` | 设置杠杆倍数 |

### 3.2 Bitget 订单类型

```python
# 订单方向
side_map = {
    'long': 'open_long',   # 开多
    'short': 'open_short', # 开空
}

# 订单类型
order_type_map = {
    'limit': 'limit',   # 限价单（挂单）
    'market': 'market', # 市价单
}

# 产品类型
product_type = 'USDT-FUTURES'  # U本位永续合约
```

### 3.3 订单参数映射

| 模拟交易参数 | Bitget API 参数 | 说明 |
|-------------|----------------|------|
| `symbol` | `symbol` | 交易对 (如 BTCUSDT) |
| `side` | `side` | open_long/close_long/open_short/close_short |
| `order_type` | `orderType` | limit/market |
| `quantity` | `size` | 数量（张数） |
| `entry_price` | `price` | 委托价格 |
| `stop_loss` | `stopLoss` | 止损价格 |
| `take_profit` | `takeProfit` | 止盈价格 |
| `leverage` | `leverage` | 杠杆倍数 |

---

## 四、实施步骤

### 阶段一：准备工作 (1-2天)

#### 1.1 Bitget API 密钥申请
- [ ] 注册 Bitget 账户
- [ ] 开启合约交易功能
- [ ] 创建 API Key
- [ ] 配置 IP 白名单
- [ ] **选择测试网进行初期测试**

#### 1.2 测试网环境搭建
- [ ] 获取 Bitget 测试网凭证
- [ ] 配置测试网 API 端点：`https://api-testnet.bitget.com`
- [ ] 验证 API 连接性

#### 1.3 风险控制参数设置
```bash
# .env 新增配置
BITGET_API_KEY=your_api_key
BITGET_API_SECRET=your_api_secret
BITGET_PASSPHRASE=your_passphrase  # 如果需要
BITGET_USE_TESTNET=true  # 初期使用测试网

# 实盘交易配置
REAL_TRADING_ENABLED=false          # 实盘交易总开关
REAL_TRADING_MAX_POSITION=5000      # 单笔最大持仓 (USDT)
REAL_TRADING_MAX_TOTAL_RATIO=0.5    # 最大总仓位比例（账户的50%）
REAL_TRADING_DEFAULT_LEVERAGE=10    # 默认杠杆（低于模拟）
REAL_TRADING_RISK_PER_TRADE=0.02    # 每笔交易风险（2%）
```

### 阶段二：实盘交易服务开发 (2-3天)

#### 2.1 创建 `BitgetTradingAPI` 类

**文件**: `backend/app/services/bitget_trading_api.py`

```python
class BitgetTradingAPI:
    """Bitget 实盘交易 API"""

    def __init__(self, api_key: str, api_secret: str, use_testnet: bool = True):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = TESTNET_URL if use_testnet else PROD_URL

    def place_order(self, symbol: str, side: str, size: float,
                   price: float = None, order_type: str = 'limit') -> dict:
        """下单"""
        # POST /api/mix/v1/order/placeOrder

    def cancel_order(self, symbol: str, order_id: str) -> dict:
        """撤单"""
        # POST /api/mix/v1/order/cancelOrder

    def close_position(self, symbol: str, side: str, size: float) -> dict:
        """平仓"""
        # POST /api/mix/v1/order/closePosition

    def get_position(self, symbol: str = None) -> list:
        """查询持仓"""
        # GET /api/mix/v1/position/allPosition

    def get_balance(self) -> dict:
        """查询余额"""
        # GET /api/mix/v1/account/account

    def set_leverage(self, symbol: str, leverage: int) -> dict:
        """设置杠杆"""
        # POST /api/mix/v1/account/setLeverage
```

#### 2.2 创建 `RealTradingService` 类

**文件**: `backend/app/services/real_trading_service.py`

**核心方法**:
```python
class RealTradingService:
    """实盘交易服务 - 接口与 PaperTradingService 保持一致"""

    def create_order_from_signal(self, signal: Dict, current_price: float) -> Dict:
        """从信号创建实盘订单"""
        # 1. 风险检查（仓位、杠杆、余额）
        # 2. 调用 BitgetTradingAPI.place_order()
        # 3. 记录订单到数据库
        # 4. 发送通知

    def check_price_triggers(self, symbol: str, price: float) -> List:
        """检查止盈止损（从 Bitget 获取持仓状态）"""
        # 1. 获取实际持仓状态
        # 2. 判断是否触发止盈止损
        # 3. 调用平仓 API

    def get_account_status(self) -> Dict:
        """获取账户状态"""
        # 调用 Bitget API 获取真实余额和持仓
```

### 阶段三：集成与切换 (1-2天)

#### 3.1 配置开关设计

```python
# config.py
class Settings(BaseSettings):
    # 交易模式选择
    trading_mode: str = "paper"  # "paper" 或 "real"

    # 模拟交易配置（保留）
    paper_trading_enabled: bool = True

    # 实盘交易配置
    real_trading_enabled: bool = False

    # Bitget API 配置
    bitget_api_key: str = ""
    bitget_api_secret: str = ""
    bitget_use_testnet: bool = True
```

#### 3.2 服务切换逻辑

```python
# crypto_agent.py 或根据 trading_mode 动态选择
if settings.trading_mode == "paper":
    from app.services.paper_trading_service import get_paper_trading_service
    trading_service = get_paper_trading_service()
else:
    from app.services.real_trading_service import get_real_trading_service
    trading_service = get_real_trading_service()
```

#### 3.3 修改的文件清单

| 文件 | 修改内容 |
|------|---------|
| `config.py` | 添加实盘交易配置项 |
| `crypto_agent.py` | 添加交易模式选择逻辑 |
| `main.py` | 价格监控适配实盘交易 |
| `api/paper_trading.py` | 添加实盘交易 API 端点 |

### 阶段四：测试验证 (2-3天)

#### 4.1 测试网测试
- [ ] 下单功能测试
- [ ] 撤单功能测试
- [ ] 平仓功能测试
- [ ] 持仓查询测试
- [ ] 止盈止损触发测试

#### 4.2 小资金实盘测试
- [ ] 使用小额资金（如 100 USDT）
- [ ] 执行 10-20 笔交易
- [ ] 验证盈亏计算准确性
- [ ] 验证通知及时性

#### 4.3 压力测试
- [ ] 极端行情下系统稳定性
- [ ] API 限频处理
- [ ] 网络异常恢复
- [ ] 订单状态同步

---

## 五、风险控制

### 5.1 技术风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| API 故障 | 无法交易 | 多重异常处理 + 飞书告警 |
| 网络延迟 | 滑点增大 | 限价单为主，设置合理价格偏差 |
| 订单状态不同步 | 重复开仓 | 定期同步持仓状态 |
| 限频被封 | 暂停交易 | 请求频率控制 + 重试机制 |

### 5.2 交易风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 策略失效 | 亏损 | 测试网充分验证 + 小资金试运行 |
| 极端行情 | 爆仓 | 严格止损 + 仓位控制 |
| 误操作 | 意外亏损 | 双重确认 + 实盘交易前测试 |
| API 泄露 | 资金风险 | IP 白名单 + 只读权限分离 |

### 5.3 资金管理建议

```python
# 资金管理配置
MAX_ACCOUNT_RATIO = 0.5        # 最大使用账户50%资金
MAX_SINGLE_POSITION = 0.1     # 单笔最大10%仓位
MAX_TOTAL_POSITION = 0.3      # 总持仓最大30%
DEFAULT_LEVERAGE = 10          # 实盘杠杆低于模拟(20x)
STOP_LOSS_PERCENT = 0.02      # 每笔最大亏损2%
```

---

## 六、监控与告警

### 6.1 必需监控指标

```python
# 实时监控
- 账户余额变化
- 持仓盈亏实时状态
- 订单执行状态
- API 调用成功率
- 系统响应时间
```

### 6.2 告警机制

```python
# 飞书告警场景
- 订单执行失败
- 止损/止盈触发
- 账户余额异常变化
- API 连接失败
- 系统异常错误
```

### 6.3 日志记录

```python
# 实盘交易必需日志
- 每笔订单的完整生命周期
- API 请求和响应记录
- 价格监控日志
- 错误和异常详情
```

---

## 七、实施时间表

| 阶段 | 任务 | 预计时间 | 依赖 |
|------|------|---------|------|
| **阶段一** | 准备工作 | 1-2天 | - |
| **阶段二** | 实盘服务开发 | 2-3天 | 阶段一完成 |
| **阶段三** | 集成与切换 | 1-2天 | 阶段二完成 |
| **阶段四** | 测试验证 | 2-3天 | 阶段三完成 |
| **总计** | | **6-10天** | |

---

## 八、关键决策点

### 8.1 必须解决的问题

1. ✅ **订单映射**
   - 模拟交易订单 ↔ Bitget 实盘订单 ID
   - 状态同步机制

2. ✅ **持仓同步**
   - 定期从 Bitget 获取实际持仓
   - 与本地数据库保持一致

3. ✅ **止损策略**
   - 模拟交易：本地价格轮询检查
   - 实盘交易：可使用 Bitget 条件单 API

4. ✅ **错误处理**
   - API 失败时的降级策略
   - 部分成交处理

### 8.2 可选优化

1. ⭕ **条件单 API**
   - 使用 Bitget 条件单实现止损止盈
   - 减少本地轮询，降低 API 调用

2. ⭕ **WebSocket 推送**
   - 使用 Bitget WebSocket 实时获取成交和持仓更新
   - 降低延迟

3. ⭕ **仓位管理优化**
   - 根据账户余额动态调整仓位
   - 凯利公式资金管理

---

## 九、推荐实施顺序

### 第一步：最小化实盘功能 (3-4天)
- ✅ 实现 `BitgetTradingAPI` 基础下单/撤单/平仓
- ✅ 实现 `RealTradingService` 核心功能
- ✅ 测试网验证

### 第二步：完整集成 (2-3天)
- ✅ 添加配置开关
- ✅ 修改现有调用逻辑
- ✅ 数据库适配

### 第三步：生产验证 (持续)
- ✅ 小资金试运行
- ✅ 监控告警完善
- ✅ 逐步增加资金规模

---

## 十、总结与建议

### ✅ 可行性评估

| 方面 | 评估 | 说明 |
|------|------|------|
| **技术可行性** | ✅ 高 | Bitget API 完善，所有功能都支持 |
| **实施复杂度** | ⚠️ 中 | 需要处理订单同步、状态管理 |
| **风险可控性** | ✅ 高 | 测试网 + 小资金 + 双重确认 |
| **时间投入** | ⚠️ 中 | 6-10天完整实施 |

### ⚠️ 重要提醒

1. **先在测试网充分验证**
   - 所有功能都在测试网验证通过
   - 模拟各种异常情况

2. **小资金试运行**
   - 初期使用最小可交易资金
   - 验证1-2周后再逐步增加

3. **保留模拟交易**
   - 双模式并存，随时可切回模拟
   - 用于策略回测和新功能验证

4. **严格风控**
   - 实盘杠杆低于模拟
   - 仓位控制更保守
   - 止损必须执行

### 📋 下一步行动

**如果你确认要实施实盘交易，建议按以下顺序进行**:

1. **立即**: 申请 Bitget 测试网账户和 API 密钥
2. **第1天**: 创建 `BitgetTradingAPI` 基础类
3. **第2-3天**: 实现核心交易功能（下单、撤单、平仓）
4. **第4-5天**: 测试网验证所有功能
5. **第6-7天**: 小资金实盘测试（100 USDT）
6. **验证稳定后**: 逐步增加资金规模

---

**方案制定完成，等待确认后开始实施**