新增 WMS 搬运规则与任务管理

支持搬运规则维护、候选预览、任务生成、预占、下发、取消和完成，并完善仓储管理前端交互。
2026-06-25 11:02:22 +08:00
parent 1cb8091bbe
commit 15405ba114
101 changed files with 4167704 additions and 152 deletions
@@ -0,0 +1,151 @@
+# AGV 播放 API
+
+> 版本 1 · `http://127.0.0.1:8765`（先 `python serve.py`，并保持 `play.html` 打开）  
+> 集成步骤与代码示例见 [接入教程.md](./接入教程.md)。
+
+对外仅 **2 个 HTTP 接口**、**3 个动作**。
+
+---
+
+## 接口
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| `GET` | `/api/catalog` | 查有哪些车、每辆车有哪些动作 |
+| `POST` | `/api/agv` | 控制播放（`playAction` / `stopAction` / `clearActions`） |
+
+---
+
+## 协议
+
+**POST 请求体：**
+
+```json
+{
+  "version": 1,
+  "method": "playAction",
+  "params": {
+    "modelId": "英招",
+    "actionId": "dongzuo1"
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `version` | 固定 `1` |
+| `method` | `playAction` · `stopAction` · `clearActions` |
+| `params.modelId` | **必填**，车辆 ID |
+| `params.actionId` | `playAction` / `stopAction` 必填 |
+
+**响应：**
+
+```json
+{
+  "version": 1,
+  "ok": true,
+  "data": {
+    "dispatched": true,
+    "subscribers": 1,
+    "modelId": "英招",
+    "activeActions": ["dongzuo1"]
+  },
+  "error": null
+}
+```
+
+`subscribers: 0` 表示播放页未打开，命令已缓存，打开 `play.html` 后自动执行。
+
+---
+
+## 1. GET /api/catalog — 查目录
+
+```
+GET http://127.0.0.1:8765/api/catalog
+```
+
+响应 `data.vehicles` 示例：
+
+```json
+[
+  {
+    "modelId": "英招",
+    "name": "英招",
+    "actions": [
+      { "id": "dongzuo1", "label": "动作1" }
+    ]
+  }
+]
+```
+
+---
+
+## 2. POST /api/agv — 控制播放
+
+须先打开：`http://127.0.0.1:8765/viewer/play.html`
+
+### playAction — 开启动作（自动切车）
+
+```json
+{
+  "version": 1,
+  "method": "playAction",
+  "params": {
+    "modelId": "英招",
+    "actionId": "dongzuo1"
+  }
+}
+```
+
+### stopAction — 关闭指定动作
+
+```json
+{
+  "version": 1,
+  "method": "stopAction",
+  "params": {
+    "modelId": "英招",
+    "actionId": "dongzuo1"
+  }
+}
+```
+
+### clearActions — 关闭该车全部动作
+
+```json
+{
+  "version": 1,
+  "method": "clearActions",
+  "params": {
+    "modelId": "英招"
+  }
+}
+```
+
+---
+
+## 联调流程
+
+```
+GET /api/catalog  →  取 modelId、actionId
+        ↓
+POST playAction   →  播放页执行
+        ↓
+POST stopAction / clearActions  →  停止
+```
+
+---
+
+## 常见问题
+
+| 现象 | 处理 |
+|------|------|
+| 页面打不开 | 只保留一个 `python serve.py` 进程 |
+| Postman 卡住 | 重启 `serve.py` |
+| `subscribers: 0` | 先打开 `play.html` |
+| `params.modelId 必填` | 三个动作都要带 `modelId` |
+| `UNKNOWN_METHOD` | POST 只能用上述 3 个 method；查目录用 GET |
+
+---
+
+*数字孪生开发组*