opc source code

docs/softbus_transport.md

@@ -0,0 +1,110 @@
+# softbus_transport
+
+**路径：** `src/softbus_transport`  
+**构建目标：** `softbus_transport`（STATIC 库）  
+**层级：** L2 服务层
+
+## 1. 概述
+
+`softbus_transport` 实现边缘与守护进程之间的 **TCP 传输层**，定义 UplinkWire JSON 行协议，提供 Server（守护进程监听）与 Client（边缘连接）对称实现。
+
+## 2. CONSTRAINTS
+
+- 传输层仅负责 TCP 连接管理与线消息编解码，不包含业务解析逻辑。
+- 消息格式遵循 [UPLINK_WIRE_PROTOCOL.md](UPLINK_WIRE_PROTOCOL.md)，不得引入私有扩展字段而不更新协议文档。
+- Server 与 Client 均基于 asio 异步 I/O，不得阻塞调用线程。
+- 传输层不得直接操作 OPC UA 或插件。
+
+## 3. 核心组件
+
+### 3.1 UplinkWire — 线协议
+
+| 类型/函数 | 说明 |
+|-----------|------|
+| `WireMessageType` | 枚举：`RawPacket`、`ExecuteCommand`、`Unknown` |
+| `WireMessage` | 解码结果联合体 |
+| `encodeWireMessage(RawPacket)` | 上行编码 |
+| `encodeWireMessage(ExecuteCommand)` | 下行编码 |
+| `decodeWireMessage(line)` | 单行解码 |
+| `base64Encode` / `base64Decode` | payload 编解码 |
+
+### 3.2 TcpUplinkServer — 守护进程侧
+
+| 方法 | 说明 |
+|------|------|
+| `TcpUplinkServer(io_context, host, port)` | 构造，绑定监听地址 |
+| `start()` | 启动 acceptor |
+| `stop()` | 停止服务 |
+| `setRawPacketHandler(handler)` | 注册上行回调 `function<void(RawPacket)>` |
+| `sendCommand(ExecuteCommand)` | 向已连接边缘发送下行命令 |
+
+**行为：**
+
+- 监听 TCP 端口，接受边缘连接
+- 按 `\n` 分行读取，解码 `rawPacket` 消息
+- 触发 `rawHandler` 回调
+- 通过 `sendCommand` 向边缘推送 `executeCommand`
+
+### 3.3 TcpUplinkClient — 边缘侧
+
+| 方法 | 说明 |
+|------|------|
+| `TcpUplinkClient(io_context, host, port)` | 构造，指定守护进程地址 |
+| `connect()` | 连接守护进程 |
+| `disconnect()` | 断开连接 |
+| `sendRawPacket(RawPacket)` | 发送上行原始包 |
+| `poll()` | 轮询接收下行命令 |
+| `setCommandHandler(handler)` | 注册命令回调 `function<void(ExecuteCommand)>` |
+
+## 4. 数据流
+
+### 4.1 上行
+
+```
+Edge: UplinkClient.sendRawPacket(packet)
+  → encodeWireMessage(packet) + "\n"
+  → TCP send
+  → Server: handleLine(line)
+  → decodeWireMessage(line)
+  → rawHandler(rawPacket)
+```
+
+### 4.2 下行
+
+```
+Daemon: CommandDispatcher.dispatch(cmd)
+  → TcpUplinkServer.sendCommand(cmd)
+  → encodeWireMessage(cmd) + "\n"
+  → TCP send
+  → Client: handleLine(line)
+  → decodeWireMessage(line)
+  → commandHandler(cmd)
+```
+
+## 5. 配置
+
+| 配置项 | 来源 | 默认值 |
+|--------|------|--------|
+| `uplink.listenHost` | `daemon_profile.json` | `127.0.0.1` |
+| `uplink.listenPort` | `daemon_profile.json` | `9000` |
+| Edge 连接地址 | CLI `--daemon host:port` | `127.0.0.1:9000` |
+
+## 6. 依赖
+
+- `softbus_core`（RawPacket）
+- `softbus_api`（ExecuteCommand）
+- `asio`（FetchContent standalone，v1.30.2）
+- **被依赖：** softbus_edge, softbus_daemon
+
+## 7. 构建
+
+```cmake
+add_library(softbus_transport STATIC ...)
+target_link_libraries(softbus_transport PUBLIC softbus_core softbus_api asio)
+```
+
+## 8. Phase 2 规划
+
+- 支持多边缘连接与连接池
+- 增加断线重连与心跳机制
+- 可选迁移至 SBUP 二进制协议