cfdaily
299 lines
10 KiB
Markdown
299 lines
10 KiB
Markdown
# 📐 架构设计：整合数据平台与回测环境
|
||
|
||
**任务ID**: integrate-data-platform-20260430
|
||
**撰写人**: 庞统
|
||
**日期**: 2026-04-30
|
||
|
||
---
|
||
|
||
## 一、现状分析
|
||
|
||
### 数据资产清单
|
||
|
||
| 数据类型 | 格式 | 存储位置 | 文件组织 | 数量 |
|
||
|----------|------|---------|---------|------|
|
||
| 日线行情 | Parquet | `raw/daily/{year}/{code}_daily.parquet` | 按年分目录 | 2013-2025 |
|
||
| 财务估值 | Parquet | `raw/financial/valuation/{code}_valuation.parquet` | 按类型分目录 | ~5000股 |
|
||
| 股票信息 | CSV | `raw/stock_info/stock_basic_info_*.csv` | 单文件 | 5493股 |
|
||
| HS300成分 | CSV | `raw/stock_info/hs300_constituents_latest.csv` | 单文件 | 300只 |
|
||
| 日线(旧) | Parquet | `raw/a_stock_daily/{year}/` | 按年分目录，无文件 | 可能为空 |
|
||
|
||
### 已有组件
|
||
|
||
| 组件 | 语言 | 接口 | 依赖 |
|
||
|------|------|------|------|
|
||
| VnpyLocalDataAdapter | Python | 类方法 | akshare |
|
||
| backtest-service | Python | REST API (FastAPI) | vnpy |
|
||
| 张飞回测框架 | Python | 函数调用 | numpy, pandas |
|
||
|
||
### 关键发现
|
||
|
||
1. **数据格式已经是 Parquet**（不是 CSV），字段：`date, open, high, low, close, volume, amount, outstanding_share, turnover, year`
|
||
2. **姜维适配器路径硬编码** `/Users/chufeng/nas/stock/sanguo_vnpy/zhaoyun-data/data`，与实际数据路径不同
|
||
3. **a_stock_daily/ 和 daily/ 是两套目录**，需确认哪套是主数据
|
||
|
||
---
|
||
|
||
## 二、架构设计
|
||
|
||
### 核心原则：最简方案
|
||
|
||
**不新建独立包/服务**。直接在现有项目内加一个 `data_platform.py` 配置文件 + 一个 `catalog.py` 数据接口。
|
||
|
||
### 架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 策略开发者 │
|
||
│ (张飞回测 / vnpy回测 / 未来策略) │
|
||
└───────────────────┬─────────────────────────────┘
|
||
│ 调用
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ DataCatalog (catalog.py) │
|
||
│ │
|
||
│ get_daily(symbol, start, end) → DataFrame │
|
||
│ get_stock_list() → DataFrame │
|
||
│ get_financial(symbol) → DataFrame │
|
||
│ get_index_constituents(index) → DataFrame │
|
||
└───────────────────┬─────────────────────────────┘
|
||
│ 读取
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ data_platform_config.yaml │
|
||
│ DATA_ROOT: /path/to/zhaoyun-data/data │
|
||
└───────────────────┬─────────────────────────────┘
|
||
│ 指向
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 赵云数据目录 (zhaoyun-data/data/) │
|
||
│ │
|
||
│ raw/daily/{year}/{code}_daily.parquet │
|
||
│ raw/financial/valuation/{code}_valuation.parquet│
|
||
│ raw/stock_info/stock_basic_info_*.csv │
|
||
│ raw/stock_info/hs300_constituents_latest.csv │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 模块划分
|
||
|
||
```
|
||
sanguo_quant_live/
|
||
├── data_platform/ # 🆕 数据平台模块（新建）
|
||
│ ├── __init__.py
|
||
│ ├── config.py # 配置加载（读 yaml + 环境变量）
|
||
│ ├── catalog.py # DataCatalog 核心接口
|
||
│ └── data_platform_config.yaml # 配置文件（DATA_ROOT 等）
|
||
├── zhaoyun-data/ # 赵云数据（已有）
|
||
│ └── data/raw/...
|
||
├── zhangfei-technical/ # 张飞回测（已有）
|
||
└── jiangwei-platform/ # 姜维基建（已有）
|
||
|
||
sanguo_vnpy/
|
||
└── src/
|
||
└── adapters/
|
||
└── vnpy_local_data_adapter.py # 姜维适配器（改路径配置）
|
||
```
|
||
|
||
---
|
||
|
||
## 三、接口定义
|
||
|
||
### data_platform_config.yaml
|
||
|
||
```yaml
|
||
# 数据平台配置
|
||
data_root: "${ZHAOYUN_DATA_ROOT}" # 优先环境变量
|
||
# 默认值（环境变量未设置时）
|
||
default_data_root: "/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/zhaoyun-data/data"
|
||
|
||
# 数据源配置
|
||
sources:
|
||
daily:
|
||
format: parquet
|
||
path_pattern: "raw/daily/{year}/{code}_daily.parquet"
|
||
date_range: [2013, 2025]
|
||
columns: [date, open, high, low, close, volume, amount, outstanding_share, turnover]
|
||
|
||
stock_info:
|
||
format: csv
|
||
path: "raw/stock_info"
|
||
file_pattern: "stock_basic_info_*.csv"
|
||
|
||
financial:
|
||
format: parquet
|
||
path_pattern: "raw/financial/valuation/{code}_valuation.parquet"
|
||
|
||
index_constituents:
|
||
format: csv
|
||
path: "raw/stock_info/hs300_constituents_latest.csv"
|
||
|
||
# fallback（本地无数据时）
|
||
fallback:
|
||
enabled: true
|
||
provider: akshare
|
||
```
|
||
|
||
### config.py
|
||
|
||
```python
|
||
"""数据平台配置加载"""
|
||
import os
|
||
import yaml
|
||
from pathlib import Path
|
||
|
||
def load_config() -> dict:
|
||
"""加载配置，环境变量优先"""
|
||
config_path = Path(__file__).parent / "data_platform_config.yaml"
|
||
with open(config_path) as f:
|
||
config = yaml.safe_load(f)
|
||
|
||
# 环境变量覆盖 data_root
|
||
env_root = os.environ.get("ZHAOYUN_DATA_ROOT")
|
||
if env_root:
|
||
config["data_root"] = env_root
|
||
elif "${" in config.get("data_root", ""):
|
||
config["data_root"] = config["default_data_root"]
|
||
|
||
return config
|
||
```
|
||
|
||
### catalog.py 核心接口
|
||
|
||
```python
|
||
"""DataCatalog - 统一数据访问接口"""
|
||
import pandas as pd
|
||
from pathlib import Path
|
||
from typing import Optional
|
||
from .config import load_config
|
||
|
||
class DataCatalog:
|
||
def __init__(self, config: dict = None):
|
||
self._config = config or load_config()
|
||
self._data_root = Path(self._config["data_root"])
|
||
|
||
def get_daily(self, symbol: str, start: str = None, end: str = None) -> pd.DataFrame:
|
||
"""获取日线行情
|
||
Args:
|
||
symbol: 股票代码，如 "000001" 或 "sh600519"
|
||
start: 开始日期 "YYYY-MM-DD"
|
||
end: 结束日期 "YYYY-MM-DD"
|
||
"""
|
||
...
|
||
|
||
def get_stock_list(self) -> pd.DataFrame:
|
||
"""获取全部A股列表"""
|
||
...
|
||
|
||
def get_financial(self, symbol: str) -> pd.DataFrame:
|
||
"""获取财务估值数据"""
|
||
...
|
||
|
||
def get_index_constituents(self, index: str = "000300") -> pd.DataFrame:
|
||
"""获取指数成分股"""
|
||
...
|
||
```
|
||
|
||
### stock code 标准化规则
|
||
|
||
```
|
||
输入格式：
|
||
"000001" / "sz000001" / "000001.SZ" → 标准化为 "sz000001"（parquet文件名）
|
||
"600519" / "sh600519" / "600519.SH" → 标准化为 "sh600519"
|
||
|
||
规则：
|
||
0/3 开头 → sz 前缀
|
||
6 开头 → sh 前缀
|
||
已有 sh/sz 前缀 → 保持
|
||
```
|
||
|
||
---
|
||
|
||
## 四、数据流设计
|
||
|
||
### 日线数据流
|
||
|
||
```
|
||
赵云采集脚本 → raw/daily/{year}/{code}_daily.parquet
|
||
↓
|
||
DataCatalog.get_daily("600519", "2024-01-01", "2024-12-31")
|
||
↓
|
||
1. 标准化 code → sh600519
|
||
2. 扫描 2024/ 目录
|
||
3. pd.read_parquet("raw/daily/2024/sh600519_daily.parquet")
|
||
4. 按 start/end 过滤日期
|
||
5. 返回 DataFrame
|
||
```
|
||
|
||
### 张飞回测对接
|
||
|
||
```
|
||
# 改前（张飞直接读CSV，硬编码路径）
|
||
df = pd.read_csv("/path/to/data.csv")
|
||
|
||
# 改后（通过 DataCatalog）
|
||
from data_platform import DataCatalog
|
||
catalog = DataCatalog()
|
||
df = catalog.get_daily("000001", "2024-01-01", "2025-12-31")
|
||
```
|
||
|
||
### vnpy适配器对接
|
||
|
||
```python
|
||
# 改前（姜维硬编码路径）
|
||
ZHAOYUN_DATA_BASE = "/Users/chufeng/nas/stock/sanguo_vnpy/zhaoyun-data/data"
|
||
|
||
# 改后（读取 DataCatalog 配置）
|
||
from data_platform.config import load_config
|
||
config = load_config()
|
||
ZHAOYUN_DATA_BASE = config["data_root"]
|
||
```
|
||
|
||
---
|
||
|
||
## 五、权衡取舍
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| 新建独立包 vs 项目内模块 | **项目内模块** | 代码量小（~200行），不值得独立包 |
|
||
| YAML配置 vs JSON | **YAML** | 支持注释，可读性好 |
|
||
| Parquet vs CSV | **Parquet（保持现状）** | 已有数据都是Parquet，不改格式 |
|
||
| 环境变量 vs 配置文件 | **环境变量优先+配置文件兜底** | 生产环境用环境变量，开发用配置文件 |
|
||
| 全量加载 vs 按需加载 | **按需加载（按symbol+日期范围）** | 避免内存浪费 |
|
||
| fallback akshare | **保留但默认关闭** | 策略开发者应先确认本地数据完备 |
|
||
|
||
---
|
||
|
||
## 六、待澄清项
|
||
|
||
| # | 问题 | 影响范围 |
|
||
|---|------|---------|
|
||
| Q1 | `raw/a_stock_daily/` 和 `raw/daily/` 是否有重叠？哪个是主数据？ | catalog.py 的路径配置 |
|
||
| Q2 | 财务数据除了 valuation 还有其他类型吗（income/balance/cashflow）？ | get_financial 接口设计 |
|
||
| Q3 | 分钟线数据是否纳入本次 DataCatalog？ | 是否实现 get_minute() |
|
||
| Q4 | NAS 路径 `/Users/chufeng/nas/stock/` 当前是否可用？ | vnpy适配器是否能正常工作 |
|
||
|
||
---
|
||
|
||
## 七、各角色分工
|
||
|
||
| 角色 | 任务 | 交付物 |
|
||
|------|------|--------|
|
||
| 赵云 | Q1-Q3 澄清 + 数据目录确认 + 更新SOP | 数据目录说明 + 更新脚本 |
|
||
| 张飞 | 回测框架对接 DataCatalog | 修改后的回测代码 |
|
||
| 关羽 | 风控数据接口验证 | 风控相关数据接口测试 |
|
||
| 姜维 | config.py + catalog.py 实现 + vnpy适配器更新 + 回测环境文档 | 代码 + 文档 |
|
||
| 司马懿 | 架构评审 | 评审意见 |
|
||
| 庞统 | 整合交付 | 最终报告 |
|
||
|
||
---
|
||
|
||
## 八、不做的事
|
||
|
||
1. ❌ 不建数据库
|
||
2. ❌ 不建独立 pip 包
|
||
3. ❌ 不做实时行情
|
||
4. ❌ 不做 Web UI
|
||
5. ❌ 不做云端部署
|
||
6. ❌ 不改 vnpy 核心代码
|