From f555dcc6c7ca5d8ed8aabcb5113a0aedd5c4360d Mon Sep 17 00:00:00 2001
From: gavindiaz <cnws2018@gmail.com>
Date: Thu, 9 Jul 2026 06:12:37 +0000
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0API=E4=BD=BF=E7=94=A8?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Mt5Bridge使用指南.md | 45 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/Mt5Bridge使用指南.md b/Mt5Bridge使用指南.md
index 2c70fd4..d3840cd 100644
--- a/Mt5Bridge使用指南.md
+++ b/Mt5Bridge使用指南.md
@@ -156,6 +156,44 @@ broker 实际 fill:     1.41715
 
 两者都是 `10009 = success`，但**别假设 0 是 success**。建议统一判 `retcode == 10009`。
 
+### P7. `data: []` 与"默认值数据"的语义混淆
+
+Bridge 的所有 list 端点（`/account`, `/positions`, `/orders`, `/history/deals`, `/symbols` 等）都遵循这个统一约定：
+
+- **"有数据"** ⇒ `{"data": [{...}], "count": 1, ...}`
+- **"无数据"** ⇒ `{"data": [], "count": 0, ...}`（**HTTP 仍 200**，不是错误）
+
+客户端很容易把"无数据"误判成"默认值数据"。例：
+
+```python
+# ❌ 错：data:[] 时 fallback 到 {}，默认零值看着像合法数据
+info = api('/account')
+acc = (info.get('data') or [{}])[0]
+if not acc.get('trade_allowed'):
+    raise PermissionError('trading disabled')
+    # ↑ 实际可能是"账户未登录"，不是"Algo Trading 真关闭"
+
+# ❌ 错：bool({})==True，让健康检查通过
+if api('/account'):
+    mark_healthy()
+```
+
+**正确做法**：用 `data` 长度 + 身份字段（如 `login`、`ticket`）作为"真实数据就绪"的标志：
+
+```python
+def data_ready(info, key='login'):
+    """data 非空 + 身份字段 > 0 ⇒ 真实数据"""
+    items = info.get('data') or []
+    return bool(items) and (items[0].get(key, 0) if items else 0) not in (0, None, '')
+
+# ✅
+info = api('/account')
+if not data_ready(info, 'login'):
+    raise ConnectionError('account not loaded yet')
+```
+
+**适用所有 list 端点**。判 `positions`、`orders`、`deals` 同理。
+
 ---
 
 ## 1. 健康检查
@@ -1080,7 +1118,7 @@ Invoke-RestMethod "http://61.164.252.86:13485/rates/from-date?symbol=XAUUSD&time
 
 ## 常见问题
 
-> **第一次调这个 bridge？先去读 [§「⚠️ 隐含约定与已知陷阱」](#-隐含约定与已知陷阱先读)** —— 6 个非显而易见的约定（date_to 排他、`entry` 字段语义反、`/order/send` 不返回 fill 价 等），不读这一节直接调接口几乎必踩。
+> **第一次调这个 bridge？先去读 [§「⚠️ 隐含约定与已知陷阱」](#-隐含约定与已知陷阱先读)** —— 7 个非显而易见的约定（date_to 排他、`entry` 字段语义反、`/order/send` 不返回 fill 价、`/account` 空 data 误判 等），不读这一节直接调接口几乎必踩。
 
 ### 返回 "Unauthorized"
 API Key 错误或没带。检查 Header 中的 `X-API-Key` 或 URL 中的 `?key=`。
@@ -1098,4 +1136,7 @@ API Key 错误或没带。检查 Header 中的 `X-API-Key` 或 URL 中的 `?key=
 多半是手动把 `positions.profit` 当 quote currency 处理。`positions.profit` 是 deposit currency（USD），不是 quote currency。详见 §隐含约定 P4。
 
 ### 返回 "无法连接到远程服务器"
-Bridge 未运行或网络不通，先检查 `/health`。
\ No newline at end of file
+Bridge 未运行或网络不通，先检查 `/health`。
+
+### 业务字段返回默认值 → 怎么区分"无数据"和"真状态"
+`/account` 在账户未加载完成时返回 `data:[]` + 全零字段（HTTP 200）。客户端若只看 `bool(response)` 或 `field == 0`，会把"无数据"误判成"零值正常状态"。详见 §隐含约定 P7。
\ No newline at end of file