# 期货统一数据平台 - 项目文档

> **版本**: 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