仪器调试平台 · 程序架构解析报告

系统由 3 类进程 + 1 个服务进程 组成，CAN 总线世界由独立服务进程统一托管：

┌───────────────────────────────── CanSimulatorServer.exe（总线权威，独立进程） ─────────────────────────────────┐
│  TcpListener 127.0.0.1:9000                                                                                      │
│   ├─ TcpSimulatorHost   接受连接，每连接一个 ServerSession                                                        │
│   ├─ ServerSession      HELLO 状态机 + 一问一答保序响应 + EV:RECV 推送（写锁串行、命令期暂存门）                 │
│   ├─ CanBusManager      按名懒建 CanBusSimulator；(bus,nodeIndex) 唯一性仲裁                                     │
│   ├─ CanCommandExecutor 命令串执行（SEND/QUERY/AUTO_RESPONSE/BUS_ECHO/FILTER/LOG/STATUS…）                       │
│   └─ CanBusSimulator    复用原路由/自动响应/总线日志 + 总线级应答器 EchoResponderToSender                    │
│  UI：监听状态 · 节点树 · 实时帧表(TX/RX) · 统计 · 日志 · 应答器复选框                                              │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
        ▲ TCP 9000（NodeChannelTransport）              ▲ TCP 9000（宿主物理会话）
        │                                               │
┌───────┴───────────────┐   命名管道 RPC   ┌────────────┴─────────────┐
│ Plugin.IntegrationTest │ ◄──────────────► │  DeviceBroker.exe         │
│ （主程序，Local 设备）  │  aging.broker-   │ （Broker 共享设备宿主）   │
│  CAN-001/002 …         │  b01.v1          │  CAN-003/004 …            │
└────────────────────────┘                  └───────────────────────────┘

数据文件（%LOCALAPPDATA%\PluginIntegrationTest）：
  data.db  设备定义（含 ExecutionMode=Local/Broker、BrokerId、Endpoint、PhysicalSessionKey）
  arb.db   跨进程租约仲裁（resource_state / lease_history / recovery_checkpoint / authority_meta）
  debug.db 调试会话（debug_session 状态机持久化 + 操作日志）

Local 直连客户端进程内 CanDeviceDriver 经 NodeChannelTransport 直接 TCP 连模拟器。
Broker 代理客户端 CanDeviceDriver 经 BrokerRpcTransport 走命名管道委托宿主，宿主内再用 CanDeviceDriver(NodeChannel) 连模拟器。
服务CanSimulatorServer 是唯一的总线世界权威，所有进程的同名总线其实是同一个进程内的同一总线对象，因此跨进程设备天然互通。

与旧结构的关键差异：不再有"进程内 static 总线字典"，跨进程隔离问题从根上消除；CAN 驱动只剩一个类。

① 用户手动启动 CanSimulatorServer.exe（主程序与 Broker 都不拉起它）
   └ TcpSimulatorHost.StartAsync(9000) 监听；UI 就绪；应答器默认 OFF

② 启动 Plugin.IntegrationTest.exe → MainWindow.InitializePlugins（顺序敏感）
   1. DeviceConfig.InitFinish        → 建库/迁移 data.db
   2. SeedPresetCanDevices()         → 预置 CAN 设备（必须先于基础设施，Bootstrapper 扫库决定注册）
   3. InitializeAutoServices()
      InfrastructureBootstrapper.Initialize(data.db)
        a. DbLeaseStore(arb.db,"local-main")
        b. ReconcileAfterBoot       ← SweepExpired + ApproveRecovery 回收上次进程泄漏/过期租约
        c. LayeredResourceManager 注册进 UtilContainer（"ResourceManager"/"LeaseCoordinator"）
        d. DeviceManager/DeviceService/AutoDeviceFacade/CanBusService
        e. LoadDevicesFromConfig + RegisterBrokeredDrivers（Broker 设备→CanDeviceDriver.CreateBrokerProxy）
   4. 自动拉起 DeviceBroker.exe（存在 Broker 设备时）
      └ BrokerServer 构造时同样 ReconcileAfterBoot(broker:...)
   5. DeviceDebug.InitFinish          ← 此时 UtilContainer 就绪，能拿到仲裁服务

全系统只有一个 CAN 驱动类 CanDeviceDriver，Local/Broker 差异下沉到构造时选择的传输后端 ICanTransport，上层（自动化 DeviceManager.GetDriver、调试面板）完全无感知。

IDeviceDriver（统一契约）
    ▲
CanDeviceDriver  ← 命令解析 / _recvBuffer / DriverFrameReceived 事件 / 连接状态机
 ├─ NodeChannelTransport   (Local)  TCP 直连模拟器：HELLO→命令一问一答→读循环分流响应/推送→断线重连
 └─ BrokerRpcTransport     (Broker) 命名管道委托宿主：SubmitBody RPC→ResultBody 态映射→解析 |PUSHED 捎带

分派来源：
 · DriverFactory.CreateDriver("CAN", endpoint) → new CanDeviceDriver(deviceId, "bus:node")   // Local / 宿主物理会话
 · InfrastructureBootstrapper.RegisterBrokeredDrivers → CanDeviceDriver.CreateBrokerProxy(...) // Broker 客户端

关键：全系统只有一份"节点通道驱动"代码——Broker 模式下宿主内部的物理会话同样是 CanDeviceDriver(NodeChannel)。

5.1 分帧

4 字节大端长度前缀 + UTF8 文本行（SimulatorFraming）。读侧循环读满头部与帧体，天然处理粘包/半包；长度非法抛 InvalidDataException；EOF 返回 null 触发断线感知。

5.2 消息类型

5.3 ServerSession 保序与暂存门

读循环(单线程): 逐行读请求 → Process() → 响应经"写锁"发出 → FlushHeldPushes()
命令处理期间路由产生的 EV:RECV 先进 _heldPushes（满 1000 丢最老），
响应写完后再补发 → 保证客户端"首行必为响应、推送随后"。
空闲期推送：写锁串行即发即走。

错误码：ERR:NODE_BUSY（同 bus 同 nodeIndex 被占）、ERR:NOT_HANDSHAKED、ERR:UNKNOWN_CMD、ERR:BAD_FRAME。

两种"自动回复"能力，语义不同、互不干扰：

OnNodeFrameSent(frame, src=node0):
  1) 路由到其它节点；每个接收节点若 AutoResponseEnabled → SendAutoResponse(回它收到的帧)
  2) 若 EchoResponderToSender：把 frame 复制、SourceNodeId="RESPONDER"，直接投递回发送节点自身
     → 发送节点 FrameReceived → ServerSession 推送 EV:RECV 回该连接 → 发送者收到"回显"

DeviceDebug（壳，SimpleMaskControl 插件入口）
 ├─ 顶栏：设备下拉(仅列未打开设备) + [加入调试] + [关闭当前页] + 刷新
 └─ TabControl
     └─ DeviceDebugTab × N（每个 = 一个设备，独立会话/租约/面板/日志）
          ├─ 信息栏(设备ID/型号/连接/版本/预约/会话状态)
          ├─ [进入维护控制] [退出维护]
          ├─ panelContainer：LoadPanel(kind)
          │     CanDevice → CanDebugPanel(多通道壳) → CanChannelView(单通道)
          │     PowerSupply / PLC → 对应面板
          └─ 操作日志(本会话)

规则：一会一设备——加入时若设备已开则聚焦其 Tab；下拉过滤掉已开设备；关闭 Tab 调 CloseSessionSilently() 释放会话与租约，设备重新回到可选。CAN 通道内部再套一层 CanDebugPanel TabControl，可对同设备开多通道。

OpenSession(deviceId) → ReadOnly
   │ RequestMaintenance：ReserveAsync(复用缓存 ownerToken) 拿维护租约(TTL=300s)
   ▼
AcquiringMaintenance → ActivateMaintenance → MaintenanceActive
   │  └ 启动租约心跳 Timer：每 120s 对每个 MaintenanceActive 会话
   │        Coordinator.Renew(grant, 300) 续期，防 TTL 过期
   │ 退出维护 / 关闭 Tab：CloseSession
   ▼
Closing → Closed（ReleaseReservationAsync 用同一 ownerToken 释放租约；无维护会话则停心跳）

9.1 发送 — Local 设备

CanChannelView.发送 → CanDeviceDriver.SendCommandAsync("SEND:0x300:AA BB")
 → NodeChannelTransport.TransceiveAsync → TCP 写 "SEND:0x300:AA BB"
 → ServerSession 处理 → CanCommandExecutor.HandleSend → CanNode.SendFrame → CanBusSimulator 路由
 → 回 "OK:TX:0x300:2" → 驱动返回；面板加 TX 行

9.2 发送 — Broker 设备（CAN-003）

面板 → CanDeviceDriver(BrokerRpc).SendCommandAsync("SEND:…")
 → BrokerRpcTransport 映射 opCode=SEND,payload=整串 → SubmitBody 经命名管道
 → BrokerServer.ExecuteOneShotAsync：
     ① 白名单+域内设备  ② configHash 对账(INV-04)  ③ 租约栅栏(INV-01/03)  ④ SessionGate 串行
     ⑤ 宿主内 CanDeviceDriver(NodeChannel).SendCommandAsync → TCP → 模拟器路由
     ⑥ ResultBody.Readback 末尾 AppendPushes：把宿主驱动自上次以来收到的 EV:RECV
        以 "|PUSHED:n|EV:RECV…" 拼上 → 同管道返回
 → 客户端 BrokerRpcTransport 剥离 |PUSHED 段并触发 FramePushed

9.3 接收 — 统一事件模型

服务端路由/应答器产生帧 → 目标节点 FrameReceived → ServerSession 推送 EV:RECV
 ├─ Local：NodeChannel 读循环收到 EV:RECV → CanDeviceDriver.OnFramePushed
 │           → _recvBuffer + _pendingPushLines + DriverFrameReceived → 面板 BeginInvoke 上屏
 └─ Broker：宿主读循环收到 → 宿主驱动 _pendingPushLines 暂存
            客户端下一次 STATUS/SEND 轮询时，宿主 AppendPushes 捎带 → 客户端 FramePushed → 事件 → 上屏
（面板 PollTimer 每 100ms 调 QueryAsync("STATUS")：既刷新统计，也触发 Broker 捎带 drain）

• Broker 接收实时性为"请求驱动"：靠宿主 STATUS/SEND 轮询捎带 drain，非纯推送；面板 100ms 轮询保证最终一致。真实硬件无此层。
• owner↔clientInstanceId 弱对齐：同机 arb.db 仅存在性/相位校验，未做签名凭据（V3.0 §13 P2）。
• 应答器为总线级：一次开关作用于该总线所有发送者；如需按节点/按帧ID 精细映射为后续项。
• UI 待办：临时诊断日志撤除；RecoveryRequired 人工审批 UI（现由启动对账代偿）；App.Success/Warn 标题本地化。
• 构建：WPF 链路须用 VS 完整版 MSBuild（不加 /p:Platform=x64）；模拟器核心可 dotnet 构建/测试。

本报告与代码同步于 2026-11-09；实现变更请同步更新本文件。