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-04_device-task.md
+++ b/docs/09-04_device-task.md
@@ -0,0 +1,165 @@
+<!-- mipuyun-api-doc: device-task -->
+# device/task/{taskId} - 查询任务
+
+## 概述
+
+任务查询API用于查询设备任务的执行状态和详情。通过绑定/解绑接口获取的任务ID，可以使用本接口查询任务进度。
+
+### 用户使用场景
+
+本接口用于：
+- 查询VCC卡绑定任务的状态
+- 查询VCC卡解绑任务的状态
+- 查询支付任务的状态
+- 获取任务的详细信息和设备状态
+
+## 请求说明
+
+| 项目 | 值 |
+|------|-----|
+| **请求地址** | `https://${endpoint}/device/task/{taskId}` |
+| **请求方法** | GET |
+| **注意事项** | taskId从绑定/解绑接口返回中获取 |
+
+### Header 参数
+
+| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
+|----------|------|----------|--------|------|
+| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
+| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
+
+### URL 参数
+
+| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
+|----------|------|----------|--------|------|
+| taskId | String | 是 | "task-bind-123456" | 任务ID，从绑定/解绑接口返回 |
+
+## 返回参数
+
+成功时返回任务详情：
+
+```json
+{
+  "deviceId": "device-001",
+  "deviceStatus": "ONLINE",
+  "task": {
+    "taskId": "task-bind-123456",
+    "taskType": "BIND_VCC",
+    "status": "PROCESSING",
+    "createTime": "2025-01-15T10:30:00Z",
+    "updateTime": "2025-01-15T10:35:00Z",
+    "deviceId": "device-001",
+    "orderId": null,
+    "creditCard": {
+      "cardNumber": "424242******4242",
+      "cvv": "***",
+      "expiryDate": "12/25"
+    },
+    "orderDetail": null
+  }
+}
+```
+
+| 参数名称 | 类型 | 说明 |
+|----------|------|------|
+| deviceId | String | 执行任务的设备ID |
+| deviceStatus | String | 设备状态：ONLINE=在线，OFFLINE=离线 |
+| task | Object | 任务详细信息 |
+
+### Task 任务信息
+
+| 参数名称 | 类型 | 说明 |
+|----------|------|------|
+| 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 |
+| orderId | String | 订单ID（仅PAYMENT类型任务） |
+| creditCard | Object | 信用卡信息（仅BIND_VCC类型任务，脱敏显示） |
+| orderDetail | String | 订单详情（仅PAYMENT类型任务） |
+
+## 业务案例
+
+### 查询绑定任务状态
+
+### 请求
+
+```bash
+curl -X GET "https://${endpoint}/device/task/task-bind-123456" \
+  -H "client-key: your_key" \
+  -H "client-secret: your_secret"
+```
+
+### 响应 - 任务处理中
+
+```json
+{
+  "deviceId": "device-001",
+  "deviceStatus": "ONLINE",
+  "task": {
+    "taskId": "task-bind-123456",
+    "taskType": "BIND_VCC",
+    "status": "PROCESSING",
+    "createTime": "2025-01-15T10:30:00Z",
+    "updateTime": "2025-01-15T10:35:00Z",
+    "deviceId": "device-001",
+    "creditCard": {
+      "cardNumber": "424242******4242",
+      "cvv": "***",
+      "expiryDate": "12/25"
+    }
+  }
+}
+```
+
+### 响应 - 任务完成
+
+```json
+{
+  "deviceId": "device-001",
+  "deviceStatus": "ONLINE",
+  "task": {
+    "taskId": "task-bind-123456",
+    "taskType": "BIND_VCC",
+    "status": "COMPLETED",
+    "createTime": "2025-01-15T10:30:00Z",
+    "updateTime": "2025-01-15T10:36:00Z",
+    "deviceId": "device-001"
+  }
+}
+```
+
+### 响应 - 任务不存在
+
+```json
+{
+  "deviceId": null,
+  "deviceStatus": null,
+  "task": null
+}
+```
+
+## 常见问题
+
+### 任务状态有哪几种？
+
+- **PENDING**：任务在队列中等待执行
+- **PROCESSING**：任务正在执行中
+- **COMPLETED**：任务执行完成
+- **FAILED**：任务执行失败
+
+### 任务查询不到是什么原因？
+
+- 任务ID错误
+- 任务已完成且已被清理（根据系统配置，任务可能会在完成后一段时间被清理）
+- 任务ID来自其他客户
+
+### 为什么要轮询查询任务状态？
+
+因为绑定/解绑操作是异步的，设备需要时间完成操作。建议间隔3-5秒轮询一次，直到任务状态变为 COMPLETED 或 FAILED。
+
+### 信用卡信息为什么要脱敏？
+
+为了保护支付安全，任务详情中的信用卡信息只显示脱敏后的卡号和掩码CVV。