lulu/arbitrage-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
arbitrage-engine/docs/ai/07-glossary.md
fanziqi 22787b3e0a docs: add AI documentation suite and comprehensive code review report 
- Generate full AI-consumable docs (docs/ai/): system overview, architecture,
  module cheatsheet, API contracts, data model, build guide, decision log,
  glossary, and open questions (deep tier coverage)
- Add PROBLEM_REPORT.md: categorized bug/risk summary
- Add DETAILED_CODE_REVIEW.md: full line-by-line review of all 15 backend
  files, documenting 4 fatal issues, 5 critical deployment bugs, 4 security
  vulnerabilities, and 6 architecture defects with prioritized fix plan
2026-03-03 19:01:18 +08:00

101 lines
8.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
generated_by: repo-insight
version: 1
created: 2026-03-03
last_updated: 2026-03-03
source_commit: 0d9dffa
coverage: deep
---
# 07 — Glossary
## Purpose
项目中使用的专业术语、领域术语和项目自定义术语的定义。
## TL;DR
- 项目混合使用量化交易、加密货币和工程术语，中英文混用。
- "R" 是风险单位，1R = 单笔风险金额（PAPER_RISK_PER_TRADE × 余额）。
- CVD 是核心指标：累计 delta = 主动买量 - 主动卖量，衡量买卖压力。
- ATR 用于动态计算止盈止损距离（TP/SL 均以 ATR 倍数表示）。
- "tier" 指仓位档位：light/standard/heavy，对应不同仓位大小倍数。
## Canonical Facts
### 交易与量化术语
| 术语 | 定义 |
|------|------|
| **资金费率（Funding Rate）** | 永续合约中多空双方每8小时相互支付的费率。正费率：多头付给空头；负费率：空头付给多头。以小数表示（如 `0.0001` = 0.01%）。 |
| **永续合约（Perpetual / Perp）** | 无到期日的期货合约，通过资金费率机制锚定现货价格。本项目操作 Binance USDC-M 永续合约。 |
| **套利（Arbitrage）** | 持有现货多头 + 永续空头，资金费率为正时空头每8小时收取费率收益，实现无方向性风险的稳定收益。 |
| **年化（Annualized）** | `平均费率 × 3次/天 × 365天 × 100%`，将单次资金费率换算为年化百分比。 |
| **CVD（Cumulative Volume Delta）** | 累计成交量差值 = 主动买量 - 主动卖量。正值表示买方主导，负值表示卖方主导。本项目计算三个窗口：CVD_fast（30分钟）、CVD_mid（4小时）、CVD_day（UTC日内）。 |
| **aggTrade** | Binance 聚合成交数据：同一方向、同一价格、同一时刻的多笔成交合并为一条记录，包含 `is_buyer_maker` 字段（0=主动买，1=主动卖）。 |
| **is_buyer_maker** | `0`：买方是 taker（主动买入），`1`：买方是 maker（被动成交，即主动卖）。CVD 计算：0→买量，1→卖量。 |
| **VWAP（Volume Weighted Average Price）** | 成交量加权平均价格。用于判断当前价格相对于短期平均成本的位置。 |
| **ATR（Average True Range）** | 平均真实波动幅度，衡量市场波动性。本项目使用 5 分钟 K 线、14 周期 EMA 计算。 |
| **ATR Percentile** | 当前 ATR 在过去 24 小时内的历史分位数（0~100），衡量当前波动性是高还是低。 |
| **P95 / P99** | 过去 24 小时内成交量的第 95/99 百分位数，作为"大单阈值"。超过 P99 的成交视为大单，对信号评分有影响。 |
| **Long/Short Ratio（多空比）** | 全市场多头账户数 / 空头账户数。反映市场情绪拥挤程度。 |
| **Top Trader Position（顶级交易者持仓比）** | 大户多头持仓占比，范围 0~1。高于 0.55 视为多头拥挤，低于 0.45 视为空头拥挤。 |
| **Open Interest（OI，持仓量）** | 市场上所有未平仓合约的总名义价值（USD）。OI 增加 ≥3% 视为环境强势信号。 |
| **Coinbase Premium** | Coinbase Pro BTC/USD 现货价格相对 Binance BTC/USDT 的溢价比例。正溢价（>0.05%）被视为看涨信号（美国机构买入）。以比例存储（如 `0.0005` = 0.05%）。 |
| **清算（Liquidation）** | 爆仓事件。空头清算多于多头清算（短时间内）视为看涨信号（逼空）。本项目使用 5 分钟窗口内多空清算 USD 之比进行评分。 |
| **R（风险单位）** | 单笔风险金额。1R = `初始余额 × 风险比例`（默认 2%，即 200U）。盈亏以 R 倍数表示：1R=保本，2R=盈利1倍风险，-1R=全亏。 |
| **PnL_R** | 以 R 为单位的盈亏：`pnl_r = (exit_price - entry_price) / risk_distance × direction_sign`。 |
| **TP1 / TP2（Take Profit）** | 止盈目标价。TP1 为第一目标（触发后平一半仓位），TP2 为第二目标（平剩余）。 |
| **SL（Stop Loss）** | 止损价。SL 触发后视 TP1 是否已命中：未命中→亏损 1R；已命中→保本（sl_be 状态）。 |
| **Tier（档位）** | 仓位大小分级。`light`=0.5×R，`standard`=1.0×R，`heavy`=1.5×R。信号分数越高触发越重的档位：score ≥ max(threshold+10, 85) → heavy；score ≥ threshold → standard。 |
| **Warmup（冷启动）** | signal_engine 启动时读取历史 `agg_trades` 填充滚动窗口的过程，完成前不产生信号（`state.warmup=True`）。 |
| **Signal Cooldown（信号冷却）** | 同一 symbol 同一策略触发信号后，10 分钟内不再触发新信号，防止过度交易。 |
### 策略术语
| 术语 | 定义 |
|------|------|
| **v51_baseline** | V5.1 基准策略。6 个信号：cvd, p99, accel, ls_ratio, oi, coinbase_premium。SL=1.4×ATR，TP1=1.05×ATR，TP2=2.1×ATR。 |
| **v52_8signals** | V5.2 扩展策略。8 个信号（v51 + funding_rate + liquidation）。SL=2.1×ATR，TP1=1.4×ATR，TP2=3.15×ATR（更宽止损，更高盈亏比目标）。 |
| **Score / 信号分数** | 0~100 的综合评分，由多层加权指标累加得出，阈值 75 触发信号。 |
| **Direction Layer（方向层）** | 评分第一层，最高 45 分（v51）或 40 分（v52）。基于 CVD_fast、CVD_mid 同向性和 P99 大单方向。 |
| **Crowding Layer（拥挤层）** | 基于多空比和顶级交易者持仓的市场拥挤度评分。 |
| **Environment Layer（环境层）** | 基于持仓量变化（OI change）的市场环境评分。 |
| **Confirmation Layer（确认层）** | CVD 快慢线同向确认，15 分（满足）或 0 分。 |
| **Auxiliary Layer（辅助层）** | Coinbase Premium 辅助确认，0~5 分。 |
| **Accel Bonus（加速奖励）** | CVD 快线斜率正在加速时额外加分（v51: +5分，v52: +0分）。 |
| **Score Factors** | 各层得分详情，以 JSONB 格式存储在 `paper_trades.score_factors` 和 `live_trades.score_factors`。 |
### 工程术语
| 术语 | 定义 |
|------|------|
| **Paper Trading / 模拟盘** | 不真实下单、仅模拟记录的交易，用于验证策略。数据存储在 `paper_trades` 表。 |
| **Live Trading / 实盘** | 通过 Binance API 真实下单执行的交易。数据存储在 `live_trades` 表。 |
| **Testnet** | Binance 测试网（`https://testnet.binancefuture.com`），使用虚拟资金。`TRADE_ENV=testnet`。 |
| **Production** | Binance 生产环境（`https://fapi.binance.com`），使用真实资金。`TRADE_ENV=production`。 |
| **Circuit Break（熔断）** | risk_guard 触发的保护机制，阻止新开仓甚至强制平仓。通过 `live_config` 表的 flag 通知 live_executor。 |
| **Dual Write（双写）** | 同一数据同时写入本地 PG 和 Cloud SQL，Cloud SQL 写失败不阻断主流程。 |
| **Partition / 分区** | `agg_trades` 表的月度子表（如 `agg_trades_202603`），用于管理大表性能。 |
| **NOTIFY/LISTEN** | PostgreSQL 原生异步通知机制。signal_engine 用 `NOTIFY new_signal` 触发，live_executor 用 `LISTEN new_signal` 接收。 |
| **TradeWindow** | signal_engine 中的滚动时间窗口类，维护 CVD 和 VWAP 的实时滚动计算。 |
| **SymbolState** | 每个交易对的完整状态容器，包含三个 TradeWindow、ATRCalculator、market_indicators 缓存和信号冷却记录。 |
| **Invite Code（邀请码）** | 注册时必须提供的一次性（或限次）代码，由管理员通过 `admin_cli.py` 生成。 |
| **Subscription Tier** | 用户订阅等级（`free` 等），存储在 `subscriptions` 表，当前代码中使用有限。 |
| **万分之** | 前端显示资金费率时的单位表述，实际值 × 10000 展示。例如 `0.0001` 显示为 `1.0000 万分之`。 |
## Interfaces / Dependencies
无。
## Unknowns & Risks
- [inference] `Subscription Tier` 功能在 schema 中有定义但实际业务逻辑中使用程度不确定（可能是预留字段）。
- [inference] "no_direction" 状态（CVD_fast 和 CVD_mid 不一致时）的处理逻辑：方向取 CVD_fast，但标记为不触发信号，可用于反向平仓判断。
## Source Refs
- `backend/signal_engine.py:1-16` — CVD/ATR/VWAP/P95/P99 架构注释
- `backend/signal_engine.py:69-81` — Paper trading 参数定义（R、tier 倍数）
- `backend/signal_engine.py:170-207` — TradeWindow 类（CVD/VWAP 定义）
- `backend/signal_engine.py:209-257` — ATRCalculator 类
- `backend/signal_engine.py:410-651` — evaluate_signal（各层评分逻辑）
- `backend/strategies/v51_baseline.json`, `v52_8signals.json` — 策略参数
- `backend/trade_config.py` — 交易对精度配置
- `frontend/app/page.tsx:186` — "万分之" 显示注释
Reference in New Issue View Git Blame Copy Permalink