---
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/
```