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 请求的真实结果才是唯一可靠的在线判断。