- 根 docs/ 保留产品入口文档(README/部署手册/检查表/离线部署)
- 按内容归类到子目录:
  requirements/(需求) design/(设计/接口/方案/UI) architecture/(架构)
  implementation/(实施/计划/跟踪) bugfix/(缺陷记录) testing/(测试)
  guides/(操作指南:配置/模型/命令/依赖/调试) archive/(源码片段归档)
- 删除 superpowers 目录(edge 与 control 两处, 含历史设计草稿)
- 更新 docs/README.md 导航与新结构一致

2026-08-02 11:28:51 +08:00

1.1 KiB

Raw Blame History

设备发现与在线状态设计原则

核心划分

机制	职责	使用场景
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 请求的真实结果才是唯一可靠的在线判断。

1.1 KiB Raw Blame History Unescape Escape

设备发现与在线状态设计原则

核心划分

禁止行为

正确做法

设计理由

1.1 KiB

Raw Blame History