endpointhash

docs/数据流转.md

@@ -4,7 +4,7 @@
 
 - **物理设备**：真实硬件端口（当前主要是串口），由 `SerialQtDriver` 直接读写。
 - **设备实例**：`SerialDevice`，负责单设备生命周期、驱动回调、上下行数据接入。
-- **原始总线消息**：`RawBusMessage`，包含 `endpoint`、`protocolHint`、`payload`、`traceId`、`direction` 等基础字段。
+- **原始总线消息**：`RawBusMessage`，包含 `endpointHash`、`protocol`、`routingKey`、`header`、`payload`、`traceId`、`direction` 等基础字段。
 - **流水线上下文**：`PipelineContext`，继承 `RawBusMessage`，增加 `frameKind`、`frameSeq` 等管道字段。
 - **业务消息**：经过协议解析和映射后得到 `DOMMessage`（统一语义数据）。
 
@@ -30,10 +30,12 @@
 1. 从 `MemoryPool` 分配内存块并拷贝原始字节。
 2. 构造 `RawBusMessage`：
    - `direction = Upstream`
-   - `endpoint = 串口名`
-   - `protocolHint = DeviceInfo.protocol`
-   - `payload/payloadSize = 原始字节数据`
-   - `traceId = serial:<endpoint>:<timestamp>`
+   - `endpointHash = makeEndpointHash(串口名)`
+   - `protocol = protocolTypeFromHint(DeviceInfo.protocol)`
+   - `routingKey = makeRoutingKey(endpointHash, deviceId)`
+   - `header = ProtocolHeader{}`（由后续 framer/parser 按协议填充 OOB 元数据）
+   - `payload = 原始字节数据`（长度由 `payload.length` 表示，不再维护 `payloadSize`）
+   - `traceId = serial:<endpoint>:<timestampMs>`
 3. 调用 `m_ingress->push(std::move(ctx))` 进入统一入口。
 4. 若内存池不足或 ingress 队列满，通过 `reportError(...)` 记录错误。
 
@@ -54,7 +56,7 @@
 `enqueueIngress(...)` 分两种模式：
 
 - **并行模式（parallelPipeline=true）**
-  - 按 `endpoint` 创建/复用独立 `EndpointFramingState`（每端点一个分帧线程 + chunk 队列）。
+  - 按 `endpointHash` 创建/复用独立 `EndpointFramingState`（每端点一个分帧线程 + chunk 队列）。
   - chunk 先进入端点队列，端点线程负责分帧并赋值 `frameSeq`。
   - 完整帧进入 `m_framedQ`，由解析线程池处理。
 - **单线程模式（parallelPipeline=false）**
@@ -64,9 +66,10 @@
 
 `dispatchFramer(...)` 的选择策略：
 
-1. 优先根据 `protocolHint` 从插件管理器选择协议分帧插件。
-2. 按 `endpoint + pluginId` 复用 framer session（保持协议状态机连续性）。
+1. 按 `protocol`（`ProtocolType`）从插件管理器选择协议分帧插件。
+2. 按结构化键 `SessionKey{endpointHash, pluginId}` 复用 framer/parser/mapper session（保持协议状态机连续性）。
 3. 若没有可用插件，降级到 `PassthroughFramer`（透传/整包策略）。
+4. framer session 创建接口已升级为 `createFramerSession(uint32_t endpointHash, ...)`，不再传递 endpoint 字符串。
 
 输出：`frameKind = CompleteFrame` 的帧批次。
 
@@ -84,6 +87,7 @@
    - 最低校验当前为 `messageId` 非空。
 4. **Transform/Enrich**
    - 仅对通过 filter+validator 的 `DOMMessage` 应用动态规则（scale/offset/unit）。
+  - 规则作用域按 `endpointHash/deviceId/stableKey` 匹配，不再按 endpoint 字符串匹配。
    - 写入 trace，补充富化字段。
 
 说明（与代码一致）：
@@ -96,7 +100,7 @@
 - 未开启有序出口：解析成功后直接进入 `m_egressQ`。
 - 开启 `orderedEgress`：
   - 解析线程先写入 `m_mergeQ`。
-  - `mergerLoop` 按 `endpoint + frameSeq` 重排。
+  - `mergerLoop` 按 `endpointHash(映射键) + frameSeq` 重排。
   - 使用 `nextExpected` 保证同端点有序输出。
   - 超过 `maxReorderDepth` 的乱序缓存上限会丢弃并计数。
 
@@ -138,7 +142,7 @@ SerialQtDriver(read callback)
 ## 6. egress 到设备（现状）
 
 - `DeviceBusManager` 已启动 `processEgressLoop`，持续从 `PipelineEngine::tryPopEgress` 取数据并调用 `EgressRouter::send`。
-- `EgressRouter` 已实现 `endpoint -> SerialDevice` 查找和 `writePayload(...)` 发送。
+- `EgressRouter` 已实现基于 `endpointHash` 的 `SerialDevice` 查找和 `writePayload(...)` 发送。
 - 当前关键缺口：`SerialDeviceManager::initializeSerialDeviceWithDeps` 中 `bindSerialDevice(...)` 仍被注释，导致路由表通常为空，`send` 多数返回失败。
 - 因此当前链路是“egress 框架已存在，但默认没有绑定到串口实例”。