# 需求规格文档：本地数据源体系建设

**任务ID**: data-platform-20260502
**节点**: pangtong_requirements
**作者**: 庞统（副军师）
**日期**: 2026-05-02

---

## 一、项目背景与核心问题

### 1.1 现状

| 资产 | 状态 | 位置 |
|------|------|------|
| NAS日线Parquet | ✅ 2010-2026年全市场，按年分目录 | `/Volumes/stock/A股数据/日线数据/daily/{year}/sh{code}_daily.parquet` |
| NAS分钟线Parquet | ⚠️ 仅84只15分钟线 | `/Volumes/stock/minute_kline/15min/sz{code}_15min.parquet` |
| vnpy quant_trading.db | ❌ **空库（8KB，0张表）** | `/Volumes/stock/sanguo_vnpy/data/quant_trading.db` |
| 回测服务 | ✅ 运行中（http://192.168.2.154:8088） | Docker容器 |
| 本地数据适配器 | ⚠️ 已有但路径硬编码Mac本地 | `vnpy_local_data_adapter.py`（指向`/Users/chufeng/nas/stock/...`） |

### 1.2 核心问题

**vnpy回测服务的数据库是空的**，回测引擎 `engine.load_data()` 从数据库读取数据 → 无数据 → 所有回测任务必然失败。

回测服务executor.py关键代码（L171-175）：
```python
engine.load_data()  # 从vnpy SQLite数据库加载
```
如果没有数据，直接抛出 `ValueError("无法加载历史数据")`。

### 1.3 目标

打通 **NAS Parquet → vnpy SQLite DB → 回测引擎** 的数据通路，让回测服务可以正常执行回测任务。

---

## 二、功能需求

### P1：打通vnpy数据通路

#### P1-1：确认Docker volume映射路径

| 项 | 说明 |
|-----|------|
| 需求 | 确认Mac写入的文件，Docker容器内能读到 |
| 输入 | NAS目录结构、Docker容器配置 |
| 输出 | 明确的映射关系文档：Mac路径 ↔ 容器内路径 |
| 验证 | 在Mac写入测试文件，容器内能读到；反之亦然 |

**关键证据**：
- 回测服务配置 `base_dir = "/app/backtest_jobs"`
- 数据目录 `data_dir = settings.base_dir.replace("backtest_jobs", "data")` → `/app/data`
- quant_trading.db 位于 `/Volumes/stock/sanguo_vnpy/data/`
- 需确认Docker容器启动时是否挂载了 `/Volumes/stock/sanguo_vnpy/data` → `/app/data`

#### P1-2：编写vnpy DB导入脚本

| 项 | 说明 |
|-----|------|
| 需求 | 将NAS日线Parquet数据批量导入vnpy SQLite数据库 |
| 输入 | `/Volumes/stock/A股数据/日线数据/daily/{year}/sh{code}_daily.parquet` |
| 输出 | quant_trading.db 中有完整的日线bar数据 |
| 验证 | 回测引擎 `load_data()` 能读出数据 |
| 约束 | 幂等操作（INSERT OR REPLACE），可重复执行 |

**vnpy DB Schema要求**（待姜维确认）：
- vnpy 4.x的BacktestingEngine通过 `MainEngine` + `BaseDataManager` 加载数据
- 数据表名和字段名由vnpy内部定义
- 必须先搞清楚vnpy 4.x期望的数据库结构，再写导入脚本

**Parquet字段**：
```
date, open, high, low, close, volume, amount, outstanding_share, turnover, year
```

**导入脚本功能要求**：
1. 扫描 `/Volumes/stock/A股数据/日线数据/daily/` 下所有年份目录
2. 每个Parquet文件解析股票代码（从文件名提取，如 `sh600000` → `600000.SSE`）
3. 转换为vnpy DB格式并批量写入
4. 支持增量导入（只导入新增数据）
5. 支持断点续传（中断后可继续）
6. 记录导入日志（成功/失败数、耗时）

#### P1-3：全量导入日线

| 项 | 说明 |
|-----|------|
| 需求 | 运行导入脚本，将全市场2010-2026年日线数据全部导入 |
| 输入 | P1-2的导入脚本 + NAS日线Parquet |
| 输出 | quant_trading.db 填满日线数据 |
| 验证 | 统计导入记录数，抽查几只股票确认数据完整 |
| 风险 | 导入耗时长（预估2-4小时），需支持断点续传 |

#### P1-4：验证回测服务可用

| 项 | 说明 |
|-----|------|
| 需求 | 提交一个简单回测任务，确认回测引擎能加载数据并完成回测 |
| 输入 | 回测服务API + 简单策略代码 |
| 输出 | 回测成功返回统计结果 |
| 验证 | total_trades > 0 或 total_days > 0 |

---

### P2：数据基础设施

#### P2-1：多源降级管理器 `fallback.py`

| 项 | 说明 |
|-----|------|
| 需求 | 统一数据获取入口，支持多数据源顺序降级 |
| 降级链（日线） | akshare `stock_zh_a_hist` → 腾讯K线API |
| 降级链（实时） | 新浪实时 → 东方财富 → 腾讯 |
| 接口 | `get_daily(symbol, start, end)` / `get_realtime(symbol)` |
| 行为 | 第一个源失败自动切下一个，记录使用的源 |
| 产出 | ~150行 |

#### P2-2：数据校验层 `validator.py`

| 项 | 说明 |
|-----|------|
| 需求 | 入库前校验数据质量，fatal级拒绝入库 |
| V1规则（7条fatal） | D1: close/open/high/low > 0；D2: OHLC一致性(high≥max(open,close), low≤min(open,close))；D3: volume ≥ 0；D6: 同股同日不重复；D7: date ≤ 今天；R1: 实时价格 > 0；R7: 必须携带source+fetched_at |
| 接口 | `validate(df) → (passed: bool, errors: List[str])` |
| 产出 | ~150行 |

#### P2-3：实时行情三源降级 `realtime.py`

| 项 | 说明 |
|-----|------|
| 需求 | 获取实时行情，支持3个源降级 |
| 降级链 | 新浪实时 → 东方财富 → 腾讯 |
| 接口 | `get_realtime_quote(symbol) → dict` |
| 产出 | ~200行 |

#### P2-4：增量更新 `updater.py`

| 项 | 说明 |
|-----|------|
| 需求 | 每日增量更新，Parquet+vnpy DB双写 |
| 流程 | 1.获取最新日期 2.拉取增量数据 3.校验 4.写Parquet（原子：临时文件+rename） 5.写vnpy DB（INSERT OR REPLACE幂等） 6.一致性校验 |
| 约束 | Parquet是真相源；vnpy DB失败不影响Parquet |
| 接口 | `update_daily() → UpdateResult` |
| 产出 | ~150行 |

#### P2-5：cron定时任务

| 项 | 说明 |
|-----|------|
| 需求 | 每交易日15:30自动执行增量更新 |
| 配置 | Mac crontab（Mac已确认永不休眠） |
| 验证 | 下一个交易日检查是否自动执行 |

---

### P3：分钟线数据

#### P3-1：P0限频验证

| 项 | 说明 |
|-----|------|
| 需求 | 验证腾讯API限频阈值 |
| 测试1 | 100只股票15分钟线连续下载，是否成功 |
| 测试2 | 连续1小时请求，记录每分钟成功次数、封禁恢复时间 |
| 输出 | 限频验证报告（每分钟最大请求数、封禁时长、恢复策略） |
| 决策 | 报告决定P3-2/P3-3的实现策略（分批间隔、每批数量） |

#### P3-2/P3-3：分钟线全量下载

| 项 | 说明 |
|-----|------|
| 需求 | 下载HS300/全市场15分钟线 |
| 前置 | P3-1限频验证通过 |
| 数据源 | 腾讯mkline API（唯一可用源，akshare分钟线已失效） |
| 存储路径 | `/Volumes/stock/minute_kline/15min/` |
| 约束 | 15分钟线优先，1分钟线暂缓 |

#### P3-4：分钟线导入vnpy DB

| 项 | 说明 |
|-----|------|
| 需求 | 将分钟线Parquet导入vnpy DB |
| 前置 | P1-2已确认vnpy DB Schema + 分钟线Parquet已下载 |
| 不确定项 | vnpy 4.x如何区分不同周期（15min vs 1min）的分钟线 |

---

### P4：配套skill与自动化

#### P4-1/P4-2：更新skill文档

更新 `data-acquisition` 和 `quant-backtest` SKILL.md，补充vnpy数据通路说明。

#### P4-3：全量校验脚本

关羽设计的V2规则（14条），用于定期全量扫描。

#### P4-4：周维护cron

每周校验Parquet与vnpy DB一致性。

---

## 三、交付物清单

### 代码文件（放到 `~/.openclaw/sanguo_projects/sanguo_vnpy/data_platform/`）

| 文件 | 功能 | 阶段 | 预估行数 |
|------|------|------|---------|
| `import_vnpy.py` | Parquet → vnpy DB 导入 | P1 | ~200 |
| `fallback.py` | 多源降级管理器 | P2 | ~150 |
| `validator.py` | 数据校验（V1 7条fatal） | P2 | ~150 |
| `realtime.py` | 实时行情三源降级 | P2 | ~200 |
| `updater.py` | 增量更新（双写） | P2 | ~150 |
| `validate_full.py` | 全量校验（V2 14条） | P4 | ~100 |

### 文档文件

| 文件 | 内容 | 位置 |
|------|------|------|
| 需求规格文档 | 本文档 | `docs/data-platform/01-requirements.md` |
| 设计方案文档 | 接口设计、数据流、Schema映射 | `docs/data-platform/02-design.md` |
| 验证报告 | 限频验证、导入验证、回测验证 | `docs/data-platform/reports/` |

### 配置文件

| 文件 | 内容 |
|------|------|
| crontab配置 | 每日15:30增量更新 |
| vnpy DB路径映射 | Mac ↔ Docker |

---

## 四、假设与不确定项

| # | 假设/不确定项 | 影响范围 | 验证人 | 验证时机 |
|---|-------------|---------|--------|---------|
| 1 | **Docker volume映射**：Mac写入NAS的文件Docker容器能读到 | P1全部 | 姜维 | P1开始前 |
| 2 | **vnpy 4.x DB Schema**：回测引擎load_data()期望的表结构和字段 | P1-2, P3-4 | 姜维 | P1开始前 |
| 3 | **vnpy分钟线周期区分**：vnpy如何存储/区分不同粒度分钟线 | P3-4 | 姜维 | P3开始前 |
| 4 | **腾讯API限频**：连续请求的频率上限和封禁恢复时间 | P3全部 | 赵云 | P3开始前 |
| 5 | **全量导入耗时**：5500只×17年数据的导入时间 | P1-3 | 张飞/赵云 | P1-3执行时 |
| 6 | **SQLite并发**：cron写入+回测读取是否冲突 | P2-5 | 姜维 | P2-5配置时 |
| 7 | NAS存储空间充足（1.5TB可用，只需28GB） | 全局 | 已确认 | - |
| 8 | Mac永不休眠（cron可靠执行） | P2-5 | 已确认 | - |
| 9 | 不引新依赖（只用akshare+urllib+已有库） | 全局 | 约束 | - |

**关键阻塞项**：#1和#2如果不明确，P1无法开始。**建议姜维先验证这两项。**

---

## 五、约束

1. 所有产出放到 `~/.openclaw/sanguo_projects/sanguo_vnpy/` 目录下
2. 不引新依赖（只用akshare + urllib + 已有的库）
3. 不改Docker/NAS配置，数据通过volume映射
4. Parquet是唯一真相源，vnpy DB是可重建的派生缓存
5. 双写顺序：先Parquet（原子写入）→ 再vnpy DB（幂等写入）
6. 腾讯API是唯一可用的分钟线源
7. 15分钟线优先，1分钟线暂缓
8. 不确定项遇到阻塞时，用最大尝试轮数限制，不无限重试
9. 每个阶段先输出需求和设计方案，经评审再编码

---

## 六、成功标准

| # | 标准 | 验证方法 |
|---|------|---------|
| 1 | vnpy DB有全市场日线数据 | `SELECT count(*) FROM ...` > 0 |
| 2 | 回测服务能完成一次完整回测 | 提交回测任务返回成功 |
| 3 | 增量更新可自动执行 | crontab触发后日志显示成功 |
| 4 | 数据校验拦截bad data | 构造异常数据，校验返回fatal |
| 5 | 多源降级正常工作 | 关掉主源，自动切到备用源 |
| 6 | 分钟线P0验证有结论 | 限频报告有明确数字 |

---

## 七、数据流架构

```
Layer 1: 远程数据源
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │   akshare    │  │  新浪实时     │  │  腾讯API     │
  │  (日线主源)   │  │ (实时主源)    │  │ (分钟线唯一源)│
  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
         │                 │                 │
         └────────┬────────┴────────┬────────┘
                  │ fallback.py     │
                  │ 降级管理         │
                  ▼                 │
Layer 2: 校验层    │                 │
         validator.py               │
         (7条fatal规则)             │
                  │                 │
                  ▼                 ▼
Layer 3: NAS持久层 (唯一真相源)
  /Volumes/stock/A股数据/日线数据/daily/{year}/{code}_daily.parquet
  /Volumes/stock/minute_kline/15min/{code}_15min.parquet
                  │
                  │ import_vnpy.py / updater.py
                  ▼
Layer 4: vnpy SQLite DB (派生缓存)
  /Volumes/stock/sanguo_vnpy/data/quant_trading.db
                  │
                  │ engine.load_data()
                  ▼
Layer 5: 回测引擎
  BacktestingEngine → 回测结果
```