595 lines
24 KiB
Markdown
595 lines
24 KiB
Markdown
---
|
||
title: "Arbitrage Engine 完整项目规格文档"
|
||
---
|
||
# Arbitrage Engine — 完整项目规格文档
|
||
> 供 Codex 重写使用。描述现有系统的所有功能、界面、后端逻辑、数据库结构。
|
||
> 语言：精确、无歧义、面向 AI。
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
**项目名称**：ArbitrageEngine
|
||
**核心目标**：加密货币量化策略研究平台，通过实时信号引擎计算多因子评分，在模拟盘上验证策略表现，为未来实盘交易提供数据支撑。
|
||
**当前阶段**：模拟盘运行（paper trading），不连接真实资金。
|
||
**主要币种**：BTCUSDT、ETHUSDT、SOLUSDT、XRPUSDT（币安永续合约）
|
||
|
||
---
|
||
|
||
## 二、技术栈
|
||
|
||
### 后端
|
||
- **语言**：Python 3.11
|
||
- **框架**：FastAPI（异步 HTTP）
|
||
- **数据库**：PostgreSQL 18（GCP Cloud SQL，内网 IP 10.106.0.3，数据库名 arb_engine）
|
||
- **认证**：JWT（HS256，secret=`arb-engine-jwt-secret-v2-2026`）
|
||
- **进程管理**：PM2
|
||
- **WebSocket**：`websockets` 库，连接币安 WebSocket stream
|
||
|
||
### 前端
|
||
- **框架**：Next.js 14（App Router）
|
||
- **UI 组件**：shadcn/ui + Tailwind CSS + Radix UI + Lucide Icons
|
||
- **图表**：Recharts
|
||
- **主题**：默认暗色，主色 slate + cyan
|
||
- **HTTP 客户端**：fetch（原生）
|
||
|
||
### 基础设施
|
||
- **服务器**：GCP asia-northeast1-b，Ubuntu，Tailscale IP 100.105.186.73
|
||
- **Cloud SQL**：GCP，内网 10.106.0.3，公网 34.85.117.248，PostgreSQL 18
|
||
- **PM2 路径**：`/home/fzq1228/Projects/ops-dashboard/node_modules/pm2/bin/pm2`
|
||
- **项目路径**：`/home/fzq1228/Projects/arbitrage-engine/`
|
||
- **前端端口**：4333（arb-web）
|
||
- **后端端口**：4332（arb-api）
|
||
- **对外域名**：`https://arb.zhouyangclaw.com`
|
||
|
||
---
|
||
|
||
## 三、PM2 进程列表
|
||
|
||
| ID | 名称 | 职责 |
|
||
|----|------|------|
|
||
| 0 | arb-web | Next.js 前端，端口 4333 |
|
||
| 8 | arb-api | FastAPI 后端，端口 4332 |
|
||
| 9 | signal-engine | 核心信号引擎（Python，单进程事件循环） |
|
||
| 24 | agg-collector | 从币安 WebSocket 收集逐笔成交（agg_trades） |
|
||
| 25 | paper-monitor | 模拟盘实时止盈止损监控（WebSocket 价格推送） |
|
||
| 26 | liq-collector | 收集强平数据（liquidations 表） |
|
||
| 27 | market-collector | 收集市场指标（资金费率、OI、多空比等） |
|
||
| 28 | position-sync | 实盘持仓同步（暂不使用） |
|
||
| 29 | risk-guard | 风控守护进程 |
|
||
|
||
---
|
||
|
||
## 四、数据库完整结构
|
||
|
||
### 4.1 `strategies` — 策略配置表（V5.4 核心）
|
||
|
||
每行代表一个可独立运行的策略实例。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| strategy_id | uuid PK | 自动生成，全局唯一 |
|
||
| display_name | text | 展示名，如 `BTC_CVD15x1h_TP保守` |
|
||
| schema_version | int | 默认 1 |
|
||
| status | text | `running` / `paused` / `deprecated` |
|
||
| status_changed_at | timestamp | 状态变更时间 |
|
||
| last_run_at | timestamp | 最近一次信号评估时间 |
|
||
| deprecated_at | timestamp | 停用时间 |
|
||
| symbol | text | 交易对，如 `BTCUSDT` |
|
||
| direction | text | `long` / `short` / `both`（默认 both） |
|
||
| cvd_fast_window | text | CVD 快线窗口，如 `5m` / `15m` / `30m` |
|
||
| cvd_slow_window | text | CVD 慢线窗口，如 `30m` / `1h` / `4h` |
|
||
| weight_direction | int | 方向层权重（默认 55） |
|
||
| weight_env | int | 环境层权重（默认 25） |
|
||
| weight_aux | int | 辅助层权重（默认 15） |
|
||
| weight_momentum | int | 动量层权重（默认 5） |
|
||
| entry_score | int | 开仓最低分（默认 75） |
|
||
| gate_obi_enabled | bool | 是否启用 OBI 否决门 |
|
||
| obi_threshold | float | OBI 否决阈值（默认 0.3） |
|
||
| gate_whale_enabled | bool | 是否启用鲸鱼否决门 |
|
||
| whale_usd_threshold | float | 鲸鱼成交额阈值（默认 $50,000） |
|
||
| whale_flow_pct | float | 鲸鱼流向占比阈值 |
|
||
| gate_vol_enabled | bool | 是否启用波动率门 |
|
||
| vol_atr_pct_min | float | 最低 ATR/price 比例（默认 0.002） |
|
||
| gate_spot_perp_enabled | bool | 是否启用期现背离门 |
|
||
| spot_perp_threshold | float | 期现背离阈值（默认 0.002） |
|
||
| gate_cvd_enabled | bool | 是否启用 CVD 共振门 |
|
||
| sl_atr_multiplier | float | SL 宽度倍数，`risk_distance = sl_atr_multiplier × ATR`，定义 1R 的价格距离（默认 1.5） |
|
||
| tp1_ratio | float | TP1 目标，以 R 计：`TP1 距离 = tp1_ratio × risk_distance`（默认 0.75） |
|
||
| tp2_ratio | float | TP2 目标，以 R 计：`TP2 距离 = tp2_ratio × risk_distance`（默认 1.5） |
|
||
| timeout_minutes | int | 超时平仓分钟数（默认 240） |
|
||
| flip_threshold | int | 反向信号强制平仓的最低分（默认 80） |
|
||
| initial_balance | float | 初始模拟资金（默认 $10,000） |
|
||
| current_balance | float | 当前模拟余额 |
|
||
| description | text | 策略描述 |
|
||
| tags | text[] | 标签数组 |
|
||
| created_at | timestamp | 创建时间 |
|
||
| updated_at | timestamp | 更新时间 |
|
||
|
||
**已有的固定 UUID 策略（legacy，status=deprecated）**：
|
||
- `00000000-0000-0000-0000-000000000053` → v53 Standard（BTCUSDT+ETHUSDT+SOLUSDT+XRPUSDT，30m/4h）
|
||
- `00000000-0000-0000-0000-000000000054` → v53 Middle（全币种，15m/1h）
|
||
- `00000000-0000-0000-0000-000000000055` → v53 Fast（全币种，5m/30m）
|
||
|
||
**当前运行中策略（18个 BTC 对照组）**：
|
||
- 命名规则：`BTC_CVD{fast}x{slow}_TP{保守|平衡|激进}`
|
||
- 6个 CVD 组合 × 3个 TP 方案 = 18个策略
|
||
- symbol 全部 = `BTCUSDT`
|
||
- 权重统一：dir=38 / env=32 / aux=28 / mom=2 / entry_score=71
|
||
|
||
---
|
||
|
||
### 4.2 `paper_trades` — 模拟盘交易记录
|
||
|
||
每行代表一笔模拟交易（开仓→平仓）。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint PK | 自增 |
|
||
| symbol | text | 交易对 |
|
||
| direction | text | `LONG` / `SHORT` |
|
||
| score | int | 开仓时评分 |
|
||
| tier | text | `light` / `standard` / `heavy`（仓位档位） |
|
||
| entry_price | float | 开仓价格（实时成交价快照） |
|
||
| entry_ts | bigint | 开仓时间戳（毫秒） |
|
||
| exit_price | float | 平仓价格 |
|
||
| exit_ts | bigint | 平仓时间戳（毫秒） |
|
||
| tp1_price | float | 止盈1价格 |
|
||
| tp2_price | float | 止盈2价格 |
|
||
| sl_price | float | 止损价格 |
|
||
| tp1_hit | bool | 是否曾触及 TP1 |
|
||
| status | text | `active` / `tp1_hit` / `tp` / `sl` / `sl_be` / `timeout` / `signal_flip` |
|
||
| pnl_r | float | 盈亏（以 R 计，1R = SL 距离） |
|
||
| atr_at_entry | float | 开仓时 ATR 值 |
|
||
| score_factors | jsonb | 四层评分详情 |
|
||
| strategy | varchar | 策略名（如 `custom_62047807`） |
|
||
| risk_distance | float | 1R 对应的价格距离（= sl_atr_multiplier × ATR） |
|
||
| calc_version | int | 计算版本（1=VWAP，2=last_trade） |
|
||
| price_source | text | 价格来源 |
|
||
| strategy_id | uuid FK | 关联 strategies 表 |
|
||
| strategy_name_snapshot | text | 开仓时的策略展示名快照 |
|
||
|
||
**status 含义**：
|
||
- `active`：持仓中，尚未触及 TP1
|
||
- `tp1_hit`：已触及 TP1，移动止损到保本价
|
||
- `tp`：全仓止盈出场（同时触及 TP2，或手动）
|
||
- `sl`：止损出场（pnl_r = -1.0）
|
||
- `sl_be`：保本止损出场（pnl_r ≈ +0.5 × tp1_ratio，小正收益）
|
||
- `timeout`：持仓超时平仓（240分钟）
|
||
- `signal_flip`：反向信号强制平仓
|
||
|
||
**pnl_r 计算规则**（以价格距离除以 1R = risk_distance 为基准）：
|
||
- SL 触发：`pnl_r = -1.0`（恒定）
|
||
- TP1 触发后 SL_BE：`pnl_r = 0.5 × tp1_ratio`
|
||
- 全仓 TP2：`pnl_r = 0.5 × tp1_ratio + 0.5 × tp2_ratio`
|
||
- timeout/flip：`pnl_r = (exit_price - entry_price) / risk_distance`（LONG 方向，SHORT 取反）
|
||
- 实际实现中，以上结果再统一减去手续费折算：`fee_r = (2 × fee_rate × entry_price) / risk_distance`，当前 `fee_rate = 0.0005`（0.05% taker），即最终写入的 `pnl_r = 上述值 - fee_r`。
|
||
|
||
**胜率定义**（重要）：`pnl_r > 0` 的笔数 / 总闭仓笔数。不用 status 字段判断。
|
||
|
||
---
|
||
|
||
### 4.3 `signal_indicators` — 信号指标快照
|
||
|
||
每次信号引擎评估时写入一行，记录当时所有原始指标和评分结果。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint PK | 自增 |
|
||
| ts | bigint | 时间戳（毫秒） |
|
||
| symbol | text | 交易对 |
|
||
| cvd_fast | float | 旧字段：30m CVD（别名，实际=cvd_30m） |
|
||
| cvd_mid | float | 旧字段：4h CVD（别名，实际=cvd_4h） |
|
||
| cvd_day | float | 24h CVD |
|
||
| cvd_fast_slope | float | CVD 快线斜率 |
|
||
| atr_5m | float | 5分钟粒度 ATR |
|
||
| atr_percentile | float | ATR 百分位（0~100） |
|
||
| vwap_30m | float | 30分钟 VWAP |
|
||
| price | float | 当前价格（实时最新成交价） |
|
||
| p95_qty | float | 过去1分钟成交量 P95 |
|
||
| p99_qty | float | 过去1分钟成交量 P99 |
|
||
| buy_vol_1m | float | 过去1分钟主动买入量 |
|
||
| sell_vol_1m | float | 过去1分钟主动卖出量 |
|
||
| score | int | 综合评分（0~100） |
|
||
| signal | text | `LONG` / `SHORT` / null（null=无信号） |
|
||
| factors | jsonb | 四层评分详情，格式见下 |
|
||
| strategy | varchar | 策略名 |
|
||
| atr_value | float | ATR 值（用于计算 SL/TP） |
|
||
| cvd_5m | float | 5分钟 CVD |
|
||
| cvd_15m | float | 15分钟 CVD |
|
||
| cvd_30m | float | 30分钟 CVD |
|
||
| cvd_1h | float | 1小时 CVD |
|
||
| cvd_4h | float | 4小时 CVD |
|
||
| strategy_id | uuid FK | 关联 strategies 表 |
|
||
| strategy_name_snapshot | text | 策略展示名快照 |
|
||
|
||
**factors jsonb 结构**：
|
||
```json
|
||
{
|
||
"direction": {"score": 38.0, "detail": "CVD共振LONG, cvd_fast=1234.5, cvd_slow=5678.9"},
|
||
"environment": {"score": 32.0, "detail": "ATR正常, VWAP上方"},
|
||
"auxiliary": {"score": 28.0, "detail": "OBI=0.45, 无否决"},
|
||
"momentum": {"score": 2.0, "detail": "P99成交量正常"},
|
||
"total": 75,
|
||
"gate_passed": true,
|
||
"block_reason": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 `agg_trades` — 逐笔成交数据（分区表）
|
||
|
||
主表 + 按月分区子表（agg_trades_202602, agg_trades_202603 等）。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| agg_id | bigint PK | 币安 agg trade ID |
|
||
| symbol | text | 交易对 |
|
||
| price | float | 成交价格 |
|
||
| qty | float | 成交量 |
|
||
| time_ms | bigint | 成交时间戳（毫秒） |
|
||
| is_buyer_maker | smallint | 0=主动买入，1=主动卖出 |
|
||
|
||
**数据量**：
|
||
- BTCUSDT：2026-02-05 起，约 8949 万条
|
||
- ETHUSDT：2026-02-25 起，约 3297 万条
|
||
- SOLUSDT/XRPUSDT：2026-02-28 起，约 400~500 万条
|
||
|
||
---
|
||
|
||
### 4.5 `market_indicators` — 市场宏观指标
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int PK | 自增 |
|
||
| symbol | varchar | 交易对 |
|
||
| indicator_type | varchar | 指标类型（`funding_rate` / `open_interest` / `ls_ratio` 等） |
|
||
| timestamp_ms | bigint | 时间戳 |
|
||
| value | jsonb | 指标值（结构因类型而异） |
|
||
| created_at | timestamp | 写入时间 |
|
||
|
||
---
|
||
|
||
### 4.6 `rate_snapshots` — 资金费率快照
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| ts | 时间戳（毫秒） |
|
||
| btc_rate | BTC 资金费率 |
|
||
| eth_rate | ETH 资金费率 |
|
||
| btc_price | BTC 价格 |
|
||
| eth_price | ETH 价格 |
|
||
| btc_index_price | BTC 指数价格 |
|
||
| eth_index_price | ETH 指数价格 |
|
||
|
||
---
|
||
|
||
### 4.7 `liquidations` — 强平数据
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| symbol | 交易对 |
|
||
| side | `LONG` / `SHORT` |
|
||
| price | 强平价格 |
|
||
| qty | 数量 |
|
||
| usd_value | USD 价值 |
|
||
| trade_time | 时间戳（毫秒） |
|
||
|
||
---
|
||
|
||
### 4.8 `users` — 用户认证
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| id | bigint PK |
|
||
| email | 邮箱（唯一） |
|
||
| password_hash | bcrypt 哈希 |
|
||
| role | `admin` / `user` |
|
||
| discord_id | Discord 用户 ID |
|
||
| banned | 0=正常，1=封禁 |
|
||
|
||
Admin 账号：`fzq1228@gmail.com`，role=admin。
|
||
|
||
---
|
||
|
||
### 4.9 `signal_feature_events` — 信号特征事件（机器学习数据集）
|
||
|
||
记录每次 gate 决策的全部原始特征，用于事后分析和 Optuna 优化。
|
||
|
||
重要字段：`gate_passed`（bool）、`score_direction`、`score_crowding`、`score_environment`、`score_aux`、`score_total`、`block_reason`。
|
||
|
||
---
|
||
|
||
## 五、信号引擎（signal_engine.py）详细逻辑
|
||
|
||
### 5.1 架构
|
||
|
||
- **单进程 Python 事件循环**（asyncio），每 ~15 秒运行一轮
|
||
- 每轮对 4 个币种 × N 个策略 进行评估
|
||
- 实时数据来源：`agg_trades` 表（由 agg-collector 写入）
|
||
- 附加数据来源：`market_indicators` 表（OBI、OI、资金费率等）
|
||
|
||
### 5.2 滑动窗口
|
||
|
||
每个币种维护 3 个滑动窗口（按 `agg_trades.time_ms` 切片）：
|
||
- `win_fast`：30分钟窗口（`WINDOW_FAST = 30 * 60 * 1000 ms`）
|
||
- `win_mid`：4小时窗口（`WINDOW_MID = 4 * 3600 * 1000 ms`）
|
||
- `win_day`：24小时窗口（`WINDOW_DAY = 24 * 3600 * 1000 ms`）
|
||
|
||
每个窗口存储 `(time_ms, qty, price, is_buyer_maker)` 元组列表，定期淘汰过期数据。
|
||
|
||
**CVD 计算**：
|
||
`CVD = 主动买入量 - 主动卖出量`（在窗口时间范围内求和）
|
||
|
||
**动态切片**：
|
||
当策略配置了非标准窗口（如 15m、1h）时，从 `win_fast` 或 `win_mid` 的 trades 列表中按时间范围切片重算 CVD：
|
||
- fast 周期 ≤ 30m → 从 `win_fast.trades` 切片
|
||
- fast 周期 > 30m → 从 `win_mid.trades` 切片
|
||
- slow 周期 → 始终从 `win_mid.trades` 切片
|
||
|
||
### 5.3 评分模型（`evaluate_factory_strategy`，别名 `evaluate_v53`，原 `_evaluate_v53`）
|
||
|
||
**四层线性评分**，总分 = 各层得分之和，满分 = 各层权重之和。
|
||
|
||
#### 门控系统（5个门，按顺序，任意一门否决则 gate_passed=false，不开仓）
|
||
|
||
| 门 | 条件 | 否决理由 |
|
||
|----|------|----------|
|
||
| 门1 波动率 | `ATR/price >= vol_atr_pct_min` | ATR 过小，市场太平静 |
|
||
| 门2 CVD共振 | `cvd_fast` 和 `cvd_slow` 同向（同正=LONG，同负=SHORT） | 快慢 CVD 不共振 |
|
||
| 门3 鲸鱼否决 | 大额成交（>whale_usd_threshold）的净流向与信号方向一致（或该门禁用） | 鲸鱼反向 |
|
||
| 门4 OBI否决 | OBI（订单簿不平衡）不与信号方向矛盾（或该门禁用） | OBI 反向 |
|
||
| 门5 期现背离 | 现货-永续价差在阈值内（或该门禁用） | 期现背离过大 |
|
||
|
||
门2（CVD共振）同时决定信号方向：两个 CVD 都正→LONG，都负→SHORT，不同向→HOLD（跳过）。
|
||
|
||
#### 评分计算（gate_passed=true 后）
|
||
|
||
**方向层**（weight_direction，默认 38）：
|
||
- CVD共振强度 → 占方向层满分的比例
|
||
- 公式：`score_dir = weight_direction × min(1.0, abs(cvd_fast + cvd_slow) / normalization_factor)`
|
||
|
||
**环境层**（weight_env，默认 32）：
|
||
- ATR 百分位（价格波动强度）
|
||
- VWAP 相对位置
|
||
- 资金费率方向
|
||
|
||
**辅助层**（weight_aux，默认 28）：
|
||
- OBI 强度
|
||
- 期现背离程度
|
||
- 强平数据方向
|
||
|
||
**动量层**（weight_momentum，默认 2）：
|
||
- P99 成交量异常
|
||
- 买卖量比
|
||
|
||
**开仓条件**：`total_score >= entry_score`（默认 75）
|
||
|
||
### 5.4 开仓逻辑
|
||
|
||
```
|
||
for each symbol:
|
||
update sliding windows with new agg_trades
|
||
for each strategy (status=running):
|
||
if strategy.symbol != symbol → skip
|
||
evaluate_signal(strategy_cfg) → result
|
||
if result.signal and score >= entry_score:
|
||
if no active position for this strategy:
|
||
if active_position_count < max_positions:
|
||
paper_open_trade(...)
|
||
```
|
||
|
||
**开仓价格**：取 `signal_indicators.price`（实时最新成交价），不是 VWAP。
|
||
|
||
**SL/TP 计算**：
|
||
- `risk_distance = sl_atr_multiplier × ATR`（1R）
|
||
- LONG：`SL = price - risk_distance`，`TP1 = price + tp1_ratio × risk_distance`，`TP2 = price + tp2_ratio × risk_distance`
|
||
- SHORT：`SL = price + risk_distance`，`TP1 = price - tp1_ratio × risk_distance`，`TP2 = price - tp2_ratio × risk_distance`
|
||
|
||
**当前标准TP/SL配置（BTC 18组对照）**：
|
||
- 保守：`sl=2.0×ATR, tp1=0.75×ATR, tp2=1.5×ATR`（TP全到=+0.5625R）
|
||
- 平衡：`sl=2.0×ATR, tp1=1.0×ATR, tp2=2.0×ATR`（TP全到=+1.5R）
|
||
- 激进：`sl=2.0×ATR, tp1=1.5×ATR, tp2=3.0×ATR`（TP全到=+2.25R）
|
||
|
||
### 5.5 平仓逻辑（paper_monitor.py）
|
||
|
||
独立进程，通过币安 WebSocket 实时接收 mark price：
|
||
|
||
1. `price >= tp1_price`（LONG）或 `price <= tp1_price`（SHORT）→ 触发 TP1：status 改为 `tp1_hit`，移动止损到保本价
|
||
2. TP1 已触发后，`price >= tp2_price` → 全仓 TP2：status=`tp`
|
||
3. `price <= sl_price`（LONG）或 `price >= sl_price`（SHORT）→ 止损：status=`sl`，`pnl_r=-1.0`
|
||
4. 持仓超 240 分钟 → status=`timeout`
|
||
5. 反向信号强度 >= flip_threshold → signal_engine 触发 `signal_flip`
|
||
|
||
---
|
||
|
||
## 六、FastAPI 后端接口（main.py）
|
||
|
||
### 6.1 认证
|
||
- `POST /api/auth/login` → 返回 JWT token
|
||
- `POST /api/auth/register` → 注册（需邀请码）
|
||
- 所有接口需 Bearer JWT，通过 `Depends(get_current_user)` 校验
|
||
|
||
### 6.2 行情数据
|
||
- `GET /api/rates` → 最新资金费率快照（rate_snapshots 最新一行）
|
||
- `GET /api/snapshots` → 多个时间点的资金费率历史
|
||
- `GET /api/kline?symbol=BTC&interval=1m&limit=100` → K线（从 agg_trades 聚合）
|
||
|
||
### 6.3 信号引擎
|
||
- `GET /api/signals/latest?strategy=v53` → 各币种最新一条信号指标（signal_indicators 每币种 LIMIT 1）
|
||
- `GET /api/signals/latest-v52?strategy=v52_8signals` → 同上，v52 字段
|
||
- `GET /api/signals/indicators?symbol=BTCUSDT&strategy=v53&limit=100` → 历史信号指标列表
|
||
- `GET /api/signals/signal-history?symbol=BTC&strategy=v53&limit=50` → 有信号（signal IS NOT NULL）的历史列表
|
||
- `GET /api/signals/market-indicators?symbol=BTCUSDT` → 最新市场宏观指标（OI/多空比/资金费率）
|
||
- `GET /api/signals/history?strategy=v53&limit=100` → 信号历史（含各层分数）
|
||
|
||
### 6.4 模拟盘（paper trading）
|
||
- `GET /api/paper/config` → 读取 paper_config.json
|
||
- `POST /api/paper/config` → 更新 paper_config.json（控制总开关和每策略开关）
|
||
- `GET /api/paper/summary?strategy=v53&strategy_id=uuid` → 总览（总盈亏R/USDT、胜率、余额、持仓数、盈亏比）
|
||
- `GET /api/paper/positions?strategy=v53&strategy_id=uuid` → 当前活跃持仓列表（含实时浮盈计算）
|
||
- `GET /api/paper/trades?strategy=v53&strategy_id=uuid&symbol=BTC&status=tp&limit=100` → 历史交易列表
|
||
- `GET /api/paper/equity-curve?strategy=v53&strategy_id=uuid` → 权益曲线（按时间累加 pnl_r）
|
||
- `GET /api/paper/stats?strategy=v53&strategy_id=uuid` → 详细统计（胜率/盈亏比/MDD/Sharpe/avg_win/avg_loss，按币种分组）
|
||
- `GET /api/paper/stats-by-strategy` → 所有策略的汇总统计（策略广场用）
|
||
|
||
### 6.5 策略广场（strategy plaza）
|
||
- `GET /api/strategy-plaza?status=running` → 策略列表（支持 status 过滤）
|
||
- `GET /api/strategy-plaza/{strategy_id}/summary` → 单策略总览卡
|
||
- `GET /api/strategy-plaza/{strategy_id}/signals` → 单策略最新信号
|
||
- `GET /api/strategy-plaza/{strategy_id}/trades` → 单策略交易记录
|
||
|
||
### 6.6 策略管理 CRUD
|
||
- `POST /api/strategies` → 创建新策略（写入 strategies 表，signal_engine 15秒内热重载）
|
||
- `GET /api/strategies` → 策略列表（含 open_positions 数量）
|
||
- `GET /api/strategies/{sid}` → 单策略详情
|
||
- `PATCH /api/strategies/{sid}` → 更新策略参数
|
||
- `POST /api/strategies/{sid}/pause` → 暂停（status=paused）
|
||
- `POST /api/strategies/{sid}/resume` → 恢复（status=running）
|
||
- `POST /api/strategies/{sid}/deprecate` → 停用（status=deprecated）
|
||
- `POST /api/strategies/{sid}/restore` → 恢复到 running
|
||
- `POST /api/strategies/{sid}/add-balance` → 补充模拟资金
|
||
|
||
### 6.7 服务器监控
|
||
- `GET /api/server/status` → 服务器资源（CPU/内存/磁盘/PM2进程状态）
|
||
|
||
### 6.8 实盘接口（暂未真实使用）
|
||
- `GET /api/live/*` → 实盘持仓、交易、权益曲线、账户余额、风控状态等
|
||
- `POST /api/live/emergency-close` → 紧急平仓
|
||
- `POST /api/live/block-new` → 暂停新开仓
|
||
- `POST /api/live/resume` → 恢复开仓
|
||
|
||
---
|
||
|
||
## 七、前端页面列表
|
||
|
||
### 7.1 主导航（Sidebar）
|
||
|
||
固定左侧 sidebar，包含所有页面入口和当前 BTC/ETH 资金费率实时显示。
|
||
|
||
### 7.2 页面详情
|
||
|
||
#### `/` (首页/Dashboard)
|
||
- 资金费率历史折线图（BTC/ETH 双轨）
|
||
- 资金费率 24h 统计（最大/最小/均值）
|
||
- 近期套利机会卡片
|
||
|
||
#### `/signals-v53` (信号引擎 v5.3，老页面)
|
||
- CVD 三轨卡片（cvd_fast/cvd_mid/cvd_day + 斜率 + 共振判断）
|
||
- ATR / VWAP / P95 / P99 市场环境指标
|
||
- 信号状态卡（LONG/SHORT/无信号 + 评分 + 四层分数进度条）
|
||
- Gate-Control 卡（5门详情：波动率/CVD共振/鲸鱼/OBI/期现背离）
|
||
- 信号历史列表（最近20条：时间/方向/评分）
|
||
- CVD 折线图（可切 1h/4h/12h/24h 时间范围）
|
||
- 币种切换：BTC/ETH/SOL/XRP
|
||
|
||
#### `/paper-v53` (模拟盘 v5.3，老页面)
|
||
- 总览卡片（总盈亏R/USDT/胜率/持仓数/盈亏比/余额）
|
||
- 最新信号（四币种最近信号+四层分+Gate状态）
|
||
- 控制面板（启动/停止按钮）
|
||
- 当前活跃持仓（实时价格WebSocket/浮盈R/入场TP SL价格）
|
||
- 权益曲线（面积图）
|
||
- 历史交易列表（筛选币种/盈亏；入场/出场价/状态/评分/持仓时长）
|
||
- 详细统计（胜率/盈亏比/avg_win/avg_loss/MDD/Sharpe，按币种分Tab）
|
||
|
||
#### `/strategy-plaza` (策略广场，主入口)
|
||
- 策略列表卡片视图（按 status 过滤：running/paused/deprecated）
|
||
- 每个卡片显示：策略名/币种/CVD周期/TP方案/胜率/净R/余额/状态
|
||
- 快速操作：暂停/恢复/停用
|
||
- 「新建策略」按钮 → 跳转 `/strategy-plaza/create`
|
||
|
||
#### `/strategy-plaza/create` (新建策略)
|
||
- 表单：策略名/symbol/CVD快慢周期/四层权重/五门阈值/TP-SL参数/初始余额
|
||
- 提交后 POST /api/strategies，signal_engine 15秒内热重载
|
||
|
||
#### `/strategy-plaza/[id]` (策略详情页，通用)
|
||
- Tab1: 信号引擎（SignalsGeneric 组件）
|
||
- 动态显示该策略配置的 CVD 周期、权重、Gate 阈值
|
||
- 实时信号评分
|
||
- 信号历史、CVD 图表
|
||
- Tab2: 模拟盘（PaperGeneric 组件）
|
||
- 总览统计、活跃持仓、权益曲线、交易列表、详细统计
|
||
- 启停控制
|
||
|
||
#### `/strategy-plaza/[id]/edit` (编辑策略)
|
||
- 同新建表单，预填当前参数，提交 PATCH /api/strategies/{id}
|
||
|
||
#### `/server` (服务器状态)
|
||
- CPU/内存/磁盘/PM2进程状态实时监控
|
||
|
||
#### `/kline` (K线图)
|
||
- 任意币种 K线，支持 1m/5m/15m/1h 粒度
|
||
|
||
#### `/login` / `/register`
|
||
- JWT 登录/邀请码注册
|
||
|
||
---
|
||
|
||
## 八、paper_config.json（模拟盘控制文件）
|
||
|
||
路径：`backend/paper_config.json`
|
||
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"enabled_strategies": [],
|
||
"initial_balance": 10000,
|
||
"risk_per_trade": 0.02,
|
||
"max_positions": 100,
|
||
"tier_multiplier": {"light": 0.5, "standard": 1.0, "heavy": 1.5}
|
||
}
|
||
```
|
||
|
||
- `enabled_strategies` 为空列表 = 全部策略放行
|
||
- `max_positions` 当前设为 100（实际无限制）
|
||
|
||
---
|
||
|
||
## 九、数据流（完整链路）
|
||
|
||
```
|
||
币安 WebSocket（逐笔成交）
|
||
↓ agg-collector.py
|
||
agg_trades 表（PostgreSQL 分区表）
|
||
↓ signal_engine.py（每15秒读取）
|
||
滑动窗口（win_fast 30m / win_mid 4h / win_day 24h）
|
||
↓ 计算CVD/ATR/VWAP
|
||
evaluate_factory_strategy() （内部别名 evaluate_v53，原 _evaluate_v53）
|
||
↓ 5门检查 → 四层评分
|
||
signal_indicators 写入
|
||
↓ signal IS NOT NULL 且 score >= entry_score
|
||
paper_open_trade() → paper_trades 写入
|
||
↓
|
||
paper_monitor.py（WebSocket 实时价格监控）
|
||
↓ 触及 TP1/TP2/SL 或超时
|
||
paper_trades 平仓（status/exit_price/pnl_r 更新）
|
||
↓
|
||
FastAPI（main.py）← Next.js 前端查询展示
|
||
```
|
||
|
||
---
|
||
|
||
## 十、已知缺陷（Codex 重写需改进）
|
||
|
||
1. **signal_engine.py 单体巨型文件**（1800+ 行），所有逻辑混在一起
|
||
2. **所有策略共享同一个 snapshot**，无法真正独立评估
|
||
3. **CVD 动态切片依赖 win_fast/win_mid 两个固定窗口**，扩展性受限
|
||
4. **开仓逻辑耦合在 signal_engine 主循环**，paper_monitor 只管平仓
|
||
5. **前端页面碎片化**：每个策略版本有独立页面，维护困难
|
||
6. **strategy_name 路由逻辑脆弱**：`custom_` 路由曾多次因 scp 覆盖丢失
|
||
7. **API 无分页**，大数据量接口可能超时
|
||
|
||
---
|
||
|
||
## 十一、关键配置
|
||
|
||
```
|
||
数据库连接: postgresql://arb:arb_engine_2026@10.106.0.3/arb_engine
|
||
JWT Secret: arb-engine-jwt-secret-v2-2026
|
||
Admin: fzq1228@gmail.com (id=1, role=admin)
|
||
前端: https://arb.zhouyangclaw.com (端口 4333)
|
||
后端: 端口 4332
|
||
项目路径: /home/fzq1228/Projects/arbitrage-engine/
|
||
```
|