# softbus_daemon API 接口表

本文档汇总 `src/api` 当前对外接口，分为：
- D-Bus 直接方法
- `executeCommand` JSON 命令接口
- HTTP REST 接口

## 1) D-Bus 服务基础信息

| 项目 | 值 |
|---|---|
| Service | `com.softbus.Daemon` |
| ObjectPath | `/com/softbus/Daemon` |
| Interface | `com.softbus.Daemon` |
| 适配类 | `IpcDBus` |

## 2) D-Bus 方法表（IpcDBus）

| 方法 | 入参 | 返回 | 说明 |
|---|---|---|---|
| `isRunning()` | 无 | `bool` | 核心服务是否初始化完成 |
| `ping()` | 无 | `QString` | 健康探针，固定返回 `pong` |
| `getVersion()` | 无 | `QString` | 进程版本号 |
| `getStatus()` | 无 | `QString(JSON)` | 返回服务状态（pid/role/running/timestamp 等） |
| `getPid()` | 无 | `qint64` | 返回守护进程 PID |
| `shutdown()` | 无 | `void` | 关闭 CoreService 并退出进程 |
| `reloadConfig()` | 无 | `bool` | 预留，当前为占位实现 |
| `executeCommand(requestJson)` | `QString(JSON)` | `QString(JSON)` | 统一 JSON 命令入口 |

## 3) executeCommand 协议

### 3.1 请求格式

```json
{
  "id": "req-001",
  "action": "add_filter",
  "params": {}
}
```

### 3.2 响应格式

```json
{
  "id": "req-001",
  "code": 0,
  "message": "ok",
  "data": {}
}
```

## 4) action 路由表（CommandDispatcher）

| action | params 关键字段 | 成功 code | 失败 code | 说明 |
|---|---|---:|---:|---|
| `add_filter` | `id`, `endpointHash?`, `deviceId?`, `stableKey?`, `condition?` | `0` | `4001` | 添加过滤规则 |
| `remove_filter` | `id` | `0` | `4041` | 删除过滤规则 |
| `add_transform_rule` | `id`, `endpointHash?`, `deviceId?`, `stableKey?`, `scale?`, `offset?`, `unit?` | `0` | `4002` | 添加转换规则 |
| `remove_transform_rule` | `id` | `0` | `4042` | 删除转换规则 |
| `add_mapping_rule` | `compositeKey`, `domPath`, `scale?`, `offset?`, `unit?`, `metadataId?`, `pointId?`, `catalogVersion?`, `updatedBy?` | `0` | `4004` / `5002` | 新增/更新映射规则；成功后持久化到 `runtime_mappings.json`；`5002` 表示持久化失败 |
| `remove_mapping_rule` | `compositeKey` | `0` | `4043` / `5002` | 删除映射规则并持久化 |
| `list_mapping_rules` | 无 | `0` | - | 返回 `items` 与 `mappingCatalogVersion` |
| `discovery_start` | `ttlMs?` | `0` | - | 开启嗅探模式 |
| `discovery_stop` | 无 | `0` | - | 关闭嗅探模式 |
| `discovery_clear` | 无 | `0` | - | 清空发现池 |
| `list_rules` | 无 | `0` | - | 返回规则计数状态 |
| `get_status` | 无 | `0` | - | 返回规则计数 + discovery/mapping 状态 |
| `get_rules_status` | 无 | `0` | - | 规则 + 映射计数与 `mappingCatalogVersion` |
| `get_discovery_status` | 无 | `0` | - | discovery 状态 JSON |
| `list_discovery_samples` | `offset?`, `limit?`, `endpointHash?`, `protocol?` | `0` | - | 返回 `samples` 数组 |
| `get_pipeline_status` | 无 | `0` | `5003` | PipelineEngine `status()`；不可用时 `pipeline_unavailable` |
| `get_pipeline_counters` | 无 | `0` | `5003` | 计数 JSON |
| `get_pipeline_config` | 无 | `0` | `5003` | 运行时配置 JSON |
| `clear_pipeline_counters` | 无 | `0` | `5003` | 清零后返回计数 JSON |
| `get_device_tree` | 无 | `0` | `5003` | 返回 `tree` |
| `list_devices` | 无 | `0` | - | 返回 `devices` |
| `get_device` | `deviceId` | `0` | `4044` | 单设备 JSON；未找到 `device_not_found` |
| `patch_device_tree_node` | `id`, `patch`（字段同设备树节点） | `0` | `4045`/`5003` | 更新节点并协调；成功时可选带 `edgeTreeDownlink`（对 `params.edgeId` / `edges/<id>/` 作用域自动 `TREE_FULL`） |
| `list_edge_sessions` | 无 | `0` | - | 返回边缘 TCP 会话 `sessions`（`edgeId`/`helloOk`/`peer`） |
| `get_edge_tree_revision` | 无 | `0` | - | 返回 `treeRevision`（与边缘 `CTRL_TREE_PROPOSE` 乐观锁对齐） |
| `push_edge_tree` | `edgeId` | `0` | `4000`/`4047`/`5003`/`5005` | 向已 HELLO 的会话下行 `TREE_FULL`；成功返回 `sent`、`treeRevision`；无在线会话 `no_active_session`；ingress 未启用 `edge_ingress_disabled` |
| （edge TCP）`TREE_PROPOSE` | JSON：`edgeId`、`baseTreeRevision`、`entries` | - | `CONFLICT`/`FORBIDDEN_SCOPE` 等 | 与 D-Bus 共用 `DeviceTreeModel::applyEdgePropose`；`entries` 支持 `op` 省略/`patch` 与 **`op: upsert`**（边缘子树内新增或整节点合并），见 `docs/EDGE_UPLINK_PROTOCOL_v1.md` §6 |
| `get_plugins` | 无 | `0` | - | 合并 protocol/framer/mapper 插件列表 |
| `get_plugins_protocols` | 无 | `0` | - | `protocols` |
| `get_plugins_mappers` | 无 | `0` | - | `mappers` |
| `list_metadata` | 无 | `0` | `5004` | `metadatas` + `catalogVersion` |
| `get_metadata` | `metadataId` | `0` | `4046`/`5004` | 单条 metadata；`metadata_not_found` |
| `upsert_metadata` | `payload`（须含 `metadataId`） | `0` | `4005`/`5004` | 写回字典文件，返回新 `catalogVersion` |
| `delete_metadata` | `metadataId` | `0` | `4046`/`5004` | 删除并递增 `catalogVersion` |
| `list_profiles` | 无 | `0` | - | `profiles` + `catalogVersion` |
| `list_profiles_for_device` | `deviceId` | `0` | - | 按设备过滤的 `profiles` |
| 其他未知 action | - | - | `4040` | 未知动作 |

## 5) 控制面入口（无 HTTP）

`softbus_daemon` 不再内置 HTTP 服务。浏览器侧请使用 **`softbus_orchestrator_py`**（`python -m softbus_orchestrator`）：提供治理 REST、`/v1/command` 与 `/api/v1/*` 到 D-Bus 的 HTTP 兼容层，以及 DAG ingress。运维能力在进程内仍通过 **`executeCommand`** 转发到 `com.softbus.Daemon`。

治理 **`graph_catalog.json`**：`POST /api/v1/graphs` 按 **`graphId` 幂等 upsert**（合并字段，未传 `versions` 时保留已有版本）；**拓扑与 `nodes`/`edges`** 应通过 **`POST /api/v1/graphs/{graph_id}/versions`** 追加版本体；若 `graph_id` 尚不存在，该接口会**自动创建**图壳再写入版本。**Pipeline 与 DOM 的可视化绑定** 若需统一图模型，需在产品与 daemon 侧另行定义配置 schema（当前无单一 REST）。

## 6) 通用错误码约定（当前实现）

| code | message | 说明 |
|---:|---|---|
| `0` | `ok` | 成功 |
| `4000` | `invalid_json` | 请求 JSON 无法解析或非对象 |
| `4001` | `invalid_filter_rule` | 过滤规则参数非法 |
| `4002` | `invalid_transform_rule` | 转换规则参数非法 |
| `4003` | `invalid_action` | action 为空或分发器不可用 |
| `4004` | `invalid_mapping_rule` | 映射规则参数非法 |
| `4040` | `unknown_action` | action 未注册 |
| `4041` | `filter_not_found` | 删除过滤规则时未找到 |
| `4042` | `transform_rule_not_found` | 删除转换规则时未找到 |
| `4043` | `mapping_rule_not_found` | 删除映射规则时未找到 |
| `5002` | `persist_mappings_failed` | 映射规则内存更新成功但写入 `runtime_mappings.json` 失败 |
| `5003` | `pipeline_unavailable` / `device_tree_unavailable` | Pipeline 或设备树模型未就绪 |
| `5004` | `metadata_*` | 元数据字典读写/解析/保存失败 |
| `5005` | `edge_ingress_disabled` / `edge_ingress_unavailable` | 边缘 TCP ingress 未启用或未初始化 |
| `4005` | `invalid_metadata` | `upsert_metadata` 缺少 `metadataId` |
| `4044` | `device_not_found` | `get_device` 未找到 |
| `4045` | `node_not_found` | `patch_device_tree_node` 未找到节点 |
| `4046` | `metadata_not_found` | `get_metadata` / `delete_metadata` 未找到 |
| `4047` | `no_active_session` | `push_edge_tree` 时该 `edgeId` 无已 HELLO 的 TCP 会话 |

## 7) 维护建议

- 新增 action 时，同时更新：
  - `CommandDispatcher::dispatch(...)`
  - 本文档第 4 节 action 表
- 若扩展返回结构，保持 `code/message/data` 三元组不变，避免客户端兼容性问题。