# Arbitrage Engine 后端运行说明（Backend Runtime Guide）

> 本文从“后端工程师 / 运维”的角度，描述项目的后端模块、进程拓扑和数据流。  
> 详细字段与业务规则仍以 `docs/arbitrage-engine-full-spec.md` 为准。

---

## 1. 后端整体结构概览

后端主要由三类组件组成：

1. **FastAPI HTTP API（arb-api）**
   - 文件：`backend/main.py`
   - 职责：
     - 提供 `/api/...` 下的所有 HTTP 接口；
     - 负责认证（集成 `auth.py` 的路由）；
     - 对数据库执行查询和聚合逻辑，为前端和脚本服务；
     - 启动少量后台任务（如资金费率快照）。

2. **信号与交易引擎进程**
   - `backend/signal_engine.py`：信号引擎（策略评估 + 模拟盘开仓）；
   - `backend/paper_monitor.py`：模拟盘平仓（TP/SL/timeout/signal_flip）；
   - `backend/live_executor.py`（未来/暂定）：连接实盘执行；
   - `backend/risk_guard.py`：风控守护进程；
   - `backend/position_sync.py`：实盘仓位同步。

3. **数据采集与维护进程**
   - `backend/agg_trades_collector.py`：从币安 WebSocket 收集逐笔成交写入 `agg_trades`；
   - `backend/market_data_collector.py`：收集资金费率、OI、多空比等写入 `market_indicators`；
   - `backend/liquidation_collector.py`：收集爆仓数据写入 `liquidations`；
   - `backend/backfill_agg_trades.py`：历史数据回补；
   - `backend/fix_historical_pnl.py` 等维护脚本：用于修复历史统计。

这些组件通过 PostgreSQL 共享状态，FastAPI 作为对外唯一 HTTP 入口，信号/模拟盘引擎作为“后端大脑”，采集进程负责填充数据湖。

---

## 2. FastAPI API（arb-api）

入口文件：`backend/main.py`  
运行方式：由 PM2 管理的 `arb-api` 进程（端口 4332）。

主要职责：

- 提供 `/api/...` REST 接口：
  - 资金费率/历史数据（`/api/rates`、`/api/history`、`/api/kline`、`/api/snapshots`）；
  - 信号相关接口（`/api/signals/*`）；
  - 模拟盘接口（`/api/paper/*`）；
  - 策略管理接口（`/api/strategies*`、`/api/strategy-plaza*`）；
  - 实盘状态与控制接口（`/api/live/*`）；
  - 服务器监控接口（`/api/server/status`）。
- 初始化数据库连接：
  - 在 `startup` 事件中调用 `init_schema()` 和 `ensure_auth_tables()`；
  - 初始化 asyncpg 连接池（`get_async_pool()`）。
- 启动后台任务：
  - `background_snapshot_loop()`：每 2 秒从币安拉资金费率 + 标记价，写入 `rate_snapshots`。

开发/调试提示：

- 本地如需仅调试 API 层，可以只启动 `main.py`（例如 `uvicorn main:app --reload`），连接已有 Cloud SQL；  
- 复杂查询（如 stats / strategy-plaza）建议先查阅 `docs/API_CONTRACTS.md`，再看对应路由实现。

---

## 3. 信号与交易引擎进程

### 3.1 signal_engine.py — 信号引擎

文件：`backend/signal_engine.py`  
PM2 名称：`signal-engine`

职责（结合 full-spec）：

- 定时循环（约每 15 秒）：
  1. 从 `agg_trades` 滑动窗口计算 CVD、ATR、VWAP 等指标；
  2. 从 `market_indicators` / `liquidations` 读取宏观指标和爆仓数据；
  3. 对每个策略（`strategies` 表中 `status=running` 的记录）调用评估函数（V5.3 之前 `_evaluate_v53`，V5.4 起为 `evaluate_factory_strategy`，内部别名 `evaluate_v53` 的策略工厂流程）；
  4. 生成评分与信号（`score`、`signal`），写入 `signal_indicators`；
  5. 在满足开仓条件时写入 `paper_trades`，通过 `paper_open_trade()` 等逻辑开模拟仓。

- 与前端/上层接口的关系：
  - 前端 `/signals*` 页面只读 `signal_indicators` 和相关汇总接口，不直接调用 signal_engine；
  - `/paper`、`/strategy-plaza` 通过 `paper_trades` 和 `strategies`/`signal_indicators` 组合呈现结果。

注意：

- `signal_engine.py` 是最复杂的单体文件之一，对其进行修改前建议：
  - 阅读 `arbitrage-engine-full-spec.md` 中“信号引擎”章节；
  - 阅读 `docs/AI_HANDBOOK.md` 中关于“禁止/谨慎修改”的约束；
  - 在未来可以为其单独增加 `GUIDE_SIGNAL_ENGINE.md` 做更细粒度说明。

### 3.2 paper_monitor.py — 模拟盘平仓

文件：`backend/paper_monitor.py`  
PM2 名称：`paper-monitor`

职责：

- 通过币安 WebSocket 获取 mark price；
- 监控所有 `paper_trades` 中 `status="active"` 或 `tp1_hit` 的持仓；
- 根据价格触发规则：
  - 触及 TP1 → 将 status 改为 `tp1_hit`，移动 SL 到保本价；
  - 触及 TP2 → status=`tp`，计算 `pnl_r`；
  - 触及 SL → status=`sl`，`pnl_r=-1`；
  - 超时（持仓超过 timeout_minutes）→ status=`timeout`，按价差换算 R；
  - 被反向信号强平 → status=`signal_flip`。

信号引擎负责开仓逻辑，paper_monitor 负责平仓逻辑，两者通过 `paper_trades` 协作。

### 3.3 其他进程（概要）

- `live_executor.py`：
  - 负责将信号转换为实盘订单（当前可能处于试验/非默认启用状态）；
  - 与 `/api/live/*` 接口、`risk_guard.py` 共同控制实盘行为。
- `risk_guard.py`：
  - 独立风控守护进程，通过检查日内 R、连续亏损、API 状态等判断是否触发熔断；
  - 与 `/api/live/risk-status` 和 `/api/live/emergency-close` 等控制接口关联。
- `position_sync.py`：
  - 定期从交易所拉取真实仓位，对齐本地 `live_positions` 记录；
  - 为 `/api/live/reconciliation` 提供比对数据。

这些进程对模拟盘的影响有限，但对实盘 `/live` 页至关重要。

---

## 4. 数据采集与维护脚本

### 4.1 市场数据采集

- `agg_trades_collector.py`
  - 订阅币安逐笔成交 WebSocket 流；
  - 将成交写入 `agg_trades` 分区表；
  - 为 CVD/ATR/VWAP 等指标计算提供原始成交数据。

- `market_data_collector.py`
  - 定期从币安/其他来源拉取资金费率、未平仓合约（OI）、多空比、订单簿不平衡等；
  - 写入 `market_indicators`；
  - 供 signal_engine 的环境层/拥挤层/辅助层使用。

- `liquidation_collector.py`
  - 拉取爆仓（强平）数据；
  - 写入 `liquidations`；
  - 供 V5.2/V5.3 的 liquidation 层打分使用。

### 4.2 历史数据与修复

- `backfill_agg_trades.py`
  - 用于历史数据回补；
  - 配合 `/api/server/status` 中 `backfill_running` 标记监控运行状态。

- `fix_historical_pnl.py` 等修复脚本：
  - 针对旧数据的 PnL 计算错误或结构变更进行一次性修复；
  - 修改前请查阅 full-spec 中对应章节，并记录在决策/变更文档中。

---

## 5. 后端数据流（服务视角）

从“服务/进程”的角度看，主数据流可简化为：

1. **行情写入**
   - 币安 WebSocket → `agg_trades_collector.py` → `agg_trades`；
   - 市场宏观指标 API → `market_data_collector.py` → `market_indicators`；
   - 强平数据 → `liquidation_collector.py` → `liquidations`；
   - 资金费率快照 → `main.py` 中后台任务 → `rate_snapshots`。

2. **信号生成**
   - `signal_engine.py` 周期性读取：
     - `agg_trades` 滑动窗口；
     - `market_indicators`；
     - `liquidations`；
     - `strategies` 配置；
   - 计算指标与评分 → 写入 `signal_indicators`；
   - 满足条件时 → 写入 `paper_trades`（开仓记录）。

3. **模拟盘结算**
   - `paper_monitor.py` 通过 WebSocket 获取 price；
   - 根据 `paper_trades` 的 SL/TP/timeout 规则更新 `paper_trades.status` 和 `pnl_r`。

4. **API 展示与控制**
   - `main.py` 通过 `/api/paper/*`、`/api/signals/*`、`/api/strategy-plaza*` 等接口对外提供：
     - 信号历史和当前状态；
     - 模拟盘持仓、交易历史、统计与权益曲线；
     - 策略列表与管理操作。
   - `/api/live/*` 接口与 `live_executor.py` / `risk_guard.py` 等进程协作控制实盘。

---

## 6. 本地开发与调试建议

1. **仅调试前端 + API（不跑引擎）**
   - 使用现有 Cloud SQL 作为只读数据源：
     - 启动 `backend/main.py`（uvicorn 或 PM2）；
     - 启动前端 `frontend`（Next.js dev 模式）；
   - 适用于：
     - 调整页面布局与数据展示；
     - 优化 `/api/...` 查询逻辑；
     - 编写/验证新接口契约。

2. **调试信号引擎/模拟盘**
   - 启动 `signal_engine.py` 和 `paper_monitor.py` 所需的最小进程集合；
   - 确保 `agg_trades` / `market_indicators` 至少有一部分历史数据（可以从线上复制或运行简化版 collector）；
   - 使用日志和 `signal_indicators` / `paper_trades` 查询验证新策略。

3. **调试实盘页面 `/live`**
   - 在本地/测试环境建议仅连接测试网账户；
   - 启动相关进程：
     - `live_executor.py`、`risk_guard.py`、`position_sync.py`（视具体实现和需求而定）；
   - 通过 `/api/live/*` 接口与 `/live` 页面观察状态变化，避免直接在生产环境实验未验证的逻辑。

4. **变更规则**
   - 修改后端关键逻辑（尤其是 signal_engine、risk_guard）时，建议遵守：
     - 先更新/确认 `arbitrage-engine-full-spec.md` 中对应章节；
     - 再确保 `API_CONTRACTS.md` 与前端用法一致；
     - 最后通过少量回测/模拟盘运行做 smoke test。

---

本文件的目标是提供一个“后端模块地图”和“进程视角的数据流”，让未来的你（以及 AI 助手）在需要修改/排障时，不必反复从头翻 full-spec 和代码，就能快速知道该看哪几个模块、查哪几张表、重启哪些进程。