From 22ae4fa4b496af772b4fc2d8a4b515e83b7d2740 Mon Sep 17 00:00:00 2001
From: caoqianming <caoqianming@foxmail.com>
Date: Wed, 25 Mar 2026 14:27:49 +0800
Subject: [PATCH] docs(api): add missing Tag, Page, Log sections and
 batch-auto/set-tags endpoints

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 API.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 213 insertions(+)

diff --git a/API.md b/API.md
index 5b9f7b0..731fe3d 100644
--- a/API.md
+++ b/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
 
 ### 连接地址