diff --git a/docs/arbitrage-engine/v54-requirements.md b/docs/arbitrage-engine/v54-requirements.md new file mode 100644 index 0000000..ae076d4 --- /dev/null +++ b/docs/arbitrage-engine/v54-requirements.md @@ -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 通过后，再开始写数据合约文档