# depthGather-chat · 深度均匀性查看工具

<!-- [skill: go-team-standards · 技术文档] 深度聚合页产品说明 — 封板版 -->

> **状态：封板**  
> `depthGather-chat.html` 已完成验收，**后续不再改动**。  
> Mock 数据、配置、说明文档可在本目录其他文件中维护。

---

## 一、工具是干什么的

**核心目的：查看本所某个交易对的挂单深度是否均匀。**

铺单 / 量化程序会在 Mark 价上下多档挂限价单。如果某一侧出现：

- 某些价位 **量特别大**、相邻档 **量特别小**（头重脚轻）
- 价位之间 **跨度不一致**（该密的不密、该疏的不疏）
- 某一方向 **长期缺档** 或 **只有一两档有量**

都会影响成交体验、滑点表现和对外盘口观感。本工具把 `/debug/depthGather` 返回的**按价位聚合**数据，用「订单簿 + 纵向单档图」直观呈现出来，方便快速判断深度是否铺得均匀。

---

## 二、适合谁、什么时候用

| 场景 | 看什么 |
|------|--------|
| 铺单策略上线 / 调参后 | 买卖两侧各档 `Qty` 是否大致符合预期分布 |
| 值班巡检 | AP/BP 附近是否有明显「断崖」或空洞 |
| 排查客诉「盘口薄 / 滑点大」 | 远端档是否断档、近端是否过度集中 |
| 对比不同 symbol | 切换 `symbol_id` 看各交易对深度形态 |

---

## 三、页面怎么看

```
┌─────────────────────────────────────────────────────────────┐
│  [定时刷新]  symbol_id  [Mock 本地 ▼ 测试环境]   AP/BP/MP… │
├──────────────┬──────────────────────────────────────────────┤
│  卖盘 ASK     │                                              │
│  UV Qty Price│         纵向深度图                             │
│  ─────────── │    价格 ↑                                    │
│  买盘 BID     │    买盘 ◀ │ ▶ 卖盘  （每档独立量，非累计）    │
│  Price Qty UV│                                              │
└──────────────┴──────────────────────────────────────────────┘
```

### 左侧订单簿（每一行 = 一个价位档）

| 列 | 接口字段 | 均匀性排查时的关注点 |
|----|----------|----------------------|
| **UV** | `uid_num` | 该档有多少不同 UID；长期为 1 可能是单一铺单源 |
| **Qty** | `number` | **最关键**：该档标的量；相邻行之间是否忽大忽小 |
| **Price** | `price` | 档间价差是否规律（是否与 `price_step` / 铺单盒子一致） |

图标表示订单来源（Web / App / 量化 / 强平等），悬停图例可看说明。

### 右侧纵向图

- **纵轴**：价格  
- **横轴**：该档 **单档量**（与表格 `Qty` 一致，**不是累计深度**）  
- 买盘向左、卖盘向右；**条形越齐整，深度越均匀**；某几档特别长/特别短一眼能看出来  

### 顶栏指标（全盘汇总）

| 缩写 | 含义 | 均匀性相关 |
|------|------|------------|
| AP / BP | 最优卖 / 买价 | 价差是否正常 |
| MP | 标记价 | 对照铺单中心 |
| Cap | 买卖价差（‱） | 过宽可能近端缺档 |
| AV / BV | 卖 / 买盘总量 | 两侧是否严重失衡 |
| UV / TV | 全盘 UID 数 / 笔数 | 是否过于集中在少数 UID |

鼠标悬停各指标与图例，有字段说明。

---

## 四、怎么判断「均匀 / 不均匀」

### 相对均匀（健康形态，示意）

- 近 Mark 价若干档：`Qty` 在同一数量级内小幅波动  
- 纵向图：买卖两侧阶梯 **宽度相近**，无明显「一根特别长、旁边几乎为零」  
- 价位序列：Ask 价递增、Bid 价递减，档距符合预期 step  
- AV 与 BV 同一量级（除非策略刻意偏一侧）  

### 需要关注（可能不均匀）

| 现象 | 可能含义 |
|------|----------|
| 相邻两档 `Qty` 差 10 倍以上 | 铺单盒子参数或某层未生效 |
| 中间缺价位、跳档 | 价格区间未覆盖或订单未挂上 |
| 仅 1～2 档有量，其余近零 | 铺单程序异常 / 只 partial fill |
| 纵向图一侧极窄 | 该方向深度不足 |
| UV 长期为 1 且 Qty 极大 | 可能只有量化账户在撑量 |

**建议操作：** 输入 `symbol_id` → 选「测试环境」→ 开「定时刷新」→ 对照左侧表格逐档看 `Qty`，同时看右侧图形是否「台阶齐」。

---

## 五、快速上手

```bash
cd quant-visual-tools
./start.sh
# 浏览器打开
# http://localhost:8080/depth-gather/depthGather-chat.html
```

1. 填写 **symbol_id**（如 `1000001`）  
2. 下拉选 **测试环境**（查真实深度）或 **Mock 本地**（离线演示）  
3. 点击 **定时刷新**，500ms 轮询  
4. 展开页内「depthGather 接口 · 用户 / 挂单字段说明」查字段含义  

### 数据源切换

| 选项 | 用途 |
|------|------|
| **测试环境** | 生产验收、看真实均匀性（默认） |
| **Mock 本地** | 无内网时演示页面能力 |

两项**始终同时存在**，下拉切换后立即刷新。  
Mock 技术细节见 [demo.html](./demo.html)。

---

## 六、接口说明（摘要）

```
GET {api_base}/debug/depthGather?symbol_id={id}
```

本页使用 `data.depth.ask / data.depth.bid` 数组，**每元素一个价位档**：

```json
{
  "price": "66921.1",
  "number": "0.36",
  "uid_num": 2,
  "order_num": 15,
  "user_ids": "10001,10002",
  "source_list": ["1", "3"],
  "direction": -1
}
```

- `number` → 表格 **Qty**、纵向图柱宽  
- `asks` / `bids` 累计数组：接口原样返回，**本页图表不使用**  

---

## 七、目录与维护约定

| 文件 | 是否可改 | 说明 |
|------|----------|------|
| `depthGather-chat.html` | **否（封板）** | 主页面，不再改动 |
| `README.md` | 是 | 本文档 — 产品目的与用法 |
| `demo.html` | 是 | Mock / 接口技术说明 |
| `js/mock-bridge.js` | 是 | Mock 与测试环境切换 |
| `data/mock/*.json` | 是 | 离线演示数据 |

---

## 八、相关链接

- [打开工具（测试环境）](./depthGather-chat.html)
- [Mock 演示 `?mock=1`](./depthGather-chat.html?mock=1)
- [Mock / 接口技术说明](./demo.html)
- [量化工具首页](../index.html)