From f0dbe5b1c525b8c65c454a3ecb59f802b9d58ae3 Mon Sep 17 00:00:00 2001
From: ozh <sylphy.ou@tfegroup.com.hk>
Date: Thu, 10 Sep 2026 11:12:18 +0800
Subject: [PATCH] =?UTF-8?q?docs(ble):=20=E8=A1=A5=E8=AE=B0=E6=81=A2?=
 =?UTF-8?q?=E5=A4=8D=E8=BF=87=E6=BB=A4=E6=89=AB=E6=8F=8F=E4=BC=98=E5=85=88?=
 =?UTF-8?q?=E4=B8=8E=E6=8E=92=E9=9A=9C=E6=97=A5=E5=BF=97=E7=9A=84=E5=86=B3?=
 =?UTF-8?q?=E7=AD=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/unified-ble-flow.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/unified-ble-flow.md b/docs/unified-ble-flow.md
index 70978a2..73686e4 100644
--- a/docs/unified-ble-flow.md
+++ b/docs/unified-ble-flow.md
@@ -132,6 +132,19 @@ async function runStandardFlow({ key, ssid, password }) {
 
 ## 6. 修改记录
 
+### 2026-09-10 恢复过滤扫描优先 + 搜索排障日志
+
+#### src/ble/discovery.js
+- 回退 2026-09-09 的"放弃过滤扫描改直接全扫"方案：真机验证该机型下无过滤扫描反而搜不出设备（修改前过滤扫描正常），存在机型兼容差异；恢复 `DISCOVERY_FILTER_SERVICE_UUIDS` 过滤扫描优先 + `fallbackToUnfilteredDiscoveryIfNeeded` 4s 兜底切全扫的原始策略，兜底切换日志（`[BLE][SCAN] filtered scan found nothing, fallback to unfiltered`）可在 vConsole 确认切换是否发生
+- `upsertDevice` 返回布尔（是否新命中），事件通道（`device:found`）与轮询通道（`getBluetoothDevices`）均输出排障日志：`[BLE][SCAN] native devices=N newHits=M`（原生采集总量 vs JS 匹配命中量）、`[BLE][FOUND] event devices=N newHits=M`。真机排障按三级定位：
+  - `native devices=0` → 原生层没采到任何设备（权限/适配器/机型问题）
+  - `native devices>0, newHits=0` → 采到了但 JS 匹配规则全没命中（设备广播内容与关键词不符）
+  - 无任何 `[BLE][SCAN]` 日志 → 扫描流程未走到（初始化/会话状态问题）
+- 启动扫描处输出 `[BLE][SCAN] filtered discovery started` / 过滤启动失败转全扫日志，均带 sessionId
+
+#### src/constants/bluetooth.js
+- 恢复 `DISCOVERY_FILTER_SERVICE_UUIDS` 导出（三个 128 位完整 UUID），供过滤扫描使用
+
 ### 2026-09-09 Taro 迁移后交互卡顿修复
 
 #### src/ble/discovery.js