文档:新增实盘下单盘口深度预览开发方案

Co-authored-by: Cursor <cursoragent@cursor.com>

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. 决策摘要(已拍板)
+
+- **要做**:按计划名义展示「覆盖该名义所需」的对手盘摘要 + 预估均价/滑点.  
+- **做空看买单,做多看卖单**.  
+- **首版只展示 + 软提示,不挡单**.  
+- **不为小资金做整屏盘口墙**;大名义时深度预览才有关键决策价值.