soft_bus_edge/README.md

# softbus_edge_agent

独立边缘进程：连接核心 `softbus_daemon` 的 **edgeIngress** TCP 端口，发送 **HELLO**、**DATA_RAWBUS**，以及通过极简 **本地 HTTP**（`GET /`、`GET /ui`、`POST /propose` 等）触发 **TREE_PROPOSE** 反向同步。

## 目录布局（与 `softbus_daemon` 的 `src/` 对齐）

| 路径 | 说明 |
|------|------|
| `src/device_bus/tree/` | 与核心同源的 `DeviceTreeModel`（本地子树、`TREE_FULL` 落盘加载） |
| `src/device_bus/monitor/` | **udev 串口发现**、`EdgeDiscoveryCoordinator`（防抖后组 `TREE_PROPOSE` / `upsert` 向核心注册） |
| `src/device_bus/manager/` | `SerialDeviceManager`、`CanDeviceManager`（无 Registry / Pipeline，仅 `IIngressPort` + 内存池） |
| `src/device_bus/EdgeDeviceBus.*` | 边缘总线编排：加载本地树、**reconcile** 串口与 **SocketCAN** 实例 |
| `src/devices/`、`src/hardware/` | 与核心同源的 `SerialDevice`、`SerialQtDriver` 等 |
| `src/message_bus/ingress/` | `EdgeSession`、`EdgeUplinkWire`、`EdgeTcpUplinkPort`（`RawBusMessage` → SBUP 上行） |

协议与核心侧文档对齐：

- 核心权威说明：[softbus_daemon/docs/EDGE_UPLINK_PROTOCOL_v1.md](../softbus_daemon/docs/EDGE_UPLINK_PROTOCOL_v1.md)（若仓库路径不同请自行调整相对链接）。

## 构建

```bash
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64
cmake --build build
./build/bin/softbus_edge_agent config/edge_manifest.example.json
```

依赖 **Qt6 Core、Network、SerialPort**；若 Qt 安装包含 **SerialBus** 模块，CMake 会自动检测并链接，从而在边缘启用 **SocketCAN reconcile**（设备树 `can:...` 节点）。未安装时仍可完整构建，CAN 节点将被忽略。

## 配置 `edge_manifest.json`（可选）

若默认路径 **`config/edge_manifest.json`** 不存在、或传入的 manifest 路径无法打开、或 JSON 非法，进程会使用**内置默认值**启动（等价于示例 manifest 的字段），并在日志中提示。

仍可通过命令行指定路径覆盖默认文件位置：

```text
./build/bin/softbus_edge_agent /path/to/edge_manifest.json
```

见 [config/edge_manifest.schema.json](config/edge_manifest.schema.json) 与示例 [config/edge_manifest.example.json](config/edge_manifest.example.json)。

要点：

- **`coreHost` / `corePort`**：与 `daemon_config.json` 中 `edgeIngress` 一致。
- **`edgeId`**：HELLO 与会话绑定；`TREE_PROPOSE` 必须相同。
- **`edgeDiscoveryEnabled`**（bool，默认 `true`）：在 TCP 连接且 **HELLO 成功** 后启动 udev 发现协调器，将串口以 `op: upsert` 写入核心设备树（需 Linux + `libudev`）。设为 `false` 可仅依赖手工 `TREE_PROPOSE` 或核心下发树。
- **`endpoint`**：用于计算 `endpointHash`（与核心一致：`qHash(endpoint)` 即 Qt 默认字符串哈希）。
- **`fakeDeviceId`**：组装 `routingKey = (endpointHash << 32) | deviceId` 与核心 `makeRoutingKey` 一致。
- **`fakeIntervalMs`**：设为 `0` 可关闭假数据定时器；**真实串口**由核心下发的设备树节点驱动（`type`/`endpoint` 可识别为 Serial，且 `params.online` 为 true）。节点 `params.deviceId` 会写入上行 `RawBusMessage::deviceId`（未设则 `-1`）。

## 运维 HTTP

若 `opsListenPort > 0`，监听 `127.0.0.1:opsListenPort`：

- `GET /`：返回 `localTreePath` 文件内容（无文件则返回占位 HTML，含指向配置页的链接）。
- **`GET /ui`**：**阶段 5** 简易配置页——从 **`GET /discovered`** 同源列表选择已发现串口节点，填写 `params.protocol`（如 `modbus_rtu`）、波特率等，提交后由边缘组装 **`op: upsert`** 的 `TREE_PROPOSE` 发往核心（使用当前会话的 **`baseTreeRevision`**，须已 HELLO 且收到过 `TREE_RESULT`）。
- **`POST /register_discovered`**：可由浏览器表单（`application/x-www-form-urlencoded`）或 **JSON** 调用；字段含 `nodeId`（必填，一般为 `edges/<edgeId>/discovered/<stableKey>`）、`devnode`（可选，若不在发现列表中需填 `/dev/tty…`）、`protocol`、`baudRate`、`name`。表单提交成功返回简短 **HTML** 确认页；JSON 请求返回 `{"accepted":true,"sentNodeId":...}`。若尚未拿到有效 `treeRevision`，返回 **503**。
- **`GET /discovered`**：返回最近 udev 发现事件 JSON（`{ "items": [ ... ] }`），便于无核心时调试；与 `EdgeDiscoveryCoordinator` 内存环缓冲一致（最多约 64 条）。
- `POST /propose`：body 为 **完整** `CTRL_TREE_PROPOSE` JSON（含 `edgeId`、`baseTreeRevision`、`entries`），将原样经 TCP 发往核心。

示例：

```bash
curl -s http://127.0.0.1:9080/
curl -s http://127.0.0.1:9080/ui
curl -s http://127.0.0.1:9080/discovered
curl -s -X POST http://127.0.0.1:9080/register_discovered \
  -H 'Content-Type: application/json' \
  -d '{"nodeId":"edges/edge-dev-1/discovered/12345","protocol":"modbus_rtu","baudRate":115200}'
curl -s -X POST http://127.0.0.1:9080/propose \
  -H 'Content-Type: application/json' \
  -d '{"edgeId":"edge-dev-1","baseTreeRevision":1,"entries":[{"id":"edges/edge-dev-1/gw","patch":{"name":"gw"}}]}'
```

（`entries` 中节点 id 必须满足核心 `DeviceTreeModel::nodeBelongsToEdge` 规则。）

## 本地树文件

`TREE_FULL` 落盘格式为 `{ "treeRevision", "edgeId", "tree": [ ... ] }`。**`EdgeDeviceBus`** 会将其中的 `tree` 当作 `device_tree` 加载，并对 **Serial** 与 **CAN**（`endpoint` 形如 `can:vcan0`，`type`/`endpoint` 推断为 CAN）执行 **reconcile**：打开设备后读到的数据经 `EdgeTcpUplinkPort` 编码为 `DATA_RAWBUS` 发往核心。与核心真源同步仍通过 **TREE_PROPOSE**（含边缘 **`upsert`** 自动注册）、核心侧 D-Bus `patch_device_tree_node` 或运维 **`push_edge_tree`**。

### 发现 → 注册流程（简要）

1. 边缘连接核心并 **HELLO**；核心下发 **`TREE_FULL`**，本地落盘并 reconcile 已有节点。  
2. `edgeDiscoveryEnabled` 为真时，`EdgeDiscoveryCoordinator` 扫描/监听 udev 串口 **add/remove**，在拿到有效 **`baseTreeRevision`**（来自 `TREE_RESULT`）后发送 **`TREE_PROPOSE`**：`op: upsert` 注册 `edges/<edgeId>/discovered/<stableKey>`，remove 时 **`patch`** `params.online: false`。  
3. 核心 `applyEdgePropose` 成功后再次 **`TREE_FULL`**；边缘 reload 树文件后对 **Serial/CAN** 执行 reconcile，**raw 仅上行**。