# PLC Control 接口说明 本文档基于当前服务端路由与处理器代码整理，覆盖 HTTP API、SSE 日志流和 WebSocket 实时消息。 ## 基本信息 - 服务端默认提供静态 UI：`/ui` - HTTP API 前缀：`/api` - 公共实时 WebSocket：`/ws/public` - 客户端专属 WebSocket：`/ws/client/{client_id}` ## 通用错误响应 接口失败时通常返回： ```json { "err_code": 400, "err_msg": "Invalid JSON format", "err_detail": null } ``` 常见状态码： - `400 Bad Request`：参数错误 - `403 Forbidden`：写入权限不足 - `404 Not Found`：资源不存在 - `500 Internal Server Error`：服务端内部错误 --- ## Source ### GET `/api/source` 获取所有已启用数据源及其连接状态。 响应示例： ```json [ { "id": "uuid", "name": "PLC-1", "protocol": "opcua", "endpoint": "opc.tcp://127.0.0.1:4840", "security_policy": null, "security_mode": null, "enabled": true, "created_at": "2026-03-20 10:00:00.000", "updated_at": "2026-03-20 10:00:00.000", "is_connected": true, "last_error": null, "last_time": "2026-03-20 10:05:00.000" } ] ``` ### POST `/api/source` 创建数据源。 请求体： ```json { "name": "PLC-1", "endpoint": "opc.tcp://127.0.0.1:4840", "enabled": true } ``` 响应： ```json { "id": "uuid" } ``` ### PUT `/api/source/{source_id}` 更新数据源。 请求体字段均可选： ```json { "name": "PLC-1", "endpoint": "opc.tcp://127.0.0.1:4840", "enabled": true, "security_policy": "None", "security_mode": "None", "username": "user", "password": "pass" } ``` 响应： ```json { "ok_msg": "Source updated successfully" } ``` ### DELETE `/api/source/{source_id}` 删除数据源。 成功响应：`204 No Content` ### POST `/api/source/{source_id}/reconnect` 手动重连指定数据源。 响应： ```json { "ok_msg": "Source reconnected successfully" } ``` ### POST `/api/source/{source_id}/browse` 从 OPC UA 源浏览节点并写入本地 `node` 表。 响应： ```json { "ok_msg": "Browse completed", "total_nodes": 123 } ``` ### GET `/api/source/{source_id}/node-tree` 获取指定数据源的节点树。 响应字段： - `id` - `source_id` - `external_id` - `namespace_uri` - `namespace_index` - `identifier_type` - `identifier` - `browse_name` - `display_name` - `node_class` - `parent_id` - `children` --- ## Point ### GET `/api/point` 分页获取点位列表。 查询参数： - `source_id`：可选，按数据源过滤 - `page`：页码 - `page_size`：每页条数 响应示例： ```json { "data": [ { "id": "uuid", "node_id": "uuid", "name": "Temperature", "description": null, "unit": null, "tag_id": null, "created_at": "2026-03-20 10:00:00.000", "updated_at": "2026-03-20 10:00:00.000", "point_monitor": { "protocol": "opcua", "source_id": "uuid", "point_id": "uuid", "client_handle": 1001, "scan_mode": "subscribe", "timestamp": "2026-03-20 10:05:00.000", "quality": "good", "value": 12.3, "value_type": "float", "value_text": "12.3", "old_value": 12.1, "old_timestamp": "2026-03-20 10:04:59.000", "value_changed": true } } ], "total": 1, "page": 1, "page_size": 100 } ``` ### GET `/api/point/{point_id}` 获取单个点位。 ### GET `/api/point/{point_id}/history` 获取点位最近历史样本。数据来自进程内存中的环形缓冲，不是持久化历史库。 查询参数： - `limit`：可选，默认 `120`，最大 `1000` 响应示例： ```json [ { "timestamp": "2026-03-20 10:05:00.000", "quality": "good", "value": 12.3, "value_text": "12.3", "value_number": 12.3 } ] ``` 说明： - `value_number` 便于前端直接绘图 - 非数值型点位时，`value_number` 可能为 `null` ### PUT `/api/point/{point_id}` 更新点位元数据。 请求体： ```json { "name": "Temperature", "description": "Room temperature", "unit": "°C", "tag_id": "uuid" } ``` ### DELETE `/api/point/{point_id}` 删除单个点位。 响应： ```json { "ok_msg": "Point deleted successfully" } ``` ### POST `/api/point/batch` 根据节点批量创建点位。 请求体： ```json { "node_ids": ["uuid1", "uuid2"] } ``` 响应： ```json { "success_count": 2, "failed_count": 0, "failed_node_ids": [], "created_point_ids": ["uuid3", "uuid4"] } ``` ### DELETE `/api/point/batch` 批量删除点位。 请求体： ```json { "point_ids": ["uuid1", "uuid2"] } ``` 响应： ```json { "deleted_count": 2 } ``` ### PUT `/api/point/batch/set-tags` 批量设置点位标签。 请求体： ```json { "point_ids": ["uuid1", "uuid2"], "tag_id": "uuid" } ``` ### POST `/api/point/value/batch` 批量写点。 请求头： - `X-Write-Key: ` 请求体： ```json { "items": [ { "point_id": "uuid", "value": 12.3 } ] } ``` 响应： ```json { "success": true, "err_msg": null, "success_count": 1, "failed_count": 0, "results": [ { "point_id": "uuid", "success": true, "err_msg": null } ] } ``` --- ## Tag ### GET `/api/tag` 分页获取标签列表。 查询参数： - `page` - `page_size` ### GET `/api/tag/{tag_id}` 当前实现返回该标签下的点位列表。 ### POST `/api/tag` 创建标签。 请求体： ```json { "name": "Area-A", "description": "Area A points", "point_ids": ["uuid1", "uuid2"] } ``` ### PUT `/api/tag/{tag_id}` 更新标签。 请求体： ```json { "name": "Area-A", "description": "Updated", "point_ids": ["uuid1", "uuid2"] } ``` ### DELETE `/api/tag/{tag_id}` 删除标签。 成功响应：`204 No Content` --- ## Page `page` 用于保存页面布局或组件映射数据。 ### GET `/api/page` 查询页面列表。 查询参数： - `name`：可选，按名称模糊搜索 ### GET `/api/page/{page_id}` 获取单个页面。 ### POST `/api/page` 创建页面。 请求体： ```json { "name": "Dashboard", "data": { "widgetA": "uuid1", "widgetB": "uuid2" } } ``` ### PUT `/api/page/{page_id}` 更新页面。 请求体字段均可选： ```json { "name": "Dashboard", "data": { "widgetA": "uuid1" } } ``` ### DELETE `/api/page/{page_id}` 删除页面。 成功响应：`204 No Content` --- ## Log ### GET `/api/logs` 读取日志文件内容。 查询参数： - `file`：可选，指定日志文件名，仅允许 `app.log*` - `cursor`：可选，从指定游标后读取 - `tail_lines`：可选，默认 `200` - `max_bytes`：可选 响应： ```json { "file": "app.log", "cursor": 1024, "lines": ["..."], "truncated": false, "reset": false } ``` ### GET `/api/logs/stream` SSE 实时日志流。 事件类型： - `log` - `error` 客户端可使用 `EventSource` 订阅。 --- ## WebSocket ## 连接地址 - 公共广播：`/ws/public` - 客户端专属：`/ws/client/{client_id}` ## 服务端主动消息 ### `PointNewValue` ```json { "type": "PointNewValue", "data": { "protocol": "opcua", "source_id": "uuid", "point_id": "uuid", "client_handle": 1001, "scan_mode": "subscribe", "timestamp": "2026-03-20 10:05:00.000", "quality": "good", "value": 12.3, "value_type": "float", "value_text": "12.3", "old_value": 12.1, "old_timestamp": "2026-03-20 10:04:59.000", "value_changed": true } } ``` ### `PointSetValueBatchResult` ```json { "type": "PointSetValueBatchResult", "data": { "success": true, "err_msg": null, "success_count": 1, "failed_count": 0, "results": [] } } ``` ## 客户端发送消息 ### 写权限认证 ```json { "type": "auth_write", "data": { "key": "your-write-key" } } ``` ### 批量写点 ```json { "type": "point_set_value_batch", "data": { "items": [ { "point_id": "uuid", "value": 12.3 } ] } } ``` --- ## 备注 - 历史曲线接口当前使用内存缓存，服务重启后历史会清空。 - 实时遥测与 WebSocket 推送是“最新值优先”的设计，在高压场景下允许丢弃部分中间消息。 - `/api/tag/{tag_id}` 当前返回的是标签下点位，而不是标签自身详情。