From c8c2d801a214685344342c231d0380ed967a6ef8 Mon Sep 17 00:00:00 2001 From: dev-worker Date: Tue, 3 Mar 2026 05:26:27 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E5=A5=97=E5=88=A9?= =?UTF-8?q?=E5=BC=95=E6=93=8E=E7=A7=81=E6=9C=89=E6=96=87=E6=A1=A3=E7=AB=99?= =?UTF-8?q?=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从private.darkerilclaw.com同步以下文档： - requirements-v1.3.md: 需求定稿v1.3 - v5-signal-system.mdx: V5信号系统文档 - v2-v4-plan.mdx: V2-V4方案 - funding-rate-arbitrage-plan.md: 资金费率套利方案 - phase0-progress.md: Phase0进度 - index.mdx: 项目首页 后续工作流：git仓库先写 → 再同步到私有文档站 --- .../funding-rate-arbitrage-plan.md | 205 +++++++ docs/arbitrage-engine/index.mdx | 20 + docs/arbitrage-engine/phase0-progress.md | 138 +++++ docs/arbitrage-engine/requirements-v1.3.md | 540 ++++++++++++++++++ docs/arbitrage-engine/v2-v4-plan.mdx | 417 ++++++++++++++ docs/arbitrage-engine/v5-signal-system.mdx | 239 ++++++++ 6 files changed, 1559 insertions(+) create mode 100644 docs/arbitrage-engine/funding-rate-arbitrage-plan.md create mode 100644 docs/arbitrage-engine/index.mdx create mode 100644 docs/arbitrage-engine/phase0-progress.md create mode 100644 docs/arbitrage-engine/requirements-v1.3.md create mode 100644 docs/arbitrage-engine/v2-v4-plan.mdx create mode 100644 docs/arbitrage-engine/v5-signal-system.mdx diff --git a/docs/arbitrage-engine/funding-rate-arbitrage-plan.md b/docs/arbitrage-engine/funding-rate-arbitrage-plan.md new file mode 100644 index 0000000..c5db978 --- /dev/null +++ b/docs/arbitrage-engine/funding-rate-arbitrage-plan.md @@ -0,0 +1,205 @@ +--- +title: Funding Rate Arbitrage Plan v2 +--- + +> 初版日期：2026年2月 +> v2更新：2026年2月24日（露露×小周15轮联合数据验证） +> 数据来源：Binance官方API实算，覆盖2019-2026全周期 + +--- + +## 核心定位 + +**自用低风险稳定收益策略**，不依赖行情判断，赚市场机制的钱。 + +- 目标年化：全周期均值 **11-14%**（PM模式净值） +- 风险等级：低（完全对冲，不暴露方向风险） +- 对标：大幅优于债基（年化2%）、银行理财（3-4%） +- 执行方式：**选好点位买入后长期持有不动** + +--- + +## 原理 + +永续合约每8小时结算一次资金费率： +- 多头多 → 多头付钱给空头（费率为正） +- 空头多 → 空头付钱给多头（费率为负） + +**套利做法**：现货买入 + 永续做空，完全对冲币价风险，净收资金费率（USDT结算）。 + +``` +买入1 BTC现货（$96,000） +做空1 BTC永续（$96,000，1倍杠杆） + +BTC涨跌：两边对冲，净盈亏=0 +资金费率：每8小时直接收USDT +``` + +--- + +## 全周期真实数据（2019-2026，Binance实算） + +### BTC（BTCUSDT永续，2019.9至今） + +| 年份 | 年化毛收益 | 市场特征 | +|------|-----------|---------| +| 2019 | 7.48% | 起步期 | +| 2020 | 17.19% | 牛市前奏 | +| **2021** | **30.61%** | **大牛市** | +| 2022 | 4.16% | 熊市 | +| 2023 | 7.87% | 复苏 | +| 2024 | 11.92% | 牛市 | +| 2025 | 5.13% | 震荡 | +| 2026 YTD | 2.71% | 震荡 | +| **全周期均值** | **12.33%** | - | +| **PM净年化** | **11.67%** | 扣0.06%手续费 | + +- 每8小时费率均值：0.011257% +- 负费率占比：13.07% + +### ETH（ETHUSDT永续，2019.11至今） + +| 年份 | 年化毛收益 | 市场特征 | +|------|-----------|---------| +| 2019 | 8.91% | 起步期 | +| 2020 | 27.41% | 牛市前奏 | +| **2021** | **37.54%** | **大牛市** | +| 2022 | 0.79% | 熊市 | +| 2023 | 8.26% | 复苏 | +| 2024 | 12.96% | 牛市 | +| 2025 | 4.93% | 震荡 | +| 2026 YTD | 0.83% | 震荡 | +| **全周期均值** | **14.87%** | - | +| **PM净年化** | **14.09%** | 扣0.06%手续费 | + +- 每8小时费率均值：0.013584% +- 负费率占比：12.17% + +### BTC+ETH 50/50组合 + +- **全周期组合年化毛收益：13.81%** +- **PM净年化：13.08%** + +--- + +## 关键结论（数据验证后确认） + +1. **全周期PM净年化11-14%**，远超债基和银行理财 +2. **收益是USDT**，不承受币价波动风险 +3. **费率为负时不动（A方案）**：负费率仅占12-13%，长期均值为正 +4. **只做BTC和ETH**：流动性最好、费率最稳定，不做山寨币 +5. **年际波动大**：牛市30%+，熊市0-4%，需要耐心 +6. **50万美金在BTC/ETH市场无滑点问题** +7. **策略已被机构验证**：Ethena（TVL数十亿）、Binance Smart Arbitrage、Presto Research回测 + +--- + +## Portfolio Margin（组合保证金）· 必须开通 + +**为什么必须用PM模式**： + +| 维度 | 传统模式 | Portfolio Margin | +|------|---------|-----------------| +| $50万可做规模 | ~$25万（一半做保证金） | ~$47.5万（95%利用率） | +| 额外USDT需求 | 需$25万USDT | 不需要 | +| 年化收益 | ~6%（资金效率低） | ~12%（资金效率高） | +| 风险识别 | 不识别对冲 | 识别对冲，保证金需求低 | + +**PM关键信息**： +- Binance 2024年10月已取消最低余额要求，所有用户可开 +- BTC/ETH抵押率：0.95（5%折扣） +- 支持360+种加密货币作为抵押品 + +**PM风控线**： +- uniMMR < 1.35 → 内部预警 +- uniMMR < 1.25 → 评估减仓 +- uniMMR < 1.20 → Binance限制开新仓 +- uniMMR < 1.05 → 触发强平 + +--- + +## 执行流程 + +### 开仓 +- 确认市场趋势（不急，等好点位） +- 开通Portfolio Margin +- 同时执行：现货买入BTC/ETH + 永续做空等值（1倍杠杆） + +### 持仓 +- **完全不动**，每8小时自动收取资金费率 +- 费率为负不平仓，长期均值为正 +- 只监控uniMMR安全垫 + +### 平仓条件（极端情况） +- 正常情况：**不平仓，长期持有** +- 极端情况：uniMMR接近1.25时评估是否减仓 + +--- + +## 手续费说明（PM模式下影响极小） + +| 操作 | 0.06%费率档 | $50万单次 | +|------|-----------|----------| +| 现货买入 | 0.06% | $285 | +| 永续开空 | 0.02% | $95 | +| **开仓合计** | | **$380** | + +因为"买入后不动"，手续费只在开仓时发生一次。 +$50万本金年收益约$6万（12%），$380手续费可忽略。 + +--- + +## 风险清单 + +| 风险 | 严重程度 | 说明 | +|------|---------|------| +| 市场周期 | ⚠️ 中 | 熊市年化可降至0-4%，但不亏本金 | +| 费率持续为负 | 🟢 低 | 历史负费率占比仅12-13%，长期均值为正 | +| 交易所对手方 | ⚠️ 中 | FTX教训，建议未来考虑分散 | +| 爆仓（PM模式） | 🟢 低 | 1倍杠杆+对冲，理论需BTC翻倍才触发 | +| 基差波动 | 🟢 低 | 长期持有不影响，只影响平仓时机 | + +--- + +## 与替代方案对比 + +| 方案 | 年化 | 风险 | 操作难度 | 备注 | +|------|------|------|---------|------| +| **本方案（自建）** | 11-14% | 低 | 中 | 完全自主可控 | +| Ethena sUSDe | 4-15% | 中（合约风险） | 低 | DeFi，依赖协议安全 | +| Binance Smart Arbitrage | 未知 | 低 | 低 | 官方产品，黑盒 | +| 银行理财 | 3-4% | 极低 | 无 | 对标基准 | +| 债基 | 2% | 低 | 无 | 对标基准 | + +--- + +## 执行计划 + +### 第一阶段：准备（现在） +- [ ] 开通Binance Portfolio Margin +- [ ] 确认VIP等级和手续费档位 +- [ ] 准备资金（USDT入金） + +### 第二阶段：模拟验证（可选，1-2个月） +- [ ] 搭建模拟系统，实时跑数据验证 +- [ ] 对比模拟结果与历史回测 + +### 第三阶段：入场 +- [ ] 等待合适入场时机（趋势确认） +- [ ] 同时开BTC+ETH对冲仓位 +- [ ] 开始收费率 + +### 第四阶段：长期持有 +- [ ] 每日检查uniMMR安全垫 +- [ ] 每周记录累计收益 +- [ ] 不主动平仓，长期持有 + +--- + +## 数据验证过程 + +本文档数据经过露露（Claude Opus 4.6）和小周（GPT-5.3-Codex）15轮交叉验证： +- 数据来源：Binance fapi/v1/fundingRate 官方API +- 覆盖周期：2019年9月至2026年2月（约6.5年） +- 验证内容：费率均值、年化收益、负费率占比、手续费敏感性、PM模式资金效率 +- 外部参考：Presto Research、Ethena、CoinCryptoRank、FMZ量化 diff --git a/docs/arbitrage-engine/index.mdx b/docs/arbitrage-engine/index.mdx new file mode 100644 index 0000000..3f05adc --- /dev/null +++ b/docs/arbitrage-engine/index.mdx @@ -0,0 +1,20 @@ +--- +title: Project ArbitrageEngine +--- + +套利引擎（ArbitrageEngine，简称 AE）— 资金费率自动化套利系统 + 短线交易信号系统。 + +## 当前状态 + +🟢 **V2-V4 已上线** — 权限管控 + aggTrades采集 + 成交流分析面板 +🟡 **V5 方案定稿** — 短线交易信号系统，待开发 +🔗 **面板地址**：https://arb.zhouyangclaw.com +⏳ **实盘阻塞**：等范总提供Binance API Key + PM + 资金 + +## 文档 + +- [V5 短线交易信号系统方案](/docs/project-arbitrage-engine/v5-signal-system) — 信号体系、风控、回测方案、开发路线图 🆕 +- [V2-V4 产品技术文档](/docs/project-arbitrage-engine/v2-v4-plan) — 权限管控 / aggTrades / 成交流面板 +- [Phase 0 开发进度](/docs/project-arbitrage-engine/phase0-progress) — 已完成功能、Git结构 +- [Funding Rate Arbitrage Plan v2](/docs/project-arbitrage-engine/funding-rate-arbitrage-plan) — 策略原理、数据验证、执行方案 +- [Requirements v1.3.1](/docs/project-arbitrage-engine/requirements-v1.3) — 完整PRD（产品+技术+商业） diff --git a/docs/arbitrage-engine/phase0-progress.md b/docs/arbitrage-engine/phase0-progress.md new file mode 100644 index 0000000..5723931 --- /dev/null +++ b/docs/arbitrage-engine/phase0-progress.md @@ -0,0 +1,138 @@ +--- +title: Phase 0 开发进度 +--- + +> 更新日期：2026年2月27日 +> 状态：🟡 Phase 0 进行中（监控面板已上线，SaaS MVP已上线） + +--- + +## Phase 0 — 已完成 + +### 监控面板（arb.zhouyangclaw.com）✅ + +**上线时间**：2026-02-26 + +**技术栈**： +- 后端：FastAPI（Python，端口4332） +- 前端：Next.js 16 + shadcn/ui + Tailwind + Recharts（端口4333） +- 部署：小周服务器 34.84.9.167，Caddy反代，HTTPS + +**已实现功能**： + +| 页面 | 功能 | 状态 | +|------|------|------| +| 仪表盘（/） | BTC/ETH实时费率、标记价格、下次结算时间 | ✅ 2秒刷新 | +| 历史（/history） | 过去7天费率走势图（Recharts折线图）+ 历史记录表格 | ✅ | +| 信号（/signals） | 套利信号历史记录（触发时间/币种/年化） | ✅ | +| 说明（/about） | 策略原理、历史年化数据表、风险说明 | ✅ | + +**API端点**： +``` +GET /api/health — 健康检查 +GET /api/rates — 实时资金费率（BTC/ETH） +GET /api/history — 7天历史费率数据 +GET /api/stats — 7天统计（均值/年化/50-50组合） +``` + +**性能优化**： +- rates：3秒缓存（2秒前端刷新，不会触发限速） +- history/stats：60秒缓存（避免Binance API限速） +- User-Agent已设置（防403） + +--- + +### 信号推送系统 ✅ + +**逻辑**：BTC或ETH 7日年化 > 10% 时自动触发 + +**推送渠道**：Discord Bot API（#agent-team频道） + +**信号格式**： +``` +📊 套利信号 +BTC 7日年化: 12.33% +ETH 7日年化: 8.17% +建议：BTC 现货+永续对冲可开仓 +时间: 2026-02-26 14:00 UTC +``` + +**定时任务**：每小时检查一次（crontab，小周服务器） + +**数据库**：SQLite（arb.db），signal_logs表记录推送历史 + +--- + +### SaaS MVP 用户系统 ✅ + +**上线时间**：2026-02-26 + +**新增页面**： + +| 页面 | 功能 | +|------|------| +| /register | 邮箱+密码注册，支持绑定Discord ID | +| /login | JWT登录 | +| /dashboard | 用户面板：订阅等级、Discord绑定、升级入口 | + +**API端点**： +``` +POST /api/auth/register — 注册 +POST /api/auth/login — 登录（返回JWT） +POST /api/user/bind-discord — 绑定Discord ID +GET /api/user/me — 获取用户信息 +GET /api/signals/history — 信号历史 +``` + +**订阅等级预设**（支付接入前为占位）： +| 等级 | 价格 | 功能 | +|------|------|------| +| 免费 | ¥0 | 实时费率面板 | +| Pro | ¥99/月 | 信号推送+历史数据 | +| Premium | ¥299/月 | Pro全部+定制阈值+优先客服 | + +--- + +## Git仓库 + +- **地址**：https://git.darkerilclaw.com/lulu/arbitrage-engine +- **主要目录结构**： + ``` + backend/ + main.py — FastAPI主文件（rates/history/stats + 缓存） + auth.py — 用户注册/登录/JWT + subscriptions.py — 订阅管理 + signal_pusher.py — 信号检测+Discord推送 + frontend/ + app/ + page.tsx — 仪表盘 + history/ — 历史页 + signals/ — 信号历史页 + about/ — 策略说明页 + register/ — 注册页 + login/ — 登录页 + dashboard/ — 用户面板 + components/ + Navbar.tsx — 响应式导航（手机端汉堡菜单） + RateCard.tsx — 费率卡片 + StatsCard.tsx — 统计卡片 + FundingChart.tsx — 费率走势图 + ``` + +--- + +## Phase 1 — 待开发 + +> 需范总提供Binance API Key后开始 + +| 功能 | 依赖 | 预估工时 | +|------|------|---------| +| 接入真实Binance账户余额/持仓 | Binance API Key（只读权限） | 1天 | +| 手动开仓/平仓界面 | 范总确认Portfolio Margin已开通 | 2天 | +| 自动再平衡（持仓期间） | Phase 1基础完成后 | 2天 | +| 风控熔断+自动告警 | — | 1天 | + +**Phase 1开启条件（范总需提供）**： +1. Binance API Key（Read + Trade，禁止Withdraw） +2. 确认Portfolio Margin账户已开通 +3. 初始资金就位（建议$500 = BTC$250 + ETH$250） diff --git a/docs/arbitrage-engine/requirements-v1.3.md b/docs/arbitrage-engine/requirements-v1.3.md new file mode 100644 index 0000000..dd7c362 --- /dev/null +++ b/docs/arbitrage-engine/requirements-v1.3.md @@ -0,0 +1,540 @@ +--- +title: Requirements v1.3.1 +--- + +> 定稿日期：2026年2月24日 +> 参与：露露（Claude Opus 4.6）、小周（GPT-5.3-Codex）、范总确认 +> 状态：✅ 需求锁定，待开发 +> 版本：v1.3.1（部署方案确认） + +--- + +## 0. 文档定位 + +- **文档类型**：项目基石级 PRD + 技术需求定稿（用于研发、验收、后续商业化） +- **优先级**：安全性 > 可控性 > 稳定性 > 收益表现 > 开发速度 +- **约束前提**：先需求锁定，再开发；先 API 全测通，再实盘；先 Dry Run 1 周，再 Real + +--- + +## 1. 项目定义与商业化定位 + +- **产品名**：套利引擎（ArbitrageEngine，简称 AE） +- **定位升级**：从 v1.2 的"范总单用户工具"升级为"可商业化产品雏形" + - Phase 1：服务范总实盘验证（单用户形态） + - 但架构上 Day1 预埋多租户和计费能力，避免二次重构 +- **核心价值主张**： + - 对用户：低门槛执行资金费率套利（PM + 风控 + 可视化） + - 对团队：沉淀可复制交易基础设施，具备对外 SaaS 化能力 +- **竞争差异化**： + - 完整前端（非CLI黑框） + - 安全第一（TOTP、审计、熔断） + - Dry Run验证（降低用户心理门槛） + - PM优化（资金效率提升） + - 自定义风控（非黑盒） + +--- + +## 2. 目标与边界 + +**目标（Phase 1）**： +- Binance 上完成 BTC/ETH 对冲套利闭环 +- 支持 PM 模式，执行"开/平人工确认，中间自动运行" +- 全链路审计、风控、告警、报表可用 + +**非目标（Phase 1 不做）**： +- 不做多交易所聚合 +- 不做自动择时开平仓 +- 不做资金托管与代客资管 +- 不做公开注册与支付计费（仅预埋） + +--- + +## 3. 已确认业务决策（锁定） + +| 项目 | 确认结果 | +|------|---------| +| 执行模式 | C — 开仓/平仓需人工确认，持仓期间自动化 | +| 初始实盘资金 | $500（BTC $250 + ETH $250） | +| 收益处理 | 留账户复利，不自动提取 | +| 部署服务器 | 小周服务器 34.84.9.167（GCP东京，Binance延迟11ms） | +| 上线节奏 | Phase 0 API测通 → Dry Run 1周 → Real 2个月 | +| 费率为负 | 完全不动（A方案） | + +--- + +## 4. 系统状态机 + +### 模式状态 +``` +DRY_RUN ──(Phase 0 checklist 100%通过 + 范总确认)──→ REAL +REAL ──(手动降级)──→ DRY_RUN +``` + +### 交易生命周期 +``` +IDLE ──(用户点"开始执行"+二次确认)──→ OPENING +OPENING ──(双腿成交+偏差≤1%)──→ HOLDING +OPENING ──(单边失败+补偿失败/超时/API连续失败)──→ HALTED +HOLDING ──(用户点"平仓"+确认)──→ CLOSING +HOLDING ──(uniMMR<1.25)──→ HALTED（不自动平仓，禁止新操作，立即告警） +CLOSING ──(双腿平完+仓位归零)──→ IDLE +任意状态 ──(硬风控触发/关键系统异常)──→ HALTED +HALTED ──(范总手动恢复)──→ IDLE +``` + +--- + +## 5. 风控参数（硬编码，不可前端修改） + +| 参数 | 值 | 说明 | +|------|-----|------| +| 最大单次名义 | $600 | $500本金+20%缓冲 | +| 最大滑点 | 0.10% | 超过取消下单 | +| 最大对冲偏差 | 1.00% | \|spot-perp\|/target | +| 最大杠杆 | 1x | 不可修改 | +| uniMMR预警线 | 1.35 | 告警 | +| uniMMR危险线 | 1.25 | 自动HALTED | +| API失败熔断 | 连续5次 | 进入HALTED | +| 单腿超时（补单） | 8s | 触发补单逻辑 | +| 单腿超时（熔断） | 30s | 触发HALTED | +| 时钟漂移阈值 | >1000ms | 禁止交易请求 | + +--- + +## 6. Dry Run 对照机制 + +Dry Run 期间必须记录"拟交易账本"： +- 拟下单价格、拟成交数量、拟手续费、拟持仓 +- 拟资金费率收入（按实际市场费率与拟仓位估算） + +**产出对照报告**： +- 如果 Real 执行，理论会得到的收益区间 +- 引擎计算准确性与一致性验证 + +**通过标准**：Dry Run 1周内无关键错配、无状态机死锁、无风险漏报 + +--- + +## 7. 功能模块清单（Phase 1） + +### 认证与安全 +- 账号密码 + TOTP（Google Authenticator） +- 会话超时（30分钟） +- 连续登录失败锁定（5次失败后锁定15分钟） +- 审计日志全记录（append-only） + +### Binance 接入 +- API权限自检（Read/Trade only，禁Withdraw） +- 行情、费率、账户、持仓、下单、回查 +- 连接状态实时监控（心跳检测） +- API调用频率控制（避免触发限流） + +### 执行引擎 +- REST并发下单（现货买入 + 永续做空同时发出） +- WebSocket订阅成交回报、仓位变化 +- 单边失败补偿、对冲偏差修复、熔断 +- 下单前检查：余额、价格、滑点预估 + +### 监控告警 +- uniMMR、对冲偏差、当前/预测费率、累计收益 +- Discord实时告警 + 每日自动汇报 +- 双通道告警预留（Discord + 邮件/短信） + +### 报表 +- 8小时/日/周/月收益统计 +- 手续费统计、资金费率贡献 +- 净值曲线图表 +- Dry Run对照报告 + +### 运维 +- PM2健康检查、自动拉起 +- 重启后自动对账恢复 +- 分api/worker进程 + +--- + +## 8. 多租户架构预埋（v1.3核心新增） + +### 数据模型要求 +- 所有核心业务表强制包含 `user_id`（或 `tenant_id`） + +### 执行隔离要求 +- Worker任务必须携带 `user_id` 上下文 +- 严禁跨用户读取订单、仓位、密钥、日志 + +### 密钥管理 +- 按用户分区加密存储（每用户独立密钥上下文） +- 主密钥与业务库分离，密钥不落盘 + +### 权限模型预留 +- 用户表保留 `role` 字段（RBAC扩展位） +- 前端不写死"唯一管理员" + +### 审计不可篡改 +- 审计日志 append-only，禁止更新/删除业务接口 +- 仅允许归档，不允许逻辑改写 +- 预留哈希链字段（后续可选） + +--- + +## 9. Binance API 接口清单 + +### 认证与账户（Phase 0 必测） +| 接口 | 用途 | +|------|------| +| `GET /api/v3/account` | Spot账户资产、权限 | +| `GET /fapi/v2/account` | Futures账户信息 | +| `GET /fapi/v2/balance` | Futures余额 | +| `GET /fapi/v2/positionRisk` | 永续持仓风险 | +| `GET /fapi/v1/leverageBracket` | 杠杆/名义分档 | +| `GET /sapi/v1/portfolio/account` | PM账户信息 | + +### 行情与费率 +| 接口 | 用途 | +|------|------| +| `GET /api/v3/ticker/bookTicker` | Spot最优买卖价 | +| `GET /fapi/v1/ticker/bookTicker` | Perp最优买卖价 | +| `GET /fapi/v1/premiumIndex` | 标记价格+当前/预测费率 | +| `GET /fapi/v1/fundingRate` | 历史费率 | +| `GET /api/v3/depth` | Spot深度（滑点估算） | +| `GET /fapi/v1/depth` | Perp深度（滑点估算） | + +### 交易执行 +| 接口 | 用途 | +|------|------| +| `POST /api/v3/order` | Spot下单（市价/限价） | +| `GET /api/v3/order` | Spot订单回查 | +| `DELETE /api/v3/order` | Spot撤单 | +| `POST /fapi/v1/order` | Futures下单（开空/平空） | +| `GET /fapi/v1/order` | Futures订单回查 | +| `DELETE /fapi/v1/order` | Futures撤单 | +| `GET /fapi/v1/openOrders` | 未完成单查询 | +| WebSocket listenKey | 成交回报+仓位变化 | + +### 资金与收益 +| 接口 | 用途 | +|------|------| +| `GET /fapi/v1/income` | 资金费率收入、手续费、盈亏 | +| `GET /fapi/v2/positionRisk` | 未实现PnL、保证金风险 | + +--- + +## 10. 前端页面清单 + +### `/login` +- 用户名/密码 + TOTP输入 +- 登录审计记录 + +### `/dashboard` +- 当前模式（Dry Run / Real）+ 状态机状态 +- BTC/ETH仓位卡片：持仓量、对冲偏差、当前/预测费率 +- uniMMR + 风险灯（🟢 >1.35 / 🟡 1.25-1.35 / 🔴 <1.25） +- 当日收益、累计收益、手续费 +- 净值收益曲线图 + +### `/execute` +- 参数展示（只读）：BTC $250 / ETH $250 +- 「开始执行（开仓）」按钮（二次确认弹窗） +- 「请求平仓」按钮（二次确认弹窗） +- 执行过程实时日志流（SSE） + +### `/risk` +- 风控阈值参数表（只读展示） +- 告警历史列表 +- 熔断记录 + 恢复操作按钮 + +### `/records` +- 订单记录（Spot/Futures，可筛选） +- 费率收入记录（8h维度，可按日/周/月汇总） +- 审计日志（全操作记录） + +### `/settings` +- API Key配置（加密存储，显示为***） +- Discord Webhook配置 +- 模式切换（Dry Run ↔ Real，需二次确认） + +--- + +## 11. 数据库结构（PostgreSQL，v1.3） + +```sql +-- 用户（多租户预埋） +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + username VARCHAR(64) UNIQUE NOT NULL, + password_hash VARCHAR(256) NOT NULL, + totp_secret_enc VARCHAR(256) NOT NULL, + role VARCHAR(16) DEFAULT 'admin', -- RBAC预留 + status VARCHAR(16) DEFAULT 'active', + created_at TIMESTAMPTZ DEFAULT NOW(), + last_login_at TIMESTAMPTZ +); + +-- API凭据（按用户分区） +CREATE TABLE api_credentials ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + account_name VARCHAR(64), + api_key_enc TEXT NOT NULL, + api_secret_enc TEXT NOT NULL, + perm_read BOOLEAN DEFAULT true, + perm_trade BOOLEAN DEFAULT true, + perm_withdraw BOOLEAN DEFAULT false, + ip_whitelist_ok BOOLEAN DEFAULT false, + pm_enabled BOOLEAN DEFAULT false, + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW() +); + +-- 策略实例 +CREATE TABLE strategy_instances ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + mode VARCHAR(16) NOT NULL, -- DRY_RUN / REAL + state VARCHAR(16) NOT NULL, -- IDLE / OPENING / HOLDING / CLOSING / HALTED + base_capital DECIMAL(18,2), + btc_alloc DECIMAL(18,2), + eth_alloc DECIMAL(18,2), + started_at TIMESTAMPTZ, + closed_at TIMESTAMPTZ +); + +-- 订单 +CREATE TABLE orders ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + strategy_id INT REFERENCES strategy_instances(id), + venue VARCHAR(8) NOT NULL, -- SPOT / FUTURES + symbol VARCHAR(16) NOT NULL, + side VARCHAR(8) NOT NULL, + type VARCHAR(16) NOT NULL, + client_order_id VARCHAR(64), + exchange_order_id VARCHAR(64), + price DECIMAL(18,8), + orig_qty DECIMAL(18,8), + executed_qty DECIMAL(18,8), + status VARCHAR(16), + is_reduce_only BOOLEAN DEFAULT false, + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW() +); + +-- 仓位快照 +CREATE TABLE positions_snapshot ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + strategy_id INT REFERENCES strategy_instances(id), + symbol VARCHAR(16) NOT NULL, + spot_qty DECIMAL(18,8), + futures_qty DECIMAL(18,8), + spot_notional DECIMAL(18,2), + futures_notional DECIMAL(18,2), + hedge_deviation DECIMAL(8,4), + mark_price DECIMAL(18,2), + captured_at TIMESTAMPTZ DEFAULT NOW() +); + +-- 资金费率收入 +CREATE TABLE funding_income ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + symbol VARCHAR(16) NOT NULL, + funding_time TIMESTAMPTZ NOT NULL, + income_asset VARCHAR(8), + income_amount DECIMAL(18,8), + rate DECIMAL(18,8), + position_notional DECIMAL(18,2), + source_tx_id VARCHAR(64) +); + +-- 风控事件 +CREATE TABLE risk_events ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + strategy_id INT REFERENCES strategy_instances(id), + event_type VARCHAR(32) NOT NULL, + severity VARCHAR(16) NOT NULL, + metric_value DECIMAL(18,8), + threshold_value DECIMAL(18,8), + action_taken VARCHAR(64), + created_at TIMESTAMPTZ DEFAULT NOW() +); + +-- 审计日志（append-only，不可删改） +CREATE TABLE audit_logs ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id), + actor VARCHAR(64) NOT NULL, + action VARCHAR(64) NOT NULL, + target VARCHAR(128), + payload_json JSONB, + ip VARCHAR(64), + hash_chain VARCHAR(128), -- 预留哈希链字段 + created_at TIMESTAMPTZ DEFAULT NOW() +); + +-- 系统运行记录 +CREATE TABLE system_runs ( + id SERIAL PRIMARY KEY, + user_id INT REFERENCES users(id) NOT NULL, + mode VARCHAR(16) NOT NULL, + start_at TIMESTAMPTZ NOT NULL, + end_at TIMESTAMPTZ, + result VARCHAR(16), + notes TEXT +); +``` + +--- + +## 12. 三阶段产品路线图 + +| 阶段 | 目标 | 交付 | 预计周期 | +|------|------|------|---------| +| **Phase 1** | 范总$500跑通2个月 | 单用户验证版（含风控+审计+告警+报表） | 开发2-3周 + 实盘2月 | +| **Phase 2** | 开放小规模内测 | 注册体系+RBAC+订阅计费+运维扩容 | 2-4周 | +| **Phase 3** | 公开获客规模化 | 营销站点+渠道投放+客户成功+合规增强 | 持续 | + +--- + +## 13. Phase 2 新增模块预览 + +### 账户体系 +- 注册、邮箱验证、找回密码、设备管理、2FA强制策略 + +### RBAC权限 +- Owner / Admin / Operator / Viewer 角色与资源权限矩阵 + +### 订阅计费 +- 套餐分层、试用期、续费、到期降级、账单与发票记录 + +### 多租户运维 +- 队列隔离、限流配额、租户级熔断、租户级监控面板 + +### 客服与支持 +- 工单、系统公告、状态页 + +--- + +## 14. 商业模式设计 + +### 方案A：SaaS订阅制（推荐先做） +- 参考定价：$29 / $59 / $99 月费分层（按功能与账户规模） +- 优势：合规压力相对低、收入稳定、扩展快 +- 用户资金在自己Binance账户，平台不碰钱 + +### 方案B：收益分成制（后评估） +- 管理费（1-2%/年）+ 超额收益分成（20%） +- 风险：合规、牌照、托管责任显著上升 + +### 建议路径 +- 先SaaS，再评估收益分成 +- 不在Phase 1/2落地资管模式 + +--- + +## 15. 技术选型（锁定） + +| 层 | 技术 | 说明 | +|-----|------|------| +| 执行层 | 自建引擎 | 不fork Hummingbot | +| API层 | Binance官方SDK | `@binance/connector` | +| 后端 | Node.js + Express | 和灵镜统一 | +| 前端 | Next.js | 深色UI | +| 数据库 | PostgreSQL | 多租户友好 | +| 进程管理 | PM2 | 分api/worker | +| 部署 | 34.84.9.167 (GCP东京) | Binance延迟11ms | + +--- + +## 15.1 部署与网络安全方案（v1.3.1 新增） + +### 部署服务器 +- **机器**：34.84.9.167（GCP asia-northeast1-b） +- **选择理由**： + - Binance API TCP延迟 11ms（露露服务器22ms的一半） + - 内存可用 6.4GB、磁盘可用 187GB + - 仅1个PM2服务运行，负载极低 + - GCP基础设施安全性高于普通VPS + - 非root用户运行（fzq1228） + +### 网络访问方案（域名 + HTTPS + 强认证） +- **访问方式**：子域名 + Caddy自动HTTPS +- **不使用IP白名单**（范总IP不固定） +- **安全靠认证层保障**： + +| 安全层 | 措施 | +|--------|------| +| 传输层 | HTTPS（Caddy自动TLS证书） | +| 认证层 | 账号密码 + TOTP双因素 | +| 会话层 | 30分钟超时自动登出 | +| 防暴破 | 连续5次登录失败锁定15分钟 | +| 审计层 | 所有登录/操作记录，append-only | +| 数据库 | PostgreSQL仅监听localhost | +| 进程隔离 | 单独系统用户运行套利引擎 | + +### GCP防火墙规则（需配置） +- 开放端口：仅HTTPS（443） +- 其他端口：全部关闭 +- SSH：仅密钥登录 + +### Phase 2 安全升级路径 +- 可选：Cloudflare Zero Trust（Tunnel + Access认证） +- 可选：WAF规则（防SQL注入/XSS） +- 可选：Cloudflare Access策略（邮箱OTP二次验证） + +--- + +## 16. Phase 0 验收Checklist + +### 认证与权限 +- [ ] API签名请求成功 +- [ ] 读取余额成功 +- [ ] 读取持仓成功 +- [ ] 验证无提现权限 +- [ ] PM状态可读 + +### 行情与费率 +- [ ] Spot/Perp bookTicker可读 +- [ ] premiumIndex可读 +- [ ] fundingRate历史可拉取（BTC/ETH） +- [ ] 深度数据可拉取 + +### 交易闭环 +- [ ] Spot下单/回查/撤单成功 +- [ ] Futures下单/回查/撤单成功 +- [ ] WebSocket成交推送正常 +- [ ] 单腿失败补偿流程演练通过 +- [ ] 熔断触发与恢复流程通过 + +### 风控机制 +- [ ] 滑点超阈拦截通过 +- [ ] 对冲偏差超阈拦截通过 +- [ ] API连续失败熔断通过 +- [ ] 重启后自动对账通过 +- [ ] uniMMR预警/危险触发通过 + +### 报表与告警 +- [ ] 8小时收益计算正确 +- [ ] 每日汇报自动推送成功 +- [ ] 异常告警实时送达成功 + +**验收标准**：Checklist 100%通过才允许进入 1周 Dry Run。 + +--- + +## 17. 风险与原则 + +- **原则**：真金白银系统，宁慢勿错 +- **风险优先级**：执行错误 > 权限泄露 > 可用性 > 收益偏差 +- **处置原则**：触发风险先停机后恢复，先对账后继续 + +--- + +## 18. 下一步（文档后动作） + +1. 独立服务器准备完成 +2. API Key权限配置完成（Read+Trade，禁Withdraw，白名单） +3. Phase 0执行计划与验收人确认 +4. 开始开发 diff --git a/docs/arbitrage-engine/v2-v4-plan.mdx b/docs/arbitrage-engine/v2-v4-plan.mdx new file mode 100644 index 0000000..9b9639b --- /dev/null +++ b/docs/arbitrage-engine/v2-v4-plan.mdx @@ -0,0 +1,417 @@ +--- +title: Arbitrage Engine V2-V4 产品+技术文档 +description: 权限管控、aggTrades全量采集、成交流分析面板的完整设计 +--- + +# Arbitrage Engine V2-V4 产品+技术文档 + +## 1. 项目概述 + +### 1.1 当前状态（V1.0 ✅） +- 实时BTC/ETH资金费率监控（2秒刷新） +- K线图（本地2秒粒度聚合，9个周期） +- 历史费率走势 + 明细表 +- YTD年化统计 +- 信号推送（Discord） +- 用户注册/登录框架（无鉴权保护） +- URL: https://arb.zhouyangclaw.com + +### 1.2 战略升级方向 +从「公开费率监控面板」升级为「私有交易数据研究平台」。 + +核心目标： +1. 收集全量逐笔成交数据，建立独家数据资产 +2. 结合K线与成交流，研究价格变动的微观成因 +3. 通过复盘标注→模式识别→模拟盘验证，逐步量化短线策略 +4. 数据不公开，邀请制访问 + +### 1.3 核心定位 +> 炒币是情绪盘，每一段价格背后都代表着集体情绪走向。K线是情绪的结果，成交流是情绪的过程。我们要看到过程。 + +--- + +## 2. V2.0 — 权限管控 + 邀请制 + +### 2.1 JWT鉴权设计 + +**Token体系：** +| Token | 有效期 | 用途 | +|-------|--------|------| +| Access Token | 24小时 | API请求鉴权（放header） | +| Refresh Token | 7天 | 刷新access token | + +**实现策略：** 在现有`auth.py`基础上增量改造，不重写。 + +**新增接口：** +- `POST /api/auth/login` → 返回 `{access_token, refresh_token, expires_in}` +- `POST /api/auth/refresh` → 用refresh token换新access token +- `POST /api/auth/register` → 注册（必须提供有效邀请码） +- `GET /api/auth/me` → 当前用户信息 + +**依赖库：** `python-jose[cryptography]` 或 `PyJWT` + +### 2.2 邀请码机制 + +**表结构：** +```sql +CREATE TABLE invite_codes ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + code TEXT UNIQUE NOT NULL, -- 8位随机码 + created_by INTEGER, -- admin user_id + max_uses INTEGER DEFAULT 1, -- 默认一码一用 + used_count INTEGER DEFAULT 0, + status TEXT DEFAULT 'active', -- active/disabled/exhausted + expires_at TEXT, -- 可选过期时间 + created_at TEXT DEFAULT (datetime('now')) +); + +CREATE TABLE invite_usage ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + code_id INTEGER NOT NULL, + user_id INTEGER NOT NULL, + used_at TEXT DEFAULT (datetime('now')), + FOREIGN KEY (code_id) REFERENCES invite_codes(id), + FOREIGN KEY (user_id) REFERENCES users(id) +); +``` + +**注册流程：** +1. 用户填写邀请码 + 用户名 + 密码 +2. 后端验证：邀请码存在 + status=active + used_count < max_uses + 未过期 +3. 创建用户 → 记录使用 → used_count+1 +4. 返回JWT token对 + +### 2.3 路由保护 + +**公开路由（无需登录）：** +- `GET /api/health` +- `POST /api/auth/login` +- `POST /api/auth/register` +- `POST /api/auth/refresh` +- `GET /api/rates`（基础费率，作为引流） + +**受保护路由（需登录）：** +- `GET /api/kline` +- `GET /api/snapshots` +- `GET /api/history` +- `GET /api/stats` +- `GET /api/stats/ytd` +- `GET /api/signals/history` +- `GET /api/trades/*`（V3新增） +- `GET /api/analysis/*`（V4新增） + +**Admin路由（需admin角色）：** +- `POST /api/admin/invite-codes` — 生成邀请码 +- `GET /api/admin/invite-codes` — 查看所有邀请码 +- `DELETE /api/admin/invite-codes/:id` — 禁用邀请码 +- `GET /api/admin/users` — 查看所有用户 +- `PUT /api/admin/users/:id/ban` — 封禁用户 + +### 2.4 权限模型 + +| 资源 | Guest | User | Admin | +|------|-------|------|-------| +| 基础费率 | ✅ | ✅ | ✅ | +| K线/历史/统计 | ❌ | ✅ | ✅ | +| 成交流数据 | ❌ | ✅ | ✅ | +| 分析面板 | ❌ | ✅ | ✅ | +| 标注 | ❌ | ✅(自己) | ✅(全部) | +| 邀请码管理 | ❌ | ❌ | ✅ | +| 用户管理 | ❌ | ❌ | ✅ | + +### 2.5 Admin CLI工具 + +```bash +# 生成邀请码 +python3 admin_cli.py gen-invite --count 5 + +# 查看邀请码状态 +python3 admin_cli.py list-invites + +# 禁用邀请码 +python3 admin_cli.py disable-invite CODE123 + +# 查看用户 +python3 admin_cli.py list-users + +# 封禁用户 +python3 admin_cli.py ban-user 42 +``` + +### 2.6 前端改造 + +- 未登录用户：仪表盘只显示实时费率卡片（引流），其他区域显示blur遮挡 + 「登录后查看」 +- 登录页：用户名 + 密码 + 邀请码（注册时） +- Token存储：`localStorage`（access_token + refresh_token） +- 请求拦截器：自动带token、过期自动刷新 +- 401处理：跳转登录页 + +### 2.7 验收标准 +- [ ] 无邀请码无法注册 +- [ ] 无token访问受保护API返回401 +- [ ] Token过期后refresh成功 +- [ ] Admin API非admin用户返回403 +- [ ] 前端未登录正确遮挡数据区域 + +--- + +## 3. V3.0 — aggTrades全量采集 + +### 3.1 数据模型 + +**按月分表，单库（arb.db）：** +```sql +-- 自动建表（每月1张） +CREATE TABLE IF NOT EXISTS agg_trades_202602 ( + agg_id INTEGER PRIMARY KEY, -- Binance aggTradeId（天然唯一） + symbol TEXT NOT NULL, -- BTCUSDT / ETHUSDT + price REAL NOT NULL, + qty REAL NOT NULL, + first_trade_id INTEGER, + last_trade_id INTEGER, + time_ms INTEGER NOT NULL, -- 成交时间(毫秒) + is_buyer_maker INTEGER NOT NULL -- 0=主动买, 1=主动卖 +); + +CREATE INDEX IF NOT EXISTS idx_agg_trades_202602_time + ON agg_trades_202602(symbol, time_ms); +``` + +**辅助表：** +```sql +CREATE TABLE agg_trades_meta ( + symbol TEXT PRIMARY KEY, + last_agg_id INTEGER NOT NULL, -- 最后写入的agg_id + last_time_ms INTEGER NOT NULL, -- 最后写入的时间 + updated_at TEXT DEFAULT (datetime('now')) +); +``` + +### 3.2 采集架构 + +``` +┌─────────────────────┐ +│ WebSocket主链路 │ ← wss://fstream.binance.com/ws/btcusdt@aggTrade +│ (实时推送) │ ← wss://fstream.binance.com/ws/ethusdt@aggTrade +└──────┬──────────────┘ + │ 攒200条 or 1秒 + ▼ +┌─────────────────────┐ +│ 批量写入器 │ → INSERT OR IGNORE INTO agg_trades_YYYYMM +│ (去重+分表路由) │ → UPDATE agg_trades_meta +└──────┬──────────────┘ + │ +┌──────┴──────────────┐ +│ 补洞巡检（每分钟） │ → 检查agg_id连续性 +│ │ → REST /fapi/v1/aggTrades?fromId=X 补缺 +└─────────────────────┘ +``` + +**断线重连流程：** +1. WS断线 → 立即重连 +2. 读取`last_agg_id` → REST `fromId=last_agg_id+1` 批量拉取（每次1000条） +3. 追平后切回WS流 +4. 全程记日志 + +### 3.3 写入优化 + +- 批量大小：200条 or 1秒（取先到者） +- SQLite WAL模式 + `PRAGMA synchronous=NORMAL` +- 单线程写入，避免锁竞争 +- 月初自动建新表 + +### 3.4 去重策略 + +- `agg_id`作为PRIMARY KEY，`INSERT OR IGNORE`天然去重 +- WS和REST可能有重叠，完全靠PK去重，零额外成本 + +### 3.5 监控与告警 + +| 指标 | 阈值 | 动作 | +|------|------|------| +| 采集中断 | >30秒无新数据 | Discord告警 | +| agg_id断档 | 缺口>10 | 自动REST补洞 | +| 写入延迟P95 | >500ms | 日志警告 | +| 磁盘占用 | >80% | Discord告警 | +| 日数据完整性 | 缺口率>0.1% | 日报标红 | + +### 3.6 存储容量规划 + +| 时间跨度 | BTC | ETH | 合计 | +|---------|-----|-----|------| +| 1天 | ~200MB | ~150MB | ~350MB | +| 1个月 | ~6GB | ~4.5GB | ~10.5GB | +| 6个月 | ~36GB | ~27GB | ~63GB | +| 1年 | ~73GB | ~55GB | ~128GB | + +200GB磁盘可存1年+。超出时按月归档到外部存储。 + +### 3.7 数据查询接口（需登录） + +- `GET /api/trades/raw?symbol=BTC&start_ms=X&end_ms=Y&limit=10000` — 原始成交 +- `GET /api/trades/summary?symbol=BTC&start_ms=X&end_ms=Y&interval=1m` — 分钟级聚合 + - 返回：`{time, buy_vol, sell_vol, delta, trade_count, vwap, max_single_qty}` + +### 3.8 验收标准 +- [ ] BTC/ETH双流并行采集，PM2常驻 +- [ ] agg_id连续性>99.9% +- [ ] 断线重连+补洞在60秒内完成 +- [ ] 每日完整性报告自动生成 +- [ ] 查询API响应时间<2秒（10万条范围内） + +--- + +## 4. V4.0 — 成交流分析面板 + +### 4.1 页面布局 + +``` +┌────────────────────────────────────────────┐ +│ [BTC▼] [时间范围选择] [1m 5m 15m] │ ← 全局控制栏 +├────────────────────────────────────────────┤ +│ │ +│ K线图 (lightweight-charts) │ ← 可框选时间段 +│ │ +├────────────────────────────────────────────┤ +│ │ +│ 成交流热图 (ECharts heatmap) │ ← 时间×价格×密度 +│ 绿=主动买 红=主动卖 │ +│ │ +├──────────────────────┬─────────────────────┤ +│ 时段摘要 │ 标注面板 │ +│ 总成交量: 1,234 BTC │ [上涨前兆] [下跌前兆] │ +│ 买/卖比: 62%/38% │ [震荡] [放量突破] │ +│ Delta: +427 BTC │ │ +│ 最大单笔: 12.5 BTC │ [保存标注] │ +│ 成交速率: 89笔/秒 │ [AI分析] [导出] │ +└──────────────────────┴─────────────────────┘ +``` + +### 4.2 共享时间轴 + +使用`zustand`或React Context管理全局时间范围： + +```typescript +interface TimeRange { + startMs: number; + endMs: number; + source: 'kline' | 'heatmap' | 'control' | 'manual'; +} +``` + +K线框选、热图缩放、控制栏切换都更新同一个state，所有组件响应式联动。 + +### 4.3 热图实现 + +- 库：ECharts heatmap（首版） +- 数据格式：`[timeMs, priceLevel, volume]` +- 价格分档：按0.1%粒度（BTC约$67 = 1档） +- 颜色映射：买量→绿色深度，卖量→红色深度 +- 数据量控制：15分钟窗口 ≈ 几千个格子，ECharts轻松渲染 + +### 4.4 复盘工具交互 + +**核心流程：** +1. 选择日期和币种 +2. 浏览K线，找到明显波动区间 +3. 框选 → 下方热图+摘要自动聚焦 +4. 观察波动前5-15分钟的成交流特征 +5. 发现有意义的模式 → 标注保存 +6. 可选：点「AI分析」让AI解读该时段特征 + +### 4.5 标注系统 + +```sql +CREATE TABLE annotations ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + user_id INTEGER NOT NULL, + symbol TEXT NOT NULL, + start_ms INTEGER NOT NULL, + end_ms INTEGER NOT NULL, + label TEXT NOT NULL, -- 上涨前兆/下跌前兆/震荡/突破/假突破/洗盘... + note TEXT, -- 用户备注 + confidence INTEGER DEFAULT 3, -- 1-5 置信度 + version INTEGER DEFAULT 1, -- 版本号（修改时递增） + features_json TEXT, -- 当时的特征快照（delta/速率/大单等） + created_at TEXT DEFAULT (datetime('now')), + updated_at TEXT, + FOREIGN KEY (user_id) REFERENCES users(id) +); +``` + +### 4.6 AI辅助分析 + +**流程：** +``` +原始成交数据（该时段） + ↓ Python预处理（后端） +结构化摘要（~500字）： + - 成交速率变化曲线（文字描述） + - Delta累计走势 + - 大单列表（>平均5倍） + - 价格关键点（高低点+突破位） + ↓ AI分析 +结论+建议（~200字） +``` + +**Token消耗：** ~3000 token/次分析，成本忽略不计。 + +### 4.7 验收标准 +- [ ] K线与热图时间同步，无偏移 +- [ ] 热图渲染15分钟窗口<1秒 +- [ ] 标注CRUD正常，支持版本回溯 +- [ ] AI分析响应<10秒 +- [ ] 手机端可用（响应式布局） + +--- + +## 5. 开发排期 + +| 版本 | 内容 | 预估工期 | 依赖 | +|------|------|---------|------| +| V2.0 | 权限管控+邀请制 | 2天 | 无 | +| V3.0 | aggTrades全量采集 | 2天 | V2.0（受保护路由） | +| V4.0 | 成交流分析面板 | 3-5天 | V3.0（数据源） | + +**里程碑：** +- V2.0完成：所有数据需登录访问，邀请码可用 +- V3.0完成：数据开始积累，每日完整性报告 +- V3.0+2周：积累足够数据，可以开始第一次复盘分析 +- V4.0完成：完整的复盘研究工具 + +--- + +## 6. 安全与隐私 + +1. **成交流数据不公开** — 所有`/api/trades/*`和`/api/analysis/*`必须登录 +2. **邀请码范总一人控制** — Admin角色仅范总 +3. **JWT密钥** — 32字节随机，存环境变量 +4. **SQLite安全** — WAL模式，每日备份 +5. **数据永久保留** — 不删不改，原始完整性最重要 + +--- + +## 7. 回滚与故障预案 + +| 故障 | 预案 | +|------|------| +| V2上线后鉴权阻断 | git回退到V1 commit + PM2 restart | +| V3采集进程崩溃 | PM2自动重启 + REST补洞 | +| 磁盘满 | 按月归档旧数据到外部存储 | +| SQLite损坏 | 每日备份恢复 | +| 前端build失败 | 保持上一版本运行，不restart | + +--- + +## 8. 数据库迁移规范 + +- 每次DDL变更写migration脚本，带版本号 +- 命名：`migration_001_add_invite_codes.sql` +- 所有migration必须幂等（`IF NOT EXISTS`） +- 发布顺序：先跑migration → 再更新代码 → 再restart服务 + +--- + +*文档版本: v1.0* +*最后更新: 2026-02-27* +*作者: 露露(Opus 4.6) × 小周(GPT-5.3-Codex)* diff --git a/docs/arbitrage-engine/v5-signal-system.mdx b/docs/arbitrage-engine/v5-signal-system.mdx new file mode 100644 index 0000000..e5e5a9d --- /dev/null +++ b/docs/arbitrage-engine/v5-signal-system.mdx @@ -0,0 +1,239 @@ +--- +title: V5 短线交易信号系统方案 +--- + +# V5 短线交易信号系统方案 + +> 版本：v5.0 | 日期：2026-02-27 | 状态：方案定稿，待开发 +> +> 来源：露露（Opus 4.6）× 小周（GPT-5.3-Codex）10轮讨论 + +--- + +## 1. 目标 + +将 aggTrades 成交流数据转化为**可执行的短线做多/做空交易信号**，实现从"监控工具"到"交易工具"的升级。 + +## 2. 信号体系 + +### 2.1 核心门槛（3/3 必须全部满足） + +| # | 条件 | 做多 | 做空 | +|---|------|------|------| +| 1 | CVD_fast (30m 滚动) | > 0 且斜率正 | < 0 且斜率负 | +| 2 | CVD_mid (4h 滚动) | > 0 | < 0 | +| 3 | VWAP 位置 | price > VWAP_30m | price < VWAP_30m | + +**说明**：CVD = Cumulative Volume Delta（累计买卖差额），是成交流分析最核心的指标。 + +- **CVD_fast**：30分钟滚动窗口，捕捉短线动量 +- **CVD_mid**：4小时滚动窗口，确认大方向 +- **CVD_day**：UTC日内重置，作为盘中强弱基线参考（不作为入场条件） + +> ⚠️ CVD_fast 在剧烈波动时自适应：当1m成交量超过均值3倍时，窗口自动拉长到60m，防噪音误判。 + +### 2.2 加分条件（决定仓位大小，满分60分） + +| 条件 | 分值 | 说明 | +|------|------|------| +| ATR 压缩→扩张 | +25 | 5m ATR分位从 <40% 突破 >60%，波动开始放大 | +| 无反向 P99 超大单 | +20 | 最近15分钟内无极端反向成交 | +| 资金费率配合 | +15 | 做多时费率<0.01%，做空时费率>0.01% | + +### 2.3 仓位映射 + +| 加分总分 | 仓位等级 | 占总资金 | +|----------|----------|----------| +| 0-15 | 最小仓 | 2% | +| 20-40 | 中仓 | 5% | +| 45-60 | 满仓 | 8% | + +### 2.4 预估信号频率 + +核心3条件同时满足概率约 20-30%，每5分钟检查一次。去掉冷却期重复后，预计**日均 5-15 个有效信号**。 + +## 3. 指标计算 + +### 3.1 CVD（Cumulative Volume Delta） + +``` +CVD = Σ(主动买量) - Σ(主动卖量) + +三轨并行： +- CVD_fast：滚动30m窗口（入场信号） +- CVD_mid：滚动4h窗口（方向过滤） +- CVD_day：UTC日内重置（盘中基线） +``` + +入场优先看 fast，方向必须与 mid 同向。 + +### 3.2 大单阈值（动态分位数） + +``` +基于最近24h成交量分布： +- P99：超大单阈值 +- P95：大单阈值 +- 兜底下限：max(P95, 5 BTC) + +区分"大单买"和"大单卖"的不对称性： +- 上涨趋势中出现P99大卖单，意义远大于P99大买单 +``` + +### 3.3 ATR（Average True Range） + +``` +周期：5分钟K线，14根 +用于： +1. 波动压缩→扩张判断（分位数） +2. 止损距离计算 +``` + +### 3.4 VWAP（Volume Weighted Average Price） + +``` +滚动30分钟：VWAP_30m = Σ(price × qty) / Σ(qty) +用于：价格位置过滤（做多 price > VWAP，做空 price < VWAP） +``` + +## 4. 风控体系 + +### 4.1 止盈止损 + +| 参数 | 值 | 说明 | +|------|-----|------| +| 止损 (SL) | 1.2 × ATR(5m, 14) | 动态止损，适应波动 | +| 止盈1 (TP1) | 1.0R | 减仓50% | +| 止盈2 (TP2) | 2.0R | 剩余仓位移动止损 | +| 时间止损 | 30分钟 | 无延续即平仓，防磨损 | + +> R = 1倍止损距离 + +### 4.2 冲突与冷却 + +- **信号冲突**：持仓中出现反向信号 → 先平仓 + 10分钟冷却再接受新信号 +- **同方向冷却**：10分钟内不重复入场 +- **单币限频**：每小时最多2次入场 + +### 4.3 多品种风控 + +- BTC / ETH 独立出信号 +- 两个同时同向时，总仓位上限 10% +- 需要相关性过滤（ETH Delta 经常跟 BTC 走） + +## 5. 回测达标线 + +| 指标 | 达标线 | +|------|--------| +| 胜率 | ≥ 45% | +| 盈亏比 (Avg Win / Avg Loss) | ≥ 1.5 | +| 最大回撤 (MDD) | ≤ 5% | +| 日均信号数 | 2-8 个 | +| 扣手续费后 | 正收益 | + +**手续费模型**： +- Maker: 0.02%, Taker: 0.04%（Portfolio Margin 档位） +- 按 Taker 0.04% 双向估算（保守） +- 回测报告必须包含净收益/毛收益对比 + +**额外统计**： +- 持仓时长分布（验证30min时间止损合理性） +- Rate-limit 重试统计（回补脚本用） + +## 6. 技术架构 + +### 6.1 进程拓扑 + +``` + ┌─────────────────┐ +Binance WS ──────→ │ agg-collector │ ──→ agg_trades_YYYYMM + └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ signal-engine │ ──→ signal_indicators (5s) + │ │ ──→ signal_indicators_1m (聚合) + │ │ ──→ signal_trades + │ │ ──→ Discord推送 + └─────────────────┘ + │ + ┌─────────────────┐ + │ backtest.py │ ──→ 回测报告 + └─────────────────┘ +``` + +- **agg-collector**：只做采集+落库，不动（已有） +- **signal-engine**：新建独立进程，指标计算 + 信号生成 +- **backtest.py**：离线回测脚本 + +### 6.2 数据库新增表 + +| 表名 | 用途 | 保留策略 | +|------|------|----------| +| signal_indicators | 每5秒指标快照（CVD/ATR/VWAP/P95等） | 30天 | +| signal_indicators_1m | 1分钟聚合（前端默认读此表） | 长期 | +| signal_trades | 信号触发的开仓/平仓记录 | 长期 | + +### 6.3 指标计算策略 + +- **内存滚动 + 增量更新**（不是每次SQL全量聚合） +- 启动时回灌历史窗口（30m/4h/24h）到内存 +- 之后只处理新增 agg_id 增量 +- 每5秒把快照落库（幂等） + +### 6.4 冷启动处理 + +signal-engine 重启后： +1. 从DB回读最近4h的aggTrades重算所有指标 +2. 前N根标记为 `warmup`，不出信号 +3. warmup 完成后开始正常信号生成 + +## 7. 历史数据回补 + +### 7.1 回补脚本（backfill_agg_trades.py） + +``` +参数：--symbol BTCUSDT --days 7 --batch-size 1000 +流程： +1. 查DB中最早的agg_id +2. 从最早agg_id向前REST分页补拉 +3. 每次1000条，sleep 200ms防限流 +4. INSERT OR IGNORE 写入agg_trades_YYYYMM +5. 断点续传：记录进度到meta表 +6. 完成后输出统计+连续性检查 +``` + +### 7.2 速率控制 + +- Binance aggTrades REST 限流：weight 20/min +- 每请求 sleep 200ms，实际约 3-5 req/s +- 带指数退避重试，429后等60s +- 记录 rate-limit 统计（429次数、退避次数） + +## 8. 开发时间线 + +| Day | 任务 | 交付物 | 负责 | +|-----|------|--------|------| +| 1 | 回补脚本 + 1天小样本 | backfill跑通，BTC/ETH各1天入库 | 露露开发，小周部署 | +| 2 | 全量7天回补 + 连续性验证 | 完整7天aggTrades，缺口=0 | 小周跑+验收 | +| 3-4 | signal-engine + 前端指标展示 | CVD三轨/ATR/VWAP/大单标记实时可视化 | 露露开发，小周部署 | +| 5 | 回测框架 + 首版回测报告 | 胜率/盈亏比/MDD/持仓分布/净收益 | 露露开发 | +| 6+ | 调参优化 → 达标后模拟盘 | 模拟交易记录 | 协同 | + +## 9. 前置依赖 + +| 依赖 | 状态 | 影响范围 | +|------|------|----------| +| aggTrades 实时采集 | ✅ 已运行 | Phase 1-3 已满足 | +| 历史数据回补 | ⏳ Day 1-2 | 回测需要 | +| Binance API Key | ⏳ 等范总 | 仅Phase 4实盘 | +| Portfolio Margin | ⏳ 等范总 | 仅Phase 4实盘 | +| 资金准备 | ⏳ 等范总 | 仅Phase 4实盘 | + +> Phase 1-3 不依赖范总，可立即开工。 + +## 10. 版本历史 + +| 版本 | 日期 | 内容 | +|------|------|------| +| v2-v4 | 2026-02-27 | 权限管控+aggTrades采集+成交流面板 | +| **v5.0** | **2026-02-27** | **短线交易信号系统方案定稿** |