优化项目说明文档

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 模式无需 Key) · 能力驱动,适配 Free → Expert 全档位订阅 · 🔌 **自由接入第三方扩展数据**(Tushare、自有量化项目数据等)
-能力驱动,适配 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) —— 策略构建步骤
 
 ---
 
@@ -285,13 +352,3 @@ docker compose run --rm test
 ## ⚠️ 免责声明
 
 本项目仅供**学习与量化研究**,**不构成任何投资建议**。回测结果不代表未来收益。A 股有风险,入市需谨慎。数据准确性以数据源官方为准。
-
----
-
-## 📄 License
-
-[MIT](./LICENSE) © stock-panel contributors
-
-## 社区
-
-本开源项目已链接并认可 [LINUX DO 社区](https://linux.do)。