# fd_trader

**Repository Path**: gznofeng/fd_trader

## Basic Information

- **Project Name**: fd_trader
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fd_trader

轻量级 A 股 / ETF 量化交易系统。一套策略代码同时支持**回测**与**实盘/模拟盘定时执行**，通过 Web 界面管理任务、查看回测报告与持仓流水。

无需 MySQL / Redis，仅依赖 **SQLite + 本地文件**，拷贝整个目录即可迁移。

---

## 界面预览

| 策略管理                                          | 策略台                                          |
|:---------------------------------------------:|:--------------------------------------------:|
| ![策略管理](docs/images/screenshots/strategy.png) | ![策略台](docs/images/screenshots/platform.png) |

| 实时分析                                          | 系统任务                                      |
|:---------------------------------------------:|:-----------------------------------------:|
| ![实时分析](docs/images/screenshots/analysis.png) | ![系统任务](docs/images/screenshots/jobs.png) |

---

## 特性

- **回测引擎**：滑动窗口逐 K 线执行策略，输出收益率、夏普、最大回撤、胜率，并生成 [QuantStats](https://github.com/ranaroussi/quantstats) HTML 报告
- **增量回测**：策略台支持从快照恢复状态，只跑新增区间（适合长周期迭代）
- **定时调度**：基于 APScheduler，支持日线 Cron 与 15 分钟线（A 股交易时段）
- **策略注册表**：`strategies/` 目录自动发现策略，Web 表单动态渲染参数
- **多数据源**：QMT API、新浪财经、zzshare，可在「系统管理」页切换
- **策略台**：多工作区管理、回测快照、买卖流水查看
- **实时分析**：财联社概念 + 个股筛选（需网络）
- **系统任务**：独立调度器，可定时执行 `jobs/` 下 Python 脚本

---

## 技术栈

| 类别   | 技术                   |
| ---- | -------------------- |
| Web  | FastAPI、Jinja2、原生 JS |
| 数据   | Pandas、NumPy         |
| 存储   | SQLite               |
| 调度   | APScheduler          |
| 绩效报告 | QuantStats           |
| HTTP | httpx、requests       |

**Python >= 3.10**

---

## 快速开始

### 1. 克隆与安装

```bash
git clone <your-repo-url> fd_trader
cd fd_trader

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirement.txt
```

### 2. 配置环境变量

复制配置模板并填写你自己的密钥与 API 地址：

```bash
# macOS / Linux
cp .env.example .env

# Windows
copy .env.example .env
```

用编辑器打开 `.env`，至少配置数据源相关项（二选一或都填）：

| 变量                                        | 说明                     |
| ----------------------------------------- | ---------------------- |
| `BASE_URL`                                | QMT K 线 API 地址         |
| `KLINE_CLIENT_ID` / `KLINE_CLIENT_SECRET` | QMT 客户端凭证              |
| `ZZSHARE_TOKEN`                           | zzshare Token（仅 A 股个股） |
| `WXPUSHER_APP_TOKEN`                      | WxPusher 推送（实盘通知，可选）   |

> `.env` 已在 `.gitignore` 中忽略，**不会提交到 Git**。仓库仅包含无密钥的 `.env.example`。

也可在启动后打开 **系统管理** 页面（`/system`）切换数据源；首次启动前仍建议先完成 `.env` 中的 QMT / zzshare 配置。

### 3. 启动

在项目根目录 `fd_trader/` 下执行（静态资源使用相对路径，请勿从其他目录启动）：

```bash
python main.py
```

或：

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

浏览器访问：**http://localhost:8000**（若用 `python app.py` 启动，默认端口为 **.env中的端口设置**）

📖 **新手入门**：[如何使用回测系统](docs/getting-started.md)

首次启动会自动创建：

- `database/data.db` — 回测记录、交易流水、系统配置、策略台工作区
- `database/scheduler_jobs.db` — 策略定时任务持久化
- `output/reports/` — QuantStats HTML 报告

---

## 使用指南

详细图文教程见 **[docs/getting-started.md](docs/getting-started.md)**（配置数据源 → 策略台第一次回测 → 读懂结果）。

### Web 页面

| 路径          | 功能                |
| ----------- | ----------------- |
| `/`         | 首页概览              |
| `/strategy` | 策略管理：添加/暂停/触发定时任务 |
| `/platform` | 策略台：工作区、回测、增量回测   |
| `/analysis` | 实时分析（财联社）         |
| `/jobs`     | 系统定时脚本任务          |
| `/system`   | 数据源与系统设置          |

### 典型工作流

**① 回测验证策略**

1. 打开 `/platform` 或策略页的「回测」区域
2. 选择标的（如 `510300.SH`）、策略（如双均线）、周期、日期区间
3. 提交后轮询状态，完成后查看指标与 QuantStats 报告（`/reports/...`）

**② 添加定时任务（模拟盘）**

1. 打开 `/strategy`
2. 填写股票代码、策略类型、参数、调度时间
3. 运行模式选 **PAPER（模拟）**
4. 点击「添加任务」— 系统将在指定时间自动拉取 K 线并执行策略

**③ 切换数据源**

1. 打开 `/system`
2. 选择 QMT / 新浪 / zzshare 并填写对应配置
3. 保存后立即生效（回测与实盘共用）

> **提示**：zzshare 仅支持 A 股个股日线/分钟线，**不支持 ETF**。ETF 策略请使用 QMT 或新浪财经。

### 内置策略

| 名称                           | 说明                          |
| ---------------------------- | --------------------------- |
| `double_ma`                  | 双均线金叉买入、死叉卖出                |
| `etf_low_high`               | ETF 低买高卖（股票池模式，代码填 `*` 跑全池） |
| `etf_rotation_511520_511360` | 政金债 / 短融滚动策略                |
| `stock_picker`               | 沪深精选，成份股池 + 动态止盈止损          |

新策略放入 `strategies/` 并定义 `STRATEGY_META` 与策略类，重启后自动注册。

---

## 编写自定义策略

在 `strategies/` 下新建文件，例如 `my_strategy.py`：

```python
from strategies.base_strategy import BaseStrategy, Context
import pandas as pd

STRATEGY_META = {
    "name": "my_strategy",
    "label": "我的策略",
    "description": "策略简介",
    "params": [
        {"key": "window", "label": "窗口", "type": "int", "default": 10, "min": 2, "max": 60},
    ],
}

class MyStrategy(BaseStrategy):
    def on_bar(self, df: pd.DataFrame, ctx: Context) -> None:
        if len(df) < self.params["window"]:
            return
        price = float(df["close"].iloc[-1])
        # ctx.buy(ctx.symbol, price, volume)
        # ctx.sell(ctx.symbol, price, volume)
```

核心约定：

- 实现 `on_bar(df, ctx)`，每根 K 线调用一次
- 通过 `ctx.buy()` / `ctx.sell()` 发出信号，**不要**在策略里直接访问数据库
- 回测时注入 `BacktestContext`（内存撮合），实盘时注入 `LiveContext`（写库 + 可选推送）

股票池策略可额外实现 `resolve_pool()`、`pool_total_capital()` 等类方法，参考 `etf_low_high.py`。

---

## API 概览

所有 JSON API 前缀为 `/api`，统一响应风格 `{ "ok": true/false, ... }`。

| 方法   | 路径                          | 说明     |
| ---- | --------------------------- | ------ |
| GET  | `/api/strategies`           | 可用策略列表 |
| GET  | `/api/scheduler/tasks`      | 定时任务列表 |
| POST | `/api/scheduler/add`        | 添加定时任务 |
| POST | `/api/backtest/run`         | 启动异步回测 |
| GET  | `/api/backtest/{id}/status` | 回测状态   |
| GET  | `/api/backtest/history`     | 回测历史   |
| GET  | `/api/system/settings`      | 读取系统配置 |
| PUT  | `/api/system/settings`      | 更新系统配置 |
| GET  | `/api/platform/workspaces`  | 策略台工作区 |

完整接口定义见 `web/routes/api.py`、`web/routes/jobs_api.py`。

---

## 测试

```bash
# 单元测试（回测引擎、Context，无网络）
python -m pytest tests/test_base_strategy.py tests/test_backtest_engine.py -v

# API 冒烟测试（临时 SQLite，不调用外部 K 线）
python -m pytest tests/test_api_smoke.py -v

# 全部测试
python -m pytest tests/ -q
```

---

## 项目结构

```
fd_trader/
├── main.py                 # FastAPI 入口
├── config.py               # 全局配置（读取 .env）
├── docs/
│   ├── getting-started.md  # 新手入门（回测教程）
│   └── images/screenshots/ # 文档截图
├── database/               # SQLite（自动生成）
├── engine/
│   ├── backtest_engine.py  # 回测引擎
│   ├── db_mgr.py           # 数据库管理
│   ├── scheduler_mgr.py    # 策略调度器
│   └── job_scheduler.py    # 系统任务调度器
├── strategies/             # 策略（自动注册）
├── jobs/                   # 可定时执行的脚本
├── web/
│   ├── routes/             # 页面与 API 路由
│   ├── templates/          # Jinja2 模板
│   └── static/             # 前端静态资源
├── utils/
│   ├── data_fetcher.py     # K 线数据门面
│   └── backends/           # 各数据源实现
├── output/reports/         # QuantStats 报告输出
└── tests/                  # 单元测试与 API 冒烟测试
```

---

## 设计说明

- **空中加油**：不落地海量历史 K 线，回测与实盘均实时从数据源拉取到内存计算
- **一套代码双端运行**：策略只依赖 `Context` 接口，环境差异由引擎注入
- **单文件迁移**：核心状态集中在 `database/` 两个 db 文件，便于备份与迁移

更详细的设计文档见 [CODEBUDDY.md](./CODEBUDDY.md)。

---

## 常见问题

**Q: 启动后页面 404 或静态资源加载失败？**  
A: 请确保在 `fd_trader/` 根目录启动，不要 `cd` 到其他目录再运行 `uvicorn`。

**Q: 回测一直 running / 失败？**  
A: 检查「系统管理」中数据源是否可用；ETF 请勿使用 zzshare。查看终端日志或回测详情中的 `error_msg`。

**Q: 如何备份数据？**  
A: 复制 `database/data.db`、`database/scheduler_jobs.db` 及 `output/reports/` 即可。

**Q: 如何部署到生产？**  
A: 建议使用 `uvicorn main:app --host 0.0.0.0 --port 8000`（去掉 `--reload`），前置 Nginx 反向代理。在服务器上 `cp .env.example .env` 并填入生产环境密钥，**勿将 `.env` 提交到仓库。**

---

## 免责声明

本项目仅供学习与研究，不构成任何投资建议。量化交易存在风险，使用者需自行承担实盘损失。作者不对因使用本软件产生的任何盈亏负责。

---

## 参与贡献

欢迎提交 Issue 与 Pull Request。贡献前建议：

1. 运行 `python -m pytest tests/ -q` 确保测试通过
2. 新策略放在 `strategies/` 并附带 `STRATEGY_META`
3. 遵循现有代码风格（中文注释、PEP 8）
4. 更新界面截图时放入 `docs/images/screenshots/`，并在 README 中引用

---

## License

尚未指定开源协议。如需二次分发，请先与维护者确认或自行添加 `LICENSE` 文件。