diff --git a/pangtong-value/research/task-20260430-data-platform-integration/requirements.md b/pangtong-value/research/task-20260430-data-platform-integration/requirements.md new file mode 100644 index 000000000..daf52c3de --- /dev/null +++ b/pangtong-value/research/task-20260430-data-platform-integration/requirements.md @@ -0,0 +1,155 @@ +# 📋 需求规格文档:整合数据平台与回测环境 + +**任务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