# 软总线系统架构文档

## 目录结构

```
soft_bus/
├── src/
│   ├── common/                # [公共定义] 所有层共用的数据结构、枚举、DOM模型
│   │   ├── dom/               # DOM模型定义 (ProcessData, ControlCommand...)
│   │   │   └── DomBase.h
│   │   └── types.h
│   │
│   ├── core/                  # [核心逻辑] 没有任何 UI 代码，可以在无头模式运行
│   │   ├── pal/               # Layer 1: Protocol Adapter Layer (协议适配)
│   │   │   ├── interfaces/    # 协议插件接口
│   │   │   │   └── IProtocolAdapter.h
│   │   │   └── serial/        # 对应原 serial_manager
│   │   │       └── SerialProtocolAdapter.h/cpp
│   │   │
│   │   ├── dal/               # Layer 2: Data Abstraction Layer (数据抽象)
│   │   │   ├── mapper/        # 映射引擎 (Addr -> Name)
│   │   │   │   └── DataMapper.h/cpp
│   │   │   └── processor/     # 预处理 (Deadband, Scale)
│   │   │       └── DataProcessor.h/cpp
│   │   │
│   │   ├── sbl/               # Layer 3: Service Bus Layer (服务总线核心)
│   │   │   ├── dispatcher/    # 消息调度内核
│   │   │   │   └── MessageDispatcher.h/cpp
│   │   │   └── pubsub/        # 发布订阅引擎 (Topic Tree)
│   │   │       └── TopicTree.h/cpp
│   │   │
│   │   └── SoftBusCore.h/cpp  # 核心单例/入口，管理上述模块的生命周期
│   │
│   ├── api/                   # Layer 4: Unified Interface Layer (统一接口)
│   │   └── SoftBusAPI.h/cpp   # UI 唯一调用的头文件
│   │
│   └── gui/                   # [界面层] 纯粹的视图，只负责显示和发送指令
│       ├── main_window/
│       ├── view_serial/       # 移除内部逻辑，改为通过 API 获取数据
│       ├── view_can/
│       └── message_viewer/
│
└── main.cpp                   # 程序入口，负责组装 Core 和 GUI
```

## 数据流

### 数据采集流程（上行）

```
物理设备 
  -> ProtocolAdapter (PAL层: 协议解析)
  -> DataMapper (DAL层: 地址映射、工程量转换)
  -> MessageDispatcher (SBL层: 优先级队列、路由)
  -> SoftBusAPI (API层: 统一接口)
  -> UI Widgets (GUI层: 显示)
```

### 控制指令流程（下行）

```
UI Widgets (GUI层: 用户操作)
  -> SoftBusAPI::sendCommand() (API层)
  -> MessageDispatcher (SBL层: 高优先级队列)
  -> ProtocolAdapter (PAL层: 协议封装)
  -> 物理设备
```

## 核心组件说明

### 1. DOM模型 (Domain Object Model)

定义在 `src/common/dom/DomBase.h`：

- **ProcessData**: 过程数据，高频刷新
- **ControlCommand**: 控制指令，必达，需确认
- **MonitorData**: 监控数据，状态变化驱动
- **ManagementData**: 管理数据，大数据量

### 2. 协议适配层 (PAL)

**接口**: `IProtocolAdapter`
- 统一所有协议的接口
- 将物理协议转换为DOM对象

**实现**: 
- `SerialProtocolAdapter`: 串口协议适配器
- 未来可扩展: `CanProtocolAdapter`, `ModbusTcpAdapter`等

### 3. 数据抽象层 (DAL)

**DataMapper**: 
- 加载映射配置（JSON/XML）
- 物理地址 -> 逻辑点名
- 工程量转换（Scale/Offset）
- 死区过滤（Deadband）

**DataProcessor**:
- 数据质量标记
- 限值检查

### 4. 服务总线层 (SBL)

**MessageDispatcher**:
- 优先级队列管理
- 消息路由和分发
- 支持主题订阅

**TopicTree**:
- 高效的主题匹配
- 支持通配符订阅

### 5. 统一接口层 (API)

**SoftBusAPI**:
- UI层唯一调用的接口
- 提供简单的查询、订阅、发送接口
- 屏蔽底层复杂性

## 使用示例

### 初始化

```cpp
// 1. 初始化API
SoftBusAPI* api = SoftBusAPI::instance();
api->initialize();

// 2. 注册协议适配器
SerialProtocolAdapter* adapter = new SerialProtocolAdapter();
adapter->setSerialManager(serialManager);
SoftBusCore::instance()->registerProtocolAdapter(adapter);

// 3. 加载映射配置
SoftBusCore::instance()->getDataMapper()->loadProfile("config/tag_mapping.json");
```

### UI订阅数据

```cpp
// 订阅所有数据
api->subscribe("*");

// 连接信号
connect(api, &SoftBusAPI::dataChanged,
        this, &MyWidget::onDataChanged);

void MyWidget::onDataChanged(QString tagName, QVariant value, int quality) {
    if (tagName == "Tank.Level") {
        ui->labelLevel->setText(value.toString());
    }
}
```

### 发送控制指令

```cpp
// 发送控制指令
api->sendCommand("Pump.Main.Control", 1, true);

// 监听确认
connect(api, &SoftBusAPI::commandAcknowledged,
        this, &MyWidget::onCommandAck);
```

## 扩展性

### 添加新协议

1. 实现 `IProtocolAdapter` 接口
2. 在初始化时注册到 `SoftBusCore`
3. 无需修改其他层代码

### 添加新传输方式

1. 在 `core/sbl/transport/` 下实现传输适配器
2. 修改 `MessageDispatcher` 使用新的传输方式
3. UI层无需修改

### 无头模式运行

核心层（core/）不依赖Qt Widgets，可以：
- 编译为库文件
- 在CLI程序中使用
- 在服务器端运行