c8c2d801a2
从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仓库先写 → 再同步到私有文档站
418 lines
14 KiB
Plaintext
418 lines
14 KiB
Plaintext
---
|
||
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)*
|