sanguo_vnpy_v2/docs/spec_quant_terminal_redesign.md

# 三国量化研究台 · 终端化重构 Spec

> 范围：前端视觉/功能改造 + 后端引擎适配 + 模拟实盘功能改造
> 制定：前后端 session · 2026-08-12 · 状态：**待评审**

---

## 1. 背景与目标

**现状**：功能骨架齐全（回测/组合/优化/因子/模拟/实盘/Dashboard），视觉停留在 GitHub Dark 工具风——信息密度低、无命令面板、分析深度停在 P0 基线、组合策略只回测得了跑不了模拟实盘。

**目标**：重做为科幻量化终端（深空黑+荧光青+琥珀），对标 Bloomberg/Wind 终端 UX + QuantConnect 分析深度，组合策略贯通 backtest→paper→live。

**三大改造**：
1. 前端终端化（视觉 + 功能补齐 + 多面板）
2. 组合策略引擎贯通模拟/实盘（适配层接入）
3. 模拟实盘功能完善（组合/多账户/多策略同账户）

---

## 2. 核心原则（不可违背）

| # | 原则 | 说明 |
|---|------|------|
| **P1** | **vnpy 是适配不是改造** | `vnpy_v4.4.0/` 为上游源码，**零改动**；CTA 侧通过子类化适配层（`ashare_engine.py` 模式）扩展。验收：`git diff vnpy_v4.4.0/` 恒为空 |
| **P2** | **组合策略为主线** | 选股+择时+调仓+风控一体（bullet_trade 聚宽风格）是产品重心；未来加 AI 辅助、多策略同账户 |
| **P3** | **CTA 不淡化** | 所有功能 CTA/组合都做，CTA 优先级靠后。关注同功能下两者实现分歧，一套代码覆盖优先 |
| **P4** | **miniQMT 只管交易** | 下单通道与策略引擎解耦，CTA/组合共用 QMT；策略差异在引擎层不在 QMT 层 |
| **P5** | **自研可改、上游只适配** | `bullet_trade`/`sanguo_trader`/`sanguo_live`/`sanguo_qmt_bridge` 是自研可改；vnpy 是上游只适配 |

---

## 3. 现状基线（改造起点）

### 3.1 引擎层
| 引擎 | 归属 | backtest | paper 模拟 | live 实盘 |
|------|------|:---:|:---:|:---:|
| vnpy CTA（ashare_engine 适配） | 上游·只适配 | ✅ | ✅ per-symbol | ✅ 单标的 |
| bullet_trade 组合 | 自研·可改 | ✅ | ❌ | runner_live 有 / **web 接入层缺** |
| sanguo_trader 自研撮合 | 自研·可改 | — | paper 用 | — |
| sanguo_qmt_bridge | 自研·可改 | — | — | QMT 下单通道（共用） |

### 3.2 前端层
- 回测：New/Progress/Result/History/Optimize/PortfolioBacktest
- 模拟：paper(New/List/Result/Live) · live(New/List/Monitor)
- 设计系统已变量化（CSS tokens + `echartsDark`）→ 换肤友好

### 3.3 模拟实盘 3 种运行方式
| 方式 | 引擎 | 数据源 | 撮合 | 策略范式 |
|------|------|--------|------|---------|
| ① paper-replay 回放 | 自研撮合 | 历史 parquet | 快速重放·立即出结果 | CTA per-symbol（+组合待加）|
| ② paper-live 实走 | 自研撮合 | 日终 parquet | 每日定时 step·checkpoint 续跑 | CTA（+组合待加）|
| ③ live-miniQMT 实盘模拟 | QMT 直连 | QMT 实时行情 | 券商模拟账户真实下单 | CTA 单标的（+组合 runner_live 待接入）|

---

## 4. 前端改造

### 4.1 视觉语言（科幻终端）
- **色板**：深空黑 `#05080d` + 荧光青 `#00e5ff`（主强调）+ 琥珀 `#ffb000`（数据高亮）+ 红涨 `#ff4d5e`/绿跌 `#2ee68a`
- **字体**：等宽数据字体（全局 `tabular-nums`）+ 无衬线正文
- **元素**：1px 网格底 / 信号灯（绿运行·琥警告·红 critical）/ 扫描线 / 几何角标（无 emoji）/ 直角·2px 圆角
- **落地**：CSS 变量层换肤，不改 Element Plus 组件结构，全站一次性换肤
- **参考**：提案页 `docs/frontend_terminal_redesign_proposal.html`（已验证视觉）

### 4.2 功能补齐（回测结果页，CTA+组合共用一套）
| 功能 | 优先级 | 说明 |
|------|:---:|------|
| 月度收益热力图 / 每日收益柱状 / 回撤 Top5 / 收益分布 | P0 | QuantConnect 标杆 |
| 指标卡补齐：胜率/盈亏比/换手率/PSR | P0 | 现 11 项缺这 4 个 |
| 净值图超额线 + brush 缩放 | P0 | 现仅策略+基准两线 |
| 克隆重跑 / 导出报告(Excel/PDF) | P0 | 效率闭环 |
| Cmd+K 命令面板 / 所有表导出 | P0 | 终端 UX 共识 |
| 多回测对比页 / Rolling Sharpe·Beta | P1 | 差异化 |
| 参数优化热力图·3D 曲面 / 选股→回测→归因闭环 | P1 | vnpy 只有表格，超越 |
| Crisis Events 压力测试 | P1 | QuantConnect 独占 |
| Brinson/Barra 归因 / 多面板可拖拽 / 股票智能补全 | P1 | 专业化 |
| AI 策略助手 / 无代码策略生成器 / 社区广场 / Bar Replay | P2 | 长期 |

### 4.3 页面改造
- **结果页**：单列堆叠 → 多面板终端布局（指标塔 + 主图 + 回撤 + 月度热力 + 持仓信号 + 交易 ticker），一屏高密度
- **模拟盘/实盘监控**：科幻风监控台（状态灯 + 实时净值 + 持仓 + 信号 + 告警 + 下次运行时刻）
- **多账户/多策略**：多账户管理列表 + 一账户多策略分策略展示
- **组合策略创建入口**：新建回测/模拟/实盘时能选组合策略 + 股票池（不只是 CTA 类名 + 单 symbol）

---

## 5. 后端改造（引擎适配层）

> 原则 P1/P5：vnpy 只适配不改源码；bullet_trade/sanguo_trader/sanguo_live/sanguo_qmt_bridge 自研可改

### 5.1 任务 A — 组合 paper 模拟
- **目标**：组合策略能跑模拟盘（replay 回放 + live 实走）
- **方案**：bullet_trade 接入 `sanguo_trader/matcher`（自研撮合），复用 paper 的 checkpoint / 跨日 pending 机制
- **vnpy**：不涉及（纯自研引擎链路）

### 5.2 任务 B — 组合 live 接入 web
- **现状**：`sanguo_portfolio/runner_live.py` 引擎就绪（bullet_trade `LiveEngine` + `QmtBroker` + AllWeather），但未接 web
- **方案**：
  - `sanguo_live/supervisor` 识别"组合账户"类型 → 起 bullet_trade `LiveEngine`（非 vnpy engine）
  - 新建 `sanguo_api/routes_portfolio_live`（创建/启停/监控组合实盘）
  - 前端组合实盘入口 + 监控台
- **下单**：复用 `QmtBroker`/miniQMT，**不碰 QMT 适配层**
- **vnpy**：不涉及

### 5.3 任务 C — 多策略同账户 + 多账户
- **多账户**：架构已支持（`live_accounts` 表每行一账户 + per-account `mini_path`）→ 多行记录 + 多 miniQMT 客户端实例；**待 VPS 实测**单机并行实例数
- **多策略同账户**：supervisor + engine 支持一账户多策略路由 + 资金/持仓隔离
- **前端**：多账户管理 + 一账户多策略视图

### 5.4 CTA 侧（适配层，不改造 vnpy）
- CTA paper/live 继续走 `ashare_engine` / vnpy 适配层
- 功能补齐（同组合）通过适配层扩展，**vnpy_v4.4.0 源码零改动**

### 5.5 CTA vs 组合实现分歧（评估）
| 功能 | 分歧 | 处理 |
|------|:---:|------|
| backtest | 小 | 各有引擎，已就绪 |
| paper 撮合 | 中 | 组合接 matcher |
| live web 接入 | 中 | 组合接 supervisor+routes |
| 下单通道 | 无 | 共用 miniQMT |
| 结果分析/监控/导出 | 无 | **一套组件 CTA+组合共用**（P5 一套优先）|

---

## 6. 模拟实盘功能改造目标

| 目标 | 现状 | 改造后 |
|------|------|--------|
| 组合策略跑模拟 | ❌ | ✅ paper-replay + paper-live |
| 组合策略跑实盘 | runner_live 有、未接 web | ✅ web 创建/启停/监控 |
| 多账户 | 架构支持、未暴露 | ✅ 多账户管理 UI |
| 多策略同账户 | ❌ | ✅ 一账户多策略 + 隔离 |
| 监控视觉 | 朴素 | 科幻风监控台 |
| 结果分析 | 基础 | 复用回测深度（月度/归因/Top5）|

---

## 7. 路线图

| Sprint | 内容 | 风险 | 优先级 |
|--------|------|------|--------|
| **S1** 视觉层 | CSS 变量换肤全站 + 结果页科幻样板 | 低 | 即时 |
| **S2** 结果页重构 + P0 功能 | 多面板布局 + 月度/Top5/每日收益 + 指标补齐 + 克隆/导出/Cmd+K | 中 | 高 |
| **S2.5** 策略管理 | 菜单重构(策略+账户两组) + 策略配置CRUD(类+参数+标的 命名预设) + 策略在线代码编辑(Monaco+热重载) | 中 | 高·已启动 |
| **S3** 组合贯通模拟实盘 | 任务 A（组合 paper）+ B（组合 live 接 web）+ C（多账户/多策略前端）| 中高 | 高（组合主线）|
| **S4** P1 差异化 | 多回测对比 + Rolling + 优化可视化 + 选股闭环 + Crisis + 归因 + 多面板拖拽 | 中 | 中 |
| **S5** P2 选型 | AI 助手 + 无代码策略 + 社区 + Bar Replay | 高 | 长期 |
| CTA 并行 | 各 Sprint CTA 侧同步（适配层），优先级靠后 | — | P3 靠后 |

---

## 8. 职责与依赖

| Session | 职责 |
|---------|------|
| **前后端**（本 session）| 前端全部 + 后端引擎适配（A/B/C）+ CTA 适配层 + Spec/路线图 |
| 数据 | 组合策略所需数据/因子（归因数据、风格因子）|
| 策略 | 策略逻辑（all_weather 等 bullet_trade 策略本身）|
| 基建 | CI/CD/部署（commit 标 [vps]/[nas]，NAS 自动/VPS dispatch）|

> 引擎改造归属已记 memory：`portfolio-engine-paper-live-ownership.md`（防职责混淆）

---

## 9. 验收标准

- **视觉**：全站科幻终端风；结果页一屏多面板（对标提案 mockup）
- **功能**：P0 全齐；CTA 与组合共用一套结果分析组件
- **组合贯通**：组合策略能 backtest → paper(replay+live) → live(miniQMT) 全链路
- **模拟实盘**：3 种方式都支持组合 + 多账户 + 多策略同账户
- **原则 P1**：`git diff vnpy_v4.4.0/` 恒空（vnpy 零改动）
- **CTA**：功能不退化，同组合功能，优先级靠后

---

## 10. 待评审决策点

1. spec 整体方向认可吗？ ——>认可
3. S1 先做（视觉换肤 + 结果页样板）作为第一步？ -> 没问题，所有页面都给我一个样板，假的数据带页面跳转即可
4. 多账户多 miniQMT 实例数 → 安排 VPS 实测时机？-> 作为一个长期todu就行，现在不需要
5. 归因（Brinson/Barra）放 S4，还是要提前（依赖数据 session 的风格因子数据）？ -> 可以放s4

---

## 11. 菜单结构（2026-08-12 定稿）

> 用户决策：在现有 5 组基础上加「策略」「账户」两组，最小破坏现有分组。

```
工作台
策略            ← 新增
  ├ 策略库          策略配置 CRUD（列表/新建/编辑/删除）
  ├ 新建策略
  └ 代码编辑        策略在线代码编辑（Monaco）
回测
  ├ 新建回测 / ├ 组合回测 / ├ 参数优化 / └ 历史任务
投研
  └ 因子分析
模拟
  ├ 模拟盘列表 / └ 新建模拟盘
实盘模拟
  ├ 实盘列表 / └ 新建实盘
账户            ← 新增（多账户/多 miniQMT 统一视图）
```

## 12. 策略管理（2026-08-12 增补）

两层管理，对象与工作量不同：

### 12.1 策略配置 CRUD（参数层）
- **对象**：策略类 + 参数 + 标的/池 + 基准 的命名预设（如"茅台双均线(10,30)"）
- **痛点**：当前每次回测/模拟现选现填、跑完即丢；CRUD 让配置可命名/复用/一键发起回测·模拟·实盘
- **后端**：`strategies` 表(id/name/strategy_class/params JSON/symbol_or_pool/benchmark/interval/remark/created_at) + 5 路由(list/create/update/delete/duplicate)，复用 strategy_registry 校验类名。**纯自研，不碰 vnpy**
- **前端**：策略库列表(卡片) + 新建/编辑表单(选类自动载入参数) + 各 New 页"从已存策略载入"
- **工作量**：~1-2 天 ｜ **状态**：✅ 前端完成(mock) / ⏳ 后端待做(task16)

### 12.2 策略在线代码编辑（代码层）
- **对象**：策略 Python 代码本身（.py 文件）
- **边界（P1 原则）**：只编辑**自研策略**（`sanguo_trader/strategy`、`sanguo_portfolio/strategies`、`sanguo_live/strategies`）；**不编辑 vnpy 上游包**（`vnpy_ctastrategy/strategies` 属适配不改造红线）
- **方案**：Monaco Editor（VSCode 同款）+ 文件树 + 语法校验(py_compile) + 保存 + 模板新建
- **架构利好**：回测走 ProcessPool spawn（每次新进程）→ 改完代码下次回测自动加载最新，**天然热重载**，无需处理 Python reload 缓存
- **安全**：单用户内部研究台，`py_compile` 校验 + 进程超时 + ProcessPool 隔离崩溃即可，不需沙箱
- **层次**：①只读查看(~0.5天) / ②**在线编辑**⭐(~2.5-3天) / ③无代码生成(~1-2周·P2)
- **工作量(②)**：Monaco 集成 ~1.5天 + 后端文件 CRUD ~0.5天 + registry 扩展扫描自研目录 + 模板 ~1天
- **状态**：📋 本轮先做前端原型（Monaco mock）供体验，后端待体验后定

### 12.3 决策记录
- 策略 CRUD 对象 = **策略配置实例**（非代码类）✅
- 菜单 = 加「策略」「账户」两组（保留现有分组）✅
- 在线编辑 = 先前端原型体验，再定是否上后端
- 多账户多 miniQMT 实例数实测 = 长期 todo（不阻塞）

### 12.4 业界调研结论（2026-08-12 · 7 平台 agent 调研）

调研聚宽/米筐/掘金/QuantConnect/Quantopian/Alpaca/VnPy，核心结论：

1. **策略 = 代码**（6/7 一致，Alpaca 无策略层）。本轮"策略=代码"重做方向正确。
2. **"先建策略 → 再发起回测/模拟/实盘"是唯一主流模式**（6/6）。回测/模拟/实盘是策略的运行模式，不是独立顶层对象。没有一家用"回测页直接填配置"。
3. **🔑 两层模型（VnPy 范式，推荐采纳）**：策略类（代码）+ 策略实例（`setting` 参数 dict）。
   - 顶层 = 策略类列表（从 strategies/ 自动发现）
   - 二级 = 该类下的实例（每组参数 + 标的/池 = 一个实例，VnPy `strategy_name`）
   - 每实例一键：回测 / 模拟 / 实盘
   - **这正是"编辑策略=编辑参数"纠结的正解**：参数属于"实例"，不属于"策略代码"，也不该独立叫"策略"
4. **新建策略分流**：业界按**资产类别**（股票/期货/加密）分流，不按组合/CTA。本项目按"组合/CTA 范式"分流（A股组合 vs CTA 差异大），是合理的本地化，保留。
5. **参数归属**：策略专用参数（快慢线/持仓数）绑策略类（`parameters=[]` 反射生成 UI 输入框）；回测运行配置（日期/资金/基准/频率/滑点/手续费）独立，每次可改。

**组合策略 UI 配置项清单**（业界共识）：
- 实例参数层：选股池/Universe、调仓周期（日/周/月）、持仓数 Top-N、仓位算法（等权/风险平价）、风控（止损%/止盈%/单标的最大仓位%）、策略专用参数（反射 `parameters`）
- 运行配置层：初始资金、起止日期、基准、频率、滑点、手续费
- 不配置化（留代码）：选股逻辑、因子计算、下单触发条件

**修正**：当前重做（S2.5）只做了"策略类（代码）"第一层；应补**"策略实例"第二层**（策略类下创建多组参数实例，每实例一键回测/模拟/实盘）。待用户确认后补。

### 12.5 最终落地设计（2026-08-12 定稿 · 已实现前端 mock）

策略管理「三层 + 4 运行全生命周期」：

```
策略代码（.py · 编辑代码）
  └ 策略实例（参数变体 + 标的/池）
      ├ [回测]       历史全量 · 秒出 · 验证逻辑
      ├ [模拟·回放]  历史 parquet · 快速重放 · 验证撮合/滑点
      ├ [模拟·实走]  日终 parquet · 每日推进+断点续跑 · 模拟真实节奏
      └ [实盘]       miniQMT · 真下单（券商模拟/真账户）
```

**命名定稿**（消除撞名）：
- 回测（不变）
- 模拟盘 = 原"模拟"（自研撮合，**不走 QMT**），内含 回放/实走 两 mode
- 实盘 = 原"实盘模拟"（**miniQMT 真下单**；"实盘模拟"撞名已删）

**菜单最终**：工作台 / 策略(策略库·新建策略·代码编辑) / 回测 / 投研 / 模拟盘 / 实盘 / 账户

**策略库 UI**（已实现）：按策略代码分组，每组下列实例；每实例一行 = 参数摘要 + 标的/池 + 最近收益 + 4 运行状态灯(已测/运行/已停/—) + 一键发起按钮。代码无实例时提示"编辑代码后可创建"。

业界「策略=代码+实例」两层 + 「先建策略→再发起运行」模式，全部落地。后端待补：策略代码文件 CRUD + 实例 CRUD + 各运行入口接实例参数。

## 13. 撮合机制与回放设计（2026-08-12 定稿）

### 13.1 撮合频率原则（理论硬约束）
**撮合频率 = 策略决策频率**。撮合 < 决策频率 → 丢信号 + 价格失真。业界（聚宽 run_minute / vnpy on_bar / backtrader cerebro）均逐 bar 撮合，**没有"统一日级"的设计**。

用户选 3 样，撮合频率由它们推导，**不独立选**（避免矛盾配置如"15m策略+日终撮合"）：
- **interval**（数据频率 d/15m）— 决定决策频率
- **match_session**（撮合时点：开盘价/收盘价/集合竞价）
- **运行模式**（回测/回放/实走/实盘）

### 13.2 撮合频率 = interval × 运行模式
| 运行模式 | 撮合频率 | 适合策略 |
|---------|---------|---------|
| 回测 / 回放 | = interval（逐历史 bar）| 全频率 |
| paper 实走 | **固定日级**（日终一次）| **只日线** |
| 实盘（miniQMT）| **实时**（行情驱动）| 全频率（含分钟盘中）|

**两路分工**：日线策略 → paper 实走（日终低成本模拟）；分钟策略 → miniQMT 实盘（盘中实时）。paper 实走为日线设计，分钟策略不该迁就它。**UI 校验**：分钟策略(interval=15m) + paper 实走 = 不匹配，提示引导到 实盘/回放。

### 13.3 回放设计
回放 = 历史数据按选定 interval **逐根 K 线快速重放 + 自研 A 股撮合**。
- **精度 = interval**：日线 = 每天 1 撮合点；15m = 每天 ~16 点（每根 15m bar 撮合）。**选 interval 即选撮合频率**。
- **逐 bar 流程**：撮合上根 pending → 喂 `on_bar` 算信号 → 新单按 match_session 当根/下根撮合 → 记账 + 涨跌停封板/最小手数/滑点/费率/T+1 校验。
- **速度**：本地历史毫秒级/根，一段历史秒~分钟跑完，立即出结果。
- **vs 回测**：回放用自研 A 股精细撮合（封板/集合竞价/滑点/T+1），比 vnpy 回测更贴近实盘真实发生。
- **数据精度**：当前支持 **d / 15m**（baostock 5.5 年 15m）；**1m / 5m 待数据源补齐后扩展**。

### 13.4 标的 / 池控件（按策略 type）
- **CTA（单标的）**：股票代码输入框 + 智能补全
- **组合**：**池选择框**（沪深300 / 中证500 / 中证1000 / 中证2000 / 全市场 / 自定义成分），不手输