# 实盘下单 · 盘口深度预览 — 开发方案

> 状态:**方案待实现**(按本文落地;改需求先改本文).  
> 范围:**三所实例**实盘下单监控(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. 决策摘要(已拍板)

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