平台总览对接接口说明

# 平台总览对接接口说明

# 平台总览对外对接接口说明

本文档面向**外部系统开发人员**（组态软件、大屏、第三方监控等），用于与 visual\-check **平台总览**保持运行数据一致：读取快照、下发设定值与开关组操作。

| 项 | 说明 |
| --- | --- |
| 基础路径 | /api/v1/integration |
| 协议 | 生产环境须使用 HTTPS |
| 数据格式 | JSON，字符编码 UTF\-8 |
| 适用范围 | 仅本文档列出的接口；其余路径为系统内部使用，不在对外支持范围内 |

## 1\. 鉴权

支持两种方式（二选一）：

| 方式 | 适用场景 | 请求头 / 参数 |
| --- | --- | --- |
| 对接密钥 | 组态、固定大屏、机台对接 | X\-API\-Key: \<密钥\> |
| 访问令牌 | 需按账号审计、临时授权 | Authorization: Bearer \<accessToken\> |

### 1\.1 账号密码换取凭证（推荐首次对接）

使用已开通**总览对接权限**的账号，换取 accessToken 与 apiKey：

POST /api/v1/integration/auth/token  
Content\-Type: application/json  
  
{  
 "username": "your\_username",  
 "password": "your\_password"  
}

**成功响应** data

{  
 "accessToken": "eyJhbGciOiJIUzI1NiIs...",  
 "tokenType": "Bearer",  
 "expiresIn": 86400,  
 "apiKey": "your\_integration\_secret",  
 "user": {  
 "id": 1,  
 "username": "operator1",  
 "role": "operator",  
 "displayName": "操作员"  
 }  
}

| 字段 | 说明 |
| --- | --- |
| accessToken | JWT 访问令牌，默认有效期 24 小时，用于 Authorization: Bearer 或 SSE ?token\= |
| apiKey | 服务端分配的对接密钥，用于 X\-API\-Key 或 SSE ?apiKey\=（账号无权限时为 null） |
| expiresIn | 令牌有效秒数 |

**错误**

| HTTP | 说明 |
| --- | --- |
| 401 | 用户名或密码错误 |
| 403 | 账号不具备总览对接权限 |

**curl 示例**

curl \-s \-X POST "https://your\-host/api/v1/integration/auth/token" \\  
 \-H "Content\-Type: application/json" \\  
 \-d '{"username":"operator1","password":"your\_password"}'

令牌过期后需重新调用本接口。apiKey 为服务端统一对接密钥，由管理员配置；也可直接向管理员索取密钥，跳过本步骤。

### 1\.2 对接密钥（X\-API\-Key）

| 项 | 说明 |
| --- | --- |
| 请求头 | X\-API\-Key: \<对接密钥\> |
| 获取方式 | 调用 1\.1 接口，或联系管理员分配 |
| 安全要求 | 生产环境须使用 HTTPS，建议在网关层配置 IP 白名单 |

**请求示例**

GET /api/v1/integration/scenes/scene\_abc/snapshot HTTP/1\.1  
Host: your\-host:8081  
X\-API\-Key: your\_integration\_secret  
Accept: application/json

### 1\.3 访问令牌（Bearer）

Authorization: Bearer \<accessToken\>

写操作须使用具备写权限的账号换取的令牌。

### 1\.4 实时推送（EventSource）鉴权

浏览器 EventSource 无法自定义请求头，请通过查询参数传递密钥：

GET /api/v1/integration/scenes/{sceneId}/snapshot/stream?apiKey\=\<对接密钥\>\&intervalSec\=8

也支持在请求头中携带 X\-API\-Key；使用令牌时：?token\=\<accessToken\>。

### 1\.5 响应与错误码

统一响应体：

{  
 "code": 200,  
 "msg": "success",  
 "data": { }  
}

| HTTP 状态码 | 含义 |
| --- | --- |
| 200 | 请求成功（部分业务失败时 code 可能为 400，见响应体） |
| 400 | 参数错误或业务校验失败 |
| 401 | 未授权（密钥无效或缺失） |
| 404 | 场景不存在 |

## 2\. 对接流程

0\. POST /integration/auth/token（可选） → 换取 accessToken / apiKey  
1\. GET /integration/scenes → 获取 sceneId 列表  
2\. GET /integration/scenes/{id}/snapshot → 拉取快照（展示、轮询）  
 或 GET .../snapshot/stream → 服务端推送（推荐 Web 大屏）  
3\. 写操作完成后再次 GET snapshot 或等待下一帧推送 → 校验写入结果

**写操作类型**（与平台总览页操作一致）：

| 总览操作 | 接口 |
| --- | --- |
| 算法配置类参数「保存」 | PATCH .../params/{paramId} |
| 点位类参数「写入」 | POST .../points/{pointId}/write |
| 运行开关组开/关 | PUT .../switch\-groups/{groupId} |
| 批量下发（可选） | POST .../commands |

## 3\. 接口列表

| 序号 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 3\.1 | POST | /api/v1/integration/auth/token | 账号密码换取访问凭证（accessToken、apiKey） |
| 3\.2 | GET | /api/v1/integration/scenes | 获取可用场景 ID 列表 |
| 3\.3 | GET | /api/v1/integration/scenes/{sceneId}/snapshot | 拉取场景总览快照（核心读接口，支持字段裁剪） |
| 3\.4 | GET | /api/v1/integration/scenes/{sceneId}/snapshot/stream | 场景总览快照 SSE 实时推送（推荐 Web 大屏） |
| 3\.5 | PATCH | /api/v1/integration/scenes/{sceneId}/params/{paramId} | 写入算法配置类可写参数 |
| 3\.6 | POST | /api/v1/integration/scenes/{sceneId}/points/{pointId}/write | 写入点位值（经采集器下发） |
| 3\.7 | PUT | /api/v1/integration/scenes/{sceneId}/switch\-groups/{groupId} | 运行开关组一键启停 |
| 3\.8 | POST | /api/v1/integration/scenes/{sceneId}/commands | 批量下发多条写命令（可选） |

### 3\.1 换取访问凭证

使用已开通**总览对接权限**的账号与密码，换取 JWT 访问令牌及对接密钥；令牌过期后需重新调用。

POST /api/v1/integration/auth/token

见 [1\.1 账号密码换取凭证](about:blank#11-%E8%B4%A6%E5%8F%B7%E5%AF%86%E7%A0%81%E6%8D%A2%E5%8F%96%E5%87%AD%E8%AF%81%E6%8E%A8%E8%8D%90%E9%A6%96%E6%AC%A1%E5%AF%B9%E6%8E%A5)。

### 3\.2 场景列表

返回当前系统中可用于对接的场景 ID 与名称，供后续快照、写操作选择 sceneId。

GET /api/v1/integration/scenes?includeDisabled\=false

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| includeDisabled | bool | false | 是否包含已禁用场景 |

**响应** data

{  
 "items": \[  
 {  
 "sceneId": "scene\_xxx",  
 "sceneName": "除氟线",  
 "enabled": true  
 }  
 ]  
}

### 3\.3 场景总览快照（核心读接口）

获取指定场景的运行态总览数据，与平台总览页展示一致；支持按 fields 裁剪返回字段，减少 payload。

GET /api/v1/integration/scenes/{sceneId}/snapshot

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| hours | int | 8 | 趋势回溯小时数，范围 1–168 |
| compareYesterday | bool | false | 趋势是否叠加昨日曲线 |
| fields | string | 见下 | 逗号分隔的顶层字段；不传或空字符串表示返回**全量对外字段** |

**默认** fields**（推荐组态/大屏）**

scene,params,switchGroups,alerts,fetchedAt

**可选** fields **值（对外字段）**

scene、params、charts、switchGroups、alerts、fetchedAt

说明：fields 仅支持上表字段。场景配置、规则明细、触发历史、系统健康等内部数据不在对外接口中提供。

**响应** data **字段说明**

| 字段 | 说明 |
| --- | --- |
| scene | 场景基本信息：sceneId、sceneName、description |
| params | 核心参数（含当前解析值） |
| switchGroups | 运行开关组及各项状态 |
| charts | 指标趋势（含 series，数据量较大，按需请求） |
| alerts | 告警列表 |
| fetchedAt | 快照生成时间（ISO8601） |

params\[] **单项字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| paramId | string | 写算法参数时使用 |
| label | string | 显示名称 |
| group | string | 分组名（如「除碱」） |
| value | any | 当前值 |
| unit | string | 单位 |
| writable | bool | 是否可在总览写入 |
| sourceType | string | algorithm\_config（算法配置）/ point（点位）等 |
| pointId | string | 点位类写操作时使用 |
| algorithmId | string | 算法配置类参数所属算法 |
| configKey | string | 算法配置键 |
| stale | bool | 数据是否过期 |
| ageSeconds | number | 距上次更新秒数 |

switchGroups\[] **单项字段**

| 字段 | 说明 |
| --- | --- |
| groupId | 开关组 ID（写操作时使用） |
| label | 组名 |
| aggregate | 汇总状态：on / off / partial / unknown |
| items\[] | 子项：itemId、label、enabled、sourceType（如 rule\_enabled） |

**请求示例**

curl \-s \-H "X\-API\-Key: $KEY" \\  
 "https://your\-host/api/v1/integration/scenes/scene\_1/snapshot?fields\=scene,params,switchGroups,fetchedAt"

### 3\.4 快照实时推送（SSE）

按固定间隔推送场景总览快照，适合 Web 大屏；浏览器 EventSource 需通过查询参数传递 apiKey 或 token。

GET /api/v1/integration/scenes/{sceneId}/snapshot/stream

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| hours | int | 8 | 同快照接口 |
| compareYesterday | bool | false | 同快照接口 |
| intervalSec | int | 8 | 推送间隔（秒），范围 3–60 |
| fields | string | 默认同 3\.2 | 字段裁剪 |
| apiKey | string | — | 对接密钥（EventSource 场景必填） |

**事件类型**

| 事件名 | 数据说明 |
| --- | --- |
| snapshot | 与 GET snapshot 相同结构的 JSON |
| ping | 保活：{"ts": 173\..., "sceneId": "..."} |
| error | 错误：{"message": "..."} |

**JavaScript 示例**

const sceneId \= 'scene\_xxx'  
const apiKey \= 'your\_key'  
const es \= new EventSource(  
 \`/api/v1/integration/scenes/${sceneId}/snapshot/stream?apiKey\=${encodeURIComponent(apiKey)}\&intervalSec\=10\&fields\=scene,params,switchGroups,alerts,fetchedAt\`  
)  
es.addEventListener('snapshot', (e) \=\> {  
 const data \= JSON.parse(e.data)  
 // 刷新大屏  
})  
es.addEventListener('ping', () \=\> { /\* 保活 \*/ })

### 3\.5 写入算法配置参数

对应总览「核心参数」中 sourceType\=algorithm\_config 且 writable\=true 的项；成功后返回裁剪后的最新快照。

PATCH /api/v1/integration/scenes/{sceneId}/params/{paramId}  
Content\-Type: application/json  
  
{  
 "value": 7\.0  
}

**成功**：data 为裁剪后的最新快照（默认字段集）。

### 3\.6 写入点位值

对应总览「核心参数」中 sourceType\=point 的项；经采集器下发至 PLC/设备，pointId 取自快照中该参数的 pointId 字段。

POST /api/v1/integration/scenes/{sceneId}/points/{pointId}/write  
Content\-Type: application/json  
  
{  
 "value": 1  
}

**成功** data

{  
 "pointId": "pt\_xxx",  
 "success": true,  
 "snapshot": { }  
}

点位写入经采集器下发，总览刷新可能有数秒延迟，请结合 stale、ageSeconds 判断数据是否已更新。

### 3\.7 开关组一键启停

批量开启或关闭运行开关组内全部子项；可选 pendingInitByItemId 控制规则类开关在开启时是否「启用并初始化」。

PUT /api/v1/integration/scenes/{sceneId}/switch\-groups/{groupId}  
Content\-Type: application/json  
  
{  
 "enabled": true,  
 "pendingInitByItemId": {  
 "sw\_rule\_001": true  
 }  
}

| 字段 | 说明 |
| --- | --- |
| enabled | true 整组开启，false 整组关闭 |
| pendingInitByItemId | 可选；仅对 sourceType\=rule\_enabled 的 itemId 生效，表示开启时是否「启用并初始化」 |

**成功**：data 为裁剪后的最新快照。

### 3\.8 批量命令（可选）

一次请求下发多条写操作（参数、点位、开关组），便于组态侧批量同步；支持 requestId 追踪与部分失败明细。

POST /api/v1/integration/scenes/{sceneId}/commands  
Content\-Type: application/json  
  
{  
 "requestId": "550e8400\-e29b\-41d4\-a716\-446655440000",  
 "operator": "scada\-line\-1",  
 "commands": \[  
 { "type": "setParam", "paramId": "p\_ph\_target", "value": 7\.2 },  
 { "type": "writePoint", "pointId": "pt\_dose", "value": 1 },  
 {  
 "type": "switchGroup",  
 "groupId": "grp\_main",  
 "enabled": true,  
 "pendingInitByItemId": { "sw\_1": true }  
 }  
 ]  
}

**命令类型**

| type | 必填字段 |
| --- | --- |
| setParam | paramId、value |
| writePoint | pointId、value |
| switchGroup | groupId、enabled；可选 pendingInitByItemId |

**响应** data

{  
 "requestId": "...",  
 "operator": "scada\-line\-1",  
 "results": \[  
 { "index": 0, "type": "setParam", "ok": true, "msg": "已更新" }  
 ],  
 "snapshot": { },  
 "errors": \[]  
}

部分失败时 HTTP 可能仍为 200 但 code\=400，请检查 errors 数组。

## 4\. 组态 ID 映射建议

在组态侧维护映射表，避免用中文名称作为主键：

| 总览展示 | 对接 ID | 写接口 |
| --- | --- | --- |
| 场景 | sceneId | 路径参数 |
| 参数 | paramId | PATCH params |
| 点位参数 | pointId | POST points/write |
| 开关组 | groupId | PUT switch\-groups |
| 规则开关项 | itemId | pendingInitByItemId 的键 |

## 5\. 一致性与最佳实践

1. **以本系统为运行态事实源**：外部系统负责展示与下发命令，不要通过对接接口修改场景配置结构。

1. **写后读**：命令成功后应 GET snapshot 或等待 SSE 下一帧，不要仅依赖写请求的返回值。

1. **初始化规则**：每次开启开关组时**显式传递** pendingInitByItemId，不要假设服务端会记住上次勾选状态。

1. **并发**：与 Web 端同时修改同一参数时，后写覆盖；关键设定建议写前读取快照比对 value。

1. **轮询间隔**：HTTP 轮询建议 ≥ 5 秒；Web 大屏推荐 SSE，intervalSec 建议 8–15 秒。

1. **字段裁剪**：大屏常态展示建议默认 fields；需要趋势图时再追加 charts，以减小 payload。

1. **连通性检查**：可用 GET .../snapshot 代替专用健康检查；无需调用系统内部运维接口。

## 6\. 变更记录

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| 1\.3 | 2026\-06\-10 | 文档文件名中文化；接口列表补充各接口说明 |
| 1\.2 | 2026\-06\-01 | 新增账号密码换取 accessToken / apiKey 接口说明 |
| 1\.1 | 2026\-06\-01 | 文档中文化；移除系统内部接口说明；明确对外字段范围 |
| 1\.0 | 2026\-05\-27 | 初始发布：snapshot / stream / 写接口 / commands |