# 功能总览

> A股量化回测与信号监控平台 · 完整功能说明
> 正式入口：https://quant.quasarxode.cn

---

## 目录

1. [平台概览](#一平台概览)
2. [用户端功能](#二用户端功能)
3. [管理后台功能](#三管理后台功能)
4. [产品官网](#四产品官网)
5. [量化核心能力](#五量化核心能力)
6. [安全体系](#六安全体系)
7. [技术架构](#七技术架构)
8. [测试基线](#八测试基线)
9. [产品边界](#九产品边界)

---

## 一、平台概览

私有化部署的 A 股策略研究平台。围绕「策略 → 回测 → 监控 → 信号 → 下单」这条主线，
提供完整闭环，同时具备细粒度 RBAC、审计日志与多层安全防护。

### 1.1 四端形态

平台按**同域名不同路径**拆成四个独立前端产物，互不耦合：

| 路径 | 产物目录 | 技术形态 | 说明 |
|---|---|---|---|
| `/` | `website/` | 纯静态 HTML/CSS/JS | 产品官网（对外展示，不含业务数据） |
| `/docs/` | `website/docs/` | 纯静态 HTML | 部署文档页 |
| `/app/` | `frontend/` | Vue 3 SPA | 用户端：策略、回测、监控、信号、订单 |
| `/admin/` | `frontend-admin/` | Vue 3 SPA | 管理后台：用户、权限、日志、全站资源 |

后端只提供 `/api`，四端共用同一套 JWT 鉴权与 localStorage 会话。

**用户端与后台是两个完全独立的应用** —— 独立入口、独立产物目录、独立路由表。
后台不打包用户端任何业务页面，用户端也不包含任何管理功能。

### 1.2 能力地图

```
                    ┌─────────────────────────────────────┐
 浏览器 ───────────▶ │ Nginx (同域，按路径分流)              │
                    └──────────┬───────────┬───────────┬──┘
                               │           │           │
              /  /docs/        │  /app/    │  /admin/  │  /api/  /health
                               ▼           ▼           ▼       ▼
                          website/    frontend/  frontend-admin/  FastAPI
                         (纯静态)      (dist)        (dist)      (uvicorn)
                                        └───────┬───────┘
                                                │ 共用
                                       frontend-shared/src
```

### 1.3 核心数据流

```
① 用户配置策略（快慢均线 / 波动率过滤 / 风控 / 成本）
        ↓
② 运行回测 → 生成报告（净值曲线 / K 线买卖点 / 交易明细 / 分标的统计）
        ↓
③ 创建监控任务（绑定策略，定时扫描）
        ↓
④ 扫描命中 → 生成信号（数据库唯一索引去重）
        ↓
⑤ 推送（QXBot Webhook，XML 卡片 / 纯文本）
        ↓
⑥ 模拟撮合下单（paper 模式记账 / live 模式需二次确认）
```

---

## 二、用户端功能

访问路径：`/app/`　共 **13 个页面**

### 2.1 账号体系

| 页面 | 路径 | 功能 |
|---|---|---|
| 登录 | `/app/login` | 用户名 + 密码 + 图形验证码；失败锁定策略；登录后按 `redirect` 参数跳回 |
| 注册 | `/app/register` | 用户名 / 邮箱 / 密码 + 图形验证码；用户名规则：字母开头，仅含字母数字下划线，3-20 位 |
| 找回密码 | `/app/forgot` | 用管理员发放的**一次性重置码**改密（不开放邮件自助找回，避免邮箱枚举） |

**图形验证码**：纯标准库画的 PNG，一次性使用，恒定时间比较，防重放。

### 2.2 概览页 `/app/dashboard`

- 关键指标卡：策略数、回测数、信号数、订单数、累计收益
- 近 7 天净值曲线（ECharts，跟随主题切换）
- 最近回测记录
- 最新信号列表
- 行情数据源提示（tushare / 合成数据）

### 2.3 我的策略 `/app/strategies`

- 策略列表：名称、标的池、参数摘要、模式（回测/实盘）、状态
- 策略参数可视化配置，**改参数不改代码**
  - 快慢均线周期（`fast_ma` / `slow_ma`）
  - 波动率窗口与阈值（`vol_window` / `vol_threshold`）
  - 股票池（最多 50 只）
  - 风控：单笔仓位上限、组合回撤止损线、连续亏损暂停阈值
  - 成本：佣金（含最低佣金）、印花税（仅卖出）、滑点
- 一键复制策略
- 从管理员模板套用（`/api/strategies/templates/list`）

### 2.4 回测记录 `/app/backtests`

- 回测列表：状态、收益、最大回撤、夏普比率、标的数、耗时
- 运行回测（同步执行，几十毫秒级）
- 删除回测记录
- 回到测报告页 `/app/backtests/:id`

**回测报告内容**：
- 收益曲线（净值 / 收益率 / 回撤 三种视图切换）
- K 线图 + 买卖点标记
- 仓位变化曲线
- 交易明细表
- 分标的统计

### 2.5 行情监控 `/app/monitors`

- 监控任务列表：绑定策略、扫描间隔、运行状态、上次执行时间
- 启动 / 停止监控任务
- **立即执行一次**扫描（不等下一个周期）
- 调度器实时状态面板（`running` / 线程状态 / 今日扫描次数）
- 扫描仅在 A 股交易时段生效（可配置）

### 2.6 信号记录 `/app/signals`

- 信号列表：股票、方向（买/卖）、价格、触发原因、产生时间、已读状态、推送状态
- 全部标记已读
- 失败信号手动重推
- 信号统计（今日/本周/累计）

### 2.7 交易下单 `/app/orders`

- 下单表单：股票代码、方向、数量（**必须是 100 的整数倍**）、价格模式
- 幂等去重：相同 `idempotency_key` 在 10 秒窗口内返回同一订单
- 订单列表：状态（pending/filled/cancelled）、模式（paper/live）
- 撤单
- live 模式订单需**二次确认**才生效
- 下单能力说明面板（`/api/orders/capabilities`）：当前系统能做什么、不能做什么

### 2.8 个人中心 `/app/profile`

四个标签页：

| 标签 | 功能 |
|---|---|
| 基本资料 | 昵称、手机、邮箱；修改密码 |
| 推送配置 | QXBot Webhook 地址 + 卡片格式（XML / 纯文本）；**发送测试消息** |
| 券商配置 | 券商账号密码（**AES 加密入库，接口只回显掩码**）；自动交易开关 |
| 外观设置 | 浅色 / 深色 / 跟随系统三选一，偏好持久化到浏览器 |

### 2.9 其他

- `/app/403` 无权访问页
- `/app/404` 页面不存在页（兜底路由）

---

## 三、管理后台功能

访问路径：`/admin/`　共 **14 个页面**

后台采用**独立应用**形态，不打包用户端任何页面。共用同一套 JWT 会话，
但有独立的路由表和守卫（非管理员访问 → 403）。

### 3.1 数据概览 `/admin/overview`

- 六大统计卡：用户、策略、回测、信号、订单、报错数
- 调度器实时状态
- **近 7 天趋势图**：新增用户 / 回测 / 信号 / 报错逐日统计（堆叠柱 + 折线，跟随主题切换）
- **最近失败的回测榜**：管理员最需要立刻看到的待修项
- **活跃用户榜**：按策略 + 回测 + 信号三个维度的业务量排名
- 双栏布局（趋势图 + Top 榜）

### 3.2 用户管理 `/admin/users`

- 用户列表：用户名、邮箱、注册时间、状态、角色、最近登录
- 新增用户
- 编辑用户（资料 / 角色 / 状态）
- 封禁 / 解锁账号
- **生成一次性密码重置码**（发给用户自助改密）
- 删除用户

### 3.3 角色权限 `/admin/roles`

- 角色列表与权限点矩阵
- 新建角色、自定义权限组合
- 细粒度权限点共 19 个，格式 `域:动作`（详见接口文档「1.6 权限点」）
- 管理员角色拥有通配权限 `*`

### 3.4 系统设置 `/admin/settings`

以下设置**改完立即生效，不用重启**：

`tushare_token`、`rate_limit_per_minute`、`token_expire_minutes`、
`login_max_failed`、`login_lock_minutes`、`webhook_timeout`、
`allow_registration`、`allow_mock_data`、`signal_push_enabled`、
`max_backtest_codes`、`max_backtest_days`、`auto_trade_enabled`、`allow_live_trade`

### 3.5 策略模板 `/admin/templates`

- 全部模板（含未公开的）
- 新建 / 修改 / 删除模板
- 模板包含完整策略参数，用户可一键套用

### 3.6 操作日志 `/admin/logs`

- 全量 API 请求 + 业务动作审计
- 记录字段：用户、IP、路径、方法、状态码、耗时、动作描述
- 支持筛选（用户 / 动作类型 / 时间范围 / 路径）
- **导出 CSV**

### 3.7 报错日志 `/admin/errors`

- 未捕获异常记录（**含完整堆栈**）
- 堆栈只入库，不返回客户端
- 清空 / 删除单条

### 3.8 缓存管理 `/admin/cache`

- 行情缓存统计与清理
- 验证码缓存清理
- 限流计数清理
- 分类独立清理，互不影响

### 3.9 IP 黑名单 `/admin/blacklist`

- 添加 / 移除黑名单 IP
- 支持过期时间
- 中间件层拦截，早于路由匹配

### 3.10 全站数据 `/admin/data`

三个子视图，均支持**用户名 / 状态筛选**：

- 全站回测记录
- 全站信号记录
- 全站订单

### 3.11 全站监控 `/admin/monitors`

- 所有用户的监控任务列表
- 调度器实时状态
- 管理员启停任意用户的监控任务

### 3.12 全站策略 `/admin/strategies`

- 所有用户的策略列表
- 策略名筛选
- 策略详情抽屉（含标的池标签）
- 管理员停用 / 恢复策略

> **管理员的权限边界**（刻意设计，不是功能缺失）：
> 只读为主，操作受限。管理员可以停用监控任务、停用策略，
> 但**不替用户改参数、不替用户删数据、不代用户下单** ——
> 参数错了会污染用户自己的回测记录，那是用户的配置，不该由管理员代劳。
> 停用策略不等于删除，策略与历史回测记录都保留，用户可随时恢复。
> 恢复策略时监控任务**不会**自动启动：监控开关归用户，
> 管理员替他打开会产生他没预期的推送。

---

## 四、产品官网

访问路径：`/`

纯静态站点，**无构建步骤**，**不含任何业务数据**。

- 首屏：产品定位、核心能力、架构示意、部署形态
- 功能介绍：量化核心、管理后台、信号推送、安全措施
- 界面预览：双主题截图
- 部署入口：链接到 `/docs/`
- 响应式布局 + 浅色/深色跟随系统
- 滚动动效：IntersectionObserver 渐入、指标数字滚动
- 顶栏导航 + 移动端抽屉

### 部署文档页 `/docs/`

10 章完整部署指南：

1. 方案概览（三端路径表）
2. 环境要求
3. 目录结构
4. 本地构建
5. 启动后端（含「必须 `--workers 1`」警示）
6. Nginx 配置（含 named location 说明）
7. 首次上线
8. 上线验证
9. 常见问题（6 个真实踩坑）
10. 版本升级

左侧目录随滚动高亮，移动端折叠为横向标签条。

---

## 五、量化核心能力

### 5.1 策略模型

双均线 + 波动率过滤，是一个**可解释的研究起点**。

| 维度 | 参数 |
|---|---|
| 信号 | 快慢均线周期（`fast_ma` / `slow_ma`） |
| 过滤 | 波动率窗口与阈值（`vol_window` / `vol_threshold`） |
| 标的 | 股票池，最多 50 只 |
| 区间 | 自定义回测起止时间 |
| 风控 | 单笔仓位上限、组合回撤止损线、连续亏损暂停阈值 |
| 成本 | 佣金（含最低佣金）、印花税（仅卖出）、滑点 |

### 5.2 回测引擎

- 同步执行（几十毫秒级），无需任务队列
- 输出：净值曲线、收益率、回撤、K 线买卖点、仓位变化、交易明细、分标的统计
- **账目守恒**是核心正确性判据：
  `最终权益 - 初始资金 - 已实现盈亏 ≈ 0`（浮点误差 < 0.1）

### 5.3 行情服务

- 数据源：tushare.pro（免费额度）
- 失败重试：指数退避（1.5s → 2.2s → …，最多 3 次）
- 缓存：命中后大幅提速，**缓存必须记来源**（见下）
- 无 token 时退化成本地合成数据，`data_source="mock"` 透传到前端并显著警示

### 5.4 信号与推送

- 扫描：定时任务，间隔最短 5 分钟，仅交易时段生效
- 去重：数据库唯一索引兜底，并发下不会重复
- 推送：QXBot Webhook，XML 卡片 / 纯文本两种格式
- 失败可手动重推

### 5.5 下单

| 模式 | 行为 |
|---|---|
| `paper` | 按最新行情价立即成交并记账，不涉及真实资金（**默认**） |
| `live` | 受三层开关控制，订单先进入 `pending`，需人工二次确认 |

**幂等去重**：去重窗口 10 秒，键里含 10 秒时间片。
查重要**同时看当前片 + 上一片**，否则跨片边界的重试会算出另一个键 → 重复下单。

---

## 六、安全体系

| 项目 | 实现 |
|---|---|
| 认证 | JWT（HS256），payload 不含 PII |
| 密码存储 | bcrypt cost=12，绝不明文 |
| SQL 注入 | 全项目零字符串拼接，全部走 ORM 参数绑定 |
| 越权防护 | `owned_query` 统一附加 owner 条件；`assert_owner` 校验单条记录归属；**越权返回 404 而非 403**，避免探测资源存在性 |
| 接口限流 | 滑动窗口，按 IP + 路由分组；登录 10 次/分、注册 5 次/分 |
| 验证码 | 一次性使用，恒定时间比较，防重放 |
| 账号锁定 | 连续失败 5 次锁定 15 分钟（可配） |
| IP 黑名单 | 中间件层拦截，支持过期时间 |
| 审计日志 | 所有 API 请求 + 业务动作，记录用户/IP/耗时/结果 |
| 异常处理 | **堆栈只入库，不返回客户端** |
| SSRF 防护 | Webhook 地址白名单校验，拒绝内网与云元数据地址 |
| 目录穿越 | 静态文件路径解析后校验是否在 dist 内 |
| 敏感配置 | tushare token、券商密码 AES 加密入库，接口只回显掩码 |
| 限流绕过防护 | Nginx `X-Forwarded-For` 用 `$remote_addr` **覆盖**而非追加 |

### 已知的安全设计取舍

1. **不开放邮件自助找回密码** —— 避免邮箱枚举。用管理员发放的一次性重置码替代。
2. **越权返回 404 而不是 403** —— 让攻击者无法区分「资源不存在」和「资源是别人的」。
3. **不实现券商实盘直连** —— A 股散户没有公开、合法、标准化的委托下单 API。
   平台只提供模拟撮合；live 模式仅解除前置检查，订单不会真的到达券商。

---

## 七、技术架构

### 7.1 技术栈

| 层 | 选型 |
|---|---|
| 后端 | FastAPI 0.115 + SQLAlchemy 2.0 + SQLite（WAL）+ Pydantic v2 + PyJWT + bcrypt |
| 前端 | Vue 3.5 + Element Plus 2.9 + ECharts 5.5 + Pinia + Vite 6 |
| 官网 | 原生 HTML + CSS + JS（无框架，无构建步骤） |
| 部署 | Nginx + systemd / Supervisor |

**刻意不用**：Celery/Redis（单机 SQLite 下队列是过度设计）、Pillow（验证码用标准库画 PNG）、
python-dotenv（自写 20 行解析器）、APScheduler（自写线程调度器）、官网前端框架。

### 7.2 数据模型

19 张表。核心表：

| 表 | 用途 |
|---|---|
| `users` / `roles` / `permissions` | 用户与 RBAC |
| `strategies` | 策略配置 |
| `backtest_runs` | 回测记录与报告 |
| `monitor_tasks` | 监控任务 |
| `signals` | 买卖信号 |
| `orders` | 订单 |
| `audit_logs` | 操作审计 |
| `error_logs` | 异常日志 |
| `market_cache` | 行情缓存 |

### 7.3 前端关键约定

| 约定 | 说明 |
|---|---|
| Vite `base` = Router `createWebHistory(base)` | 用户端 `/app/`，后台 `/admin/`。不一致时刷新深链接直接 404 |
| `resolve.dedupe` | 共享包在应用目录之外，强制依赖从应用根 `node_modules` 解析 |
| 跨应用跳转用整页导航 | `window.location.href`，不能用 `router.push` |
| 路径常量集中管理 | `frontend-shared/src/config/paths.js`，不硬编码 |
| 主题令牌双主题都要定义 | `--q-*` 只在 `html.dark` 定义会导致浅色下整条 CSS 声明作废 |
| 触摸目标尺寸 | small 控件桌面端 ≥28px，移动端 ≥32px |

### 7.4 Nginx 三端分流（三个必踩的坑）

1. **`try_files` 的 fallback 参数会被重新做一次 location 匹配** ——
   `/index.html` 会命中官网 root，必须改用 named location。
2. **`location = /app/` 要单独处理** —— 通用段的 `rewrite` 对 `/app/` 得 `$uri` = `/`，
   触发 `index` 指令时 location 上下文已丢失。
3. **外层 `^~` 时嵌套的正则 location 永不命中** —— 静态资源要用更长的独立前缀 location。

完整配置见 `deploy/nginx.conf`（已在生产验证）。

---

## 八、测试基线

| 脚本 | 项数 | 覆盖 |
|---|---|---|
| `backend/tests/smoke_test.py` | **143** | 鉴权、越权、参数校验、SQL 注入、SSRF、限流、回测引擎、信号去重、RBAC、审计导出、下单边界、后台写操作、三端静态回落 |
| `backend/tests/idempotency_test.py` | 5 | 订单幂等去重跨片边界 |
| `deploy/verify_deployment.py` | **82** | 直连后端，业务逻辑 + 三端静态资源 + 敏感文件防护 |
| `deploy/verify_domain.py` | **59** | 走真实域名，证书 / 跳转 / 三端分流 / API 转发 / 安全防护 |
| `frontend/tests/theme-responsive.prod.cjs` | 27 | 双主题 + 响应式，19 个页面无溢出无 JS 报错 |
| `frontend/tests/admin-new-features.prod.cjs` | 20 | 后台概览趋势图与 Top 榜、全站监控、全站策略 |
| `frontend/tests/click-audit.prod.cjs` | 87 按钮实点 | 逐页逐按钮真点，找出「点了没反应」 |
| `frontend/tests/split-e2e.test.cjs` | 27 | 三端拆分后路由分流、鉴权守卫、跨应用跳转 |
| `frontend/tests/mobile-layout.test.cjs` | 88 | 4 视口 × 22 页面的排版检查 |

**接口总量**：88 个接口 / 71 个路径（详见 [接口文档](api.md)）

---

## 九、产品边界

### 9.1 引擎层面的建模缺陷

| 缺陷 | 影响 | 严重程度 |
|---|---|---|
| **不处理涨跌停** | 主板 ±10%、创业板/科创板 ±20%。一字板时真实市场根本买不进卖不出，引擎仍按可成交处理，显著高估收益 | 高 |
| **不模拟流动性冲击** | 大资金买入会推高价格。引擎按固定滑点估算，忽略成交量对价格的冲击。小盘股上偏差尤其大 | 高 |
| **不处理停牌退市** | 停牌期间无法交易，退市造成本金永久损失。引擎均未覆盖 | 中 |
| **分红送转仅近似** | 用后复权价近似，但实际税费、除权日跳空对策略的影响未精确建模 | 低 |
| **T+1 撮合简化** | 用「前一日信号 + 当日开盘价」成交。实际开盘可能直接涨停，无法买入 | 中 |
| **不考虑交易门槛** | 科创板需 50 万资产 + 2 年经验，创业板需 10 万 + 2 年。引擎不做资格校验 | 低 |

### 9.2 策略本身的局限

**双均线 + 波动率过滤**是一个**可解释的研究起点**，不是一个能稳定盈利的策略。

1. **震荡市反复挨刀** —— 横盘震荡中产生大量假信号，来回被止损。
2. **趋势市吃不到头尾** —— 均线是滞后指标，只能吃到趋势中段。
3. **参数过拟合陷阱** —— 反复调参直到曲线漂亮，本质是拟合历史噪声。
4. **单一技术指标的天花板** —— 不含基本面、资金面、情绪面信息。
5. **股票池选择偏差** —— 手工填标的，只挑「现在涨得好」的结果必然好看但无意义。
6. **成本被低估** —— 默认参数下单次往返约 0.35%，年换手 20 次吃掉约 7% 收益。

### 9.3 合规与风险

- 本平台**不构成投资建议**，是技术研究与策略学习工具。
- 回测结果系统性偏乐观，真实交易通常**显著劣于**回测。
- 行情数据来自第三方或本地合成，可能缺失、延迟、复权错误，平台不做数据质量担保。
- 信号可能延迟或丢失（扫描间隔最短 5 分钟，Webhook 依赖第三方服务）。
- 未配置 tushare token 时使用合成数据，**任何指标都毫无意义**。
- 使用本平台产生的任何行为由使用者自行承担全部法律责任。

**如果你不能接受以上任何一条，请不要使用本平台。**

---

## 相关文档

- [接口文档](/docs/api/) —— 88 个接口的完整说明
- [部署文档](/docs/) —— 私有化部署完整指南
- [项目 README](https://github.com/) —— 开发者视角的完整说明（见仓库根目录 `README.md`）