docs: add full project spec for Codex rewrite

docs/arbitrage-engine-full-spec.md

@@ -0,0 +1,593 @@
+---
+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 = 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 结构**：
+```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_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：
+
+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_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/
+```