# Bitget Python SDK 迁移指南

## 概述

已将 Bitget 交易 API 从手动实现迁移到使用 **CCXT Python SDK**。

## 主要变化

### 1. 依赖变更

**新增依赖：**
```bash
pip install ccxt>=4.0.0
```

### 2. 文件结构

| 旧文件 | 新文件 | 说明 |
|--------|--------|------|
| `bitget_trading_api.py` | `bitget_trading_api_sdk.py` | 使用 CCXT 的新实现 |
| - | `scripts/test_bitget_sdk.py` | SDK 测试脚本 |

### 3. API 响应格式变化

#### 旧版本（直接 API）
```python
# 订单响应格式
{
    'orderId': '123456789',
    'fillPrice': '50000.5',
    ...
}
```

#### 新版本（CCXT）
```python
# 订单响应格式
{
    'id': '123456789',
    'price': '50000.0',      # 委托价格
    'average': '50000.5',    # 成交均价
    'status': 'closed',      # CCXT 标准状态
    ...
}
```

### 4. 订单方向变化

#### 旧版本
```python
side_map = {
    OrderSide.LONG: 'open_long',
    OrderSide.SHORT: 'open_short'
}
```

#### 新版本（CCXT 标准化）
```python
side_map = {
    OrderSide.LONG: 'buy',
    OrderSide.SHORT: 'sell'
}
```

### 5. 交易对格式

#### 旧版本
```
BTCUSDT
ETHUSDT
```

#### 新版本（CCXT 标准化）
```
BTC/USDT:USDT
ETH/USDT:USDT
```

新实现会自动进行格式转换。

## 安装步骤

### 1. 安装依赖

```bash
cd backend
pip install -r requirements.txt
```

### 2. 配置环境变量

在 `.env` 文件中配置：

```bash
# Bitget API 配置
BITGET_API_KEY=your_api_key_here
BITGET_API_SECRET=your_api_secret_here
BITGET_PASSPHRASE=              # Bitget 不需要，保留兼容性
BITGET_USE_TESTNET=true         # 测试时设为 true

# 实盘交易开关
REAL_TRADING_ENABLED=false      # 生产环境再启用
```

### 3. 测试连接

```bash
cd scripts
python test_bitget_sdk.py
```

预期输出：
```
============================================================
测试 1: API 连接测试
============================================================
✅ API 连接成功，USDT 余额: 10000.00

============================================================
测试 2: 查询账户余额
============================================================
✅ 余额查询成功
  USDT: 可用=10000.00, 冻结=0.00
...
```

## CCXT 的优势

1. **统一接口** - 同样的代码可以支持多个交易所（Binance, OKX, Bybit 等）
2. **更好的维护** - CCXT 团队持续更新，修复 API 变更
3. **内置重试** - 自动处理网络问题和速率限制
4. **标准化格式** - 统一的订单状态、交易对格式
5. **异步支持** - 支持 async/await 模式

## API 功能对比

| 功能 | 旧实现 | 新实现（CCXT） |
|------|--------|----------------|
| 下单 | ✅ | ✅ |
| 撤单 | ✅ | ✅ |
| 查询订单 | ✅ | ✅ |
| 查询挂单 | ✅ | ✅ |
| 查询持仓 | ✅ | ✅ |
| 查询余额 | ✅ | ✅ |
| 设置杠杆 | ✅ | ✅ |
| 测试网支持 | ✅ | ✅ |
| 自动重试 | ❌ | ✅ |
| 速率限制 | ❌ | ✅ |

## 兼容性说明

- ✅ `real_trading_service.py` 已更新使用新 SDK
- ✅ 保持相同的公共接口
- ✅ 数据库模型无需更改
- ⚠️ 需要重新测试实盘交易功能

## 下一步

1. **在测试网验证** - 确保所有功能正常
2. **小资金实盘测试** - 验证订单执行
3. **监控日志** - 检查是否有任何错误
4. **逐步迁移** - 确认稳定后使用新版本

## 回滚方案

如果需要回滚到旧版本：

1. 修改 `real_trading_service.py` 第 33 行：
```python
# 从
from app.services.bitget_trading_api_sdk import get_bitget_trading_api

# 改回
from app.services.bitget_trading_api import get_bitget_trading_api
```

2. 重启服务

## 相关资源

- CCXT 官方文档: https://docs.ccxt.com/
- CCXT Bitget 支持: https://docs.ccxt.com/#exchange-sources
- Bitget 官方文档: https://www.bitget.com/api-doc

## 支持

如有问题，请检查：
1. CCXT 版本是否 >= 4.0.0
2. API 密钥是否正确
3. 网络连接是否正常
4. 测试网是否可用