|
@@ -4,7 +4,7 @@
|
|
|
|
|
|
|
|
## 1. 契约总则
|
|
## 1. 契约总则
|
|
|
|
|
|
|
|
-- 所有接口均为**只读**:仅 `GET` + `@PreAuthorize("isAuthenticated()")`,不存在任何处置、派发、确认类写入口。
|
|
|
|
|
|
|
+- 所有接口均为**只读**:仅 `GET`,不存在任何处置、派发、确认类写入口。**2026-09-28 起驾驶舱 GET 接口免鉴权**:`GET /api/cockpit/v1/**` 匿名可访问,不再要求 `Authorization`;接口安全性由部署环境的网络层内网隔离保障。非 GET 请求、其它业务 API 与管理端接口仍需认证。
|
|
|
- 统一响应信封:`{ "code": 200, "msg": "操作成功", "data": {...} }`;错误为 `{ "code": <httpStatus>, "msg": "<message>", "data": { category, message, requestId, serverTime } }`。
|
|
- 统一响应信封:`{ "code": 200, "msg": "操作成功", "data": {...} }`;错误为 `{ "code": <httpStatus>, "msg": "<message>", "data": { category, message, requestId, serverTime } }`。
|
|
|
- JSON 字段一律 `camelCase`。数据库列名属适配器内部细节,不出现在契约中。
|
|
- JSON 字段一律 `camelCase`。数据库列名属适配器内部细节,不出现在契约中。
|
|
|
- 设备唯一关联键:对外使用 `deviceCode`(对应 `equipment_base.equipment_code`)。设备主键内部使用 `equipment_base.equipment_id`;`work_order` 当前通过 `device_id` 关联设备,不能读取已删除的 `work_order.device_code`。WebSocket 迁移期同时下发 `device_code` 作为兼容别名。
|
|
- 设备唯一关联键:对外使用 `deviceCode`(对应 `equipment_base.equipment_code`)。设备主键内部使用 `equipment_base.equipment_id`;`work_order` 当前通过 `device_id` 关联设备,不能读取已删除的 `work_order.device_code`。WebSocket 迁移期同时下发 `device_code` 作为兼容别名。
|
|
@@ -107,10 +107,10 @@
|
|
|
|
|
|
|
|
## 5. WebSocket 实时增量
|
|
## 5. WebSocket 实时增量
|
|
|
|
|
|
|
|
-端点:`/ws/deviceStatus`。
|
|
|
|
|
|
|
+端点:`/ws/deviceStatus`(**免鉴权**,与驾驶舱 REST 一致;安全性由网络层内网隔离保障)。
|
|
|
|
|
|
|
|
```
|
|
```
|
|
|
-// 订阅全量驾驶舱状态
|
|
|
|
|
|
|
+// 订阅全量驾驶舱状态:连接后直接发送,无需 authenticate 帧(2026-09-28 起)
|
|
|
→ {"type":"cockpitSubscribe","scope":"all"}
|
|
→ {"type":"cockpitSubscribe","scope":"all"}
|
|
|
← {"type":"cockpitSubscribed","scope":"all","serverUpdatedAt":"2026-09-02T10:00:00+08:00"}
|
|
← {"type":"cockpitSubscribed","scope":"all","serverUpdatedAt":"2026-09-02T10:00:00+08:00"}
|
|
|
|
|
|
|
@@ -121,12 +121,10 @@
|
|
|
"monitoringPointCode":"MP-001",
|
|
"monitoringPointCode":"MP-001",
|
|
|
"data":{"status":"ALARM","statusTime":"2026-09-02T09:59:50+08:00",
|
|
"data":{"status":"ALARM","statusTime":"2026-09-02T09:59:50+08:00",
|
|
|
"serverUpdatedAt":"2026-09-02T10:00:00+08:00"}}
|
|
"serverUpdatedAt":"2026-09-02T10:00:00+08:00"}}
|
|
|
-
|
|
|
|
|
-// 兼容旧客户端:按设备订阅
|
|
|
|
|
-→ {"type":"subscribe","deviceCodes":["TC-PS-WS-202609020012"]}
|
|
|
|
|
-← {"type":"subscribed","deviceCodes":["TC-PS-WS-202609020012"]}
|
|
|
|
|
```
|
|
```
|
|
|
|
|
|
|
|
|
|
+`authenticate` 帧仅服务管理端工单推送(`workOrderReminder` 需要用户身份),驾驶舱链路不使用、不要求。
|
|
|
|
|
+
|
|
|
客户端以 `serverUpdatedAt` 判新旧(新者胜),REST 提供首帧权威快照,WebSocket 只推变化设备;断线后重新订阅即可。设备状态校准周期默认 60 秒,可配置延长。
|
|
客户端以 `serverUpdatedAt` 判新旧(新者胜),REST 提供首帧权威快照,WebSocket 只推变化设备;断线后重新订阅即可。设备状态校准周期默认 60 秒,可配置延长。
|
|
|
|
|
|
|
|
增量帧字段口径:`monitoringPointCode` 为设备关联监测点的编码(`equipment_base.equipment_code` → `equipment_point_rel` → `monitor_point.point_code`);未关联设备该字段显式 `null`,不静默丢失。`data.reason` 无异常时显式 `null`。
|
|
增量帧字段口径:`monitoringPointCode` 为设备关联监测点的编码(`equipment_base.equipment_code` → `equipment_point_rel` → `monitor_point.point_code`);未关联设备该字段显式 `null`,不静默丢失。`data.reason` 无异常时显式 `null`。
|
|
@@ -151,13 +149,14 @@ mvn -pl zksy-admin -am test -Dtest='Cockpit*Test'
|
|
|
|
|
|
|
|
联调检查表:
|
|
联调检查表:
|
|
|
|
|
|
|
|
-1. 携带正确凭据访问任一端点,返回 200 且 `data.readOnly = true`;无凭据返回 401 `UNAUTHORIZED`。
|
|
|
|
|
|
|
+1. **无凭据** `GET` 任一驾驶舱端点,返回 200 且 `data.readOnly = true`(2026-09-28 起免鉴权;接口安全由网络层内网隔离保障)。
|
|
|
2. 对每个端点构造一次非法参数,确认 400 `INVALID_REQUEST` 且不产生业务写入。
|
|
2. 对每个端点构造一次非法参数,确认 400 `INVALID_REQUEST` 且不产生业务写入。
|
|
|
3. 用 `snapshotAt` 连续请求 `page=1..n`,确认 `total` 一致、监测点不重复。
|
|
3. 用 `snapshotAt` 连续请求 `page=1..n`,确认 `total` 一致、监测点不重复。
|
|
|
4. 用同一 `deviceCode` 依次请求 archive / metrics / events / work-orders / detail-aggregate,确认关联一致。
|
|
4. 用同一 `deviceCode` 依次请求 archive / metrics / events / work-orders / detail-aggregate,确认关联一致。
|
|
|
5. `detail-aggregate` 中任一分区失败时,其余分区仍返回数据。
|
|
5. `detail-aggregate` 中任一分区失败时,其余分区仍返回数据。
|
|
|
6. 建立 WebSocket,发送 `cockpitSubscribe(scope=all)`,确认收到 `cockpitSubscribed` 与后续增量。
|
|
6. 建立 WebSocket,发送 `cockpitSubscribe(scope=all)`,确认收到 `cockpitSubscribed` 与后续增量。
|
|
|
7. 校验所有时间戳均为 `+08:00`,`freshness` 与实际数据新鲜度一致。
|
|
7. 校验所有时间戳均为 `+08:00`,`freshness` 与实际数据新鲜度一致。
|
|
|
|
|
+8. 对任一驾驶舱端点发非 GET 请求(如 POST),确认仍被拒绝(405 由映射决定,其余非 GET 仍需认证)。
|
|
|
|
|
|
|
|
## 7. 国产化与容器化可行性
|
|
## 7. 国产化与容器化可行性
|
|
|
|
|
|