SWFX（Dukascopy）XAUUSD L2 → MT4 指标 集成开发文档

本文件定义将 Dukascopy SWFX（JForex 生态）的 XAU/USD 订单簿（L2）集成本地 HTTP，并在 MT4 指标中以 500ms 频率轮询展示的完整方案。按你的偏好：仅 XAUUSD、数量使用“API 原始单位”、传输采用本地 HTTP（非文件桥接）、不做历史回放/导出。

1. 目标与范围

• 目标：在 MT4 的副图窗口稳定显示 XAUUSD 的双边多档深度（DOM），用于内部研判与可视化。
• 刷新与时延：指标端轮询 500ms；整体端到端延迟满足一般可视化（≈200–500ms）。
• 数据单位：数量原样显示（api 原始单位），不额外换算。
• 覆盖范围：仅 SWFX 流动性池的 XAU/USD 订单簿（非全行业多场所聚合）。
• 非目标：策略交易、自动下单、历史 L2 存储与回放、不对外再分发。

2. 成功标准（验收口径）

• DOM 刷新稳定（≈500ms），UI 不抖动，CPU 占用可控。
• 最优买卖价与 JForex 客户端观察保持一致（方向、排序正确）。
• 断连后 ≤1.5s 进入“Stale”，恢复后 ≤1s 回到“Live”。
• 状态与错误有明确提示（Live / Stale / Lost）。

3. 术语与缩写

• SWFX：Dukascopy 的聚合流动性池。
• L2/Order Book：多档深度（价位聚合 MBP 或订单级 MBO）。
• DOM：Depth of Market，可视化盘口表。
• TTL：数据新鲜度阈值（stale_ttl_ms）。

4. 总体架构

1) 采集：本地进程使用 JForex API 订阅 SWFX 的 XAU/USD 订单簿事件。
2) 规范化：将事件合并为快照（双边 N 档），附带时间戳与状态。
3) 发布：在 127.0.0.1:8787 暴露只读 HTTP 接口（不对外开放）。
4) 消费：MT4 指标通过 WebRequest 每 500ms 拉取并渲染 DOM。

注意：MT4 仅做展示与分析；实际交易与该显示数据无绑定关系。

5. 环境与前置条件

• 账户与权限：Dukascopy（Demo 或 Live）账号，启用 JForex API 访问与订单簿订阅权限。
• 运行环境：
  • 本地桥接进程与 MT4 运行在同一台机器（建议 Windows）。
  • 系统时间同步（NTP），避免新鲜度判断误差。
  • 防火墙允许本机回环访问 127.0.0.1:8787。
• MT4 设置：Tools → Options → Expert Advisors → 允许 WebRequest，并加入 http://127.0.0.1:8787 白名单。

6. HTTP 接口契约（本地服务 → MT4 指标）

• 基本信息：
  • Base URL：http://127.0.0.1:8787
  • Endpoint：GET /v1/orderbook?symbol=XAUUSD&levels=20
  • Headers：Content-Type: application/json; charset=utf-8
  • Cache：Cache-Control: no-store
• 状态码：
  • 200 成功：返回完整快照与状态 live|stale。
  • 204 无内容：短暂无数据（保留现有显示）。
  • 503 服务不可用：源断连/维护，指标转“Lost”并退避重试。
• JSON 结构（字段固定，未知字段可忽略）：

  {
  "ts": 1710000000123,             // 快照时间戳（Epoch ms）
  "source": "SWFX",                // 固定源标识
  "symbol_src": "XAU/USD",         // 源符号
  "symbol_hint": "XAUUSD",         // 展示建议（可与 MT4 窗口映射）
  "book_type": "MBP",              // MBP(价位聚合) / MBO(订单级)
  "qty_unit": "api_raw",           // 数量单位标识（原始）
  "qty_scale": 1,                    // 可选缩放因子（默认1）
  "levels": 20,                      // 实际返回档数
  "status": "live",                // live / stale
  "stale_ttl_ms": 1500,             // 建议的新鲜度阈值
  "bids": [                          // 从高到低
  {"p": 2145.30, "q": 500},
  {"p": 2145.29, "q": 420}
  ],
  "asks": [                          // 从低到高
  {"p": 2145.31, "q": 480},
  {"p": 2145.32, "q": 410}
  ],
  "mid": 2145.305,                  // 可选：中价
  "spread": 0.01,                   // 可选：点差（同报价精度）
  "latency_ms": 28                  // 可选：端到端延迟估计
  }

• 数据规则：
  • bids 单调不增、asks 单调不减；价格与数量为数值类型。
  • 档数不足时返回更少项；levels 反映实际返回档数。
  • status=stale 定义为当前时间与 ts 之差 > stale_ttl_ms。
  • 建议服务端输出频率 200–500ms，避免 UI 抖动；若无更新可重复上次快照但调整 ts 以反映心跳。

7. MT4 指标对接规范（行为与参数）

• 参数建议：
  • server_url：http://127.0.0.1:8787/v1/orderbook?symbol=XAUUSD&levels=20
  • refresh_ms：500（内部节流窗口）
  • stale_ttl_ms：1500（与服务端建议一致）
  • levels：10–20（显示档数上限）
  • qty_unit_label：api_raw（尾注显示单位）
  • symbol_map：可选，用于 MT4 窗口符号后缀映射（例：XAUUSD.a->XAU/USD）
• 拉取与节流：
  • WebRequest 轮询 server_url；HTTP 超时 300–400ms，失败时退避重试。
  • 采用 Timer 或 OnTick+节流，确保平均 500ms 一次渲染。
• 解析与对齐：
  • 解析固定字段（见第 6 节），忽略未知字段以增强兼容性。
  • 价格按当前符号 Digits 格式化显示；不更改数值。
  • 数量按 api_raw 原样显示；在尾注标明单位与 scale。
• 新鲜度与状态：
  • now - ts ≤ stale_ttl_ms：显示“Live”（绿色）。
  • now - ts > stale_ttl_ms：显示“Stale”（灰/黄），保留上一快照。
  • 连续错误或 503：显示“Lost”（红），提示错误码与简述。
• 渲染规范：
  • 列布局：BidQty | BidPx | | AskPx | AskQty，双边对齐，支持 N 档。
  • 颜色：买盘绿、卖盘红、表头灰、状态色区分；高亮最优一档。
  • 尾注：显示 ts / levels / qty_unit_label / status。
• 健壮性：
  • 204/空数组：保留上次显示；轻提示。
  • 自检：负价差或无序数据 → 丢弃该轮渲染。
  • 资源：复用 UI 对象，减少创建/删除造成的抖动。

8. 安装与配置步骤（无代码）

1) Dukascopy 账户准备：确认 JForex API 权限与 XAU/USD 订单簿可用。
2) 本地桥接服务：与 MT4 同机运行，仅监听 127.0.0.1:8787；实现第 6 节的接口契约。
3) MT4 白名单：Tools → Options → Expert Advisors → 允许 WebRequest，添加 http://127.0.0.1:8787。
4) 指标加载：将 DOM 指标加载到 XAUUSD 图表副图；设置参数（server_url、refresh_ms=500、stale_ttl_ms=1500、levels）。
5) 验证：最优价同步、状态切换正确、断连/恢复行为符合预期。

9. 监控与故障排查

• 健康状态：
  • Live：数据新鲜，DOM 正常更新。
  • Stale：超过 TTL 未更新；多见于源端间歇或网络抖动。
  • Lost：HTTP 503 或连续超时；检查桥接进程/白名单/端口占用。
• 常见问题速查：
  • 指标显示“HTTP 401/403”：检查 MT4 WebRequest 白名单是否包含完整 URL 前缀。
  • “超时/504”：降低 HTTP 超时（≤400ms）并确认本地服务响应时间；观察 CPU 负载。
  • “JSON 解析失败”：检查服务返回头与负载是否 UTF‑8/JSON；字段名与类型是否符合契约。
  • “价差为负/排序错”：丢弃该帧并记录告警，核查服务排序逻辑与源数据异常。

10. 合规与限制

• 数据用途限于自用/内部展示；不得对外再分发或公开展示，遵守 Dukascopy 数据使用条款。
• 禁止桥接服务向外网开放；仅绑定本机回环地址，避免数据外泄风险。

11. 变更管理

• v1.0：初始版本（仅 XAUUSD，HTTP 方案，500ms，api_raw 单位，不含历史）。
• 后续若引入多标的或图形化阶梯，请增补字段或新增端点并维护兼容性。

12. 验收清单（Checklist）

• [ ] 白名单设置：http://127.0.0.1:8787 已加入 MT4 WebRequest 允许列表。
• [ ] 拉取频率：指标 500ms 轮询稳定，CPU 占用可控。
• [ ] 数据一致性：JForex 与 MT4 DOM 最优价方向与排序一致。
• [ ] 状态切换：断连 ≤1.5s 变 Stale；恢复 ≤1s 变 Live。
• [ ] 异常处理：204/503/超时/乱序均有明确 UI 提示且不崩溃。
• [ ] 单位与精度：数量显示 api_raw，价格按 Digits 格式化。

13. 附录

13.1 字段说明

• ts：毫秒时间戳（Epoch ms），用于新鲜度判断。
• source：固定字符串 SWFX，便于多源扩展时识别。
• symbol_src：源头符号（XAU/USD）。
• symbol_hint：展示符号建议（如 XAUUSD），供 MT4 对齐。
• book_type：MBP/MBO，当前以 MBP 为主。
• qty_unit：api_raw 表示数量为源 API 原始单位。
• qty_scale：数量缩放因子（默认 1）。
• levels：本次快照实际返回档数。
• status：live/stale（源服务基于 stale_ttl_ms 计算）。
• stale_ttl_ms：建议新鲜度阈值（默认 1500）。
• bids/asks：按价位排序的数组，元素含 p（价格）、q（数量）。
• mid/spread/latency_ms：可选诊断字段。

13.2 示例请求与响应（仅示例）

• 请求：GET http://127.0.0.1:8787/v1/orderbook?symbol=XAUUSD&levels=20
• 响应（200 OK）：

  {
  "ts": 1710000000456,
  "source": "SWFX",
  "symbol_src": "XAU/USD",
  "symbol_hint": "XAUUSD",
  "book_type": "MBP",
  "qty_unit": "api_raw",
  "qty_scale": 1,
  "levels": 10,
  "status": "live",
  "stale_ttl_ms": 1500,
  "bids": [{"p":2145.30,"q":500},{"p":2145.29,"q":420}],
  "asks": [{"p":2145.31,"q":480},{"p":2145.32,"q":410}],
  "mid": 2145.305,
  "spread": 0.01,
  "latency_ms": 22
  }

如需扩展到图形化阶梯、分层配色或引入分源维度，请在维持兼容的前提下增加可选字段，并在指标端做容错解析即可。