endpointhash 1.0

docs/数据流转.md

@@ -152,4 +152,55 @@ SerialQtDriver(read callback)
 
 1. `traceId` 建议在全链路透传到最终发布侧，便于定位帧级问题。
 2. 为 Stage2/Stage3/Stage4 增加细粒度指标（成功率、耗时、drop 原因）。
-3. 文档后续可新增“协议插件开发约定”章节（framer/parser/mapper 三类插件接口对照）。
+3. 文档后续可新增“协议插件开发约定”章节（framer/parser/mapper 三类插件接口对照）。
+
+---
+
+## 8. 无规则冷启动与发现池（新增）
+
+### 8.1 设计目标
+
+- 默认保持极致性能：**未命中映射规则的寄存器不会产出 DOMMessage**。
+- 仅在配置页面开启时进入“嗅探模式（Sniffer Mode）”，将未命中点位以低成本写入内存发现池。
+- 发现池只维护“最近值”，不做全量历史存储，避免高频总线拖垮系统。
+
+### 8.2 Mapper 行为（Modbus RTU）
+
+`ModbusRtuProtocolMapperPlugin` 当前行为：
+
+1. 对 `ReadHoldingRegistersRequest` 记录 `unitId -> startAddress`，用于后续响应地址回填。
+2. 对 `ReadHoldingRegistersResponse` 遍历寄存器并构造 `compositeKey`：
+   - `compositeKey = endpointHash + protocol + slaveId + registerAddress`（位拼接）。
+3. 若 `MappingRegistry` 命中：
+   - 生成 `DOMMessage`，`messageId = domPath`，并应用 `scale/offset/unit`。
+4. 若未命中：
+   - 仅在 `DiscoveryPool.sniffingEnabled=true` 时写入发现池样本；
+   - 主链路继续 `continue`，不生成业务消息。
+
+### 8.3 DiscoveryPool 约束
+
+- 数据结构：`unordered_map<uint64_t, DiscoverySample>`。
+- 样本内容：`compositeKey/endpointHash/protocol/slaveId/registerAddress/rawValue/firstSeenMs/lastSeenMs/hitCount`。
+- 性能保护：
+  - `maxEntries` 限制最大条目数（超限按最旧 `lastSeenMs` 淘汰）；
+  - `minSampleIntervalMs` 做按键限频，降低写放大；
+  - 支持 `ttlMs` 自动关闭嗅探，防止遗留长期开启。
+
+### 8.4 REST API（配置工作台）
+
+- `POST /api/v1/discovery/start`：开启嗅探（可传 `ttlMs`）。
+- `POST /api/v1/discovery/stop`：关闭嗅探。
+- `GET /api/v1/discovery/status`：查看嗅探状态与池容量信息。
+- `GET /api/v1/discovery/samples`：拉取发现样本（支持 `offset/limit/endpointHash/protocol`）。
+- `POST /api/v1/discovery/clear`：清空发现池。
+- `POST /api/v1/mapping/bind`：新增或更新绑定规则（`compositeKey -> domPath + scale/offset/unit`）。
+- `POST /api/v1/mapping/unbind`：删除绑定规则。
+- `GET /api/v1/mapping/list`：查看当前绑定规则。
+
+### 8.5 双向匹配工作流
+
+1. Vue 打开配置页 -> 调用 `discovery/start`。
+2. 左侧“发现列表”轮询 `discovery/samples`。
+3. 用户执行 Bottom-Up（从样本创建 DOM 绑定）或 Top-Down（将样本拖到 DOM 占位符）。
+4. 前端调用 `mapping/bind`，规则即时生效。
+5. 下一帧同 `compositeKey` 数据在 mapper 命中，进入 DOM 主链路；该点位在发现列表中自动消失（查询时过滤已映射键）。