From 52760cfa9918711ed5753c852fd8f6e9a3ade951 Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Sat, 25 Jul 2026 12:41:11 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=BE=E5=A4=87=E5=9C=A8=E7=BA=BF?=
 =?UTF-8?q?=E7=8A=B6=E6=80=81=E8=AE=BE=E8=AE=A1=E5=8E=9F=E5=88=99=E2=80=94?=
 =?UTF-8?q?=E2=80=94UDP=E4=BB=85=E7=94=A8=E4=BA=8E=E5=8F=91=E7=8E=B0?=
 =?UTF-8?q?=EF=BC=8CHTTP=E5=88=A4=E6=96=AD=E5=8F=AF=E8=BE=BE=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/device-online-design.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 docs/device-online-design.md

diff --git a/docs/device-online-design.md b/docs/device-online-design.md
new file mode 100644
index 0000000..1088563
--- /dev/null
+++ b/docs/device-online-design.md
@@ -0,0 +1,25 @@
+# 设备发现与在线状态设计原则
+
+## 核心划分
+
+| 机制 | 职责 | 使用场景 |
+|------|------|---------|
+| **UDP 广播 (35688)** | **仅设备发现** | 扫描局域网、发现新设备、刷新设备列表 |
+| **HTTP API (端口 9100)** | **判断设备是否可达** | 所有业务操作前确认设备在线 |
+| **registry.Online 字段** | **仅用于 UI 展示** | 设备列表的在线/离线指示灯 |
+
+## 禁止行为
+
+- ❌ 业务操作依赖 `dev.Online` 做准入判断
+- ❌ 在 HTTP 调用链中引用 `dev.Online` 跳过请求
+- ❌ 用 UDP 发现超时判断设备是否在线
+
+## 正确做法
+
+- ✅ `dev.Online` 只在 UI 层展示在线/离线状态
+- ✅ 业务操作直接发起 HTTP 请求，由 HTTP 成功/失败判断可达性
+- ✅ UDP 搜索只在页面加载、手动刷新、设备列表时触发
+
+## 设计理由
+
+UDP 包可能在交换机上被丢弃，设备可能已通过 DHCP 换 IP，广播可能被防火墙拦截。`Online` 字段只能作为近似的 UI 提示，不能作为业务逻辑依据。HTTP 请求的真实结果才是唯一可靠的在线判断。