diff --git a/README.md b/README.md index cc565ec..cf44d99 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,9 @@ [![React](https://img.shields.io/badge/React-18-61dafb.svg)](https://react.dev/) [![Deploy: Docker](https://img.shields.io/badge/Deploy-Docker-2496ed.svg)](./Dockerfile) -🚀 **开箱即用**(单容器 / Free 模式无需 Key) -能力驱动,适配 Free → Expert 全档位订阅 · 🔌 **自由接入第三方扩展数据**(例如 Tushare、自有量化项目数据) +🚀 **开箱即用**(单容器 / Free 模式无需 Key) · 能力驱动,适配 Free → Expert 全档位订阅 · 🔌 **自由接入第三方扩展数据**(Tushare、自有量化项目数据等) -**[核心功能](#-核心功能)** · **[快速开始](#-快速开始)** · **[配置](#️-配置)** · **[路线图](#-路线图)** +**[核心功能](#-核心功能)** · **[快速开始](#-快速开始)** · **[架构](#%EF%B8%8F-架构)** · **[配置](#%EF%B8%8F-配置)** · **[路线图](#-路线图)** @@ -48,7 +47,6 @@ 回测页 监控中心 - 连板梯队 Limit Ladder @@ -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 股有风险,入市需谨慎。数据准确性以数据源官方为准。 \ No newline at end of file