junhong_cmp_fiber/openspec/specs/asset-resolve/spec.md

asset-resolve Specification

Purpose

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

Requirements

Requirement: 统一资产解析入口

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

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

查找顺序（更新后）:

1. 主路径：查 tb_asset_identifier WHERE identifier = ? → 命中则得到 asset_type + asset_id，直接查对应表取完整记录
2. Fallback 路径（注册表未命中时）：
   • 先查 tb_device（匹配 virtual_no = ? OR imei = ? OR sn = ?）
   • 未命中则查 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
• identifier: 本次查询所用的标识符（原样回传）
• virtual_no: 虚拟号（设备/卡均使用此字段）
• status: 资产状态（整型）
• asset_status: 业务状态（1-在库 2-已销售 3-已换货 4-已停用）
• generation: 资产世代编号
• batch_no: 批次号
• shop_id: 所属店铺 ID（平台库存时为空）
• shop_name: 所属店铺名称
• series_id: 套餐系列 ID（未绑定时为空）
• series_name: 套餐系列名称
• first_commission_paid: 一次性佣金是否已发放
• accumulated_recharge: 累计充值金额（分）
• activated_at: 激活时间（未激活时为空）
• created_at: 创建时间
• updated_at: 更新时间
• real_name_at（*time.Time，可为 null）：最近一次完成实名的时间
  • card 类型：直接取 IotCard.first_realname_at（未实名过则为 null）
  • device 类型：当前所有绑定卡 first_realname_at 中的最小值（无已实名卡则为 null）

状态与套餐字段（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 同步时间
• real_name_at（*time.Time，可为 null）：该卡最近一次完成实名的时间，取 IotCard.first_realname_at

流量展示计算规则:

• 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

Scenario: 通过注册表主路径精确解析

• WHEN 管理员输入 identifier 为已存在于 tb_asset_identifier 的 VirtualNo 或 ICCID
• THEN 系统单次查询注册表命中，直接查对应表返回完整资产信息，响应时间 < 50ms

Scenario: Fallback 路径解析 IMEI

• WHEN 管理员输入 identifier 为设备 IMEI（不在注册表中）
• THEN 注册表未命中，系统 fallback 查 tb_device 的 imei 字段，找到后返回资产信息
• THEN 响应中 identifier 字段原样回传该 IMEI 值

Scenario: Fallback 路径解析 MSISDN

• WHEN 管理员输入 identifier 为 IoT 卡的手机号（MSISDN）
• THEN 注册表未命中，fallback 查 tb_iot_card 的 msisdn 字段
• THEN 若存在多张卡的 MSISDN 相同，返回第一条匹配记录（MSISDN 非唯一，存在歧义，记录 warn 日志）

Scenario: 已实名的卡查询实名时间

• WHEN 通过标识符解析一张 real_name_status = 1 的卡
• THEN 响应中 real_name_at 返回该卡最近一次 0→1 变化时的时间戳

Scenario: 未实名的卡查询实名时间

• WHEN 通过标识符解析一张 real_name_status = 0 的卡
• THEN 响应中 real_name_at 返回 null

Scenario: 设备视角查询实名时间（部分卡已实名）

• WHEN 通过标识符解析一台设备，其中绑定了多张卡，部分卡已实名
• THEN 响应中 real_name_at 返回所有已实名绑定卡中 first_realname_at 最小的时间戳

Scenario: 设备视角查询实名时间（无已实名卡）

• WHEN 通过标识符解析一台设备，其所有绑定卡均未实名
• THEN 响应中 real_name_at 返回 null

Scenario: 设备绑定卡列表实名时间

• WHEN 通过标识符解析一台设备，绑定卡列表非空
• THEN cards 数组中每个 DeviceCardInfo 的 real_name_at 返回各卡自己的 first_realname_at（未实名则为 null）

---

Requirement: 手动刷新路径同步写入实名时间

系统 SHALL 在手动刷新路径（RefreshCardDataFromGateway）检测到实名状态由非已实名变为已实名（0→1）时，同步写入 first_realname_at，与轮询路径行为一致。

Scenario: 手动刷新触发实名状态变更

• WHEN 调用手动刷新接口，网关返回实名状态为已实名，且卡当前状态为未实名
• THEN tb_iot_card.first_realname_at 被更新为当前时间戳

Scenario: 手动刷新时实名状态无变化

• WHEN 调用手动刷新接口，网关返回实名状态与卡当前状态相同
• THEN tb_iot_card.first_realname_at 不被修改