diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..18aaa2d
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,112 @@
+# 配置详解
+
+所有配置从根目录 `.env` 读取(复制 `.env.example` 开始),也可在面板 **设置** 页面可视化修改。本文件解释每个配置项的作用。
+
+部署相关配置(端口/密码/老 CPU 兼容)的实操见 [deployment.md](./deployment.md)。
+
+---
+
+## 数据源:TickFlow
+
+```ini
+TICKFLOW_API_KEY=              # 留空 = None 模式(历史日K免费);填 Key = 按订阅档位解锁
+```
+
+本项目基于 [TickFlow](https://tickflow.org) 数据源。
+
+- **留空(None 模式)**:通过 free-api 使用历史日 K(当日数据盘后 1-2 小时可用),**无需付费**即可体验核心选股/回测功能
+- **填入 API Key**:按你的订阅档位解锁更多能力
+
+### 实时行情按档位
+
+| 档位     | 实时能力                                 |
+| :------- | :--------------------------------------- |
+| Free     | 自选页前 5 个标的实时监控(最低 6 秒刷新) |
+| Starter+ | 全市场实时行情                           |
+| Pro      | 分钟 K + 盘口                            |
+| Expert   | WebSocket + 财务数据                     |
+
+> 完整能力矩阵见 [tickflow.org/pricing](https://tickflow.org/pricing/),高等档位含较低档全部权益。
+> 在面板 **设置 → 凭据与能力** 点「重新检测」可查看当前档位标签。
+
+---
+
+## AI(可选)
+
+用于自然语言生成策略。**所有配置留空即跳过**,不影响核心功能。支持任意 OpenAI 兼容接口。
+
+```ini
+AI_PROVIDER=openai_compat              # openai_compat | ollama
+AI_BASE_URL=https://api.deepseek.com/v1
+AI_API_KEY=                            # 留空 = 关闭 AI
+AI_MODEL=deepseek-chat
+AI_DAILY_TOKEN_BUDGET=500000           # 每日 token 预算上限
+```
+
+| 配置项 | 说明 |
+| :--- | :--- |
+| `AI_PROVIDER` | `openai_compat`(OpenAI 兼容,支持 DeepSeek / 通义 / OpenAI 等)或 `ollama`(本地模型) |
+| `AI_BASE_URL` | 接口地址,如 DeepSeek `https://api.deepseek.com/v1` |
+| `AI_API_KEY` | 留空则关闭 AI 功能 |
+| `AI_MODEL` | 模型名,如 `deepseek-chat` |
+| `AI_DAILY_TOKEN_BUDGET` | 每日 token 预算,超限后当日不再调用 |
+
+接入示例见 [strategy.md](./strategy.md) 的「AI 生成策略」章节。
+
+---
+
+## 服务
+
+```ini
+HOST=0.0.0.0          # 监听地址
+PORT=3018             # 服务端口
+LOG_LEVEL=INFO        # DEBUG | INFO | WARNING | ERROR
+```
+
+- `HOST`:`0.0.0.0` 监听所有网卡(容器/公网部署需要);仅本机用可设 `127.0.0.1`
+- `PORT`:默认 `3018`,改端口后 Docker 映射、SSH 转发命令里的端口也要同步改
+- `LOG_LEVEL`:排查问题时改 `DEBUG`
+
+---
+
+## 数据
+
+```ini
+DATA_DIR=./data       # Parquet / DuckDB 数据存储目录
+```
+
+整个 `data/` 目录都不纳入 git —— 行情 K线、财务、自选、回测、监控记录,乃至概念/行业扩展数据,全部是程序运行时生成/拉取的用户数据。
+
+如需迁移数据,直接拷贝整个 `data/` 目录即可。详见 [deployment.md → 更新代码](./deployment.md#更新代码已部署用户必读)。
+
+---
+
+## 访问密码(公网部署)
+
+```ini
+AUTH_PASSWORD=你的密码    # 至少 6 位;仅首次生效,已设过则不覆盖
+```
+
+面板首次设置访问密码时,出于安全考虑**仅允许本机或内网访问**(防公网陌生人抢先设置锁死面板)。公网服务器部署可通过此环境变量预置首个密码。
+
+详细步骤、SSH 转发方案、重置密码方法见 [deployment.md → 访问密码设置](./deployment.md#访问密码设置公网部署必读)。
+
+---
+
+## Docker 构建 Extras(可选)
+
+```ini
+BACKEND_EXTRAS=             # 留空默认;legacy-cpu 兼容老 CPU
+```
+
+老 VPS 无 AVX2/FMA 支持时设为 `legacy-cpu`,会给 Polars 切到 `rtcompat` 运行时;需回测则 `legacy-cpu backtest`。详见 [deployment.md → 老 CPU 兼容](./deployment.md#老-cpu-兼容avx2fma-缺失)。
+
+---
+
+## 配置优先级
+
+1. **面板设置页**(`设置 → ...`):UI 修改后立即生效,持久化到 `data/`
+2. **`.env` 文件**:启动时读取
+3. **环境变量**:Docker / 系统环境变量,优先级最高
+
+> 多数配置可在面板设置页修改,无需手动编辑 `.env`。仅 AI Key、API Key 等敏感项建议放 `.env`(不提交到 git)。
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..ae9ca6b
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,177 @@
+# 部署指南
+
+本项目的几种运行方式，按推荐程度排序。配置项详解见 [configuration.md](./configuration.md)。
+
+> 📌 前置依赖:Python ≥ 3.11 · Node ≥ 20 · [`uv`](https://docs.astral.sh/uv/) · `pnpm`（`npm i -g pnpm`）
+
+---
+
+## 方式 A:Dev 模式(二次开发推荐)
+
+由于刚开源近期更新频繁,推荐开发模式运行,可随时 `git pull` 同步最新代码。
+
+```bash
+git clone https://github.com/shy3130/tickflow-stock-panel.git
+cd tickflow-stock-panel
+cp .env.example .env       # 按需填 TICKFLOW_API_KEY(留空 = None 模式)
+./dev.sh                   # Windows: .\dev.ps1
+```
+
+`dev.sh` 自动检查 / 下载依赖、释放端口、同时起前后端,Ctrl-C 一并关闭。默认:
+
+- 后端 → <http://localhost:3018> · 前端 → <http://localhost:3011>
+- 自定义端口:`BACKEND_PORT=8000 FRONTEND_PORT=5173 ./dev.sh`
+
+### 手动分别启动(不想用 dev.sh)
+
+```bash
+# 后端
+cd backend && uv sync --extra backtest   # 含回测依赖
+uv run uvicorn app.main:app --reload --port 3018
+
+# 前端
+cd frontend && pnpm install && pnpm dev   # http://localhost:3011
+```
+
+---
+
+## 方式 B:Docker(部署最省心)
+
+```bash
+cp .env.example .env
+docker compose up --build
+# 打开 http://localhost:3018
+```
+
+Docker 采用两阶段构建,前端 dist 拷进后端镜像,**单容器**运行,数据完全在自己手里。
+
+更新到新版本:
+
+```bash
+git pull
+docker compose up --build -d
+```
+
+---
+
+## 方式 C:GitHub Actions 自行构建
+
+Fork 本仓库后,手动触发 [Release 打包工作流](https://github.com/shy3130/tickflow-stock-panel/actions/workflows/release.yml) 自行构建桌面客户端安装包。
+
+> ⚠️ 目前官方 Release 的安装包存在已知问题(修复中),如需桌面客户端请优先用此方式自行构建,或用上面的 Dev / Docker 方式运行。
+
+---
+
+## 老 CPU 兼容(avx2/fma 缺失)
+
+如果运行时报 `avx2`/`fma` 缺失,或进程 `exit 132`,说明 CPU 不支持 AVX2 指令集(常见于老 VPS)。解决:
+
+- **桌面客户端**:安装包已内置兼容内核,新老 CPU 通吃
+- **Docker / 源码**:在 `.env` 打开 `BACKEND_EXTRAS=legacy-cpu` 后重建,会给 Polars 切到 `rtcompat` 运行时
+
+```ini
+BACKEND_EXTRAS=legacy-cpu          # 兼容老 CPU
+BACKEND_EXTRAS=legacy-cpu backtest # 兼容老 CPU + 回测依赖
+```
+
+### 回测依赖说明
+
+vectorbt → numba 体积较大,作为可选 extras(`uv sync --extra backtest`)。macOS / Intel 无预构建 wheel 时需 `brew install cmake` 现场编译。
+
+---
+
+## 更新代码(已部署用户必读)
+
+拉取新版本只需一条命令:
+
+```bash
+git pull
+```
+
+**整个 `data/` 目录都不纳入 git** —— 行情 K线、财务、自选、回测、监控记录,乃至概念/行业扩展数据,全部是程序运行时生成/拉取的用户数据,`git pull` 物理上无法影响它们。新用户首次启动时,概念/行业两份扩展数据会自动从远程接口拉取,无需任何手动操作。
+
+> ⚠️ **切勿使用以下命令"解决冲突"或"清理",它们会一次性删光 `data/` 下所有未被 git 跟踪的数据:**
+> - `git clean -fdx`(最危险,会删掉所有 `.gitignore` 忽略的文件)
+> - `git reset --hard`
+> - 直接删除整个项目文件夹重新 `git clone`
+>
+> 若 `git pull` 报冲突,通常是本地误改了被跟踪的文件,请先 `git stash` 暂存再 pull,或单独联系作者,不要直接执行上面的命令。
+
+---
+
+## 访问密码设置(公网部署必读)
+
+面板部署在公网服务器时,首次设置访问密码有限制 —— **必须从本机或内网访问**,以防公网上陌生人抢先设置密码锁死你的面板。
+
+如果你在公网浏览器直接打开页面,会看到提示:
+
+> 首次设置密码仅允许本机或内网访问,请通过 SSH/本地浏览器操作
+
+有两种方式解决,任选其一。
+
+### 方式一:环境变量预置密码(最简单,推荐)
+
+在 `.env` 文件(或 Docker / 系统环境变量)里设置 `AUTH_PASSWORD`:
+
+```bash
+AUTH_PASSWORD=你的密码
+```
+
+然后重启服务。启动时会自动:
+
+1. 读取 `AUTH_PASSWORD`
+2. 用 PBKDF2 哈希后写入 `auth.json`(`chmod 600`,只存哈希不存明文)
+3. **之后这个环境变量就不再被读取** —— 是一次性的初始化
+
+设完后即可用公网地址 + 这个密码正常登录。后续改密码请用页面 UI(`设置 → 修改密码`),不受环境变量影响。
+
+**注意事项:**
+
+- **密码至少 6 位**,否则会被跳过并记一条 warning 日志
+- **仅在未设过密码时生效**。已设过密码后,改这里不会覆盖(避免重启时重置你在 UI 改的密码)
+- `.env` 文件权限保持 `600`,**不要提交到 Git**
+- 明文密码只存在于 `.env` / 环境变量中,落盘的是哈希,安全性等同 `auth.json`
+
+**重置密码(忘密码时):** 删除或清空 `data/user_data/auth.json`,重启服务,会回到"未设密码"状态,此时 `AUTH_PASSWORD` 会重新生效。
+
+```bash
+rm data/user_data/auth.json   # 停服后执行,清空后重启
+```
+
+### 方式二:SSH 端口转发
+
+不用改配置,在你**自己电脑**的终端执行(不是服务器上):
+
+```bash
+ssh -L 3018:127.0.0.1:3018 用户名@服务器IP
+```
+
+例如服务器是 `123.45.67.89`、用户名 `root`、面板端口 `3018`:
+
+```bash
+ssh -L 3018:127.0.0.1:3018 root@123.45.67.89
+```
+
+保持这个 SSH 连接**不要关**,然后在**自己电脑的浏览器**打开 `http://127.0.0.1:3018`。此时后端看到的客户端 IP 是 `127.0.0.1`(本机),能通过校验,正常显示设置密码界面。
+
+**设完密码后**,SSH 连接可以断开 —— 密码已存进服务器,之后直接用公网地址 + 刚设的密码访问即可。
+
+> 如果用 `PORT` 改过端口(比如 `PORT=8080`),两处都要替换:`ssh -L 8080:127.0.0.1:8080 root@IP`。
+
+### 两种方式怎么选
+
+| | 环境变量 | SSH 转发 |
+|---|---|---|
+| 操作 | 改一行配置 + 重启 | 一条 ssh 命令 |
+| 需要改配置 | 是 | 否 |
+| 适合 | Docker / 自动化部署 / 不熟 SSH | 临时设密码 / 能 SSH 到服务器 |
+| 后续改密码 | UI(`设置 → 修改密码`) | 同左 |
+
+推荐**方式一(环境变量)**,一次配置即可,Docker 部署尤其方便。
+
+### 原理说明
+
+- **为什么限制本机/内网?** 面板部署到公网后,任何人都能访问 URL。如果不限制,攻击者可以在你之前打开页面、设置一个密码,把你的面板锁死。
+- **本机/内网如何判断?** 后端检查客户端 IP 是否属于 `127.0.0.1 / ::1 / 10.x / 192.168.x / 172.16-31.x`。
+- **SSH 转发为什么有效?** `-L` 把本机端口通过 SSH 隧道转发到服务器的 `127.0.0.1`,等同于在服务器本地访问,客户端 IP 变成 `127.0.0.1`,通过校验。
+- **反向代理注意:** 若面板在 Nginx 等反代之后,需正确配置 `X-Forwarded-For` 头,后端据此取真实客户端 IP。
diff --git a/docs/features.md b/docs/features.md
new file mode 100644
index 0000000..b808581
--- /dev/null
+++ b/docs/features.md
@@ -0,0 +1,123 @@
+# 功能手册
+
+各功能模块的详细说明。配置见 [configuration.md](./configuration.md),部署见 [deployment.md](./deployment.md),策略相关见 [strategy.md](./strategy.md)。
+
+> 首次使用建议顺序:**设置 → 凭据与能力**(重新检测) → **立即跑盘后管道**(拉日 K + 算指标) → **自选页**加标的 → **选股页**扫描 → **回测页**验证 → **监控中心**配规则。
+
+---
+
+## 🔍 选股引擎(Screener)
+
+**20 个内置策略**,每个策略一个独立 Python 文件,基于 Polars 表达式向量化实现(`backend/app/strategy/builtin/`):
+
+| 类型        | 代表策略                                                 |
+| :---------- | :------------------------------------------------------- |
+| 趋势 / 形态 | 趋势突破 · 均线多头 · MA 金叉 · MACD 金叉放量 · 布林突破 |
+| 量价 / 涨停 | 量价齐升 · 高换手强势 · 连板股 · 断板反包 · 涨停动量     |
+| 反转 / 波动 | 超跌反弹 · 超卖反转 · 新低反转 · 低波动龙头 · 回踩 MA20  |
+
+全 A 股一次扫表,Polars 毫秒级返回。选股页点策略卡片即可扫描,结果支持导出。
+
+扩展策略的三种方式见 [strategy.md → 扩展策略](./strategy.md#扩展策略的三种方式)。
+
+---
+
+## 📊 指标流水线(Indicators)
+
+原生 Polars 向量化,全 A 股一次扫表落盘 enriched Parquet:
+
+- **均线 / 趋势**:MA(5-60) · EMA · MACD · 动量 · 布林带
+- **震荡 / 波动**:RSI · KDJ · ATR · 年化波动率 · 振幅
+- **量能 / 涨跌停**:量比 · 量均线 · 涨停信号 · 连板数
+- **原子信号**:MA / MACD 金叉死叉 · N 日新高新低 · 布林突破
+- **复权**:基于除权因子自动前复权,回测与指标口径一致
+
+盘后管道(15:30 CST 自动触发)会重新拉日 K + 重算 enriched 表。
+
+---
+
+## 🧪 回测引擎(Backtest)
+
+基于 vectorbt(**三种模式**):
+
+| 模式 | 说明 |
+| :--- | :--- |
+| 个股回测 | 单标的 + 策略,看个股历史表现 |
+| 策略组合 | 一个策略扫描全市场,按组合约束回测 |
+| 自由信号组合 | 多个自定义信号组合,自定义权重 |
+
+**真实约束**:T+1 · 手续费 · 滑点 · 止损 · 最大持仓天数。
+
+**组合管理**:最大持仓数 · 敞口控制 · 等权 / 自定义仓位。
+
+输出净值曲线 · 夏普 · 最大回撤 · 胜率 · 交易明细。SSE 流式进度支持切页重连,不会丢失回测任务。
+
+---
+
+## 📡 监控中心(Monitor)
+
+统一规则引擎,一个页面管理**四类监控**:
+
+| 类型 | 场景 |
+| :--- | :--- |
+| 策略监控 | 策略扫描结果有变化时触发(如新增符合标的) |
+| 个股信号监控 | 特定个股的指标条件(如 `RSI > 80`) |
+| 价格涨跌监控 | 涨跌幅 / 价格突破阈值 |
+| 全市场异动 | 全市场异动(如快速拉升/跌停) |
+
+**特性:**
+
+- 多条件 AND/OR + 冷却期去重 + 严重级别(info / warn / critical)
+- 多入口配置:监控中心新建 / 个股详情页「加监控」/ 策略卡片一键开启
+- 命中后右下角弹窗(可配声效)+ 持久化到 `alerts.jsonl`,菜单未读徽标
+- **触发记录详情**:每条记录展示命中的具体条件(如 `RSI>80`)与当前价位,一眼看清为何触发
+
+### 飞书 Webhook 推送
+
+全局一处配置飞书群机器人地址,启用推送的规则命中即推送到飞书群(支持签名校验)。可在设置页设「默认推送渠道」,新建规则自动预填。
+
+---
+
+## 📈 个股分析(Beta)
+
+以「行情 + 关键价位」为主体的单标的决策页:
+
+- **专用日 K 图表**:主图 + 成交量 + 滑块,默认近 6 个月
+- **9 类关键价位**(纯函数实时计算,毫秒级):压力支撑 · 成交密集区 · 枢轴点 · 前高前低 · Keltner 通道 · ATR 止损 · 缺口位 · 斐波那契 · 整数关口
+- **AI 四维分析**:技术 / 基本面 / 财务 / 消息面流式生成,实战派交易员视角
+
+---
+
+## 🏆 连板梯队 & 概念分析
+
+- **连板梯队**:实时统计各连板层级(首板 / 2 连板 / 3 连板...)的标的与封单,捕捉市场情绪与题材热度
+- **概念涨幅轮动**:基于 ths 概念 / 行业,统计概念板块涨幅与 RPS 轮动,AI 分析资金主线
+- **盘后 AI 复盘**:盘后自动生成市场复盘,可推送至飞书群
+
+---
+
+## 🧰 数据与扩展
+
+### TickFlow 多源数据
+
+日 K / 分钟 K / 指数 / 财务 / 实时行情,基于 [TickFlow](https://tickflow.org) 官方 SDK。
+
+### 🔌 第三方数据接入(重点)
+
+支持将自有量化项目的数据并入,与内置数据同台分析:
+
+| 方式 | 说明 |
+| :--- | :--- |
+| HTTP 定时拉取 | Tushare 等 API,定时拉取并入库 |
+| CSV / Excel 上传 | 页面直接上传文件 |
+| JSON 写入 | 程序化写入 |
+
+接入后自动 schema 发现 + 符号归一,页面可视化配置,最终并入 DuckDB 同台分析。
+
+### 盘后定时管道
+
+APScheduler 15:30 CST 自动:拉日 K → 重算 enriched 表 → 跑监控规则。
+
+### 令牌桶限流
+
+适配各档位 rpm / batch 限制,批量合并 + 增量拉取,避免触发数据源限流。
diff --git a/docs/strategy.md b/docs/strategy.md
new file mode 100644
index 0000000..4ebdf34
--- /dev/null
+++ b/docs/strategy.md
@@ -0,0 +1,84 @@
+# 策略指南
+
+策略是选股引擎、回测、监控的基础。本文介绍策略体系与三种扩展方式。
+
+完整策略开发规范(AI 生成与手写)见 [`backend/app/strategy/prompts/strategy-guide.md`](../backend/app/strategy/prompts/strategy-guide.md)。
+
+---
+
+## 内置策略
+
+**18 个内置策略**,每个策略一个独立 Python 文件,基于 Polars 表达式向量化实现(`backend/app/strategy/builtin/`):
+
+| 类型        | 代表策略                                                 |
+| :---------- | :------------------------------------------------------- |
+| 趋势 / 形态 | 趋势突破 · 均线多头 · MA 金叉 · MACD 金叉放量 · 布林突破 |
+| 量价 / 涨停 | 量价齐升 · 高换手强势 · 连板股 · 断板反包 · 涨停动量 · 接近涨停 |
+| 反转 / 波动 | 超跌反弹 · 超卖反转 · 新低反转 · 低波动龙头 · 回踩 MA20 · 回踩支撑 · 强势开盘 |
+
+内置目录 `backend/app/strategy/builtin/` 由项目维护,**AI 生成的策略不会落入此目录**。
+
+---
+
+## 扩展策略的三种方式
+
+### 🎛️ 方式一:自定义信号(不写代码)
+
+在选股页 UI 上用 `字段 + 操作符 + 阈值` 组合,编译成 Polars 表达式热加载。适合:
+
+- 快速验证一个简单的筛选思路(如 `RSI < 30 AND 量比 > 2`)
+- 不熟悉 Python 但想自定义筛选条件
+
+底层实现在 `backend/app/strategy/custom_signals.py`。
+
+### 🤖 方式二:AI 生成
+
+一句话描述思路,LLM 读 `strategy-guide.md` 生成完整策略文件:
+
+1. **配置 AI 接口**(留空即关闭,见 [configuration.md → AI](./configuration.md#ai可选)):
+   ```ini
+   AI_PROVIDER=openai_compat
+   AI_BASE_URL=https://api.deepseek.com/v1
+   AI_API_KEY=sk-...
+   AI_MODEL=deepseek-chat
+   ```
+2. 在选股页打开「AI 策略生成器」,用自然语言描述你的策略思路
+3. LLM 生成完整策略代码,经 `ast` 安全校验(禁止 import os/sys/subprocess 等危险模块)后
+4. 落入 `data/strategies/ai/`,文件名/ID 用 `ai_` 前缀
+
+生成的策略会读取 `backend/app/strategy/prompts/` 下的提示词文档:
+
+- `strategy-guide.md` — 完整策略开发规范(作为 LLM system prompt)
+- `strategy-builder-step1.md` — 步骤 1 提示词模板(规则 → 完整代码)
+- `strategy-builder-step2.md` — 步骤 2 提示词模板(修改已有策略)
+- `strategy-example.md` — 从零创建强势反包策略的三步演示
+
+> 💡 **文件与范围铁律**:AI 生成的策略只生成一个 `.py` 文件,只 `import polars as pl`,绝不修改 `backend/`、`docs/`、`frontend/` 等现有文件。
+
+### 📝 方式三:代码迁移
+
+参照开发指南把已有策略改写为 Polars 文件,放入 `data/strategies/custom/`,引擎自动发现。
+
+手写策略需遵循 [`strategy-guide.md`](../backend/app/strategy/prompts/strategy-guide.md) 的文件结构(META / basic_filter / scoring / ENTRY_SIGNALS / filter 等),完整规范见该文档。
+
+---
+
+## 策略文件结构(简述)
+
+一个策略 `.py` 文件通常包含:
+
+| 部分 | 作用 |
+| :--- | :--- |
+| `META` | 策略元信息(名称、参数、方向等),用户可在 UI 调整阈值 |
+| `basic_filter(df, params)` | 模式 A:单日过滤,返回 `pl.Expr` |
+| `filter_history(df, params)` | 模式 B:历史窗口过滤,返回 `pl.DataFrame`(配 `LOOKBACK_DAYS`) |
+| `scoring` | 评分权重,总和 = 1.0 |
+| `ENTRY_SIGNALS` / `EXIT_SIGNALS` | 进出场信号列(回测用) |
+
+完整字段说明与示例见 [`strategy-guide.md`](../backend/app/strategy/prompts/strategy-guide.md)。
+
+---
+
+## 新增内置策略(贡献者)
+
+如果你想为项目贡献一个内置策略:在 `backend/app/strategy/builtin/` 参照现有文件实现 `StrategyDef`,引擎会自动发现并加载。欢迎提交 PR。