优化项目说明文档
This commit is contained in:
@@ -9,10 +9,9 @@
|
||||
[](https://react.dev/)
|
||||
[](./Dockerfile)
|
||||
|
||||
🚀 **开箱即用**(单容器 / Free 模式无需 Key)
|
||||
能力驱动,适配 Free → Expert 全档位订阅 · 🔌 **自由接入第三方扩展数据**(例如 Tushare、自有量化项目数据)
|
||||
🚀 **开箱即用**(单容器 / Free 模式无需 Key) · 能力驱动,适配 Free → Expert 全档位订阅 · 🔌 **自由接入第三方扩展数据**(Tushare、自有量化项目数据等)
|
||||
|
||||
**[核心功能](#-核心功能)** · **[快速开始](#-快速开始)** · **[配置](#️-配置)** · **[路线图](#-路线图)**
|
||||
**[核心功能](#-核心功能)** · **[快速开始](#-快速开始)** · **[架构](#%EF%B8%8F-架构)** · **[配置](#%EF%B8%8F-配置)** · **[路线图](#-路线图)**
|
||||
|
||||
</div>
|
||||
|
||||
@@ -48,7 +47,6 @@
|
||||
<tr>
|
||||
<td width="50%"><img src="./docs/screenshots/backtest.png" alt="回测页" title="回测页"></td>
|
||||
<td width="50%"><img src="./docs/screenshots/monitor.png" alt="监控中心" title="监控中心"></td>
|
||||
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%" align="center"><b>连板梯队 Limit Ladder</b></td>
|
||||
@@ -70,7 +68,7 @@
|
||||
|
||||
### 🔍 选股引擎(Screener)
|
||||
|
||||
**20 个内置策略** —— 每个策略是一个独立 Python 文件(`backend/app/strategy/builtin/`),基于 Polars 表达式实现:
|
||||
**20+ 个内置策略** —— 每个策略是一个独立 Python 文件(`backend/app/strategy/builtin/`),基于 Polars 表达式实现:
|
||||
|
||||
| 类型 | 代表策略 |
|
||||
| :--- | :--- |
|
||||
@@ -86,11 +84,11 @@
|
||||
|
||||
#### ➕ 添加自己的策略
|
||||
|
||||
除 20 个内置策略外,你可以用两种方式扩展:
|
||||
除 20 个内置策略外,你可以用三种方式扩展:
|
||||
|
||||
| 方式 | 说明 | 前提 |
|
||||
| :--- | :--- | :--- |
|
||||
| **🤖 AI 生成** | 用自然语言描述策略思路,LLM 读取 [strategy-guide.md](./docs/strategy-guide.md) 自动生成完整 Polars 策略文件(经 `ast` 安全校验,限定 `import polars as pl`)。生成后落入 `data/strategies/ai/`,即刻可用 | 需先在 [配置](#️-配置) 中填入 AI Key |
|
||||
| **🤖 AI 生成** | 用自然语言描述策略思路,LLM 读取 [strategy-guide.md](./docs/strategy-guide.md) 自动生成完整 Polars 策略文件(经 `ast` 安全校验,限定 `import polars as pl`)。生成后落入 `data/strategies/ai/`,即刻可用 | 需先在 [配置](#%EF%B8%8F-配置) 中填入 AI Key |
|
||||
| **📝 代码自定义 / 策略迁移** | 参照 [策略开发指南](./docs/strategy-guide.md) 的文件结构模板,把你**已有的自有策略**改写为 Polars 文件放入 `data/strategies/custom/`(文件名/ID 建议 `custom_时间戳`),引擎自动发现加载——**轻松迁移你现成的量化项目策略**,无需从头重写 | 无 |
|
||||
| **🎛️ 自定义信号配置** | 不写代码,在 UI 上用 `字段 + 操作符 + 阈值` 组合(entry / exit / both),编译成 Polars 表达式热加载,即可定义自己的买卖信号 | 无 |
|
||||
|
||||
@@ -113,7 +111,7 @@
|
||||
|
||||
### 🧪 回测引擎(Backtest)
|
||||
|
||||
基于 vectorbt(全项目**唯一**一处 pandas 出现地):
|
||||
自研 Polars/NumPy 撮合引擎为主,兼容 vectorbt 作为可选依赖:
|
||||
|
||||
- **三种回测模式**:个股 · 策略组合 · 自由信号组合
|
||||
- **真实约束**:T+1 · 手续费 · 滑点(基点) · 止损 · 最大持仓天数
|
||||
@@ -184,7 +182,7 @@ docker compose run --rm test
|
||||
1. 打开面板 → **设置 → 凭据与能力** → 点 **重新检测**,确认 Tier Label
|
||||
2. 点 **立即跑盘后管道** —— 拉日 K + 计算 enriched 表
|
||||
- **Free 用户**:只同步内置 DEMO_SYMBOLS(浦发 / 招商 / 茅台等 10 只)
|
||||
- **Starter+**:同步全 A 或可获取的 instruments 列表
|
||||
- **Starter+**:同步全 A 或根据数据源能力获取的 instruments 列表
|
||||
3. **自选**页:添加跟踪标的;点代码进 **K 线**页看蜡烛图 + 买卖点
|
||||
4. **选股**页:点任一内置策略卡片即时扫描;或用自定义信号组合条件
|
||||
5. **回测**页:选策略 / 信号 + 时间区间 → 跑回测 → 看净值 / 夏普 / 交易明细(SSE 实时进度)
|
||||
@@ -192,6 +190,86 @@ docker compose run --rm test
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
### 技术栈
|
||||
|
||||
| 层 | 选型 |
|
||||
| :--- | :--- |
|
||||
| **后端** | FastAPI · Pydantic v2 · APScheduler · sse-starlette |
|
||||
| **数据** | Polars(计算)· DuckDB(查询)· Parquet(存储)· PyArrow |
|
||||
| **回测** | 自研 Polars/NumPy 撮合引擎 · vectorbt(可选依赖) |
|
||||
| **数据源** | A 股数据源 SDK(`tickflow[all]`) |
|
||||
| **AI**(可选) | OpenAI 兼容接口(DeepSeek / 通义 / Ollama 等) |
|
||||
| **前端** | React 18 · Vite · TypeScript · Tailwind CSS · Framer Motion · Tanstack Query · Lightweight Charts · ECharts · dnd-kit |
|
||||
| **部署** | Docker 两阶段构建,前端 dist 拷进后端镜像,**单容器** |
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
backend/app/
|
||||
├── api/ # FastAPI 路由(选股/回测/监控/数据/设置等)
|
||||
├── services/ # 业务服务(选股/行情/数据同步/告警存储等)
|
||||
├── strategy/ # 策略引擎(内置/自定义/AI生成/监控规则)
|
||||
├── indicators/ # Polars 指标流水线
|
||||
├── backtest/ # 自研回测引擎
|
||||
├── tickflow/ # 数据源 SDK 适配层
|
||||
└── jobs/ # 盘后定时管道任务
|
||||
|
||||
frontend/src/
|
||||
├── pages/ # 页面组件(Dashboard/Screener/Backtest/Monitor 等)
|
||||
├── components/ # 可复用组件(图表/表格/选股/监控等)
|
||||
└── lib/ # API 客户端/QueryKey/格式化工具等
|
||||
|
||||
data/ # 本地数据目录(Parquet 分区文件)
|
||||
├── kline_daily/ # 原始日 K
|
||||
├── kline_daily_enriched/ # 带指标日 K
|
||||
├── instruments/ # 标的维表
|
||||
├── financials/ # 财务数据
|
||||
├── ext_data/ # 用户扩展数据
|
||||
└── backtest_results/ # 回测结果
|
||||
```
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
tickflow 数据源
|
||||
↓
|
||||
kline_sync / instrument_sync / index_sync / financial_sync
|
||||
↓
|
||||
Parquet 分区文件 (data/)
|
||||
↓
|
||||
DuckDB 内存视图
|
||||
↓
|
||||
Polars 内存缓存
|
||||
↓
|
||||
选股 / 回测 / 监控 / 行情服务
|
||||
↓
|
||||
FastAPI → React 前端
|
||||
```
|
||||
|
||||
### 档位能力体系
|
||||
|
||||
`tiers.yaml` 定义了 Free → Expert 五档能力,启动时自动探测真实可用能力:
|
||||
|
||||
| 档位 | 能力 |
|
||||
| :--- | :--- |
|
||||
| **none** | 无 Key,仅历史日 K(批量) |
|
||||
| **free** | 免费有效 Key,能力与 none 等价 |
|
||||
| **starter** | 实时行情、批量、标的池、除权因子 |
|
||||
| **pro** | 增加分钟 K、五档盘口 |
|
||||
| **expert** | 增加财务数据、WebSocket |
|
||||
|
||||
UI 会显示友好标签(如「≈ Pro」),未解锁的功能自动灰显。
|
||||
|
||||
### 安全
|
||||
|
||||
- `/api/*` 路径通过 `auth.py` 中间件校验访问令牌
|
||||
- 支持 `admin` / `user` 两种角色,管理员令牌可在 `.env` 中配置
|
||||
- AI 生成策略经 `ast` 安全校验,禁止 `open/exec/eval/os/sys/subprocess`,限定 `import polars as pl`
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 配置
|
||||
|
||||
所有配置通过项目根目录的 `.env` 文件读取(复制 `.env.example` 开始)。配置也可在面板 **设置** 页面内修改。
|
||||
@@ -227,24 +305,12 @@ HOST=0.0.0.0 # 监听地址
|
||||
PORT=3018 # 服务端口
|
||||
LOG_LEVEL=INFO # DEBUG | INFO | WARNING | ERROR
|
||||
DATA_DIR=./data # Parquet / DuckDB 数据存储目录
|
||||
ACCESS_UUID= # 访问控制 UUID(可选)
|
||||
ADMIN_TOKEN=admin # 管理员令牌
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 技术栈
|
||||
|
||||
| 层 | 选型 |
|
||||
| :--- | :--- |
|
||||
| **后端** | FastAPI · Pydantic v2 · APScheduler · sse-starlette |
|
||||
| **数据** | Polars(计算)· DuckDB(查询)· Parquet(存储)· PyArrow |
|
||||
| **回测** | vectorbt(全项目唯一 pandas 边界) |
|
||||
| **数据源** | A 股数据源 SDK(`tickflow[all]`) |
|
||||
| **AI**(可选) | OpenAI 兼容接口(DeepSeek / 通义 / Ollama 等) |
|
||||
| **前端** | React 18 · Vite · TypeScript · Tailwind CSS · Framer Motion · Tanstack Query · Lightweight Charts · ECharts · dnd-kit |
|
||||
| **部署** | Docker 两阶段构建,前端 dist 拷进后端镜像,**单容器** |
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ 路线图
|
||||
|
||||
| Phase | 内容 | 状态 |
|
||||
@@ -252,7 +318,7 @@ DATA_DIR=./data # Parquet / DuckDB 数据存储目录
|
||||
| **0** | 仓库骨架 / FastAPI 壳 / Vite + React SPA / Docker 一键起 | ✅ |
|
||||
| **1** | 能力探测 + Kline 同步 + K 线分析页 | ✅ |
|
||||
| **2** | Polars enriched 流水线 + Screener + 信号扫描 | ✅ |
|
||||
| **3** | vectorbt 回测 + T+1 + 手续费 + 止损 + max-hold | ✅ |
|
||||
| **3** | 自研回测引擎 + T+1 + 手续费 + 止损 + max-hold | ✅ |
|
||||
| **4** | 监控引擎 + 告警规则 + Webhook + APScheduler 盘后定时 | ✅ |
|
||||
| **5** | 统一监控中心 + 四类监控规则 + 实时推送 + 持久化触发记录 + 声效通知 | ✅ |
|
||||
| **v2** | Webhook 推送(QMT/掘金下单) · 板块异动 · 早晚报 · 更多扩展 | 🚧 |
|
||||
@@ -262,7 +328,8 @@ DATA_DIR=./data # Parquet / DuckDB 数据存储目录
|
||||
## 📚 文档
|
||||
|
||||
- [docs/strategy-guide.md](./docs/strategy-guide.md) —— 策略开发指南(AI 生成器与手写策略的规范)
|
||||
- [docs/](./docs) —— 策略构建步骤、示例
|
||||
- [docs/strategy-example.md](./docs/strategy-example.md) —— 策略示例
|
||||
- [docs/strategy-builder-step1.md](./docs/strategy-builder-step1.md) / [step2.md](./docs/strategy-builder-step2.md) —— 策略构建步骤
|
||||
|
||||
---
|
||||
|
||||
@@ -284,14 +351,4 @@ docker compose run --rm test
|
||||
|
||||
## ⚠️ 免责声明
|
||||
|
||||
本项目仅供**学习与量化研究**,**不构成任何投资建议**。回测结果不代表未来收益。A 股有风险,入市需谨慎。数据准确性以数据源官方为准。
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
[MIT](./LICENSE) © stock-panel contributors
|
||||
|
||||
## 社区
|
||||
|
||||
本开源项目已链接并认可 [LINUX DO 社区](https://linux.do)。
|
||||
本项目仅供**学习与量化研究**,**不构成任何投资建议**。回测结果不代表未来收益。A 股有风险,入市需谨慎。数据准确性以数据源官方为准。
|
||||
Reference in New Issue
Block a user