docs(api): add missing Tag, Page, Log sections and batch-auto/set-tags endpoints
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
bc6e6e889f
commit
22ae4fa4b4
213
API.md
213
API.md
|
|
@ -242,6 +242,23 @@
|
|||
}
|
||||
```
|
||||
|
||||
### PUT `/api/point/batch/set-tags`
|
||||
|
||||
批量设置点位的标签（`tag_id`，传 `null` 可清除绑定）。
|
||||
|
||||
```json
|
||||
{
|
||||
"point_ids": ["uuid1", "uuid2"],
|
||||
"tag_id": "uuid"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{ "ok_msg": "Point tags updated successfully", "updated_count": 2 }
|
||||
```
|
||||
|
||||
### POST `/api/point/value/batch`
|
||||
|
||||
批量写点。
|
||||
|
|
@ -529,6 +546,25 @@
|
|||
{ "ok_msg": "Auto control stopped", "unit_id": "uuid" }
|
||||
```
|
||||
|
||||
### POST `/api/control/unit/batch-start-auto`
|
||||
|
||||
批量启动所有已启用（`enabled = true`）控制单元的自动控制。已在运行、故障锁或通讯锁的单元将跳过。
|
||||
|
||||
```json
|
||||
{
|
||||
"started": ["uuid1", "uuid2"],
|
||||
"skipped": ["uuid3"]
|
||||
}
|
||||
```
|
||||
|
||||
### POST `/api/control/unit/batch-stop-auto`
|
||||
|
||||
批量停止所有自动控制中的控制单元。
|
||||
|
||||
```json
|
||||
{ "stopped": ["uuid1", "uuid2"] }
|
||||
```
|
||||
|
||||
### POST `/api/control/unit/{unit_id}/ack-fault`
|
||||
|
||||
人工确认故障，解除故障锁定。要求：`fault_locked = true` 且 `flt_active = false`（故障信号已消失）。
|
||||
|
|
@ -539,6 +575,183 @@
|
|||
|
||||
---
|
||||
|
||||
## Tag（标签）
|
||||
|
||||
### GET `/api/tag`
|
||||
|
||||
分页获取标签列表。
|
||||
|
||||
查询参数：`page`、`page_size`
|
||||
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "主蒸汽",
|
||||
"description": null,
|
||||
"created_at": "2026-03-20 10:00:00.000",
|
||||
"updated_at": "2026-03-20 10:00:00.000"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
```
|
||||
|
||||
### POST `/api/tag`
|
||||
|
||||
创建标签，可同时绑定点位。
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "主蒸汽",
|
||||
"description": null,
|
||||
"point_ids": ["uuid1", "uuid2"]
|
||||
}
|
||||
```
|
||||
|
||||
响应：`201 Created`
|
||||
|
||||
```json
|
||||
{ "id": "uuid", "ok_msg": "Tag created successfully" }
|
||||
```
|
||||
|
||||
### GET `/api/tag/{tag_id}`
|
||||
|
||||
获取标签下所有绑定点位。
|
||||
|
||||
响应：点位对象数组。
|
||||
|
||||
### PUT `/api/tag/{tag_id}`
|
||||
|
||||
更新标签，字段均可选（`point_ids` 传入时全量替换绑定关系）：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "主蒸汽",
|
||||
"description": "描述",
|
||||
"point_ids": ["uuid1"]
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE `/api/tag/{tag_id}`
|
||||
|
||||
删除标签。成功响应：`204 No Content`
|
||||
|
||||
---
|
||||
|
||||
## Page（自定义页面）
|
||||
|
||||
### GET `/api/page`
|
||||
|
||||
获取所有页面，按 `created_at` 排序。
|
||||
|
||||
查询参数：`name`（可选，模糊搜索）
|
||||
|
||||
响应：Page 对象数组。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "总览",
|
||||
"data": { "slot_key": "point-uuid" },
|
||||
"created_at": "2026-03-20 10:00:00.000",
|
||||
"updated_at": "2026-03-20 10:00:00.000"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
`data` 为 `{ slot_key: point_id }` 映射，用于页面布局与点位绑定。
|
||||
|
||||
### POST `/api/page`
|
||||
|
||||
创建页面。
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "总览",
|
||||
"data": { "slot_a": "uuid1", "slot_b": "uuid2" }
|
||||
}
|
||||
```
|
||||
|
||||
响应：`201 Created`
|
||||
|
||||
```json
|
||||
{ "id": "uuid", "ok_msg": "Page created successfully" }
|
||||
```
|
||||
|
||||
### GET `/api/page/{page_id}`
|
||||
|
||||
获取单个页面。
|
||||
|
||||
### PUT `/api/page/{page_id}`
|
||||
|
||||
更新页面，字段均可选：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "总览",
|
||||
"data": { "slot_a": "uuid1" }
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE `/api/page/{page_id}`
|
||||
|
||||
删除页面。成功响应：`204 No Content`
|
||||
|
||||
---
|
||||
|
||||
## Log（运行日志）
|
||||
|
||||
### GET `/api/logs`
|
||||
|
||||
读取服务端日志文件内容（默认取最新 `app.log*` 文件尾部 200 行）。
|
||||
|
||||
查询参数：
|
||||
|
||||
- `file`：可选，指定文件名（仅允许 `app.log` 前缀）
|
||||
- `cursor`：可选，上次返回的字节偏移量；传入时增量读取 cursor 之后的内容
|
||||
- `tail_lines`：可选，不传 cursor 时返回的尾部行数（默认 200，最大 2000）
|
||||
- `max_bytes`：可选，单次最多返回字节数（默认 64 KB，最大 512 KB）
|
||||
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"file": "app.log",
|
||||
"cursor": 204800,
|
||||
"lines": ["2026-03-25 10:00:00 INFO ..."],
|
||||
"truncated": false,
|
||||
"reset": false
|
||||
}
|
||||
```
|
||||
|
||||
- `truncated`：`true` 表示本次未读完，可用新 cursor 继续请求
|
||||
- `reset`：`true` 表示文件已轮转（cursor > 文件大小），已从头读取
|
||||
|
||||
### GET `/api/logs/stream`
|
||||
|
||||
以 **SSE**（Server-Sent Events）流式推送日志增量，每 800 ms 检查一次文件变化。
|
||||
|
||||
查询参数：`file`、`cursor`（可选，默认从文件末尾开始）、`max_bytes`（默认 32 KB）
|
||||
|
||||
事件格式：
|
||||
|
||||
```
|
||||
event: log
|
||||
data: { "file": "app.log", "cursor": 204800, "lines": [...], "truncated": false, "reset": false }
|
||||
|
||||
event: error
|
||||
data: log stream read failed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebSocket
|
||||
|
||||
### 连接地址
|
||||
|
|
|
|||
Loading…
Reference in New Issue