# 数据桥接对接文档

本文面向需要和 岩安测控 对接的第三方系统，覆盖两类能力：

1. 第三方系统查询设备及其物模型。
2. 第三方系统获取设备上报数据，包括 岩安测控 主动推送和第三方主动查询。

本文基于当前仓库已有接口和数据桥接实现整理。默认服务根地址记为 `{BASE_URL}`，例如 `http://1.116.124.85:8080`。

## 对接方式总览

```mermaid
flowchart LR
  Device[设备] --> Protocol[MQTT/TCP/HTTP/CoAP 等接入]
  Protocol --> 岩安测控[岩安测控 数据处理]
  岩安测控 --> Store[(MySQL/TDengine)]
  岩安测控 --> Rule[数据流脚本/规则引擎]
  Rule --> PushHTTP[主动推送 HTTP]
  Rule --> PushMQTT[主动桥接 MQTT]
  Rule --> PushDB[写入第三方数据库]
  Third[第三方系统] --> API[REST API 主动查询]
  API --> 岩安测控
```

| 场景 | 推荐方式 | 说明 |
| --- | --- | --- |
| 获取设备清单 | REST API 主动查询 | 查询 `iot_device` 设备列表或按设备编号查询详情。 |
| 获取设备物模型 | REST API 主动查询 | 查询产品级/设备级物模型，包含属性、事件、服务、计算模型。 |
| 获取实时值 | REST API 主动查询 | 查询设备运行时缓存值。 |
| 获取历史上报数据 | REST API 主动查询 | 查询数据中心历史接口，支持按设备、时间范围、物模型标识符过滤。 |
| 上报数据实时同步给第三方 | 数据桥接主动推送 | 通过数据流脚本触发 HTTP、MQTT 或数据库桥接。 |
| 第三方系统周期同步 | REST API 定时拉取 | 第三方按时间窗口分页/分段查询历史数据。 |

## 认证

除安全配置中明确放行的匿名接口外，REST API 默认需要登录 Token。

### 登录获取 Token

```http
POST {BASE_URL}/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123",
  "code": "验证码",
  "uuid": "验证码uuid"
}
```

成功响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "token": "eyJhbGciOiJIUzUxMiJ9..."
}
```

后续请求头：

```http
Authorization: Bearer {token}
```

如果系统关闭验证码或使用内部服务账号，可按部署配置调整登录参数。第三方生产对接建议单独创建服务账号，并只授予以下最小权限：

| 能力 | 权限标识 |
| --- | --- |
| 设备查询 | `iot:device:list`, `iot:device:query` |
| 物模型查询 | `iot:model:list`, `iot:model:query` |
| 历史数据查询 | `dataCenter:history:list` |
| 数据分析查询 | `dataCenter:analysis:list` |
| 数据桥接配置 | `iot:bridge:list`, `iot:bridge:add`, `iot:bridge:edit`, `iot:bridge:query` |
| 数据流脚本配置 | `iot:script:list`, `iot:script:add`, `iot:script:edit`, `iot:script:query` |

## 通用响应

普通接口返回 `AjaxResult`：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

分页接口返回 `TableDataInfo`：

```json
{
  "code": 200,
  "msg": "查询成功",
  "total": 100,
  "rows": []
}
```

常见约定：

- `code=200` 表示成功。
- 设备编号 `serialNumber` 在上报和查询中通常会转为大写处理，第三方建议统一传大写。
- 时间字段建议使用 `yyyy-MM-dd HH:mm:ss`。

## 查询设备

### 设备分页列表

```http
GET {BASE_URL}/iot/device/list?pageNum=1&pageSize=20&deviceName=xxx&serialNumber=ABC001&productId=1
Authorization: Bearer {token}
```

说明：

- Controller：`DeviceController.list`
- 权限：`iot:device:list`
- 返回：分页设备列表。
- 常用过滤字段来自 `Device` 对象，实际可用字段包括 `deviceId`、`deviceName`、`serialNumber`、`productId`、`tenantId`、`deptId`、`status` 等。

### 设备简短列表

适合第三方做设备下拉或轻量同步。

```http
GET {BASE_URL}/iot/device/shortList?pageNum=1&pageSize=100&productId=1
Authorization: Bearer {token}
```

### 查询所有设备简短列表

```http
GET {BASE_URL}/iot/device/all
Authorization: Bearer {token}
```

### 按设备 ID 查询详情

```http
GET {BASE_URL}/iot/device/{deviceId}
Authorization: Bearer {token}
```

### 按设备编号查询详情

```http
GET {BASE_URL}/iot/device/getDeviceBySerialNumber/{serialNumber}
Authorization: Bearer {token}
```

示例：

```http
GET {BASE_URL}/iot/device/getDeviceBySerialNumber/ABC001
Authorization: Bearer {token}
```

## 查询设备物模型

岩安测控 的物模型主要由 `productId + identifier` 定义。设备级计算物模型或特殊覆盖会结合 `serialNumber` 处理。

### 按产品 ID 和设备编号查询物模型

推荐第三方使用该接口，它会从缓存中合并产品级物模型和设备级处理结果。

```http
GET {BASE_URL}/iot/model/listByProductIdAndSerialNumber?productId=1&serialNumber=ABC001
Authorization: Bearer {token}
```

说明：

- Controller：`ThingsModelController.listByProductIdAndSerialNumber`
- 权限：`iot:model:list`
- 返回：`ThingsModelDTO` 列表。

典型返回项字段：

| 字段 | 含义 |
| --- | --- |
| `modelId` | 物模型 ID。 |
| `identifier` | 物模型标识符，历史数据查询和推送数据中使用该字段作为变量名。 |
| `modelName` | 物模型名称。 |
| `type` | 物模型类型，通常表示属性/功能/事件等。 |
| `datatype` | 数据类型定义，例如 number、string、bool、enum 等。 |
| `specs` | 枚举、单位、取值范围等扩展规格。 |
| `modelOrder` | 排序。 |

### 查询设备变量概况

```http
GET {BASE_URL}/iot/device/listThingsModel?deviceId=100&pageNum=1&pageSize=50
Authorization: Bearer {token}
```

可选过滤：

- `modelName`：按物模型名称模糊过滤。
- `type`：按物模型类型过滤。

### 查询产品物模型列表

```http
GET {BASE_URL}/iot/model/list?pageNum=1&pageSize=100&productId=1
Authorization: Bearer {token}
```

### 获取缓存 JSON 物模型

```http
GET {BASE_URL}/iot/model/cache/{productId}
Authorization: Bearer {token}
```

适用于需要拿完整 TSL JSON 的场景。

## 查询实时数据

### 查询设备运行时状态

```http
GET {BASE_URL}/iot/runtime/running?serialNumber=ABC001
Authorization: Bearer {token}
```

说明：

- Controller：`DeviceRuntimeController.runState`
- 返回：物模型当前值列表。
- 数据来源：运行时缓存/物模型缓存，不适合替代历史审计。

典型返回：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": "temperature",
      "name": "温度",
      "value": "26.5",
      "type": 1,
      "datatype": {
        "type": "decimal",
        "unit": "℃"
      }
    }
  ]
}
```

## 第三方主动查询设备上报数据

### 推荐接口：数据中心历史查询

```http
POST {BASE_URL}/data/center/deviceHistory
Authorization: Bearer {token}
Content-Type: application/json

{
  "deviceId": 100,
  "serialNumber": "ABC001",
  "beginTime": "2026-05-24 00:00:00",
  "endTime": "2026-05-24 23:59:59",
  "identifierList": [
    { "identifier": "temperature", "type": 1 },
    { "identifier": "humidity", "type": 1 }
  ]
}
```

说明：

- Controller：`DataCenterController.deviceHistory`
- 权限：`dataCenter:history:list`
- `serialNumber` 必填。
- `identifierList` 建议传入，避免一次拉取全部变量导致响应过大。
- `type` 与物模型类型保持一致，常见属性数据为 `1`，以实际物模型返回值为准。

典型返回结构：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "2026-05-24 10:00:00": [
        { "temperature": "26.5" },
        { "humidity": "60" }
      ]
    },
    {
      "2026-05-24 10:01:00": [
        { "temperature": "26.7" },
        { "humidity": "59" }
      ]
    }
  ]
}
```

### 设备日志列表

适合按原始日志粒度查询。

```http
GET {BASE_URL}/iot/deviceLog/list?pageNum=1&pageSize=50&serialNumber=ABC001&beginTime=2026-05-24 00:00:00&endTime=2026-05-24 23:59:59
Authorization: Bearer {token}
```

说明：

- Controller：`DeviceLogController.list`
- 权限：`iot:device:list`
- 返回：分页日志行，字段来自 `DeviceLog`。

### 设备历史数据 GET 查询

```http
GET {BASE_URL}/iot/deviceLog/history?serialNumber=ABC001&beginTime=2026-05-24 00:00:00&endTime=2026-05-24 23:59:59
Authorization: Bearer {token}
```

返回按 `identifier` 分组的历史数据，适合较简单的查询场景。

### 按时间聚合的历史数据

```http
GET {BASE_URL}/iot/deviceLog/historyGroupByCreateTime?pageNum=1&pageSize=100&serialNumber=ABC001&beginTime=2026-05-24 00:00:00&endTime=2026-05-24 23:59:59
Authorization: Bearer {token}
```

### 网关计算物模型历史

```http
POST {BASE_URL}/data/center/deviceHistoryCalculated
Authorization: Bearer {token}
Content-Type: application/json

{
  "deviceId": 100,
  "serialNumber": "GW001",
  "beginTime": "2026-05-24 00:00:00",
  "endTime": "2026-05-24 23:59:59",
  "identifierList": [
    { "identifier": "avg_temperature", "type": 1 }
  ]
}
```

### 周期拉取建议

第三方主动查询历史数据时，建议使用滑动时间窗口：

1. 首次同步：按小时或天分段拉取。
2. 增量同步：每 1 至 5 分钟拉取一次 `[lastSyncTime, now - 10s]`。
3. 去重键：`serialNumber + identifier + time`。
4. 重试：失败窗口不要丢弃，下次继续从 `lastSuccessEndTime` 拉取。
5. 大设备量：先同步设备列表，再按设备分批拉取，避免单次请求过大。

## 岩安测控 主动推送给第三方系统

岩安测控 当前主动推送走“数据流脚本 + 数据桥接”机制。设备上报后，`RuleProcess.processRuleScript(...)` 会按产品和事件类型找到启用的数据流脚本，然后执行脚本动作：

| 脚本动作 | `scriptAction` | 桥接组件 | 用途 |
| --- | ---: | --- | --- |
| HTTP 推送 | 3 | `httpBridge` | 调用第三方 HTTP 接口。 |
| MQTT 桥接 | 4 | `mqttBridge` | 发布到第三方 MQTT Broker。 |
| 数据库存储 | 5 | `databaseBridge` | 写入第三方数据库。 |

设备上报事件类型：

| 事件 | `scriptEvent` | 说明 |
| --- | ---: | --- |
| 设备上报 | 1 | 设备属性/数据上报后触发。 |
| 平台下发 | 2 | 平台服务/指令下发前后触发。 |
| 设备上线 | 3 | 设备上线触发。 |
| 设备离线 | 4 | 设备离线触发。 |
| HTTP 桥接入口数据 | 5 | 第三方调用 `/bridge/get|post|put` 后触发。 |
| MQTT 桥接入口数据 | 6 | MQTT 输入桥接触发，按脚本配置处理。 |

### 主动 HTTP 推送配置

1. 新增数据桥接。

```http
POST {BASE_URL}/iot/bridge
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "推送到第三方业务系统",
  "enable": "1",
  "type": 3,
  "direction": 2,
  "route": "https://third.example.com/iot/report",
  "configJson": "{\"method\":\"POST\",\"hostUrl\":\"https://third.example.com/iot/report\",\"requestHeaders\":\"{\\\"Authorization\\\":\\\"Bearer xxx\\\"}\",\"requestQuerys\":\"{}\",\"requestConfig\":\"\",\"requestBody\":\"\"}"
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `type=3` | HTTP 推送。 |
| `direction=2` | 输出方向。 |
| `route` | 展示/路由字段，实际 HTTP 地址以 `configJson.hostUrl` 为准。 |
| `configJson.method` | HTTP 方法，如 `POST`。 |
| `configJson.hostUrl` | 第三方接收地址。 |
| `configJson.requestHeaders` | 请求头 JSON 字符串。 |
| `configJson.requestQuerys` | Query 参数 JSON 字符串。 |
| `configJson.requestBody` | 自定义请求体模板；为空时默认使用脚本上下文 payload。 |

2. 新增数据流脚本。

下面脚本展示的是核心意图：取得 `MsgContext`，设置桥接 ID，必要时重写 `payload/topic`。不同 LiteFlow 脚本语言的上下文变量写法可能不同，落地时以当前环境脚本校验结果为准。

```http
POST {BASE_URL}/iot/script
Authorization: Bearer {token}
Content-Type: application/json

{
  "applicationName": "岩安测控",
  "scriptName": "设备上报转第三方HTTP",
  "scriptType": "script",
  "scriptLanguage": "groovy",
  "scriptPurpose": 1,
  "scriptEvent": 1,
  "scriptAction": 3,
  "productId": 1,
  "enable": 1,
  "bridgeId": 10,
  "scriptData": "def cxt = _meta.getContextBean(com.岩安测控.ruleEngine.context.MsgContext.class); cxt.setPayload(cxt.getPayload()); cxt.setData('httpBridgeID', 10);"
}
```

脚本关键点：

- `scriptPurpose=1` 表示数据流。
- `scriptEvent=1` 表示设备上报触发。
- `scriptAction=3` 表示执行 HTTP 推送组件。
- `productId` 表示该产品下设备上报时触发。
- 脚本必须向上下文写入 `httpBridgeID`，值为桥接配置 `bridge.id`；HTTP 桥接组件会从上下文读取该 ID。
- 脚本可改写 `payload`，从而控制推送给第三方的报文。

### 推荐 HTTP 推送报文

如果第三方希望使用稳定格式，建议脚本把 payload 改造成如下 JSON：

```json
{
  "event": "property.post",
  "productId": 1,
  "serialNumber": "ABC001",
  "protocolCode": "ModbusRtu",
  "reportTime": "2026-05-24 10:00:00",
  "data": [
    {
      "identifier": "temperature",
      "value": "26.5"
    },
    {
      "identifier": "humidity",
      "value": "60"
    }
  ],
  "rawPayload": "[{\"id\":\"temperature\",\"value\":\"26.5\"}]"
}
```

当前默认上下文 payload 通常是设备上报解析后的物模型数据 JSON，字段形态可能随协议解析结果变化。生产对接建议在脚本中统一出站格式，避免第三方直接依赖内部 payload。

### 主动 MQTT 桥接配置

1. 新增 MQTT 桥接。

```http
POST {BASE_URL}/iot/bridge
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "第三方MQTT桥接",
  "enable": "1",
  "type": 4,
  "direction": 2,
  "route": "third/iot/report",
  "configJson": "{\"name\":\"third-mqtt\",\"hostUrl\":\"broker.example.com:1883\",\"username\":\"user\",\"password\":\"pass\",\"clientId\":\"岩安测控-bridge\"}"
}
```

2. 新增脚本。

```json
{
  "applicationName": "岩安测控",
  "scriptName": "设备上报转第三方MQTT",
  "scriptType": "script",
  "scriptLanguage": "groovy",
  "scriptPurpose": 1,
  "scriptEvent": 1,
  "scriptAction": 4,
  "productId": 1,
  "enable": 1,
  "bridgeId": 11,
  "scriptData": "def cxt = _meta.getContextBean(com.岩安测控.ruleEngine.context.MsgContext.class); cxt.setTopic('third/iot/' + cxt.getSerialNumber() + '/property/post'); cxt.setData('mqttBridgeID', 11);"
}
```

说明：

- MQTT 桥接组件使用 `cxt.getTopic()` 作为发布主题。
- 脚本必须写入 `mqttBridgeID`；MQTT 桥接组件会从上下文读取该 ID。
- `payload` 默认透传，建议按第三方格式重写。

### 写入第三方数据库

1. 配置数据库桥接数据源。

数据库桥接组件读取 `MultipleDataSource`，字段包括：

| 字段 | 说明 |
| --- | --- |
| `databaseSource` | 数据库类型，支持 MySQL、SQLServer、Oracle、PostgreSQL、H2。 |
| `host` | 地址，包含主机和端口。 |
| `dataBaseName` | 数据库名。 |
| `userName` | 用户名。 |
| `password` | 密码。 |
| `sql` | 要执行的 SQL，可使用上下文占位符替换。 |

2. 新增数据流脚本，写入 `databaseBridgeID`。

```json
{
  "scriptPurpose": 1,
  "scriptEvent": 1,
  "scriptAction": 5,
  "productId": 1,
  "enable": 1,
  "scriptData": "def cxt = _meta.getContextBean(com.岩安测控.ruleEngine.context.MsgContext.class); cxt.setData('databaseBridgeID', 20);"
}
```

注意：数据库桥接当前通过拼接后的 SQL 执行，生产环境必须控制 SQL 模板来源和字段转义，避免把不可信 payload 直接拼入 SQL。

## 第三方调用 岩安测控 桥接入口

岩安测控 也提供了桥接入口，第三方可以把数据送入 岩安测控 的数据流脚本：

| 方法 | 地址 | 说明 |
| --- | --- | --- |
| GET | `{BASE_URL}/bridge/get` | Query/Header 进入上下文。 |
| POST | `{BASE_URL}/bridge/post` | Body 进入上下文 payload。 |
| PUT | `{BASE_URL}/bridge/put` | Body 进入上下文 payload。 |

这些入口会以：

```text
scriptPurpose=1
scriptEvent=5
route=/bridge/get|/bridge/post|/bridge/put
```

查询并执行数据流脚本。

安全注意：当前安全配置未默认放行 `/bridge/**`，因此仍需要 Token，除非部署侧自行放开。

## 推荐对接方案

### 方案 A：实时同步优先

适用：第三方需要尽快拿到设备上报数据。

1. 第三方提供 HTTP 接收地址或 MQTT Broker。
2. 岩安测控 配置 `bridge`。
3. 岩安测控 为对应产品配置数据流脚本。
4. 第三方收到推送后按 `serialNumber + identifier + reportTime` 入库去重。
5. 第三方定时调用历史查询接口补偿漏推窗口。

推荐组合：

- 实时：HTTP 推送或 MQTT 桥接。
- 补偿：`POST /data/center/deviceHistory`。

### 方案 B：第三方定时拉取

适用：第三方不开放公网回调地址，或只需要分钟级/小时级同步。

1. 调用 `/iot/device/list` 或 `/iot/device/shortList` 同步设备。
2. 调用 `/iot/model/listByProductIdAndSerialNumber` 同步物模型。
3. 按设备调用 `/data/center/deviceHistory` 拉取上报数据。
4. 使用滑动窗口和去重键保证幂等。

### 方案 C：第三方数据库落库

适用：第三方只提供数据库账号，不提供 API。

1. 配置数据库连接。
2. 为产品配置数据流脚本。
3. 数据库桥接执行 SQL 写入第三方库。

不建议把该方案作为首选，原因是数据库账号权限、SQL 模板安全和网络连通性风险更高。

## 字段映射建议

第三方侧建议建立如下最小模型。

### 设备表

| 字段 | 来源 |
| --- | --- |
| `device_id` | `iot_device.deviceId` |
| `serial_number` | `iot_device.serialNumber` |
| `device_name` | `iot_device.deviceName` |
| `product_id` | `iot_device.productId` |
| `status` | `iot_device.status` |
| `tenant_id` | `iot_device.tenantId` |

### 物模型表

| 字段 | 来源 |
| --- | --- |
| `model_id` | `ThingsModelDTO.modelId` |
| `product_id` | 查询入参或返回字段 |
| `identifier` | `ThingsModelDTO.identifier` |
| `name` | `ThingsModelDTO.modelName` |
| `type` | `ThingsModelDTO.type` |
| `datatype` | `ThingsModelDTO.datatype` |

### 设备数据表

| 字段 | 来源 |
| --- | --- |
| `serial_number` | 设备编号 |
| `product_id` | 设备所属产品 |
| `identifier` | 物模型标识符 |
| `value` | 上报值 |
| `report_time` | 历史接口返回的时间或推送报文时间 |
| `source` | `pull` 或 `push` |
| `raw_payload` | 原始推送/查询报文 |

## 幂等、重试和安全

- 推送接口必须幂等，建议第三方以 `serialNumber + identifier + reportTime` 去重。
- 岩安测控 主动推送失败当前主要依赖组件日志排查，建议第三方同时做主动拉取补偿。
- 第三方主动查询必须按时间窗口限制范围，避免一次拉取全量历史。
- HTTP 推送建议使用 HTTPS、固定 Token 或签名头。
- MQTT 桥接建议使用独立账号和最小 Topic 权限。
- 数据库桥接建议只授予 INSERT 权限，避免执行 DDL 或高危 SQL。

## 当前实现注意点

- `岩安测控-mq` 当前核心是 JVM 内本地阻塞队列，不是外部 RocketMQ 的强持久化链路。
- 主动 HTTP 推送的默认 payload 由规则脚本上下文决定，生产对接应在脚本中统一出站报文。
- 数据桥接脚本查询按 `productId + scriptPurpose + scriptEvent + enable` 等条件筛选；产品维度必须配置正确。
- 业务表关系大多没有数据库外键，第三方不要依赖数据库外键判断关联，应以 API 返回和业务字段为准。