crypto_quant/doc/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	完整的功能覆盖

📝 使用示例

基本使用

# 创建实例
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)

查询示例

# 查询最新交易
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')

统计分析示例

# 获取完整统计信息
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. 扩展性：易于维护和扩展

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