softbus_OPC/docs/softbus_core.md

# softbus_core

**路径：** `src/softbus_core`  
**构建目标：** `softbus_core`（STATIC 库）  
**层级：** L0 内核层

## 1. 概述

`softbus_core` 是全项目共享内核，提供数据模型、身份标识、配置加载、插件 ABI、日志、平台信号与时间对齐。所有上层模块均依赖本库，且模型设计保持**传输中立**——不含 D-Bus、HTTP、OPC UA 特定字段。

## 2. CONSTRAINTS

- `softbus_core` 拥有进程无关的共享模型、元数据定义、插件接口与配置解析。
- 模型结构体必须保持传输中立，不得在字段中编码 D-Bus、HTTP、Qt 或 OPC UA 特定语义。
- 插件接口须保持 ABI 稳定：优先新增字段与能力方法，避免改变已有方法语义。
- `ObjectRef` 五层路径是唯一对象寻址约定，格式为 `Site/System/Asset/Device/Point`。
- 空配置与首次运行状态合法，`ProfileLoader` 失败须由调用方处理。
- `traceId` 由 `DeviceIdentity` 统一生成，格式 `trace-xxxxxxxx`。

## 3. 子模块

### 3.1 models — 数据模型

| 类型 | 文件 | 说明 |
|------|------|------|
| `RawPacket` | `models/RawPacket.h` | 边缘上行原始包 |
| `RawBusMessage` | `models/RawBusMessage.h` | `RawPacket` 类型别名 |
| `DOMMessage` | `models/DOMMessage.h` | 统一语义消息 |
| `ObjectModelTree` | `models/ObjectModel.h` | 五层对象树定义 |
| `ObjectRef` | `models/ObjectModel.h` | 对象引用与路径转换 |
| `MetadataDef` | `models/MetadataDef.h` | 测点元数据（dataType, unit, scale） |

**RawPacket 字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `traceId` | string | 追踪标识 |
| `timestampNs` | uint64_t | 纳秒时间戳 |
| `runtimeDeviceId` | string | 运行时设备 ID |
| `sourceId` | string | 源对象路径 |
| `protocolTag` | string | 协议标签 |
| `payload` | vector<uint8_t> | 原始字节 |

**DOMMessage 字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 消息标识（通常等于 objectRef） |
| `sourceId` | string | 源对象路径 |
| `domain` | string | 数据域，如 `Process` |
| `quality` | string | 数据质量，如 `Good` |
| `value` | json | 语义值对象 |
| `traceId` | string | 追踪标识 |
| `timestampNs` | uint64_t | 时间戳 |

### 3.2 identity — 设备身份

| 类/函数 | 说明 |
|---------|------|
| `DeviceIdentity::generateTraceId()` | 生成 `trace-xxxxxxxx` |
| `DeviceIdentity::generateRuntimeDeviceId()` | 生成 `runtime-xxxxxxxx` |
| `DeviceIdentity::buildObjectRef(tree, device, point)` | 从模型构建 ObjectRef |

### 3.3 config — 配置加载

| 类 | 说明 |
|----|------|
| `ProfileLoader` | 解析 `daemon_profile.json` → `DaemonProfile` |
| `DaemonProfile` | 含 `opcua`、`uplink`、`plugins`、`security` 子结构 |
| `ObjectModelTree::loadFromFile()` | 解析 `softbus_model.json` |

### 3.4 plugin — 插件基础设施

| 接口 | 说明 |
|------|------|
| `IFramer` | 分帧：`extract(data, size) → FrameResult` |
| `IParser` | 解析：`parseFrame(data, size, sourceId) → ParseResult` |
| `PluginLoader` | dlopen/LoadLibrary 动态加载插件 |
| `SOFTBUS_PLUGIN_API` | C ABI 导出宏 |

**插件 C ABI 导出函数：**

```c
SOFTBUS_PLUGIN_API IFramer* create_framer();
SOFTBUS_PLUGIN_API void destroy_framer(IFramer* framer);
SOFTBUS_PLUGIN_API IParser* create_parser();
SOFTBUS_PLUGIN_API void destroy_parser(IParser* parser);
```

### 3.5 其他子模块

| 子模块 | 文件 | 说明 | Phase 1 状态 |
|--------|------|------|-------------|
| logging | `Logger.h/.cpp` | 单例日志，`SB_LOG_*` 宏自动附带 `[文件::函数]` 调用位置 | 已用 |
| time | `HwClock.h/.cpp` | 纳秒级时间戳 | 已用 |
| alignment | `TimeAligner.h/.cpp` | 多通道时间对齐 | 未接入 |
| platform | `PlatformSignal.h/.cpp` | SIGINT 优雅退出 | 已用 |
| queue | `LockFreeQueue.h` | 无锁队列 | 预留 |

## 4. 依赖

- **对外（PUBLIC）：** nlohmann_json
- **被依赖：** 所有其他模块

## 5. 统一入口

```cpp
#include <softbus_core/softbus_core.h>
```

聚合所有 public 头文件，供上层模块一次性引入。

## 6. 配置关联

| 配置文件 | 加载方 | 对应类型 |
|----------|--------|----------|
| `config/daemon_profile.json` | `ProfileLoader` | `DaemonProfile` |
| `config/softbus_model.json` | `ObjectModelTree` | `ObjectModelTree` |

## 7. 构建

```cmake
# src/softbus_core/CMakeLists.txt
add_library(softbus_core STATIC ...)
target_link_libraries(softbus_core PUBLIC nlohmann_json::nlohmann_json Threads::Threads)
```