From 339f5e6db0d98b07cfeb21dade5c7606c29f130e Mon Sep 17 00:00:00 2001 From: dekun Date: Mon, 17 Aug 2026 21:25:19 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=E6=96=B0=E5=A2=9E=E5=AE=9E?= =?UTF-8?q?=E7=9B=98=E4=B8=8B=E5=8D=95=E7=9B=98=E5=8F=A3=E6=B7=B1=E5=BA=A6?= =?UTF-8?q?=E9=A2=84=E8=A7=88=E5=BC=80=E5=8F=91=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- docs/实盘下单-盘口深度预览-开发方案.md | 233 +++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 docs/实盘下单-盘口深度预览-开发方案.md diff --git a/docs/实盘下单-盘口深度预览-开发方案.md b/docs/实盘下单-盘口深度预览-开发方案.md new file mode 100644 index 0000000..6031763 --- /dev/null +++ b/docs/实盘下单-盘口深度预览-开发方案.md @@ -0,0 +1,233 @@ +# 实盘下单 · 盘口深度预览 — 开发方案 + +> 状态:**方案待实现**(按本文落地;改需求先改本文). +> 范围:**三所实例**实盘下单监控(Binance / OKX / Gate);中控嵌入同一表单时一并带上. +> 相关:[manual-order-rr-preview.md](./manual-order-rr-preview.md) · [position-sizing-mode.md](./position-sizing-mode.md) · 期权侧已有「卖一开 / 买一平」深度硬约束(本方案**不照搬硬挡**,首版以预览为主). + +--- + +## 1. 背景与问题 + +实盘下单表单目前只展示 **标的现价/标记价**,再按止损与计仓模式算出预估风险 / 预估 RR. + +- **资金小**:名义仓位通常远小于盘口前几档,市价成交贴近买卖一,现价参考够用. +- **资金大**(尤其 `POSITION_SIZING_MODE=full_margin`):名义 = 可用保证金 × 缓冲 × 杠杆,容易到数十万 U. 市价单会沿对手盘穿档,入场均价偏离「现价」后,止损距离与有效盈亏比都会偏. + +典型例子: + +| 条件 | 含义 | +|------|------| +| 可用约 1 万 U,20 倍杠杆,全仓 | 计划名义约 **20 万 U** | +| **市价做空** | 立刻卖出 ≈ 20 万 U 名义 → 吃 **买单(bid)** | +| **市价做多** | 立刻买入 ≈ 20 万 U 名义 → 吃 **卖单(ask)** | + +用户需要的不是整本订单簿娱乐墙,而是回答: + +> 当前计划名义下,对手盘前几档**能不能接住**,接住后的**预估均价 / 滑点**大概多少? + +--- + +## 2. 目标(首版) + +在「实盘下单监控」开仓区增加 **计划名义 vs 对手盘深度** 的只读预览: + +1. 按当前表单算出的 **计划名义(USDT)** 与 **方向**,取对应一侧盘口. +2. 从最优档往外累加,直到累计名义 ≥ 计划名义(或盘口耗尽). +3. 展示:吃到第几档、累计可吸收名义、预估成交均价(VWAP)、相对参考价的滑点(bps 或 %). +4. **不拦截下单**(首版);可选标黄提示,见 §6. + +与现有「预估风险 / 预估盈利 / 预估盈亏比」并列,作为下单前参考,不替代服务端风控与交易所真实成交. + +--- + +## 3. 不做(首版外) + +- 完整 20/50 档盘口图、深度图动画、WebSocket 持续推送盘口(首版 REST 轮询即可) +- 按深度 **自动缩仓** 或 **禁止开仓**(期权硬约束那套;列为二期,见 §10) +- 限价挂单的「挂单价到盘口距离」专项(可后加;首版聚焦市价吃单路径) +- 平仓/止损单穿档预估(开仓侧先做;平仓可二期) +- 改开仓逻辑、改计仓公式、改交易所下单路径 +- 中控独立深度页或跨所聚合盘口 + +--- + +## 4. 产品规则 + +### 4.1 对手盘方向 + +| 用户方向 | 市价开仓动作 | 累加侧 | +|----------|--------------|--------| +| 做多(long) | 买入 | **卖盘 asks**(卖一 → 卖 N) | +| 做空(short) | 卖出 | **买盘 bids**(买一 → 买 N) | + +### 4.2 计划名义从哪来 + +与现有开仓计仓一致,优先复用服务端已有 sizing 口径(避免前后端各算一套): + +| 计仓模式 | 计划名义 | +|----------|----------| +| `full_margin` | `notional_value` ≈ 可用 × 缓冲 × 杠杆(与 `compute_full_margin_sizing` 一致) | +| `risk`(以损定仓) | 由风险金额与止损距离反推的仓位名义(与现开仓 `add_order` 路径一致) | + +表单未填齐止损/方向/币种、或无法取可用保证金时:深度预览显示「—」,不报错打断填写. + +### 4.3 参考价与滑点 + +- **参考价**:优先与表单现价条同一口径(标记价/最新价,跟现有 `symbol_live_price` / `order_defaults` 一致). +- **预估均价(VWAP)**:按所吃各档 `价格 × 该档名义` 加权. +- **滑点**: + - 做多: `(vwap - ref) / ref`(越正越差) + - 做空: `(ref - vwap) / ref`(越正越差) +- 展示可用 **bps**(1 bps = 0.01%)或 `%`,UI 统一一种即可(建议 bps,大单更直观). + +### 4.4 盘口档数 + +- 请求深度建议 **5～20 档**(实现时三所取各自 API 稳妥上限,默认 20). +- 累加只展示「覆盖计划名义所需」的档位摘要,不必把未吃到的远档全部渲染. +- 若累加后仍 `< 计划名义`:明确写 **深度不足 / 缺口约 X U**,不要伪装成已完全覆盖. + +### 4.5 文案示例(空单 20 万 U) + +``` +对手盘(买):买一～买4 累计约 23.1 万 U · 预估均价 63480(相对现价约 5 bps) +``` + +深度不足时: + +``` +对手盘(买):前 20 档累计约 12.4 万 U · 缺口约 7.6 万 U · 预估均价按已有档估算(仅供参考) +``` + +--- + +## 5. 界面位置 + +放在实盘下单开仓区、现有预览条附近,避免抢主按钮视觉: + +| 区域 | 建议 | +|------|------| +| 现价条旁或下方 | 一行摘要即可(§4.5) | +| `#order-plan-preview` | 可增一项「盘口深度」或独立 `#order-depth-preview` | +| 详细档位 | 首版可不展开;若展开,仅列出已累加到的那几档(价/量/累计名义) | + +小资金且滑点低于阈值时,可用灰色弱提示「前 N 档已覆盖,滑点可忽略」,避免噪音. + +--- + +## 6. 提示阈值(软提示,不挡单) + +建议可配置(`.env`,有默认值),仅影响颜色/文案: + +| 变量(草案) | 含义 | 默认建议 | +|------------|------|----------| +| `MANUAL_DEPTH_WARN_BPS` | 预估滑点 ≥ 此值标黄 | `5` | +| `MANUAL_DEPTH_ALERT_BPS` | 预估滑点 ≥ 此值标红/强调 | `15` | +| `MANUAL_DEPTH_SHORTFALL_WARN` | 累计名义 < 计划名义时强调 | 开 | + +首版:**不**因此 `disabled` 开仓按钮;与期权「无卖一禁止开仓」区分开. + +--- + +## 7. 技术设计 + +### 7.1 API(三所各暴露,或抽到 `lib/` 共用 handler) + +建议新增(名称可微调): + +`GET /api/order_depth_preview` + +| 参数 | 说明 | +|------|------| +| `symbol` | 与开仓表单一致 | +| `direction` | `long` / `short` | +| `sl` / `sl_pct` / `fixed_rr` / `sltp_mode` 等 | 以损定仓算名义时需要;全仓模式可只传 symbol+direction | +| 或直接传 `notional_usdt` | 若前端已从其它 preview API 拿到名义,可减少重复计算(**二选一,实现时定一种主路径**) | + +响应草案: + +```json +{ + "ok": true, + "side": "bid", + "ref_px": 63512.3, + "plan_notional_usdt": 200000, + "covered_notional_usdt": 231000, + "shortfall_usdt": 0, + "levels_used": 4, + "vwap": 63480.0, + "slippage_bps": 5.1, + "levels": [ + {"px": 63510, "sz": "...", "notional_usdt": 50000, "cum_notional_usdt": 50000} + ], + "msg": "" +} +``` + +失败(拉盘口失败、币种无效):`ok=false` + 简短 `msg`;前端显示「深度暂不可用」,不影响开仓。 + +### 7.2 交易所盘口 + +| 所 | 合约盘口 | 注意 | +|----|----------|------| +| Binance | USD-M 深度 | 数量单位换算成 USDT 名义 | +| OKX | swap books | 同左;与期权 `fetch_option_book_depth` **分开**,勿混用期权接口 | +| Gate | futures order book | 同左 | + +公共逻辑建议落在 `lib/trade/`(例如 `manual_order_depth_preview_lib.py`):输入档位列表 + 计划名义 + 方向 → 输出 VWAP / 缺口 / levels_used. +各所只负责 **拉 book + 单位换算成 USDT 名义**. + +### 7.3 前端 + +- 共享脚本(建议):`lib/common/static/manual_order_depth_preview.js` +- 与 `manual_order_rr_preview.js` 同样在币种/方向/止损/模式变更时 debounce 刷新 +- 轮询间隔建议 3～5s(仅表单可见且字段有效时);切页或无焦点可停 +- 三所 `index` / 嵌入 fragment 引入同一脚本 + +### 7.4 测试 + +- 纯函数:给定假盘口 + 名义,断言 `levels_used` / `vwap` / `shortfall` +- 方向: long 只吃 ask, short 只吃 bid +- 深度不足与刚好覆盖边界 +- 不要求联调真盘口也能合入(真盘口可手工验一次 BTC/山寨对比) + +--- + +## 8. 验收标准 + +1. 全仓 + 已知杠杆下,预览「计划名义」与开仓实际计仓名义同量级(允许四舍五入误差). +2. 市价空只反映买盘累加;市价多只反映卖盘累加. +3. BTC 厚盘:小名义常显示「前 1～2 档已覆盖、滑点很低」. +4. 人为放大名义或选薄流动性标的:能看到多档累加或「深度不足」. +5. 拉盘口失败时不阻断开仓按钮. +6. 中控嵌入实盘下单同样可见(与实例页同源表单). + +--- + +## 9. 实现顺序建议 + +1. `lib/trade` 累加/VWAP 纯函数 + 单测 +2. 一所(建议 OKX 或当前主力所)拉 book + API + 前端一行预览 +3. 抽换算差异,补 Binance / Gate +4. 接入软提示阈值与文案打磨 +5. 文档验收记录补进本文或 `docs/更新文档.md` + +--- + +## 10. 二期(明确不做进首版) + +| 项 | 说明 | +|----|------| +| 深度不够自动缩名义 | 类似期权 `cap_by_ask_depth` | +| 滑点超阈值二次确认 / 禁止市价 | 产品确认后再做硬门禁 | +| 平仓与止损穿档预估 | 持仓卡或平仓按钮旁 | +| WS 盘口 | 降低 REST 压力、更即时 | +| 限价开仓:挂单价相对盘口位置 | 另一套提示 | + +--- + +## 11. 决策摘要(已拍板) + +- **要做**:按计划名义展示「覆盖该名义所需」的对手盘摘要 + 预估均价/滑点. +- **做空看买单,做多看卖单**. +- **首版只展示 + 软提示,不挡单**. +- **不为小资金做整屏盘口墙**;大名义时深度预览才有关键决策价值.