junhong_cmp_fiber/docs/asset-detail-refactor-api-changes.md

# 资产详情重构 API 变更说明

> 适用版本：asset-detail-refactor 提案上线后
> 文档更新：2026-03-14

---

## 一、现有接口字段变更

### 1. `device_no` 重命名为 `virtual_no`

所有涉及设备标识符的接口，响应中的 `device_no` 字段已统一改名为 `virtual_no`，**JSON key 同步变更**，前端需全局替换。

受影响接口：

| 接口 | 变更字段 |
|------|---------|
| `GET /api/admin/devices`（列表/详情响应） | `device_no` → `virtual_no` |
| `GET /api/admin/devices/import/tasks/:id` | `failed_items[].device_no` → `virtual_no` |
| `GET /api/admin/enterprises/:id/devices`（企业设备列表） | `device_no` → `virtual_no` |
| `GET /api/admin/shop-commission/records` | `device_no` → `virtual_no` |
| `GET /api/admin/my-commission/records` | `device_no` → `virtual_no` |
| 企业卡授权相关响应中的设备字段 | `device_no` → `virtual_no` |

---

### 2. 套餐接口新增 `virtual_ratio` 字段

`GET /api/admin/packages` 及套餐详情响应新增：

| 新增字段 | 类型 | 说明 |
|---------|------|------|
| `virtual_ratio` | float64 | 虚流量比例（real_data_mb / virtual_data_mb）。启用虚流量时计算，否则为 1.0 |

---

### 3. IoT 卡接口新增 `virtual_no` 字段

卡列表/详情响应新增：

| 新增字段 | 类型 | 说明 |
|---------|------|------|
| `virtual_no` | string | 虚拟号（可空） |

---

## 二、新增接口

### 基础说明

- 路径参数 `asset_type` 取值：`card`（卡）或 `device`（设备）
- 企业账号调用 `resolve` 接口会返回 403

---

### `GET /api/admin/assets/resolve/:identifier`

通过任意标识符查询设备或卡的完整详情。支持虚拟号、ICCID、IMEI、SN、MSISDN。

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `asset_type` | string | `card` 或 `device` |
| `asset_id` | uint | 数据库 ID |
| `virtual_no` | string | 虚拟号 |
| `status` | int | 资产状态 |
| `batch_no` | string | 批次号 |
| `shop_id` | uint | 所属店铺 ID |
| `shop_name` | string | 所属店铺名称 |
| `series_id` | uint | 套餐系列 ID |
| `series_name` | string | 套餐系列名称 |
| `real_name_status` | int | 实名状态：0 未实名 / 1 实名中 / 2 已实名 |
| `network_status` | int | 网络状态：0 停机 / 1 开机（仅 card） |
| `current_package` | string | 当前套餐名称（无则空） |
| `package_total_mb` | int64 | 当前套餐总虚流量 MB |
| `package_used_mb` | float64 | 已用虚流量 MB |
| `package_remain_mb` | float64 | 剩余虚流量 MB |
| `device_protect_status` | string | 保护期状态：`none` / `stop` / `start`（仅 device） |
| `activated_at` | time | 激活时间 |
| `created_at` | time | 创建时间 |
| `updated_at` | time | 更新时间 |
| **绑定关系（card 时）** | | |
| `iccid` | string | 卡 ICCID |
| `bound_device_id` | uint | 绑定设备 ID |
| `bound_device_no` | string | 绑定设备虚拟号 |
| `bound_device_name` | string | 绑定设备名称 |
| **绑定关系（device 时）** | | |
| `bound_card_count` | int | 绑定卡数量 |
| `cards[]` | array | 绑定卡列表，每项含：`card_id` / `iccid` / `msisdn` / `network_status` / `real_name_status` / `slot_position` |
| **设备专属字段（card 时为空）** | | |
| `device_name` | string | 设备名称 |
| `imei` | string | IMEI |
| `sn` | string | 序列号 |
| `device_model` | string | 设备型号 |
| `device_type` | string | 设备类型 |
| `max_sim_slots` | int | 最大插槽数 |
| `manufacturer` | string | 制造商 |
| **卡专属字段（device 时为空）** | | |
| `carrier_type` | string | 运营商类型 |
| `carrier_name` | string | 运营商名称 |
| `msisdn` | string | 手机号 |
| `imsi` | string | IMSI |
| `card_category` | string | 卡业务类型 |
| `supplier` | string | 供应商 |
| `activation_status` | int | 激活状态 |
| `enable_polling` | bool | 是否参与轮询 |

---

### `GET /api/admin/assets/:asset_type/:id/realtime-status`

读取资产实时状态（直接读 DB/Redis，不调网关）。

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `asset_type` | string | `card` 或 `device` |
| `asset_id` | uint | 资产 ID |
| `network_status` | int | 网络状态（仅 card） |
| `real_name_status` | int | 实名状态（仅 card） |
| `current_month_usage_mb` | float64 | 本月已用流量 MB（仅 card） |
| `last_sync_time` | time | 最后同步时间（仅 card） |
| `device_protect_status` | string | 保护期：`none` / `stop` / `start`（仅 device） |
| `cards[]` | array | 所有绑定卡的状态（仅 device），同 resolve 的 cards 结构 |

---

### `POST /api/admin/assets/:asset_type/:id/refresh`

主动调网关拉取最新数据后返回，响应结构与 `realtime-status` 完全相同。

> 设备有 **30 秒冷却期**，冷却中调用返回 429。

---

### `GET /api/admin/assets/:asset_type/:id/packages`

查询该资产所有套餐记录，含虚流量换算字段。

**响应为数组，每项字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `package_usage_id` | uint | 套餐使用记录 ID |
| `package_id` | uint | 套餐 ID |
| `package_name` | string | 套餐名称 |
| `package_type` | string | `formal`（正式套餐）/ `addon`（加油包） |
| `status` | int | 0 待生效 / 1 生效中 / 2 已用完 / 3 已过期 / 4 已失效 |
| `status_name` | string | 状态中文名 |
| `data_limit_mb` | int64 | 真流量总量 MB |
| `virtual_limit_mb` | int64 | 虚流量总量 MB（已按 virtual_ratio 换算） |
| `data_usage_mb` | int64 | 已用真流量 MB |
| `virtual_used_mb` | float64 | 已用虚流量 MB |
| `virtual_remain_mb` | float64 | 剩余虚流量 MB |
| `virtual_ratio` | float64 | 虚流量比例 |
| `activated_at` | time | 激活时间 |
| `expires_at` | time | 到期时间 |
| `master_usage_id` | uint | 主套餐 ID（加油包时有值） |
| `priority` | int | 优先级 |
| `created_at` | time | 创建时间 |

---

### `GET /api/admin/assets/:asset_type/:id/current-package`

查询当前生效中的主套餐，响应结构同 `packages` 数组的单项。无生效套餐时返回 404。

---

### `POST /api/admin/assets/device/:device_id/stop`

批量停机设备下所有已实名卡，停机成功后设置 **1 小时停机保护期**（保护期内禁止复机）。

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `message` | string | 操作结果描述 |
| `success_count` | int | 成功停机的卡数量 |
| `failed_cards[]` | array | 停机失败列表，每项含 `iccid` 和 `reason` |

---

### `POST /api/admin/assets/device/:device_id/start`

批量复机设备下所有已实名卡，复机成功后设置 **1 小时复机保护期**（保护期内禁止停机）。

无响应 body，HTTP 200 即成功。

---

### `POST /api/admin/assets/card/:iccid/stop`

手动停机单张卡（通过 ICCID）。若卡绑定的设备在**复机保护期**内，返回 403。

无响应 body，HTTP 200 即成功。

---

### `POST /api/admin/assets/card/:iccid/start`

手动复机单张卡（通过 ICCID）。若卡绑定的设备在**停机保护期**内，返回 403。

无响应 body，HTTP 200 即成功。

---

## 三、删除的接口

### IoT 卡

| 删除的接口 | 替代接口 |
|-----------|---------|
| `GET /api/admin/iot-cards/by-iccid/:iccid` | `GET /api/admin/assets/resolve/:iccid` |
| `GET /api/admin/iot-cards/:iccid/gateway-status` | `GET /api/admin/assets/card/:id/realtime-status` |
| `GET /api/admin/iot-cards/:iccid/gateway-flow` | `GET /api/admin/assets/card/:id/realtime-status` |
| `GET /api/admin/iot-cards/:iccid/gateway-realname` | `GET /api/admin/assets/card/:id/realtime-status` |
| `POST /api/admin/iot-cards/:iccid/stop` | `POST /api/admin/assets/card/:iccid/stop` |
| `POST /api/admin/iot-cards/:iccid/start` | `POST /api/admin/assets/card/:iccid/start` |

### 设备

| 删除的接口 | 替代接口 |
|-----------|---------|
| `GET /api/admin/devices/:id` | `GET /api/admin/assets/resolve/:virtual_no` |
| `GET /api/admin/devices/by-identifier/:identifier` | `GET /api/admin/assets/resolve/:identifier` |
| `GET /api/admin/devices/by-identifier/:identifier/gateway-info` | `GET /api/admin/assets/device/:id/realtime-status` |

### 企业卡（Admin）

| 删除的接口 | 替代接口 |
|-----------|---------|
| `POST /api/admin/enterprises/:id/cards/:card_id/suspend` | `POST /api/admin/assets/card/:iccid/stop` |
| `POST /api/admin/enterprises/:id/cards/:card_id/resume` | `POST /api/admin/assets/card/:iccid/start` |

### 企业设备（H5）

| 删除的接口 | 替代接口 |
|-----------|---------|
| `POST /api/h5/enterprise/devices/:device_id/suspend-card` | `POST /api/admin/assets/device/:device_id/stop` |
| `POST /api/h5/enterprise/devices/:device_id/resume-card` | `POST /api/admin/assets/device/:device_id/start` |

---

## 四、新增错误码说明

| HTTP 状态码 | 触发场景 |
|------------|---------|
| 403 | 设备在保护期内（停机 1h 内禁止复机，反之亦然）；企业账号调用 resolve 接口 |
| 404 | 标识符未匹配到任何资产；当前无生效套餐 |
| 429 | 设备刷新冷却中（30 秒内只能主动刷新一次） |