# 设备信息同步查询接口

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `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`。