add initial AI ball protocol docs

docs/device_api.md

@@ -1,3 +1,79 @@
 # AI球设备控制协议
 
-用于定义上位机、播放器、测试工具如何控制 AI球。
+本文档定义 PC 上位机、同步播放器和测试工具控制 AI球设备的初版 API 约定。
+
+## 1. 设计原则
+
+- 命令结构简单，便于串口、USB、BLE 或网络传输适配。
+- 每条请求应包含 `request_id`，便于上位机匹配响应。
+- 设备响应应包含 `ok`、`error_code` 和必要数据。
+- 不在协议中传输 token、密码或 API key。
+
+## 2. 通用消息格式
+
+### 请求
+
+```json
+{
+  "request_id": "req-001",
+  "command": "device.ping",
+  "params": {}
+}
+```
+
+### 响应
+
+```json
+{
+  "request_id": "req-001",
+  "ok": true,
+  "error_code": null,
+  "data": {}
+}
+```
+
+## 3. 初版命令
+
+| 命令 | 方向 | 用途 |
+| --- | --- | --- |
+| `device.ping` | PC -> 设备 | 检查设备在线状态。 |
+| `device.info` | PC -> 设备 | 读取设备型号、固件版本、序列号。 |
+| `device.state.get` | PC -> 设备 | 读取当前状态机状态。 |
+| `resource.pack.info` | PC -> 设备 | 读取当前资源包信息。 |
+| `resource.pack.prepare` | PC -> 设备 | 准备接收或校验资源包。 |
+| `play.sync` | PC -> 设备 | 下发同步播放状态。 |
+| `play.stop` | PC -> 设备 | 停止当前播放并回到可控状态。 |
+| `factory.test.start` | PC -> 设备 | 开始出厂测试。 |
+| `factory.test.result` | PC -> 设备 | 读取出厂测试结果。 |
+
+## 4. 示例：同步播放
+
+```json
+{
+  "request_id": "req-100",
+  "command": "play.sync",
+  "params": {
+    "content_id": "concert-demo-001",
+    "state": "playing",
+    "position_ms": 12345,
+    "speed": 1.0
+  }
+}
+```
+
+## 5. 错误码初稿
+
+| 错误码 | 说明 |
+| --- | --- |
+| `INVALID_COMMAND` | 未知命令。 |
+| `INVALID_PARAMS` | 参数缺失或格式错误。 |
+| `RESOURCE_NOT_READY` | 资源包未准备好。 |
+| `STATE_CONFLICT` | 当前状态不允许执行该命令。 |
+| `FACTORY_TEST_FAILED` | 出厂测试存在失败项。 |
+| `INTERNAL_ERROR` | 设备内部错误。 |
+
+## 6. 待确认问题
+
+- 传输层帧格式和最大消息大小。
+- 大资源包传输是否独立于控制协议。
+- 设备序列号和生产批次字段格式。