股票数据模型

概述

股票数据模型用于存储和管理股票交易相关的数据，包括价格、成交量、时间戳等信息。

数据模型

StockData (股票数据)

字段名	类型	描述	示例	约束
code	string	股票代码	“YINN.US”	必填，唯一标识，包含市场后缀
open	float	开盘价	12.34	必填，≥0，保留2位小数
high	float	最高价	13.45	必填，≥0，保留2位小数
low	float	最低价	11.23	必填，≥0，保留2位小数
close	float	收盘价	12.78	必填，≥0，保留2位小数
volume	int	成交量	1000000	必填，≥0
turnover	float	成交额	12780000.00	必填，≥0，保留2位小数
timestamp	int	时间戳	1704067200	必填，UNIX时间戳
trade_session	enum	交易时段	“Intraday”	必填，见交易时段枚举

TradeSession (交易时段枚举)

值	描述
Intraday	盘中交易
Pre	盘前交易
Post	盘后交易
Overnight	夜盘交易

数据存储

Redis存储结构

stock_data:{code}:{timestamp_iso}  # 股票数据详情 (Hash)
stock_codes                        # 股票代码集合 (Set)
stock_data:time_index:{code}       # 时间索引 (ZSET)

存储格式说明

1. 数据键格式: stock_data:{code}:{timestamp_iso}
   • code: 股票代码（如：YINN.US）
   • timestamp_iso: 带时区的ISO格式时间戳（如：2025-09-16T12:00:00+08:00）
2. 数据存储类型: Redis Hash
   • 使用 hset 存储字段-值对
   • 支持字段级别的访问和更新
3. 时间索引: Redis ZSET
   • 使用Unix时间戳作为score
   • 支持时间范围查询

存储示例

Redis键: stock_data:YINN.US:2025-09-16T12:00:00+08:00

Hash字段:

symbol: "YINN.US"
open: "12.34"
high: "13.45"
low: "11.23"
close: "12.78"
volume: "1000000"
turnover: "12780000.00"
timestamp: "2025-09-16T12:00:00+08:00"
trade_session: "Intraday"

时间索引: stock_data:time_index:YINN.US

• Score: 1726459200 (Unix时间戳)
• Member: 1726459200

API接口

创建股票数据

• POST /api/v1/stock-data
• 请求体: StockDataCreate
• 响应: {"message": "股票数据创建成功", "success": true}

获取股票数据列表

• GET /api/v1/stock-data
• 查询参数:
  • code: 股票代码筛选 (可选，格式：YINN.US)
  • start_date: 开始日期（ISO格式，如：2025-09-16T00:00:00-04:00）(可选)
  • end_date: 结束日期（ISO格式，如：2025-09-16T23:59:00-04:00）(可选)
  • trade_session: 交易时段筛选 (可选)
  • sort_by: 排序字段 (默认: “timestamp”)
  • sort_order: 排序方式 (默认: “asc”)
  • page: 页码 (默认: 1)
  • page_size: 每页数量 (默认: 120, 最大: 1440)
  • timezone: 时区 (默认: “Asia/Shanghai”)
• 响应: StockDataResponse

获取单条股票数据

• GET /api/v1/stock-data/{code}/{timestamp}
• 响应: StockData

获取股票代码列表

• GET /api/v1/stock-codes
• 响应: StockCodeList

删除股票数据

• DELETE /api/v1/stock-data/{code}
• 查询参数:
  • start_timestamp: 开始时间戳
  • end_timestamp: 结束时间戳
• 响应: {"message": "股票数据删除成功", "success": true}

股票数据导入

• POST /api/v1/stock-import/import
• 请求体: StockImportRequest
  • symbol: 股票代码
  • start_date: 开始日期（ISO格式，如：2025-09-16T00:00:00-04:00）
  • end_date: 结束日期（ISO格式，如：2025-09-16T23:59:00-04:00）
  • timezone: 时区（默认：America/New_York）
• 响应: StockImportResponse

获取导入任务状态

• GET /api/v1/stock-import/import/{task_id}/status
• 响应: StockImportStatus

WebSocket实时日志

• WebSocket /ws/stock-import/{task_id}
• 用途: 接收股票数据导入的实时日志和状态更新

时区处理

支持的时区

• Asia/Shanghai: 北京时间
• America/New_York: 美东时间 (自动处理夏令时/冬令时)

时区转换规则

1. 前端时间格式: 使用ISO 8601格式带时区信息（如：2025-09-16T00:00:00-04:00）
2. 后端存储: 统一转换为美东时间存储
3. 查询转换: 根据用户选择的时区进行时间范围转换
4. 数据导入: 支持按用户选择的时区进行数据获取和存储

时间格式示例

• 美东时间: 2025-09-16T00:00:00-04:00 到 2025-09-16T23:59:00-04:00
• 北京时间: 2025-09-16T00:00:00+08:00 到 2025-09-16T23:59:00+08:00

数据验证

价格字段验证

• 所有价格字段必须 ≥ 0
• 保留小数点后2位
• 开盘价、最高价、最低价、收盘价必须合理 (high ≥ max(open, close), low ≤ min(open, close))

时间戳验证

• 必须为有效的UNIX时间戳
• 不能为未来时间 (根据业务需求)
• 时间戳精度为秒级

交易时段验证

• 必须为有效的交易时段枚举值
• 根据时间戳自动推断交易时段 (可选)

性能优化

索引策略

• 按股票代码建立时间索引
• 支持时间范围查询
• 支持分页查询

缓存策略

• 股票数据缓存30天
• 股票代码列表缓存1小时
• 查询结果缓存5分钟

数据清理

自动清理

• 超过30天的数据自动过期
• 无效数据自动清理

手动清理

• 支持按时间范围删除
• 支持按股票代码删除
• 支持批量删除操作