cfdaily
156 lines
6.1 KiB
Markdown
156 lines
6.1 KiB
Markdown
# 📋 需求规格文档：整合数据平台与回测环境
|
||
|
||
**任务ID**: integrate-data-platform-20260430
|
||
**撰写人**: 庞统
|
||
**日期**: 2026-04-30
|
||
|
||
---
|
||
|
||
## 一、项目背景
|
||
|
||
### 现状梳理
|
||
|
||
| 组件 | 负责人 | 现状 | 位置 |
|
||
|------|--------|------|------|
|
||
| A股数据采集工具链 | 赵云 | ✅ 已完成：基础信息/日线/财务/分钟线采集脚本 | `sanguo_quant_live/zhaoyun-data/scripts/data_acquisition/` |
|
||
| 原始数据 | 赵云 | ✅ 1.9G 已采集（raw/下含日线/财务/分钟线/基础信息） | `sanguo_quant_live/zhaoyun-data/data/raw/` |
|
||
| 技术选股回测框架 | 张飞 | ✅ 已完成：MACD/布林带/唐奇安通道回测代码 | `sanguo_quant_live/zhangfei-technical/02-algorithms/` |
|
||
| vnpy本地数据适配器 | 姜维 | ✅ 已完成：优先本地→fallback akshare | `sanguo_vnpy/src/adapters/vnpy_local_data_adapter.py` |
|
||
| vnpy回测服务 | 姜维 | ✅ 已完成：RESTful API回测服务（进程池+结果存储） | `sanguo_vnpy/src/backtest-service/` |
|
||
| NAS部署调研 | 姜维 | ✅ 已完成：Docker部署方案、阿里云方案 | `sanguo_quant_live/jiangwei-platform/research/` |
|
||
| vnpy已有数据 | 姜维 | ⚠️ 仅 `quant_trading.db` | `sanguo_vnpy/data/` |
|
||
|
||
### 核心问题
|
||
|
||
1. **数据孤岛**：赵云的数据在 `sanguo_quant_live/zhaoyun-data/data/`，vnpy 的适配器指向 NAS 路径 `/Users/chufeng/nas/stock/sanguo_vnpy/zhaoyun-data/data`，三者路径不统一
|
||
2. **接口不统一**：张飞回测直接用 pandas 读 CSV，vnpy 用自己的数据引擎，两套数据加载方式
|
||
3. **无统一数据目录服务**：策略开发者不知道数据在哪、格式是什么、怎么调用
|
||
4. **数据更新无规范**：没有定时更新机制，数据新鲜度不确定
|
||
|
||
---
|
||
|
||
## 二、功能需求
|
||
|
||
### F1：统一数据目录服务（DataCatalog）
|
||
|
||
**目标**：提供一个统一的 Python API，策略开发者调用一个接口就能获取数据，不关心底层存储位置。
|
||
|
||
**接口设计**：
|
||
```python
|
||
from data_platform import DataCatalog
|
||
|
||
catalog = DataCatalog()
|
||
|
||
# 获取日线数据
|
||
df = catalog.get_daily(symbol="000001", start="2024-01-01", end="2026-04-30")
|
||
|
||
# 获取股票列表
|
||
stocks = catalog.get_stock_list(market="A股")
|
||
|
||
# 获取财务数据
|
||
financial = catalog.get_financial(symbol="000001", report_type="income")
|
||
|
||
# 获取指数成分股
|
||
hs300 = catalog.get_index_constituents(index="000300")
|
||
```
|
||
|
||
**优先级**：P0
|
||
**验证标准**：上述4个 API 均可调用并返回有效 DataFrame
|
||
|
||
### F2：数据路径统一
|
||
|
||
**目标**：解决三方（赵云数据、vnpy适配器、张飞回测）的路径不一致问题。
|
||
|
||
**方案**：
|
||
- 定义 `DATA_ROOT` 环境变量（或配置文件），指向统一数据根目录
|
||
- 赵云采集脚本写入 `DATA_ROOT/raw/`
|
||
- DataCatalog 从 `DATA_ROOT/raw/` 和 `DATA_ROOT/processed/` 读取
|
||
- vnpy 适配器指向同一 `DATA_ROOT`
|
||
|
||
**优先级**：P0
|
||
**验证标准**：三方使用同一个 `DATA_ROOT` 配置
|
||
|
||
### F3：回测环境配置指南
|
||
|
||
**目标**：策略开发者拿到一份文档，按步骤操作即可在本地跑回测。
|
||
|
||
**内容**：
|
||
1. 环境依赖安装（Python 3.10+、akshare、vnpy 等）
|
||
2. 数据准备（一键脚本获取示例数据）
|
||
3. 回测运行示例（用张飞的回测框架 + DataCatalog）
|
||
4. vnpy 回测服务启动和使用
|
||
|
||
**优先级**：P1
|
||
**验证标准**：新开发者按文档操作，30分钟内能跑通一次回测
|
||
|
||
### F4：数据更新规范
|
||
|
||
**目标**：明确数据更新频率、更新脚本、质量检查方法。
|
||
|
||
**内容**：
|
||
1. 日线数据：每日收盘后自动更新（cron job 或手动触发）
|
||
2. 财务数据：每季度财报发布后更新
|
||
3. 基础信息：每周更新一次
|
||
4. 数据质量检查脚本
|
||
|
||
**优先级**：P2
|
||
**验证标准**：更新脚本运行成功 + 质量检查报告通过
|
||
|
||
---
|
||
|
||
## 三、交付物清单
|
||
|
||
| # | 交付物 | 负责人 | 验证方式 |
|
||
|---|--------|--------|---------|
|
||
| 1 | 统一数据平台架构文档（含目录结构、接口定义、配置方式） | 庞统（设计）→ 姜维（实现） | 文档评审通过 |
|
||
| 2 | DataCatalog Python 模块（data_platform 包） | 赵云（数据接口）→ 姜维（集成） | 4个 API 调用成功 |
|
||
| 3 | 数据路径配置文件（data_platform_config.yaml） | 姜维 | vnpy适配器+张飞回测都能读取 |
|
||
| 4 | 回测环境配置指南（Markdown文档） | 姜维 | 新人30分钟跑通 |
|
||
| 5 | 数据更新SOP（含更新脚本+质量检查脚本） | 赵云 | 脚本执行成功 |
|
||
| 6 | vnpy适配器路径更新（指向统一 DATA_ROOT） | 姜维 | 原有功能不受影响 |
|
||
|
||
---
|
||
|
||
## 四、功能边界（不做的事）
|
||
|
||
1. ❌ 不搭新的数据库（继续用文件存储 CSV/Parquet）
|
||
2. ❌ 不修改 vnpy 核心代码（只改适配器配置）
|
||
3. ❌ 不做实时行情接入（本次只解决历史数据）
|
||
4. ❌ 不做云端部署（本次只做本地环境）
|
||
5. ❌ 不做 Web UI（纯 Python API + CLI）
|
||
|
||
---
|
||
|
||
## 五、假设列表
|
||
|
||
| # | 假设 | 不确定项 | 风险 |
|
||
|---|------|---------|------|
|
||
| A1 | 赵云已采集的数据格式为标准 CSV（逗号分隔，UTF-8） | ⚠️ 需确认实际编码和分隔符 | 低 |
|
||
| A2 | 本地磁盘空间足够存储全量 A 股数据（预估 < 5G） | ⚠️ 需确认当前 1.9G 是全量还是部分 | 低 |
|
||
| A3 | vnpy 回测服务当前可用 | ⚠️ 需确认 backtest-service 是否能正常启动 | 中 |
|
||
| A4 | 张飞回测框架不依赖特定数据格式 | ⚠️ 需确认是否硬编码了数据路径 | 中 |
|
||
| A5 | akshare API 可正常访问（作为 fallback） | ⚠️ 需确认网络和频率限制 | 低 |
|
||
|
||
---
|
||
|
||
## 六、依赖关系
|
||
|
||
```
|
||
庞统需求分析（当前）→ 庞统架构设计 →
|
||
→ 赵云：数据目录标准化 + DataCatalog 数据接口
|
||
→ 张飞：回测框架对接 DataCatalog
|
||
→ 关羽：风控数据接口验证
|
||
→ 姜维：vnpy适配器更新 + 回测环境文档 + 配置文件
|
||
→ 司马懿：评审
|
||
→ 庞统总结交付
|
||
```
|
||
|
||
---
|
||
|
||
## 七、技术约束
|
||
|
||
1. Python 3.10+（与现有项目一致）
|
||
2. 不引入新的大型依赖（pandas + akshare 足够）
|
||
3. 配置文件用 YAML 格式
|
||
4. 数据格式：CSV 为主，未来可迁移到 Parquet
|