docs(02-01): 完成 PERM+FIN+POLL 9项修复计划 PERM-01/02 FIN-01/02/03 POLL-01/02/03/04

2026-03-28 10:46:10 +08:00
parent 754bbcdf3b
commit e1ec024904
18 changed files with 5548 additions and 28 deletions
--- a/docs/第三方文档/gateway设备详情同步接口.md
+++ b/docs/第三方文档/gateway设备详情同步接口.md
@@ -0,0 +1,191 @@
+# 设备信息同步查询接口
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `POST /v1/iot/openApi/device/sync-info` |
+| 请求方式 | POST |
+| Content-Type | application/json |
+| 认证方式 | appId + sign 签名验证 |
+
+## 接口说明
+
+同步查询设备信息，直接返回设备完整数据。与异步接口 `/device/info` 的区别：
+
+| | 异步 `/device/info` | 同步 `/device/sync-info` |
+|---|---|---|
+| 返回方式 | 立即返回 `requestId`，结果通过 `callbackUrl` 回调 | 直接返回设备信息 |
+| `callbackUrl` | 必传 | 不需要 |
+| 响应字段 | 部分字段（经 v1 映射） | 全量字段 |
+
+## 请求参数
+
+### 请求体
+
+```json
+{
+  "appId": "your_app_id",
+  "sign": "签名字符串",
+  "timestamp": "时间戳",
+  "data": "加密后的业务数据"
+}
+```
+
+### data 解密后结构
+
+```json
+{
+  "params": {
+    "cardNo": "设备标识"
+  }
+}
+```
+
+### cardNo 说明
+
+| 长度 | 类型 | 示例 |
+|------|------|------|
+| > 15 位 | ICCID | `89860624590014720038` |
+| 15 位 | IMEI（设备号） | `868347081100410` |
+| 11 位 | SN（序列号） | `90001473913` |
+
+## 响应参数
+
+### 响应结构
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": { ... },
+  "trace_id": "请求追踪ID"
+}
+```
+
+### data 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `device_id` | string | 设备ID（IMEI/SN） |
+| `device_name` | string | 设备名称 |
+| `imei` | string | IMEI号 |
+| `imsi` | string | IMSI用户标识码 |
+| `current_iccid` | string | 当前使用的ICCID |
+| `device_type` | string | 设备类型：`1`=诺行，`2`=玺龙，`3`=迎势达 |
+| `software_version` | string | 软件版本号 |
+| `mac_address` | string | MAC地址 |
+| `ip_address` | string | IP地址 |
+| `ssid` | string | WiFi热点名称 |
+| `wifi_password` | string | WiFi密码 |
+| `wifi_enabled` | bool | WiFi开关状态 |
+| `max_clients` | int | 最大连接客户端数 |
+| `limit_speed` | int | 限速速率（KB/s） |
+| `sync_interval` | int | 信息上报周期（秒） |
+| `switch_mode` | string | 切卡模式：`0`=自动，`1`=手动 |
+| `ul_stats` | string | 本次开机上传流量（字节） |
+| `dl_stats` | string | 本次开机下载流量（字节） |
+| `daily_usage` | string | 日使用流量（字节） |
+| `rsrp` | int | 参考信号接收功率（dBm） |
+| `rsrq` | int | 参考信号接收质量（dB） |
+| `sinr` | int | 信噪比（dB） |
+| `rssi` | string | 接收信号强度 |
+| `lan_ip` | string | 局域网网关IP地址 |
+| `wan_ip` | string | 基站分配IPv4地址 |
+| `run_time` | string | 设备本次开机运行时间（秒） |
+| `connect_time` | string | 设备本次联网时间（秒） |
+| `battery_level` | int | 电池电量百分比 |
+| `online_status` | int | 在线状态：`1`=在线，`2`=离线 |
+| `status` | int | 设备状态：`1`=正常，`0`=禁用 |
+| `last_update_time` | string | 设备信息最后更新时间（ISO 8601） |
+| `last_online_time` | string | 设备最后在线时间（ISO 8601） |
+| `created_at` | int | 创建时间（Unix时间戳） |
+| `updated_at` | int | 更新时间（Unix时间戳） |
+
+> 所有字段均可能为 `null`，表示该字段暂无数据。
+
+## 响应示例
+
+### 成功响应
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "device_id": "90001473913",
+    "device_name": "868347081100410",
+    "imei": "868347081100410",
+    "imsi": null,
+    "current_iccid": "89860865192590302917",
+    "device_type": "3",
+    "software_version": "TZ103W_CN1_YSDPTZ12_TH_P42U28_U_17_PRO_20260121",
+    "mac_address": "00904D8486DE",
+    "ip_address": null,
+    "ssid": "ZJ-8486DE",
+    "wifi_password": null,
+    "wifi_enabled": true,
+    "max_clients": null,
+    "limit_speed": 0,
+    "sync_interval": 600,
+    "switch_mode": "0",
+    "ul_stats": null,
+    "dl_stats": null,
+    "daily_usage": "150980",
+    "rsrp": null,
+    "rsrq": null,
+    "sinr": null,
+    "rssi": "-72",
+    "lan_ip": null,
+    "wan_ip": null,
+    "run_time": "2099",
+    "connect_time": null,
+    "battery_level": null,
+    "online_status": 2,
+    "status": 1,
+    "last_update_time": "2026-03-23T16:53:18+08:00",
+    "last_online_time": "2026-03-23T16:53:18+08:00",
+    "created_at": null,
+    "updated_at": null
+  },
+  "trace_id": "trace_xxx"
+}
+```
+
+### 错误响应
+
+**cardNo 为空：**
+```json
+{
+  "code": 401,
+  "msg": "cardNo nil",
+  "data": null
+}
+```
+
+**设备不存在：**
+```json
+{
+  "code": 401,
+  "msg": "获取设备信息错误，无效设备号",
+  "data": null
+}
+```
+
+**服务调用失败：**
+```json
+{
+  "code": 500,
+  "msg": "服务调用失败",
+  "data": null
+}
+```
+
+## 数据来源说明
+
+接口数据按以下优先级获取：
+
+1. **Redis 缓存**（设备最近一次上报的实时数据，TTL 10 分钟）
+2. **数据库**（缓存过期后 fallback，字段可能不完整）
+
+设备在线时优先返回缓存中的实时上报数据；设备离线后缓存过期，返回数据库中最后一次同步的数据。部分字段（如 `wifi_password`、`battery_level` 等）在离线 fallback 场景下可能为 `null`。