docs: add comprehensive project documentation (PROJECT.md)

- Full architecture overview
- All 36 files documented with purpose and line counts
- 5-layer scoring system explained
- Database schema, PM2 processes, signal sources
- Deployment info, version roadmap
- Known issues and improvements

docs/PROJECT.md

@@ -0,0 +1,425 @@
+# Arbitrage Engine V5.1 — 项目文档
+
+> 最后更新：2026-03-01
+> 版本：V5.1
+> 作者：琪智科技
+
+## 一、项目概述
+
+**Arbitrage Engine** 是一套加密货币合约交易信号系统，基于多因子评分模型，实时分析市场微观结构数据（Order Flow），生成做多/做空信号并执行模拟盘交易。
+
+### 核心能力
+- **5层100分评分体系**：方向层(45) + 拥挤层(20) + 环境层(15) + 确认层(15) + 辅助层(5)
+- **4个交易币种**：BTCUSDT、ETHUSDT、XRPUSDT、SOLUSDT
+- **8个信号源**（6个已接入评分，2个在采集中）
+- **模拟盘自动交易**：信号触发 → 开仓 → TP/SL → 平仓，全自动
+- **实时数据采集**：aggTrades、市场指标、清算数据
+- **Web仪表盘**：信号展示、模拟盘监控、收益统计
+
+### 技术栈
+| 层级 | 技术 |
+|------|------|
+| 后端 | Python 3 + FastAPI + uvicorn |
+| 前端 | Next.js 15 + React + TypeScript + Tailwind CSS |
+| 数据库 | PostgreSQL 18（GCP Cloud SQL） |
+| 进程管理 | PM2 |
+| 数据源 | Binance Futures API + WebSocket |
+| 反向代理 | Caddy |
+
+### 代码统计
+| 模块 | 文件数 | 代码行数 |
+|------|--------|---------|
+| Backend (Python) | 15个 | 4,598行 |
+| Frontend (TSX/TS) | 21个 | 3,518行 |
+| **总计** | **36个** | **8,116行** |
+
+---
+
+## 二、项目结构
+
+```
+arbitrage-engine/
+├── backend/                    # Python后端
+│   ├── main.py                 # FastAPI主入口 + 全部API路由
+│   ├── db.py                   # 数据库连接层（PG同步+异步池+Cloud SQL双写）
+│   ├── auth.py                 # 用户认证系统（JWT + 邀请码注册）
+│   ├── signal_engine.py        # 🔥 核心：信号评估引擎（5层评分）
+│   ├── paper_monitor.py        # 模拟盘监控（WebSocket实时TP/SL）
+│   ├── agg_trades_collector.py # aggTrades实时采集（Binance WS）
+│   ├── market_data_collector.py# 市场指标采集（多空比/OI/FR等）
+│   ├── liquidation_collector.py# 清算数据采集（Binance forceOrder）
+│   ├── backtest.py             # 回测框架
+│   ├── backfill_agg_trades.py  # aggTrades历史回补工具
+│   ├── admin_cli.py            # 管理命令行工具
+│   ├── signal_pusher.py        # [已废弃] 旧版信号推送
+│   ├── subscriptions.py        # [预留] 订阅系统
+│   ├── migrate_sqlite_to_pg.py # [一次性] SQLite→PG数据迁移
+│   └── migrate_auth_sqlite_to_pg.py # [一次性] Auth SQLite→PG迁移
+├── frontend/                   # Next.js前端
+│   ├── app/
+│   │   ├── page.tsx            # 首页（仪表盘概览）
+│   │   ├── layout.tsx          # 全局布局
+│   │   ├── signals/page.tsx    # 信号引擎页面（5层评分展示）
+│   │   ├── paper/page.tsx      # 模拟盘页面（持仓+历史+统计）
+│   │   ├── trades/page.tsx     # 历史交易页面
+│   │   ├── server/page.tsx     # 服务器监控页面
+│   │   ├── kline/page.tsx      # K线图页面
+│   │   ├── live/page.tsx       # 实时数据页面
+│   │   ├── dashboard/page.tsx  # 仪表盘页面
+│   │   ├── login/page.tsx      # 登录页面
+│   │   ├── register/page.tsx   # 注册页面（需邀请码）
+│   │   ├── about/page.tsx      # 关于页面
+│   │   └── history/page.tsx    # [占位] 历史页面
+│   ├── components/
+│   │   ├── Sidebar.tsx         # 侧边导航栏
+│   │   ├── Navbar.tsx          # 顶部导航栏
+│   │   ├── AuthHeader.tsx      # 认证头部
+│   │   ├── LiveTradesCard.tsx  # 实时交易卡片
+│   │   ├── FundingChart.tsx    # 资金费率图表
+│   │   ├── RateCard.tsx        # 费率卡片
+│   │   └── StatsCard.tsx       # 统计卡片
+│   ├── lib/
+│   │   ├── auth.tsx            # 前端认证逻辑（JWT管理）
+│   │   └── api.ts              # API请求封装
+│   ├── next.config.ts          # Next.js配置（API代理）
+│   ├── package.json            # 依赖配置
+│   └── tsconfig.json           # TypeScript配置
+├── docs/                       # 项目文档
+│   └── PROJECT.md              # 本文件
+├── .gitignore
+└── README.md
+```
+
+---
+
+## 三、后端文件详解
+
+### 3.1 `main.py`（949行）— API主入口
+
+FastAPI应用，包含全部HTTP API路由：
+
+**API路由：**
+| 路径 | 方法 | 功能 |
+|------|------|------|
+| `/api/health` | GET | 健康检查 |
+| `/api/signals/latest` | GET | 最新信号数据 |
+| `/api/signals/history` | GET | 历史信号 |
+| `/api/paper/summary` | GET | 模拟盘概览 |
+| `/api/paper/positions` | GET | 当前持仓 |
+| `/api/paper/trades` | GET | 历史交易 |
+| `/api/paper/equity-curve` | GET | 权益曲线 |
+| `/api/paper/stats` | GET | 详细统计（支持按币种） |
+| `/api/paper/config` | GET/POST | 模拟盘配置 |
+| `/api/server/status` | GET | 服务器监控 |
+
+**依赖：** FastAPI, uvicorn, asyncpg, psutil
+
+**运行方式：** `uvicorn main:app --host 0.0.0.0 --port 4332`
+
+---
+
+### 3.2 `signal_engine.py`（739行）— 🔥 核心信号引擎
+
+**最重要的文件**。每15秒评估一次4个币种的交易信号。
+
+**5层评分体系（100分满分）：**
+
+| 层级 | 权重 | 信号源 | 逻辑 |
+|------|------|--------|------|
+| 方向层 | 45分 | CVD三轨(fast/mid) + P99大单 + CVD加速度 | 资金流向判断多空 |
+| 拥挤层 | 20分 | 多空比 + 大户持仓比 | 市场拥挤度，反向指标 |
+| 环境层 | 15分 | OI变化率 | 合约持仓量变化 |
+| 确认层 | 15分 | CVD-Price背离 + 大单方向确认 | 信号交叉验证 |
+| 辅助层 | 5分  | Coinbase Premium | 机构资金流向 |
+
+**核心类：**
+- `TradeWindow`：滑动窗口，维护buy_vol/sell_vol/CVD，自动trim过期数据
+- `ATRCalculator`：ATR计算器，用于仓位管理和TP/SL计算
+- `SymbolState`：每个币种的完整状态（4个窗口 + ATR + 大单 + 市场指标）
+
+**数据流：**
+```
+aggTrades(PG) → process_trade() → 4个TradeWindow更新
+                                      ↓
+                              evaluate_signal() → 5层打分
+                                      ↓
+                              score >= 60 → 开仓信号
+                                      ↓
+                              paper_trading_open() → 写入paper_trades
+```
+
+**关键参数：**
+- `WINDOW_FAST = 30min`：CVD快线窗口
+- `WINDOW_MID = 4h`：CVD慢线窗口
+- `WINDOW_DAY = 24h`：P99大单计算窗口
+- `EVAL_INTERVAL = 15s`：评估间隔
+- `SIGNAL_THRESHOLD = 60`：开仓阈值分数
+- `COOLDOWN = 300s`：同币种同方向冷却时间
+
+**冷启动机制：**
+1. 启动时`load_historical()`从PG读取最近4小时aggTrades灌入窗口
+2. 前3轮(45秒)不出信号（冷启动保护）
+
+---
+
+### 3.3 `paper_monitor.py`（179行）— 模拟盘监控
+
+独立PM2进程，通过WebSocket连接Binance实时监控持仓的TP/SL。
+
+**核心逻辑：**
+1. 启动时加载所有active/tp1_hit持仓
+2. 连接Binance aggTrade WS获取实时价格
+3. 每笔成交检查是否触发TP1/TP2/SL
+4. 触发后更新paper_trades状态
+
+**TP/SL规则：**
+- TP1 = entry ± 1.5×ATR（平半仓）
+- TP2 = entry ± 3.0×ATR（平剩余）
+- SL = entry ∓ 1.0×ATR
+- TP1触发后SL移动到成本价（保本）
+
+**为什么独立进程：** TP/SL必须毫秒级响应，不能和15秒评估循环共享进程。
+
+---
+
+### 3.4 `db.py`（357行）— 数据库连接层
+
+统一的PostgreSQL连接管理，支持同步和异步两种模式。
+
+**连接池：**
+- `get_sync_pool()` / `get_sync_conn()`：psycopg2同步池（供collector/signal_engine用）
+- `get_async_pool()` / `async_fetch()`：asyncpg异步池（供FastAPI用）
+- `get_cloud_sync_pool()` / `get_cloud_sync_conn()`：Cloud SQL双写池
+
+**配置（环境变量）：**
+- `PG_HOST`：数据库地址（默认127.0.0.1，现在应指向Cloud SQL）
+- `CLOUD_PG_HOST`：Cloud SQL地址（10.106.0.3）
+- `CLOUD_PG_ENABLED`：双写开关
+
+**Schema管理：** `init_schema()` + `ensure_partitions()`（按月自动建分区表）
+
+---
+
+### 3.5 `agg_trades_collector.py`（307行）— aggTrades采集器
+
+实时采集Binance合约aggTrades数据，是数据的源头。
+
+**架构：**
+- **WebSocket主链路**：4个币种各一条WS连接，实时推送
+- **REST补洞**：断线重连后用REST API从last_agg_id追平
+- **连续性巡检**：每60秒检查agg_id连续性，发现断档自动补洞
+- **批量写入**：攒200条或1秒flush一次
+
+**双写机制：** flush_buffer同时写本地PG和Cloud SQL，Cloud SQL写失败不影响主流程。
+
+**数据量：** 目前约7000万条（BTC 23天 + ETH 3天 + XRP/SOL 3天）
+
+---
+
+### 3.6 `market_data_collector.py`（192行）— 市场指标采集
+
+每5分钟从Binance REST API采集市场指标，存入`market_indicators`表。
+
+**采集指标（5种）：**
+| 指标 | API | 用途 |
+|------|-----|------|
+| long_short_ratio | /futures/data/globalLongShortAccountRatio | 多空比 |
+| top_trader_position | /futures/data/topLongShortPositionRatio | 大户持仓比 |
+| open_interest_hist | /futures/data/openInterestHist | 持仓量变化 |
+| coinbase_premium | Coinbase vs Binance价差 | 机构资金流 |
+| funding_rate | /fapi/v1/fundingRate | 资金费率 |
+
+---
+
+### 3.7 `liquidation_collector.py`（140行）— 清算数据采集
+
+连接Binance WebSocket `forceOrder`流，实时采集强制平仓事件。
+
+**双层存储：**
+1. `liquidations`表：每笔清算原始记录
+2. `market_indicators`表：每5分钟聚合（long_liq_usd/short_liq_usd/total/count）
+
+**Side映射：** BUY order = SHORT被清算，SELL order = LONG被清算
+
+---
+
+### 3.8 `auth.py`（384行）— 认证系统
+
+基于JWT的用户认证，邀请码注册制。
+
+**功能：**
+- 注册（需邀请码）/ 登录 / Token刷新
+- Admin管理（邀请码生成/用户封禁）
+- JWT签发（access_token 24h + refresh_token 7d）
+
+**安全：** scrypt密码哈希 + HMAC-SHA256 JWT签名
+
+---
+
+### 3.9 `backtest.py`（503行）— 回测框架
+
+对历史aggTrades数据运行信号引擎，验证策略表现。
+
+**输出指标：** 胜率、PF、夏普比率、最大回撤、按方向/币种统计
+
+---
+
+### 3.10 其他文件
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `backfill_agg_trades.py` | 209 | aggTrades历史数据回补（REST API批量拉取） |
+| `admin_cli.py` | 123 | 命令行管理工具（生成邀请码、管理用户） |
+| `signal_pusher.py` | 108 | **[已废弃]** 旧版信号推送（仍用SQLite，可删除） |
+| `subscriptions.py` | 23 | **[预留]** 订阅系统占位 |
+| `migrate_sqlite_to_pg.py` | 215 | **[一次性]** SQLite→PG数据迁移脚本 |
+| `migrate_auth_sqlite_to_pg.py` | 170 | **[一次性]** Auth SQLite→PG迁移脚本 |
+
+---
+
+## 四、前端文件详解
+
+### 4.1 页面
+
+| 文件 | 行数 | 功能 |
+|------|------|------|
+| `app/page.tsx` | 320 | 首页仪表盘（资金费率卡片 + 概览） |
+| `app/signals/page.tsx` | 523 | 信号引擎（4币种实时评分 + 5层分数展示） |
+| `app/paper/page.tsx` | 459 | 模拟盘（当前持仓 + 历史交易 + 权益曲线 + 按币种统计） |
+| `app/trades/page.tsx` | 384 | 历史交易（筛选、排序、详情） |
+| `app/server/page.tsx` | 279 | 服务器监控（PM2进程 + CPU/内存 + PG状态） |
+| `app/kline/page.tsx` | 170 | K线图 |
+| `app/live/page.tsx` | 130 | 实时数据流 |
+| `app/dashboard/page.tsx` | 112 | 仪表盘 |
+| `app/login/page.tsx` | 75 | 登录 |
+| `app/register/page.tsx` | 88 | 注册（邀请码） |
+| `app/about/page.tsx` | 81 | 关于 |
+| `app/layout.tsx` | 34 | 全局布局 |
+
+### 4.2 组件
+
+| 文件 | 行数 | 功能 |
+|------|------|------|
+| `components/Sidebar.tsx` | 139 | 侧边导航栏 |
+| `components/LiveTradesCard.tsx` | 124 | 实时交易卡片组件 |
+| `components/FundingChart.tsx` | 95 | 资金费率图表（Recharts） |
+| `components/RateCard.tsx` | 82 | 费率展示卡片 |
+| `components/Navbar.tsx` | 71 | 顶部导航 |
+| `components/StatsCard.tsx` | 57 | 统计卡片 |
+| `components/AuthHeader.tsx` | 37 | 认证状态头部 |
+
+### 4.3 工具库
+
+| 文件 | 行数 | 功能 |
+|------|------|------|
+| `lib/auth.tsx` | 137 | JWT管理（存储/刷新/authFetch封装） |
+| `lib/api.ts` | 116 | API请求基础封装 |
+
+---
+
+## 五、数据库Schema
+
+### PostgreSQL（Cloud SQL）
+
+**核心表：**
+
+| 表名 | 说明 | 数据量 |
+|------|------|--------|
+| `agg_trades` | aggTrades分区父表 | 7039万+ |
+| `agg_trades_202602` | 2月分区 | 6854万 |
+| `agg_trades_202603` | 3月分区 | 185万+ |
+| `agg_trades_meta` | 每币种最新agg_id | 4条 |
+| `signal_indicators` | 信号评分记录（每15秒×4币种） | 2.7万+ |
+| `market_indicators` | 市场指标（每5分钟×4币种×5指标） | 5400+ |
+| `paper_trades` | 模拟盘交易记录 | 163+ |
+| `liquidations` | 清算事件原始记录 | 3600+ |
+| `rate_snapshots` | 资金费率快照（旧，K线图用） | 12万+ |
+| `users` | 用户表 | 1 |
+| `invite_codes` | 邀请码 | 1 |
+| `subscriptions` | 订阅信息 | 1 |
+| `refresh_tokens` | JWT刷新令牌 | — |
+| `signal_indicators_1m` | 1分钟粒度信号（备用） | — |
+| `signal_trades` | 信号交易记录（旧） | — |
+| `signal_logs` | 信号日志（旧） | — |
+
+---
+
+## 六、PM2进程列表
+
+| 进程名 | 文件 | 端口 | 说明 |
+|--------|------|------|------|
+| `arb-api` | backend/main.py | 4332 | FastAPI后端 |
+| `arb-web` | frontend/ | 4333 | Next.js前端 |
+| `signal-engine` | backend/signal_engine.py | — | 信号评估引擎 |
+| `paper-monitor` | backend/paper_monitor.py | — | 模拟盘TP/SL监控 |
+| `agg-collector` | backend/agg_trades_collector.py | — | aggTrades采集 |
+| `market-collector` | backend/market_data_collector.py | — | 市场指标采集 |
+| `liq-collector` | backend/liquidation_collector.py | — | 清算数据采集 |
+
+---
+
+## 七、信号源清单
+
+| # | 信号源 | 采集方式 | 存储 | 评分使用 |
+|---|--------|---------|------|---------|
+| 1 | CVD三轨（fast 30m / mid 4h） | aggTrades WS实时计算 | 内存 | ✅ 方向层 |
+| 2 | P99大单流 | aggTrades实时统计 | 内存 | ✅ 方向层 |
+| 3 | CVD加速度 | CVD差分计算 | 内存 | ✅ 方向层+5 bonus |
+| 4 | 多空比 + 大户持仓比 | Binance REST 5min | market_indicators | ✅ 拥挤层 |
+| 5 | OI变化率 | Binance REST 5min | market_indicators | ✅ 环境层 |
+| 6 | Coinbase Premium | Coinbase+Binance价差 | market_indicators | ✅ 辅助层 |
+| 7 | Funding Rate | Binance REST 5min | market_indicators | ⬜ 采集中 |
+| 8 | 清算数据 | Binance WS forceOrder | liquidations + market_indicators | ⬜ 采集中 |
+
+---
+
+## 八、模拟盘配置
+
+| 参数 | 值 |
+|------|-----|
+| 初始资金 | $10,000 |
+| 单笔风险 | 2%（$200 = 1R） |
+| 最大同时持仓 | 4个 |
+| TP1 | 1.5× ATR（平半仓） |
+| TP2 | 3.0× ATR（平剩余） |
+| SL | 1.0× ATR |
+| 手续费 | Taker 0.05% × 2（开仓+平仓） |
+| 反向信号 | 先平仓再开新仓 |
+| 冷却时间 | 同币种同方向300秒 |
+
+---
+
+## 九、部署信息
+
+| 项目 | 详情 |
+|------|------|
+| 运行服务器 | GCP asia-northeast1-b (n2-standard-2, 2核8G) |
+| 数据库 | GCP Cloud SQL PG18 (8核64G 100G) |
+| Cloud SQL 内网IP | 10.106.0.3 |
+| Cloud SQL 公网IP | 34.85.117.248 |
+| Web访问 | https://arb.zhouyangclaw.com |
+| Git仓库 | https://git.darkerilclaw.com/lulu/arbitrage-engine.git |
+| 反向代理 | Caddy（SSL自动） |
+
+---
+
+## 十、版本路线图
+
+| 版本 | 状态 | 内容 |
+|------|------|------|
+| V5.0 | ✅ 完成 | 基础信号系统 + PG迁移 |
+| V5.1 | ✅ 当前 | 5层评分 + 模拟盘 + 6信号源评分 + 2信号源采集 |
+| V5.2 | 📋 计划 | FR+清算加入评分 + 策略配置化 + AB测试 + 24h warmup |
+| V5.3 | 📋 远期 | 推特新闻情绪信号（多模型投票制） |
+
+---
+
+## 十一、已知问题与待改进
+
+1. **signal_pusher.py 已废弃**：仍用SQLite，应删除或重写
+2. **subscriptions.py 空文件**：预留的订阅系统未实现
+3. **history/page.tsx 空页面**：只有5行占位代码
+4. **冷启动warmup只有4小时**：P99大单需要24小时数据（V5.2改进）
+5. **开仓价用信号评估价**：实盘需改为真实成交价
+6. **双写机制**：切主库后agg_collector的本地双写可关闭
+7. **前端缺少错误边界**：API异常时无友好提示