# 📐 架构设计：整合数据平台与回测环境

**任务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 核心代码