Compare commits
1 Commits
feature/st
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
b1ed55382c |
265
docs/arbitrage-engine/v54-requirements.md
Normal file
265
docs/arbitrage-engine/v54-requirements.md
Normal file
@ -0,0 +1,265 @@
|
||||
# V5.4 Strategy Factory 需求文档
|
||||
|
||||
**版本**：v1.0
|
||||
**日期**：2026-03-11
|
||||
**作者**：露露
|
||||
**状态**：待范总 + 小范 Review
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
当前系统（V5.3）使用单体 `signal_engine.py`，所有策略逻辑耦合在一起，存在以下问题：
|
||||
|
||||
- 修改任意策略参数需重启整个引擎，中断数据采集
|
||||
- 不同策略无法独立运行和对比，A/B 测试成本高
|
||||
- 参数配置分散在 JSON 文件中，无法通过前端界面管理
|
||||
- 无法按币种独立优化权重
|
||||
|
||||
V5.4 目标：构建 **Strategy Factory（策略工厂）**，将信号引擎解耦为数据总线 + 独立策略 Worker，支持前端可视化管理策略生命周期和参数配置。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心架构
|
||||
|
||||
### 2.1 整体架构
|
||||
|
||||
```
|
||||
Signal Engine（数据总线）
|
||||
├── 采集原始数据（aggTrades / OBI / 清算 / 市场数据）
|
||||
├── 计算基础 Feature（CVD / ATR / VWAP / whale flow / OBI / spot-perp div）
|
||||
└── 广播 feature_event（每15秒一次）
|
||||
|
||||
Strategy Workers（策略工厂）
|
||||
├── Worker-1：我的BTC策略01（BTCUSDT，asyncio协程）
|
||||
├── Worker-2：我的ETH策略01（ETHUSDT，asyncio协程）
|
||||
├── Worker-N：...
|
||||
└── 每个 Worker 订阅 feature_event，独立打分、开仓、管仓
|
||||
```
|
||||
|
||||
### 2.2 关键设计原则
|
||||
|
||||
- **同一进程 + asyncio 协程**：所有 Worker 共享同一 Python 进程，feature_event 内存传递，省资源
|
||||
- **独立资金池**：每个 Worker 有独立的 paper trading 余额，互不影响
|
||||
- **15秒内热生效**：前端修改参数后，Worker 在下一个评估周期（≤15秒）自动从 DB 读取新参数
|
||||
- **配置存 DB**：所有策略配置存入数据库，JSON 文件废弃
|
||||
- **直接切换**：V5.4 上线后直接替换 V5.3 单体，不并行
|
||||
|
||||
---
|
||||
|
||||
## 3. 策略生命周期
|
||||
|
||||
### 3.1 状态定义
|
||||
|
||||
```
|
||||
created（已创建）→ running（运行中）→ paused（已暂停）→ running
|
||||
↓
|
||||
deprecated（已废弃）→ running（重新启用）
|
||||
```
|
||||
|
||||
- **只有「废弃」，没有「删除」**
|
||||
- 废弃的策略数据永久保留，可在废弃列表中检索
|
||||
- 废弃策略可重新启用，继续使用原有余额和历史数据
|
||||
|
||||
### 3.2 策略标识
|
||||
|
||||
- 用户填写**显示名称**（自由命名，如"我的BTC激进策略"）
|
||||
- 后台自动生成**UUID**作为唯一标识，用户不感知
|
||||
- `paper_trades` 等表通过 strategy_id（UUID）关联
|
||||
|
||||
### 3.3 余额管理
|
||||
|
||||
- 创建时设置初始资金（默认 10,000 USDT）
|
||||
- 支持**追加余额**：追加后，`initial_balance` 同步增加，`current_balance` 同步增加
|
||||
- 废弃后重新启用，继续使用废弃时的余额和历史数据
|
||||
|
||||
---
|
||||
|
||||
## 4. 策略配置参数
|
||||
|
||||
每个策略实例（每个币种独立）包含以下可配置参数，均存入数据库，前端可编辑。
|
||||
|
||||
### 4.1 基础信息
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 | 范围 |
|
||||
|------|------|------|--------|------|
|
||||
| display_name | 策略显示名称 | string | — | 1-50字符 |
|
||||
| symbol | 交易对 | enum | BTCUSDT | BTCUSDT / ETHUSDT / SOLUSDT / XRPUSDT |
|
||||
| direction | 交易方向 | enum | both | long_only / short_only / both |
|
||||
| initial_balance | 初始资金(USDT) | float | 10000 | 1000-1000000 |
|
||||
|
||||
### 4.2 CVD 窗口配置
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 | 可选项 |
|
||||
|------|------|------|--------|--------|
|
||||
| cvd_fast_window | 快线CVD窗口 | enum | 30m | 5m / 15m / 30m |
|
||||
| cvd_slow_window | 慢线CVD窗口 | enum | 4h | 1h / 4h |
|
||||
|
||||
### 4.3 四层权重（合计必须 = 100）
|
||||
|
||||
| 参数 | 说明 | 默认值 | 范围 |
|
||||
|------|------|--------|------|
|
||||
| weight_direction | 方向得分权重 | 55 | 10-80 |
|
||||
| weight_env | 环境得分权重 | 25 | 5-60 |
|
||||
| weight_aux | 辅助因子权重 | 15 | 0-40 |
|
||||
| weight_momentum | 动量权重 | 5 | 0-20 |
|
||||
|
||||
> 前端校验：四项之和必须 = 100，否则不允许保存
|
||||
|
||||
### 4.4 入场阈值
|
||||
|
||||
| 参数 | 说明 | 默认值 | 范围 |
|
||||
|------|------|--------|------|
|
||||
| entry_score | 入场最低总分 | 75 | 60-95 |
|
||||
|
||||
### 4.5 四道 Gate（过滤门）
|
||||
|
||||
每道 Gate 有独立开关和阈值：
|
||||
|
||||
| Gate | 说明 | 开关默认 | 阈值参数 | 默认值 | 范围 |
|
||||
|------|------|----------|----------|--------|------|
|
||||
| gate_obi | 订单簿失衡门 | ON | obi_threshold | 0.3 | 0.1-0.9 |
|
||||
| gate_whale_cvd | 大单CVD门 | ON | whale_cvd_threshold | 0.0 | -1.0-1.0 |
|
||||
| gate_vol_atr | 波动率ATR门 | ON | atr_percentile_min | 20 | 5-80 |
|
||||
| gate_spot_perp | 现货/永续溢价门 | OFF | spot_perp_threshold | 0.002 | 0.0005-0.01 |
|
||||
|
||||
### 4.6 风控参数
|
||||
|
||||
| 参数 | 说明 | 默认值 | 范围 |
|
||||
|------|------|--------|------|
|
||||
| sl_atr_multiplier | SL宽度（×ATR） | 1.5 | 0.5-3.0 |
|
||||
| tp1_ratio | TP1（×RD） | 0.75 | 0.3-2.0 |
|
||||
| tp2_ratio | TP2（×RD） | 1.5 | 0.5-4.0 |
|
||||
| timeout_minutes | 持仓超时(分钟) | 240 | 30-1440 |
|
||||
| flip_threshold | 反转平仓阈值(分) | 80 | 60-95 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端功能需求
|
||||
|
||||
### 5.1 策略广场列表页（已有基础，新增以下）
|
||||
|
||||
- **右上角「+ 新增策略」按钮**：点击进入参数配置创建界面
|
||||
- **每个卡片新增「调整参数」按钮**：点击进入参数配置编辑界面（预填当前参数）
|
||||
- **每个卡片新增「废弃」按钮**：点击弹出二次确认，确认后策略进入废弃状态
|
||||
- **每个卡片新增「追加余额」功能**：输入追加金额，确认后更新余额
|
||||
|
||||
### 5.2 参数配置界面（新建/编辑共用）
|
||||
|
||||
- 基础信息：名称、币种、交易方向、初始资金
|
||||
- CVD窗口：快线/慢线各独立选择
|
||||
- 四层权重：滑块或数字输入，实时显示合计，合计≠100时禁止保存
|
||||
- 四道Gate：开关 + 阈值输入，各有说明文字和合理范围提示
|
||||
- 风控参数：数字输入，有最小/最大值限制
|
||||
- 底部：「保存并启动」（新建）/ 「保存」（编辑）按钮
|
||||
|
||||
### 5.3 策略详情页（已有基础，新增以下）
|
||||
|
||||
- 新增第三个 Tab：**「参数配置」**
|
||||
- 展示当前所有参数，可点击编辑跳转到编辑界面
|
||||
|
||||
### 5.4 侧边栏新增入口
|
||||
|
||||
- **「废弃策略」**：点击进入废弃策略列表
|
||||
- 展示格式与正常卡片相同，额外显示废弃时间
|
||||
- 每个废弃策略有「重新启用」按钮
|
||||
- 重新启用后恢复至运行中状态，继续原余额和数据
|
||||
|
||||
### 5.5 权限
|
||||
|
||||
- 所有页面需登录才能访问（复用现有 JWT）
|
||||
- 登录后有全部操作权限，无角色区分
|
||||
|
||||
---
|
||||
|
||||
## 6. 后端架构需求
|
||||
|
||||
### 6.1 数据库新增表
|
||||
|
||||
**`strategies` 表**（策略配置主表）：
|
||||
```sql
|
||||
strategy_id UUID PRIMARY KEY
|
||||
display_name TEXT NOT NULL
|
||||
symbol TEXT NOT NULL
|
||||
direction TEXT NOT NULL DEFAULT 'both'
|
||||
status TEXT NOT NULL DEFAULT 'running' -- running/paused/deprecated
|
||||
initial_balance FLOAT NOT NULL DEFAULT 10000
|
||||
current_balance FLOAT NOT NULL DEFAULT 10000
|
||||
cvd_fast_window TEXT NOT NULL DEFAULT '30m'
|
||||
cvd_slow_window TEXT NOT NULL DEFAULT '4h'
|
||||
weight_direction INT NOT NULL DEFAULT 55
|
||||
weight_env INT NOT NULL DEFAULT 25
|
||||
weight_aux INT NOT NULL DEFAULT 15
|
||||
weight_momentum INT NOT NULL DEFAULT 5
|
||||
entry_score INT NOT NULL DEFAULT 75
|
||||
gate_obi_enabled BOOL NOT NULL DEFAULT TRUE
|
||||
obi_threshold FLOAT NOT NULL DEFAULT 0.3
|
||||
gate_whale_enabled BOOL NOT NULL DEFAULT TRUE
|
||||
whale_cvd_threshold FLOAT NOT NULL DEFAULT 0.0
|
||||
gate_vol_enabled BOOL NOT NULL DEFAULT TRUE
|
||||
atr_percentile_min INT NOT NULL DEFAULT 20
|
||||
gate_spot_perp_enabled BOOL NOT NULL DEFAULT FALSE
|
||||
spot_perp_threshold FLOAT NOT NULL DEFAULT 0.002
|
||||
sl_atr_multiplier FLOAT NOT NULL DEFAULT 1.5
|
||||
tp1_ratio FLOAT NOT NULL DEFAULT 0.75
|
||||
tp2_ratio FLOAT NOT NULL DEFAULT 1.5
|
||||
timeout_minutes INT NOT NULL DEFAULT 240
|
||||
flip_threshold INT NOT NULL DEFAULT 80
|
||||
deprecated_at TIMESTAMP
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
```
|
||||
|
||||
### 6.2 现有表调整
|
||||
|
||||
- `paper_trades`：`strategy` 字段改为存 `strategy_id`（UUID），兼容现有数据（v53/v53_middle/v53_fast 保留字符串形式）
|
||||
- `signal_indicators`：同上
|
||||
|
||||
### 6.3 API 新增端点
|
||||
|
||||
```
|
||||
POST /api/strategies 创建策略
|
||||
GET /api/strategies 获取所有策略列表（含废弃）
|
||||
GET /api/strategies/{id} 获取单个策略详情
|
||||
PATCH /api/strategies/{id} 更新策略参数
|
||||
POST /api/strategies/{id}/pause 暂停策略
|
||||
POST /api/strategies/{id}/resume 恢复策略
|
||||
POST /api/strategies/{id}/deprecate 废弃策略
|
||||
POST /api/strategies/{id}/restore 重新启用
|
||||
POST /api/strategies/{id}/add-balance 追加余额
|
||||
```
|
||||
|
||||
### 6.4 Signal Engine 改造
|
||||
|
||||
- Signal Engine 只负责 feature 计算和广播，不再包含评分/开仓逻辑
|
||||
- 每个 Strategy Worker 作为 asyncio 协程，订阅 feature_event
|
||||
- Worker 启动时从 DB 读取配置，每15秒评估时重新读取（捕获参数变更）
|
||||
|
||||
---
|
||||
|
||||
## 7. 迁移计划
|
||||
|
||||
V5.4 上线时：
|
||||
1. 将现有 v53、v53_middle、v53_fast 三个策略迁移为 `strategies` 表中的三条记录
|
||||
2. 历史 `paper_trades` 数据通过 strategy 名称映射到对应 strategy_id
|
||||
3. 直接切换，不保留 V5.3 单体并行
|
||||
|
||||
---
|
||||
|
||||
## 8. 不在本期范围内
|
||||
|
||||
- 实盘交易（本期只做 paper trading）
|
||||
- 多用户/多账户体系
|
||||
- 策略算法类型选择（本期只支持四层评分算法）
|
||||
- 自动化参数优化（Optuna 集成）
|
||||
|
||||
---
|
||||
|
||||
## 9. Review 检查清单
|
||||
|
||||
- [ ] 范总确认需求无遗漏
|
||||
- [ ] 小范审阅数据结构合理性
|
||||
- [ ] 确认 `strategies` 表字段完整性
|
||||
- [ ] 确认 API 端点覆盖所有前端操作
|
||||
- [ ] 确认迁移方案不丢失历史数据
|
||||
- [ ] 需求文档 Review 通过后，再开始写数据合约文档
|
||||
Loading…
Reference in New Issue
Block a user