lulu/arbitrage-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 同步套利引擎私有文档站内容

Browse Source 
从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仓库先写 → 再同步到私有文档站
This commit is contained in:
dev-worker 2026-03-03 05:26:27 +00:00
parent 548c7f0e33
commit c8c2d801a2
6 changed files with 1559 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

205
docs/arbitrage-engine/funding-rate-arbitrage-plan.md Normal file
View File

@ -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量化

20
docs/arbitrage-engine/index.mdx Normal file
View File

@ -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（产品+技术+商业）

138
docs/arbitrage-engine/phase0-progress.md Normal file
View File

@ -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）

540
docs/arbitrage-engine/requirements-v1.3.md Normal file
View File

@ -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. 开始开发

417
docs/arbitrage-engine/v2-v4-plan.mdx Normal file
View File

@ -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)*

239
docs/arbitrage-engine/v5-signal-system.mdx Normal file
View File

@ -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** | **短线交易信号系统方案定稿** |