# asset-resolve Specification

## Purpose

提供统一的资产解析入口，通过任意标识符（虚拟号/ICCID/IMEI/SN/MSISDN）定位卡或设备，并返回该资产的中等聚合信息，包含套餐流量、保护期状态和绑定关系。

## Requirements

### Requirement: 统一资产解析入口

系统 SHALL 提供统一的资产查找接口，通过任意标识符定位卡或设备，并返回该资产的中等聚合信息。

**API 端点**: `GET /api/admin/assets/resolve/:identifier`

**查找顺序**:
1. 先在 `tb_device` 表查找（匹配 `virtual_no = ? OR imei = ? OR sn = ?`）
2. 未命中则在 `tb_iot_card` 表查找（匹配 `virtual_no = ? OR iccid = ? OR msisdn = ?`）
3. 两表均未命中 → 返回 HTTP 404
4. 找到后应用数据权限过滤，无权限 → 返回 HTTP 403

**数据权限规则**:
- 代理用户：只能查看 `shop_id` 在自己及下级店铺范围内的资产
- 平台用户（SuperAdmin/Platform）：可查看所有资产
- 企业账号：暂不支持此接口，调用时返回 HTTP 403

**响应结构（AssetResolveResponse）**:

*通用字段（device 和 card 均有）*:
- `asset_type`: 资产类型（`"device"` 或 `"card"`）
- `asset_id`: 资产主键 ID
- `virtual_no`: 虚拟号（设备/卡均使用此字段）
- `status`: 资产状态（整型）
- `batch_no`: 批次号
- `shop_id`: 所属店铺 ID（平台库存时为空）
- `shop_name`: 所属店铺名称
- `series_id`: 套餐系列 ID（未绑定时为空）
- `series_name`: 套餐系列名称
- `first_commission_paid`: 一次性佣金是否已发放
- `accumulated_recharge`: 累计充值金额（分）
- `activated_at`: 激活时间（未激活时为空）
- `created_at`: 创建时间
- `updated_at`: 更新时间

*状态与套餐字段（device 和 card 均有）*:
- `real_name_status`: 实名状态（整型）
- `current_package`: 当前套餐名称（无套餐时返回空字符串）
- `package_total_mb`: 真总流量，即 RealDataMB（无套餐时返回 0）
- `package_virtual_mb`: 虚总流量/停机阈值，即 VirtualDataMB（无套餐时返回 0）
- `package_used_mb`: 客户端展示已使用流量（经虚流量换算，见流量计算规则）
- `package_remain_mb`: 客户端展示剩余流量
- `device_protect_status`: 保护期状态（`"none"` / `"stop"` / `"start"`）；card 类型时若绑定的设备有保护期也返回该设备的保护期状态

*绑定关系字段*:
- `iccid`: 仅 card 类型时有值，供前端调用停复机接口使用
- `bound_device_id`: 仅 card 类型且卡绑定了设备时有值
- `bound_device_no`: 绑定设备的虚拟号
- `bound_device_name`: 绑定设备的名称
- `bound_card_count`: 仅 device 类型时有值，绑定卡的总数量
- `cards`: 仅 device 类型时有值，所有绑定卡列表（含未实名、已停用）

*设备专属档案字段（asset_type=device 时有值，card 类型时为空/零值）*:
- `device_name`: 设备名称
- `imei`: IMEI
- `sn`: 序列号
- `device_model`: 设备型号
- `device_type`: 设备类型
- `max_sim_slots`: 最大插槽数
- `manufacturer`: 制造商

*卡专属档案字段（asset_type=card 时有值，device 类型时为空/零值）*:
- `carrier_id`: 运营商 ID
- `carrier_type`: 运营商类型（CMCC/CUCC/CTCC/CBN）
- `carrier_name`: 运营商名称
- `msisdn`: 卡接入号
- `imsi`: IMSI
- `card_category`: 卡业务类型（normal/industry）
- `supplier`: 供应商
- `activation_status`: 激活状态（0-未激活 1-已激活）
- `enable_polling`: 是否参与轮询

**DeviceCardInfo 结构**:
- `iot_card_id`: 卡 ID
- `iccid`: ICCID
- `virtual_no`: 卡的虚拟号
- `real_name_status`: 实名状态
- `network_status`: 网络状态
- `current_month_usage_mb`: 本月已用流量（来自持久化缓存字段）
- `last_sync_at`: 最后与 Gateway 同步时间

**流量展示计算规则**:
- `package_used_mb = current_month_usage_mb × virtual_ratio`
- `package_remain_mb = package_total_mb - package_used_mb`
- 当 `enable_virtual_data = false` 时，`virtual_ratio = 1.0`（无换算）
- 设备级套餐：`current_month_usage_mb` 为所有绑定卡本月用量之和

**特殊情况处理**:
- 卡绑定的设备已被软删除：视为独立卡，不填充绑定信息
- `cards` 列表包含所有状态的绑定卡，不过滤未实名或已停用的卡

#### Scenario: 通过 ICCID 找到卡

- **WHEN** 管理员调用 `GET /api/admin/assets/resolve/89860123456789012345`，ICCID 匹配到一张独立卡
- **THEN** 系统返回 `asset_type="card"`，包含该卡的虚拟号、状态、套餐流量信息，`bound_device_id` 为空

#### Scenario: 通过虚拟号找到设备

- **WHEN** 管理员调用 `GET /api/admin/assets/resolve/GPS-001`，设备表中 `virtual_no = "GPS-001"` 存在
- **THEN** 系统返回 `asset_type="device"`，包含该设备的绑定卡列表（DeviceCardInfo 数组），`bound_card_count` 为绑定卡总数

#### Scenario: 标识符同时命中设备和卡（设备优先）

- **WHEN** `GPS-001` 在 device 表和 iot_card 表均有匹配（virtual_no 相同）
- **THEN** 系统返回设备信息（device 优先），不返回卡信息

#### Scenario: 标识符未命中任何资产

- **WHEN** 管理员查询不存在的标识符 `UNKNOWN-999`
- **THEN** 系统返回 HTTP 404

#### Scenario: 代理用户查询无权限的资产

- **WHEN** 代理用户（shop_id=10）查询属于 shop_id=99（非下级）的设备
- **THEN** 系统返回 HTTP 403，明确提示无权限

#### Scenario: 企业账号调用 resolve

- **WHEN** 企业账号调用 `GET /api/admin/assets/resolve/:identifier`
- **THEN** 系统返回 HTTP 403，提示企业账号暂不支持此接口

#### Scenario: 卡绑定了有停机保护期的设备

- **WHEN** 管理员通过 ICCID 查询某张卡，该卡绑定的设备当前有 stop 保护期
- **THEN** 响应中 `device_protect_status = "stop"`，反映所属设备的保护期状态

#### Scenario: 设备无当前生效套餐

- **WHEN** 管理员查询一台没有购买任何套餐的设备
- **THEN** `current_package = ""`，`package_total_mb = 0`，`package_used_mb = 0`，`package_remain_mb = 0`