crypto_quant/DB_TRADE_DATA_SUMMARY.md

# DBTradeData 类设计总结

## 📋 概述

根据 `crypto_trade_data.sql` 表结构和 `db_market_data.py` 的设计模式，创建了 `DBTradeData` 类，用于管理加密货币交易数据的存储和查询。

## 🏗️ 表结构映射

### 字段映射

| SQL字段 | Python字段 | 类型 | 说明 |
|---------|------------|------|------|
| `symbol` | `symbol` | VARCHAR(50) | 交易对 |
| `ts` | `ts` | BIGINT | 交易时间戳 |
| `date_time` | `date_time` | VARCHAR(50) | 交易日期时间 |
| `tradeId` | `tradeId` | VARCHAR(50) | 交易ID |
| `side` | `side` | VARCHAR(10) | 交易方向(buy/sell) |
| `sz` | `sz` | DECIMAL(30,8) | 交易数量 |
| `px` | `px` | DECIMAL(20,5) | 交易价格 |
| `create_time` | `create_time` | VARCHAR(50) | 创建时间 |

### 索引支持

- `uniq_tradeId`: 交易ID唯一索引
- `idx_symbol`: 交易对索引
- `idx_side`: 交易方向索引
- `idx_ts`: 时间戳索引
- `idx_date_time`: 日期时间索引
- `idx_symbol_ts`: 交易对+时间戳复合索引
- `idx_side_ts`: 交易方向+时间戳复合索引

## 🔧 核心功能

### 1. 数据插入方法

| 方法名 | 速度 | 内存 | 适用场景 |
|--------|------|------|----------|
| `insert_data_to_mysql` | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 中小数据量（<10万条） |
| `insert_data_to_mysql_fast` | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 中等数据量 |
| `insert_data_to_mysql_chunk` | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 大数据量（>10万条） |
| `insert_data_to_mysql_simple` | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 简单插入（忽略重复） |

### 2. 基础查询方法

| 方法名 | 功能 | 参数 |
|--------|------|------|
| `query_latest_data` | 查询最新交易数据 | `symbol` |
| `query_data_by_tradeId` | 根据交易ID查询 | `tradeId` |
| `query_trade_data_by_symbol` | 根据交易对查询 | `symbol`, `start`, `end` |
| `query_trade_data_by_side` | 根据交易方向查询 | `side`, `symbol`, `start`, `end` |

### 3. 便捷查询方法

| 方法名 | 功能 | 说明 |
|--------|------|------|
| `query_buy_trades` | 查询买入交易 | 封装了 `query_trade_data_by_side("buy")` |
| `query_sell_trades` | 查询卖出交易 | 封装了 `query_trade_data_by_side("sell")` |
| `get_recent_trades` | 获取最近交易 | 支持限制返回数量 |

### 4. 统计分析方法

| 方法名 | 功能 | 返回数据 |
|--------|------|----------|
| `get_trade_statistics` | 交易统计信息 | 总交易数、买卖数量、成交量、价值等 |
| `get_volume_price_analysis` | 成交量价格分析 | 按买卖方向分组的统计分析 |

### 5. 范围查询方法

| 方法名 | 功能 | 参数 |
|--------|------|------|
| `get_trades_by_price_range` | 价格范围查询 | `min_price`, `max_price`, `symbol`, `start`, `end` |
| `get_trades_by_volume_range` | 成交量范围查询 | `min_volume`, `max_volume`, `symbol`, `start`, `end` |

## 🚀 设计亮点

### 1. 代码质量
- ✅ **类型提示完整**：所有方法都有完整的类型提示
- ✅ **私有方法提取**：重复逻辑提取为私有方法
- ✅ **错误处理统一**：统一的错误处理机制
- ✅ **代码风格规范**：符合PEP 8标准

### 2. 功能完整性
- ✅ **多种插入方式**：支持不同场景的数据插入
- ✅ **丰富查询接口**：支持多种查询需求
- ✅ **统计分析功能**：提供完整的统计分析
- ✅ **范围查询支持**：支持价格和成交量范围查询

### 3. 性能优化
- ✅ **索引利用**：充分利用数据库索引
- ✅ **条件构建优化**：统一的查询条件构建
- ✅ **时间处理优化**：统一的时间参数处理

## 📊 方法统计

| 类别 | 数量 | 方法列表 |
|------|------|----------|
| 私有方法 | 2 | `_process_time_parameter`, `_build_query_conditions` |
| 插入方法 | 4 | `insert_data_to_mysql`, `insert_data_to_mysql_fast`, `insert_data_to_mysql_chunk`, `insert_data_to_mysql_simple` |
| 基础查询 | 4 | `query_latest_data`, `query_data_by_tradeId`, `query_trade_data_by_symbol`, `query_trade_data_by_side` |
| 便捷查询 | 3 | `query_buy_trades`, `query_sell_trades`, `get_recent_trades` |
| 统计分析 | 2 | `get_trade_statistics`, `get_volume_price_analysis` |
| 范围查询 | 2 | `get_trades_by_price_range`, `get_trades_by_volume_range` |
| **总计** | **17** | **完整的功能覆盖** |

## 📝 使用示例

### 基本使用
```python
# 创建实例
db_trade_data = DBTradeData("mysql+pymysql://user:pass@localhost/db")

# 插入数据
df = pd.DataFrame({
    'symbol': ['BTC-USDT'],
    'ts': [1654161646974],
    'date_time': ['2022-06-01 12:34:56'],
    'tradeId': ['242720720'],
    'side': ['sell'],
    'sz': [0.00001],
    'px': [29963.2],
    'create_time': ['2024-01-01 10:00:00']
})
db_trade_data.insert_data_to_mysql(df)
```

### 查询示例
```python
# 查询最新交易
latest = db_trade_data.query_latest_data('BTC-USDT')

# 查询买入交易
buy_trades = db_trade_data.query_buy_trades('BTC-USDT', start='2024-01-01')

# 获取交易统计
stats = db_trade_data.get_trade_statistics('BTC-USDT')

# 价格范围查询
trades = db_trade_data.get_trades_by_price_range(50000, 60000, 'BTC-USDT')

# 成交量分析
analysis = db_trade_data.get_volume_price_analysis('BTC-USDT')
```

### 统计分析示例
```python
# 获取完整统计信息
stats = db_trade_data.get_trade_statistics('BTC-USDT', start='2024-01-01', end='2024-01-31')
# 返回：总交易数、买卖数量、成交量、价值、价格范围等

# 获取买卖方向分析
analysis = db_trade_data.get_volume_price_analysis('BTC-USDT')
# 返回：按买卖方向分组的成交量、价值、平均价格等
```

## 🔄 兼容性说明

- ✅ **向后兼容**：保持与现有代码的兼容性
- ✅ **扩展性强**：易于添加新的查询方法
- ✅ **配置灵活**：支持多种数据库配置
- ✅ **错误处理**：完善的错误处理机制

## 📈 总结

`DBTradeData` 类提供了完整的交易数据管理功能：

1. **功能完整性**：支持所有常见的交易数据操作
2. **性能优化**：多种插入方式和查询优化
3. **代码质量**：类型提示、错误处理、代码规范
4. **易用性**：丰富的查询接口和便捷方法
5. **扩展性**：易于维护和扩展

该类为加密货币交易数据的存储、查询和分析提供了强大的支持，是量化交易系统的重要组成部分。