|
|
# 期货统一数据平台 - 项目文档
|
|
|
|
|
|
> **版本**: 0.1.0
|
|
|
> **状态**: 开发中 (Dev)
|
|
|
> **维护者**: 小马哥
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 项目概述
|
|
|
|
|
|
本项目是一个**期货统一数据平台**，旨在解决多数据源接入、数据格式不统一、历史行情查询困难等问题。平台提供标准化的 RESTful API 供外部系统或 AI 调用，并配备管理后台进行数据源配置、合约管理及行情可视化。
|
|
|
|
|
|
### 核心目标
|
|
|
- **统一出口**：无论底层是 Tushare、CTP 还是其他数据源，对外提供统一的数据格式。
|
|
|
- **灵活配置**：支持多数据源切换、优先级管理。
|
|
|
- **高效缓存**：针对历史 K 线数据（日 K/周 K/分钟级）进行分级存储。
|
|
|
- **易于扩展**：基于适配器模式，新增数据源只需实现标准接口。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 技术架构
|
|
|
|
|
|
### 2.1 技术栈
|
|
|
|
|
|
| 层次 | 技术选型 | 说明 |
|
|
|
|------|----------|------|
|
|
|
| **前端** | Vue3 + Vite + Element Plus | 现代化 SPA，响应式布局 |
|
|
|
| **图表** | Apache ECharts 5 | 专业金融 K 线图表渲染 |
|
|
|
| **后端** | Python 3.11 + FastAPI | 高性能异步 Web 框架 |
|
|
|
| **数据库** | PostgreSQL + TimescaleDB | 专为时序数据优化，支持高效压缩与查询 |
|
|
|
| **本地开发** | SQLite | 无需外部依赖，快速验证 |
|
|
|
| **缓存/消息** | Redis | 实时行情缓存与发布订阅 |
|
|
|
| **数据源** | Tushare / AKShare / CTP (规划) | 外部数据接入 |
|
|
|
| **部署** | Docker Compose | 一键环境搭建 |
|
|
|
|
|
|
### 2.2 数据源架构
|
|
|
|
|
|
```text
|
|
|
[外部系统/AI] <--> [统一 API 网关] <--> [业务逻辑层] <--> [数据源适配器]
|
|
|
|
|
|
|
[缓存层 (Redis)]
|
|
|
|
|
|
|
[持久层 (PostgreSQL)]
|
|
|
```
|
|
|
|
|
|
- **适配器模式**：`DataSourceBase` 定义了 `get_kline_daily`、`get_contract_list` 等标准方法。
|
|
|
- **管理器模式**：`DataSourceManager` 负责加载配置、优先级排序和实例管理。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 部署与启动指南
|
|
|
|
|
|
### 3.1 环境准备
|
|
|
- Docker & Docker Compose（生产/测试环境）
|
|
|
- Python 3.11+（本地开发环境）
|
|
|
- Node.js 20+（前端开发）
|
|
|
|
|
|
### 3.2 Docker Compose 部署（推荐）
|
|
|
|
|
|
适用于拥有完整基础设施（PostgreSQL, Redis）的环境。
|
|
|
|
|
|
```bash
|
|
|
cd share_data/project/futures-data-platform
|
|
|
|
|
|
# 1. 配置环境变量
|
|
|
cp .env.example .env
|
|
|
# 编辑 .env，填入你的 Tushare Token: TUSHARE_TOKEN=xxxxxx
|
|
|
|
|
|
# 2. 启动服务
|
|
|
docker compose up -d --build
|
|
|
|
|
|
# 3. 查看日志
|
|
|
docker compose logs -f backend
|
|
|
```
|
|
|
|
|
|
**服务地址：**
|
|
|
- 管理后台：http://localhost:3000
|
|
|
- 后端 API：http://localhost:8000
|
|
|
- Swagger 文档：http://localhost:8000/docs
|
|
|
|
|
|
### 3.3 本地开发模式（SQLite）
|
|
|
|
|
|
适用于快速调试，无需启动数据库容器。
|
|
|
|
|
|
```bash
|
|
|
cd backend
|
|
|
|
|
|
# 1. 安装依赖
|
|
|
pip install -r requirements.txt
|
|
|
|
|
|
# 2. 使用 SQLite 启动后端
|
|
|
export DATABASE_URL="sqlite:///./futures.db"
|
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
|
|
|
|
# 3. 启动前端 (新终端)
|
|
|
cd frontend
|
|
|
npm install
|
|
|
npm run dev
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 操作指南
|
|
|
|
|
|
### 4.1 配置数据源
|
|
|
1. 进入**"数据源监控"**页面。
|
|
|
2. 点击 `tushare` 或 `akshare` 行的**"配置"**按钮。
|
|
|
3. 在弹出的配置对话框中：
|
|
|
- **启用状态**：使用开关快速启用/禁用该数据源
|
|
|
- **显示名称**：自定义数据源在界面上的显示名称
|
|
|
- **Token** (Tushare)：填入你的 Tushare API Token
|
|
|
- **最大重试次数** (AKShare)：设置反爬重试策略
|
|
|
- **优先级**：数字越小优先级越高，系统将优先使用高优先级数据源
|
|
|
4. 点击**"测试连接"**，确认状态为 `ok`。
|
|
|
5. 点击**"保存"**完成配置。
|
|
|
|
|
|
> **提示**：也可在表格的"启用"列直接点击开关快速切换启用/禁用状态，无需打开配置对话框。
|
|
|
|
|
|
### 4.2 同步合约信息
|
|
|
1. 进入**"合约管理"**页面。
|
|
|
2. 点击右上角**"同步合约"**按钮。
|
|
|
3. 系统将遍历所有交易所（CFFEX, SHFE, DCE 等）拉取合约信息并入库。
|
|
|
4. 同步完成后，列表将显示所有活跃合约。
|
|
|
|
|
|
### 4.3 查询与展示 K 线
|
|
|
1. 进入**"K 线查询"**页面。
|
|
|
2. 选择合约（如 `rb2401`）和周期（如 `日 K`）。
|
|
|
3. 点击**"同步数据"**（首次查询建议同步，后续直接查询数据库）。
|
|
|
4. 点击**"查询"**，下方将渲染 ECharts K 线图和详细数据表格。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 注意事项
|
|
|
|
|
|
### 5.1 Tushare 积分限制
|
|
|
- 不同积分等级对数据调用的频率和数据范围有限制。
|
|
|
- 高频调用分钟级数据或全量历史数据可能需要较高级别的积分（如 2000 分以上）。
|
|
|
- **建议**：在"接口测试"中先测试单个合约的同步，确认返回数据正常后再批量同步。
|
|
|
|
|
|
### 5.2 AKShare 反爬策略
|
|
|
AKShare 数据源内置了 `SmartRequester` 反爬管理器，包含以下策略：
|
|
|
- **随机 User-Agent**：每次请求轮换浏览器指纹。
|
|
|
- **拟人化延时**：首次请求随机延迟 0.5~1.5s，重试时指数级增加。
|
|
|
- **智能重试**：遇到 403 或网络错误自动重试（默认 3 次）。
|
|
|
- **Referer 伪装**：自动匹配目标网站的 Referer。
|
|
|
> 注：IP 代理功能预留接口，当前版本主要依赖频率控制和头部伪装。
|
|
|
|
|
|
### 5.3 数据一致性
|
|
|
- 平台默认**"优先读库"**策略。如果数据库中已有缓存数据，直接返回；若无，则调用数据源。
|
|
|
- `sync_kline` 接口采用 `upsert` 逻辑（插入或更新），支持增量同步，不会破坏已有数据。
|
|
|
|
|
|
### 5.4 生产环境配置
|
|
|
- **数据库**：务必使用 Docker Compose 中的 PostgreSQL + TimescaleDB，SQLite 仅用于本地开发。
|
|
|
- **安全性**：生产环境应移除 `cors.allow_origins=["*"]` 的宽泛策略，改为白名单；数据库密码应通过 Secret 管理。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 后续规划与改进
|
|
|
|
|
|
### Phase 1: 基础完善 (当前阶段)
|
|
|
- [x] 历史 K 线数据同步与查询（日 K/周 K/分钟）
|
|
|
- [x] 合约信息管理
|
|
|
- [x] Tushare 数据源接入
|
|
|
- [x] AKShare 数据源接入 (含反爬策略)
|
|
|
- [x] 管理后台基础功能
|
|
|
|
|
|
### Phase 2: 实时行情与推送
|
|
|
- [ ] **实时行情引擎**：开发 CTP 适配器，接入实时 Tick 和 K 线。
|
|
|
- [ ] **WebSocket 订阅**：实现实时数据推送服务，支持客户端按合约订阅。
|
|
|
- [ ] **行情快照缓存**：利用 Redis 实现最新行情快照的快速读取。
|
|
|
|
|
|
### Phase 3: 性能与高可用
|
|
|
- [ ] **TimescaleDB 优化**：配置超表（Hypertables）和自动压缩策略。
|
|
|
- [ ] **定时任务调度**：使用 APScheduler 实现每日收盘后的自动数据同步。
|
|
|
- [ ] **多数据源回退**：主数据源异常时，自动切换到备用数据源。
|
|
|
|
|
|
### Phase 4: 高级功能
|
|
|
- [ ] **数据清洗与校验**：增加数据质量监控，自动识别异常跳空或缺失数据。
|
|
|
- [ ] **AI 辅助接口**：提供专为大模型优化的自然语言转 SQL 接口。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 开发规范
|
|
|
|
|
|
- **代码风格**：后端遵循 PEP 8，使用 `black` 格式化；前端遵循 ESLint + Prettier。
|
|
|
- **提交规范**：
|
|
|
- `feat`: 新功能
|
|
|
- `fix`: 修复
|
|
|
- `docs`: 文档更新
|
|
|
- `refactor`: 重构
|
|
|
- **API 响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "ok",
|
|
|
"data": { ... }
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
> 文档最后更新：2026-05-07
|
