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 = sl_atr_multiplier × ATR（默认 1.5）
tp1_ratio	float	TP1 = tp1_ratio × ATR（默认 0.75）
tp2_ratio	float	TP2 = tp2_ratio × ATR（默认 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 计算规则：

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 取反）

胜率定义（重要）：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 结构：

{
  "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_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 × ATR，TP2 = price + tp2_ratio × ATR
SHORT：SL = price + risk_distance，TP1 = price - tp1_ratio × ATR，TP2 = price - tp2_ratio × ATR

当前标准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：

price >= tp1_price（LONG）或 price <= tp1_price（SHORT）→ 触发 TP1：status 改为 tp1_hit，移动止损到保本价
TP1 已触发后，price >= tp2_price → 全仓 TP2：status=tp
price <= sl_price（LONG）或 price >= sl_price（SHORT）→ 止损：status=sl，pnl_r=-1.0
持仓超 240 分钟 → status=timeout
反向信号强度 >= 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 → 恢复开仓

资金费率历史折线图（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 粒度

JWT 登录/邀请码注册

八、paper_config.json（模拟盘控制文件）

路径：backend/paper_config.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_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 重写需改进）

signal_engine.py 单体巨型文件（1800+ 行），所有逻辑混在一起
所有策略共享同一个 snapshot，无法真正独立评估
CVD 动态切片依赖 win_fast/win_mid 两个固定窗口，扩展性受限
开仓逻辑耦合在 signal_engine 主循环，paper_monitor 只管平仓
前端页面碎片化：每个策略版本有独立页面，维护困难
strategy_name 路由逻辑脆弱：custom_ 路由曾多次因 scp 覆盖丢失
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/

Arbitrage Engine 完整项目规格文档

On this page