From ad4b0c0680ec88983dfa1d6d719f101b37d49442 Mon Sep 17 00:00:00 2001
From: caoqianming <caoqianming@foxmail.com>
Date: Thu, 26 Mar 2026 11:12:00 +0800
Subject: [PATCH] docs(api): update control section for fault-guard changes

- start-auto now requires fault_locked=false and manual_ack_required=false
- batch-start-auto now also skips units with manual_ack_required
- add manual_ack_required to pre-flight check list

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

diff --git a/API.md b/API.md
index 731fe3d..9c2e9bf 100644
--- a/API.md
+++ b/API.md
@@ -505,7 +505,7 @@
 
 ## Control（控制命令）
 
-所有控制命令在执行前会校验：信号质量、REM 状态、FLT 状态、单元通讯锁、单元故障锁。
+所有控制命令在执行前会校验：信号质量、REM 状态、FLT 状态、单元通讯锁、单元故障锁、人工确认状态。
 
 ### POST `/api/control/equipment/{equipment_id}/start`
 
@@ -532,12 +532,19 @@
 
 ### POST `/api/control/unit/{unit_id}/start-auto`
 
-启动指定控制单元的自动控制循环。单元须已启用（`enabled = true`）。
+启动指定控制单元的自动控制循环。
+
+前置条件：
+- 单元已启用（`enabled = true`）
+- `fault_locked = false`（无活跃故障）
+- `manual_ack_required = false`（故障已人工确认）
 
 ```json
 { "ok_msg": "Auto control started", "unit_id": "uuid" }
 ```
 
+失败时返回 `400 Bad Request`，`err_msg` 说明具体原因（故障锁定 / 待人工确认）。
+
 ### POST `/api/control/unit/{unit_id}/stop-auto`
 
 停止自动控制循环。设备当前状态保持不变，不会自动停机。
@@ -548,7 +555,7 @@
 
 ### POST `/api/control/unit/batch-start-auto`
 
-批量启动所有已启用（`enabled = true`）控制单元的自动控制。已在运行、故障锁或通讯锁的单元将跳过。
+批量启动所有已启用（`enabled = true`）控制单元的自动控制。以下情况的单元将跳过：已在运行、`fault_locked`、`comm_locked`、`manual_ack_required`。
 
 ```json
 {