depth-chat · Mock 数据 Demo 说明

本目录在 smoneyfuturesservice/depth-chat.html 原页基础上， 仅增加 配置变量 与 mock 桥接（head 内 2 行 script，sync 后自动注入）。 页面 UI / 业务逻辑与原版一致。

打开 depth-chat（走 api_base 真接口） 打开 depth-chat（Mock 模式） Mock · TRX 1000003 返回 quant-visual-tools 首页
打开方式很重要： 用 file:// 双击打开时，浏览器把页面 origin 视为 null， 既不能 fetch 本地 JSON，也不能请求测试环境（全部被 CORS 拦）。 此时页面自动选中 Mock 本地，数据来自打包好的 js/mock-data.js，图表可正常演示； 但下拉切到「测试环境」必然失败。
要连测试环境，请起本地服务器：在 quant-visual-tools 目录执行 ./start.sh → 访问 http://localhost:8080/depth-chat/depth-chat.html。

1. 配置变量 api_base

配置文件：config/api-config.json

{
  "api_base": "http://18.177.36.184/futures",
  "endpoints": {
    "depth": "/debug/depth",
    "klineDiff": "/debug/klineDiff"
  }
}
备注：非 mock 模式下，页面内 #market_monitor / #market_kline 下拉框会被重写为 {api_base}/debug/depth 与 {api_base}/debug/klineDiff。 可通过 URL 覆盖：?api_base=http://18.177.36.184/futures

2. Mock / 测试环境切换（与 depth-gather 一致）

位置行为
顶栏 #market_monitorMock 本地 / 测试环境 — 本所深度
顶栏 #market_kline同上 — K 线（与本所深度同步切换）
切换任一下拉立即刷新 depth / kline / exchangeInfo / 牌价 / 对标价等本所接口
?mock=1仅默认选中 Mock；仍可在下拉切回测试环境
http:// 无参数打开默认测试环境
file:// 打开默认 Mock（真接口在此协议下必被 CORS 拦），顶栏横幅会提示
Mock 与测试环境始终并列；Mock 模式下本所 7 个接口走 data/mock/，测试环境走 api_base。 币安深度等外网接口不受此项控制。

3. Mock 接口清单

接口Mock 文件说明
GET /pub/exchangeInfoexchangeInfo.json交易对配置，填充下拉框
GET /pub/v2/tickerListtickerList.json24h 牌价滚动条
GET /debug/depthdepth.symbol-{id}.json本所深度 + 面积图
GET /debug/klineDiffklineDiff.symbol-{id}.jsonK 线对比
GET /debug/depthGatherdepthGather.symbol-{id}.json深度聚合（价位维度）
GET /debug/exchangePriceexchangePrice.json对标交易所价格
GET /debug/priceHashpriceHash.jsonMark / Index / Last
注意：币安深度等外网接口不在 mock 范围；离线演示时该区块可能为空，属预期行为。

4. Mock 文件命名

目录：data/mock/

接口文件规则回退
GET /debug/depth?symbol_id= depth.symbol-{symbol_id}.json depth.default.json
GET /debug/klineDiff?symbol_id=&resolution=&size=&from=&to= klineDiff.symbol-{symbol_id}.json klineDiff.default.json
GET /debug/depthGather?symbol_id= depthGather.symbol-{symbol_id}.json depthGather.default.json
GET /pub/exchangeInfo exchangeInfo.json —
GET /pub/v2/tickerList tickerList.json —
GET /debug/exchangePrice exchangePrice.json —
GET /debug/priceHash priceHash.json —

完整接口说明索引：data/mock/mock.json · 三套工具总索引：../config/demo-mock.json

已内置示例：

5. 响应外壳（统一）

与线上一致，前端读 json.data：

{
  "code": 0,
  "msg": "success",
  "data": { ... }
}

6. /debug/depth 数据结构

来源：smoneyfuturesservice/script/src/Controller/Debug/Depth.php::index()

5.1 data.stats — 顶栏指标

字段含义示例
ask_price最优卖价 AP0.25350
bid_price最优买价 BP0.25344
mark_price标记价 MP0.25347
diff_price盘口差（万分比 ‱）2.37
ask_qty卖盘总量（标的量）9900
bid_qty买盘总量（标的量）10980
uid_num挂单 UID 数8
order_num挂单笔数24

5.2 data.depth.ask / bid — 用户挂单详情（数组）

每条委托（用于「用户挂单详情」Tab）：

{
  "price": 0.25350,
  "trust_id": 900001,
  "rest_qty": 100,
  "number": 100.0,
  "user_id": 10001,
  "action": 0,
  "source": 1,
  "intval_time": "3s",
  "date": "2026-08-11 12:00:00",
  "liquidated": 0,
  "trust_info": { "pid": 1, "type": 1, "qty": 100, "margin": "10", ... }
}
备注：rest_qty = 张数；number = 标的量 = 张数 × contract_value。 source：1 Web / 2 App / 3 Schedule / 4 强平。

5.3 data.asks / data.bids — 累计深度（面积图 + 50 档对比）

二维数组 [价格, 累计标的量]，与 PHP 侧 $newAsksData / $newBidsData 一致：

"asks": [[0.25350, 100.0], [0.25353, 250.0], ...],
"bids": [[0.25344, 120.0], [0.25341, 285.0], ...]
备注：asks 按价格升序，bids 按价格降序；第二列为累计标的量（前端会 decumulate 成单档量）。

5.4 data.depth_analyze

HTML 字符串，深度图 tooltip 展示，格式：_{百分比} : {买量} / {卖量} <br/>

7. /debug/klineDiff 数据结构

来源：Debug/Index.php::klineDiff() + KlineLogic::kline()

请求参数（页面固定拼法）：

?symbol_id=1000003&resolution=1&size=1000&from={unix}&to={unix}
{
  "code": 0,
  "msg": "success",
  "data": {
    "last": {
      "symbolId": 1000003,
      "symbolName": "TRXUSDT",
      "kline": [
        { "t": 1786424157, "o": 0.25347, "h": 0.25367, "l": 0.25331, "c": 0.25347, "v": 50000 }
      ]
    },
    "mark": {
      "symbolId": 1000003,
      "symbolName": "TRXUSDT",
      "kline": [
        { "t": 1786424157, "o": 0.25347, "h": 0.25367, "l": 0.25331, "c": 0.25347 }
      ]
    }
  }
}
备注：t 为 Unix 秒级时间戳；last.kline 含成交量 v，mark.kline 无 v。 展开 K 线面板后每 5s 拉取一次。

8. 目录结构

depth-chat/
├── depth-chat.html          # 主页面（sync + mock hooks）
├── demo.html                # 本说明页
├── config/api-config.json   # api_base 与 mock 规则
├── js/
│   ├── mock-data.js         # 内嵌配置 + 全部 mock（file:// 兜底，脚本生成勿手改）
│   ├── api-config.js        # 加载配置（file:// 下改读 mock-data.js）
│   └── mock-bridge.js       # 拦截 jQuery.ajax 与原生 fetch / 下拉重写
├── data/mock/
│   ├── mock.json                 # 接口索引 + 说明
│   ├── exchangeInfo.json
│   ├── tickerList.json
│   ├── exchangePrice.json
│   ├── priceHash.json
│   ├── depthGather.default.json
│   ├── depthGather.symbol-1000001.json
│   ├── depth.default.json
│   ├── depth.symbol-1000001.json
│   ├── depth.symbol-1000003.json
│   ├── klineDiff.default.json
│   ├── klineDiff.symbol-1000001.json
│   └── klineDiff.symbol-1000003.json
├── tools/gen-mock-data.py   # 重新生成 js/mock-data.js
├── test/
│   ├── mock-smoke-test.js   # mock 链路冒烟测试（node，DOM 桩）
│   └── e2e-browser.js       # 浏览器级 e2e（真实 Chrome，需 puppeteer-core）
└── apply-mock-hooks.sh      # sync 后注入脚本

9. 维护

# 从 smoneyfuturesservice 同步并重新注入 mock hooks
cd quant-visual-tools && ./sync.sh

# 改过 data/mock/*.json 或 config/api-config.json 后，必须重新打包 file:// 兜底数据
cd depth-chat && python3 tools/gen-mock-data.py

# 验证 mock 链路（file:// 与 http:// 两种场景，无需浏览器）
cd depth-chat && node test/mock-smoke-test.js

# 浏览器级 e2e（真实 Chrome，查脚本时序 / 渲染 / 请求泄漏）
./start.sh 8123                      # 另开终端
npm i puppeteer-core                 # 一次性
cd depth-chat && PORT=8123 node test/e2e-browser.js
两个测试覆盖面不同：mock-smoke-test.js 用 DOM 桩验数据链路，快； e2e-browser.js 跑真实 Chrome，能抓到脚本加载时序问题—— 比如 mock 补丁装晚了导致首个 exchangeInfo 漏到生产域名，这类 bug 桩测试结构上测不出来。
忘记跑 gen-mock-data.py 的后果：http:// 下看到新数据，file:// 下还是旧数据， 两边对不上很难排查。

接口实现参考：smoneyfuturesservice/script/src/Controller/Debug/Depth.php、 Debug/Index.php::klineDiff