softbus_daemon/src/api/API_INTERFACE_TABLE.md

# 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 状态 |
| 其他未知 action | - | - | `4040` | 未知动作 |

## 5) HTTP REST 路由表（RestApiRoutes）

### 5.1 通用路由

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/health` | 健康检查，返回 `{"ok": true}` |
| `GET` | `/v1/status` | 透传 `get_status` 的状态响应 |
| `POST` | `/v1/command` | 统一命令入口（请求体为 executeCommand JSON） |

### 5.2 设备树 / 设备路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `GET` | `/api/v1/device-tree` | 无 | 返回当前设备树快照 |
| `GET` | `/api/v1/devices` | 无 | 返回当前运行态设备列表 |
| `GET` | `/api/v1/devices/{id}` | path: `id(int)` | 返回指定运行态设备详情 |
| `PATCH` | `/api/v1/device-tree/nodes/{id}` | body: 任意可变节点字段子集 | 部分更新设备树节点；当前至少保护 `id`、`params.stableKey`、`params.online`、`params.lastSeenTs` |

### 5.3 规则管理路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `GET` | `/api/v1/rules/status` | 无 | 返回动态规则计数状态 |
| `POST` | `/api/v1/rules/filter` | body: `id`, `endpointHash?`, `deviceId?`, `stableKey?`, `condition?` | 新增过滤规则 |
| `DELETE` | `/api/v1/rules/filter/{id}` | path: `id` | 删除过滤规则 |
| `POST` | `/api/v1/rules/transform` | body: `id`, `endpointHash?`, `deviceId?`, `stableKey?`, `scale?`, `offset?`, `unit?` | 新增转换规则 |
| `DELETE` | `/api/v1/rules/transform/{id}` | path: `id` | 删除转换规则 |

- 说明：
  - `transform` 规则已经在 `PipelineEngine::applyTransformAndEnrich(...)` 中生效。
  - `filter` 路由当前主要提供“注册表管理”能力；动态 filter 规则尚未真正接入 `PipelineEngine::stage3Filter(...)` 的执行链路。

### 5.4 Pipeline 路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `GET` | `/api/v1/pipeline/status` | 无 | 返回 pipeline 运行状态、session 数量、队列容量、插件摘要与 counters |
| `GET` | `/api/v1/pipeline/counters` | 无 | 返回 `in/out/drop/error/mergeDrop` 计数器快照 |
| `GET` | `/api/v1/pipeline/config` | 无 | 返回当前运行时配置快照 |

- 说明：`/v1/status` 仍然是 control-plane 摘要（规则 + discovery + mapping），不等同于 `/api/v1/pipeline/status`。

### 5.5 插件 / 协议能力路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `GET` | `/api/v1/plugins` | 无 | 返回 parser / framer / mapper 三类逻辑插件的统一列表 |
| `GET` | `/api/v1/plugins/protocols` | 无 | 返回按协议聚合后的能力快照（parser/framer/mapper pluginId） |
| `GET` | `/api/v1/plugins/mappers` | 无 | 返回 mapper 插件列表 |

### 5.6 Metadata / Profile 路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `GET` | `/api/v1/metadata` | 无 | 返回 `data`（字典数组）与可选 `catalogVersion`（根级字段） |
| `GET` | `/api/v1/metadata/{metadataId}` | path: `metadataId` | 返回指定 metadata 详情（含可选 `catalogVersion`） |
| `GET` | `/api/v1/profiles` | 无 | 返回 `data` 与可选 `catalogVersion` |
| `GET` | `/api/v1/profiles/{deviceId}` | path: `deviceId` | 返回指定 `deviceId` 关联的全部 profile（含可选 `catalogVersion`） |

### 5.7 Discovery 路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `POST` | `/api/v1/discovery/start` | body: `ttlMs?` | 开启嗅探；可设置自动关闭 TTL |
| `POST` | `/api/v1/discovery/stop` | 无 | 关闭嗅探 |
| `GET` | `/api/v1/discovery/status` | 无 | 获取发现池运行状态 |
| `POST` | `/api/v1/discovery/clear` | 无 | 清空发现池样本 |
| `GET` | `/api/v1/discovery/samples` | query: `offset?`, `limit?`, `endpointHash?`, `protocol?` | 拉取样本（按更新时间倒序，且过滤已映射 key） |

### 5.8 Mapping 路由

| 方法 | 路径 | 请求参数 | 说明 |
|---|---|---|---|
| `POST` | `/api/v1/mapping/bind` | body: `compositeKey`, `domPath`, `scale?`, `offset?`, `unit?`, `metadataId?`, `pointId?`, `catalogVersion?`, `updatedBy?` | 绑定或更新映射规则并写入 `runtime_mappings.json` |
| `POST` | `/api/v1/mapping/unbind` | body: `compositeKey` | 删除映射规则并持久化 |
| `GET` | `/api/v1/mapping/list` | 无 | 返回 `items` 与 `mappingCatalogVersion` |

## 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` 失败 |

## 7) 维护建议

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