# softbus_api

**路径：** `src/softbus_api`  
**构建目标：** `softbus_api`（STATIC 库）  
**层级：** L1 契约层

## 1. 概述

`softbus_api` 定义跨模块共享的**控制面契约**。当前仅暴露 `ExecuteCommand` 结构体，作为 OPC UA Method、TCP 下行与边缘回调的统一载荷格式。

## 2. CONSTRAINTS

- `softbus_api` 仅定义跨边界命令语义，不包含传输或协议实现。
- 新增命令类型须通过扩展 `command` 字段值实现，保持 `ExecuteCommand` 结构稳定。
- JSON 序列化/反序列化与校验逻辑集中在本模块，调用方不得绕过 `validate()`。
- 本模块不得依赖 transport、opcua、daemon 或 edge。

## 3. ExecuteCommand

### 3.1 结构定义

```cpp
namespace softbus::api {

struct ExecuteCommand {
    std::string traceId;
    std::string objectRef;
    std::string command;
    nlohmann::json params;

    static ExecuteCommand fromJson(const nlohmann::json& j);
    nlohmann::json toJson() const;
    bool validate(std::string* error) const;
};

}
```

### 3.2 JSON 字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `type` | string | 是（线协议） | 固定 `"executeCommand"`，仅线编码时包含 |
| `traceId` | string | 是 | 追踪 ID |
| `objectRef` | string | 是 | 五层对象路径 |
| `command` | string | 是 | 命令名称 |
| `params` | object | 是 | 命令参数 |

### 3.3 校验规则

`validate()` 检查：

1. `traceId` 非空
2. `objectRef` 非空且为合法五层路径
3. `command` 非空
4. `params` 为 JSON 对象（非 null、非数组）

### 3.4 示例

**写值命令：**

```json
{
  "type": "executeCommand",
  "traceId": "trace-cmd-001",
  "objectRef": "DemoSite/DemoSystem/DemoAsset/SimModbusDevice/Temperature",
  "command": "write",
  "params": {"value": 42.5}
}
```

**校验失败响应（OPC UA Method 出参）：**

```json
{"success": false, "error": "objectRef is invalid"}
```

**成功响应：**

```json
{"success": true}
```

## 4. 使用场景

| 调用方 | 场景 |
|--------|------|
| `UaMethodBinder` | OPC UA 客户端调用 `ExecuteCommand` Method |
| `CommandDispatcher` | 校验并转发至 `TcpUplinkServer` |
| `UplinkWire` | 编码/解码 TCP 线消息 |
| `softbus_edge` | 接收下行命令并执行（Phase 1 仅日志） |

## 5. 数据流位置

```
OPC UA Client
  → UaMethodBinder (JSON 入参)
  → ExecuteCommand::fromJson() + validate()
  → CommandDispatcher::dispatch()
  → UplinkWire::encodeWireMessage()
  → TCP → Edge commandHandler
```

## 6. 依赖

- `softbus_core`（`ObjectRef` 校验）
- `nlohmann_json`
- **被依赖：** softbus_transport, softbus_opcua, softbus_edge, softbus_daemon

## 7. Phase 2 规划

- 扩展命令类型：`read`、`subscribe`、`discover`
- 增加命令响应结构 `ExecuteResult`（含 `statusCode`、`result` 字段）
- 支持批量命令 `ExecuteCommandBatch`