# 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 |

---

*数字孪生开发组*