init: mipu-open 对外开放项目统一管理仓库

- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-04 12:16:08 +08:00
commit b450b512a2
38 changed files with 5473 additions and 0 deletions
--- a/docs/09-01_device-list.md
+++ b/docs/09-01_device-list.md
@@ -0,0 +1,141 @@
+<!-- mipuyun-api-doc: device-list -->
+# device/list - 设备列表
+
+## 概述
+
+设备列表API用于查询当前客户的所有设备信息，包括设备状态、绑定的VCC卡、任务状态等。
+
+### 用户使用场景
+
+本接口用于：
+- 查看所有可用设备及其在线状态
+- 检查设备的VCC卡绑定情况
+- 查看设备的任务处理状态
+
+## 请求说明
+
+| 项目 | 值 |
+|------|-----|
+| **请求地址** | `https://${endpoint}/device/list` |
+| **请求方法** | GET |
+| **注意事项** | 无需请求体，从Header中获取clientCode |
+
+### Header 参数
+
+| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
+|----------|------|----------|--------|------|
+| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
+| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
+
+## 返回参数
+
+成功时返回设备信息列表：
+
+```json
+[
+  {
+    "deviceId": "device-001",
+    "status": "ONLINE",
+    "vccCardNumber": "424242******4242",
+    "bindingVccCardNumber": "555555******5555",
+    "lastHeartbeatTime": 1704140800000,
+    "taskStatus": "PROCESSING",
+    "processingTask": {
+      "taskId": "task-123",
+      "taskType": "BIND_VCC",
+      "status": "PROCESSING",
+      "createTime": "2025-01-15T10:30:00Z",
+      "updateTime": "2025-01-15T10:35:00Z",
+      "deviceId": "device-001"
+    },
+    "pendingTasks": []
+  },
+  {
+    "deviceId": "device-002",
+    "status": "OFFLINE",
+    "vccCardNumber": "378222******2222",
+    "bindingVccCardNumber": null,
+    "lastHeartbeatTime": 1704130000000,
+    "taskStatus": "IDLE",
+    "processingTask": null,
+    "pendingTasks": [
+      {
+        "taskId": "task-124",
+        "taskType": "UNBIND_VCC",
+        "status": "PENDING",
+        "createTime": "2025-01-15T11:00:00Z",
+        "updateTime": "2025-01-15T11:00:00Z",
+        "deviceId": "device-002"
+      }
+    ]
+  }
+]
+```
+
+| 参数名称 | 类型 | 说明 |
+|----------|------|------|
+| deviceId | String | 设备编号 |
+| status | String | 设备状态：ONLINE=在线，OFFLINE=离线 |
+| vccCardNumber | String | 当前绑定的VCC卡号（脱敏显示） |
+| bindingVccCardNumber | String | 正在绑定的VCC卡号（脱敏显示，绑定任务进行中时存在） |
+| lastHeartbeatTime | Long | 最后心跳时间（时间戳毫秒） |
+| taskStatus | String | 任务状态：IDLE=空闲，PROCESSING=处理中，PENDING=有等待任务 |
+| processingTask | Object | 正在执行的任务信息 |
+| pendingTasks | Array | 等待队列中的任务列表 |
+
+### TaskInfo 任务信息
+
+| 参数名称 | 类型 | 说明 |
+|----------|------|------|
+| taskId | String | 任务ID |
+| taskType | String | 任务类型：BIND_VCC=绑定VCC卡，UNBIND_VCC=解绑VCC卡，PAYMENT=支付 |
+| status | String | 任务状态：PENDING=等待中，PROCESSING=处理中，COMPLETED=已完成，FAILED=失败 |
+| createTime | String | 创建时间（ISO 8601格式） |
+| updateTime | String | 更新时间（ISO 8601格式） |
+| deviceId | String | 设备ID |
+
+## 业务案例
+
+### 查询所有设备状态
+
+### 请求
+
+```bash
+curl -X GET "https://${endpoint}/device/list" \
+  -H "client-key: your_key" \
+  -H "client-secret: your_secret"
+```
+
+### 响应
+
+```json
+[
+  {
+    "deviceId": "device-001",
+    "status": "ONLINE",
+    "vccCardNumber": "424242******4242",
+    "bindingVccCardNumber": null,
+    "lastHeartbeatTime": 1704140800000,
+    "taskStatus": "IDLE",
+    "processingTask": null,
+    "pendingTasks": []
+  }
+]
+```
+
+## 常见问题
+
+### 设备状态ONLINE和OFFLINE的区别是什么？
+
+- **ONLINE**：设备在线，可以接收和处理任务
+- **OFFLINE**：设备离线，无法处理任务
+
+### taskStatus有几种状态？
+
+- **IDLE**：设备空闲，没有正在处理的任务
+- **PROCESSING**：设备正在执行任务
+- **PENDING**：设备有待处理的任务队列
+
+### VCC卡号为什么要脱敏显示？
+
+为了保护支付安全，VCC卡号只显示前6位和后4位，中间用*替换。