feat: 新增数据库迁移，重命名 device_no 为 virtual_no，新增 iot_card.virtual_no 和 package.virtual_ratio 字段

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

docs/discussion/资产详情重构讨论纪要.md

@@ -0,0 +1,821 @@
+# 君鸿卡管系统资产详情体系重构 - 讨论纪要
+
+> 创建时间：2026-03-12
+> 最后更新：2026-03-14
+> 当前阶段：设计讨论（尚未进入 openspec 提案）
+> 目的：保留完整上下文，供未来继续
+
+---
+
+## 一、背景与需求来源
+
+### 1.1 项目背景
+
+君鸿卡管系统（junhong_cmp_fiber）是一个面向代理/企业的物联网卡管理平台，核心资产有两类：
+- **IoT 卡（IotCard）**：纯卡资源，含 ICCID、MSISDN、流量套餐
+- **设备（Device）**：带卡的硬件设备，一个设备可绑定多张卡，设备级套餐
+
+### 1.2 需求触发点
+
+核心痛点：
+1. **接口分散且重复** - 卡和设备的查询散落在多处，H5/Admin/Personal 三端各有一套
+2. **详情信息严重缺失** - 现有的详情接口返回数据太少，前端无法据此渲染完整页面
+3. **网关裸数据透传** - 封装程度不够，没有业务层的聚合和处理
+4. **虚拟号只存在于设备** - 卡的查询只能靠 ICCID/MSISDN，不方便
+
+### 1.3 已确认的核心决策
+
+- ✅ **多接口组合** - 不做单一聚合大接口，前端按需调用
+- ✅ **统一入口** - 一个接口告诉前端查的是"卡"还是"设备"
+- ✅ **设备优先查找** - 统一入口先查设备表，再查卡表
+- ✅ **卡加虚拟号** - 虚拟号概念延伸到卡，与设备的 virtual_no 对等
+- ✅ **全部一步到位** - 改造不分期，一次性完成
+- ✅ **resolve 返回中等版本** - 包含资产类型、ID、虚拟号、状态、实名状态、套餐概况、流量使用、所属设备（如果绑定）等关键信息
+- ✅ **资产类型只有卡和设备两种** - 未来路由器也归属设备，无需预留更多类型
+- ✅ **虚拟号客服和客户都要用** - 不是只有内部人员用
+- ✅ **H5 端接口暂时不需要提供** - 后续做到时再删除旧接口
+- ✅ **套餐查询看历史记录** - 通过套餐记录/订单记录页面查看历史，同时提供当前套餐接口
+- ✅ **手动刷新接口复用 SyncCardStatusFromGateway** - 无需重新实现，设备时批量刷新所有绑定卡
+- ✅ **权限不足返回 403** - 明确告知无权限，不假装资产不存在
+- ✅ **虚拟号人工填写/批量导入** - 无格式规范，允许修改，重复时全批失败并告知原因
+- ✅ **device_no 字段全量改名为 virtual_no** - 数据库+代码全部更新，不保留旧字段
+- ✅ **设备停复机有保护期机制** - 保护状态一致性，时长 1 小时，存储在 Redis
+- ✅ **realtime-status 只查持久化数据** - 不调用网关，刷新用 refresh 接口
+- ✅ **未实名的卡不参与停复机** - 未实名卡永远是停机状态，保护期逻辑跳过
+- ✅ **企业账号 resolve 接口** - 企业账号暂不支持 resolve，未来单独开新接口
+- ✅ **resolve 响应含卡 ICCID** - card 类型时在响应中返回 ICCID，供前端调用停复机接口
+- ✅ **批量停机部分失败仍设保护期** - 部分卡停机失败时也设置 Redis 保护期，已停机的卡不回滚，失败的卡记录日志
+- ✅ **流量汇总逻辑统一** - 整个系统使用统一的流量汇总逻辑；设备级套餐从 PackageUsage 汇总多卡用量
+- ✅ **套餐历史列表规则** - 按创建时间倒序，不分页，包含所有状态（含已失效）
+- ✅ **current-package 返回主套餐** - 多套餐同时生效时只返回主套餐（master_usage_id IS NULL）
+- ✅ **轮询系统新增第四种任务** - 保护期一致性检查封装为独立轮询任务类型，不修改现有三种任务
+- ✅ **卡虚拟号导入只补空白** - 只允许为现有空白虚拟号的卡填入，不支持覆盖更新；与数据库现存数据重复则全批失败
+- ✅ **设备批量刷新需限频** - Redis 限频保护，同一设备冷却期内（建议 30 秒）不允许重复触发
+- ✅ **PersonalCustomerDevice 统一改名** - tb_personal_customer_device 表的 device_no 字段一并改为 virtual_no
+- ✅ **realtime-status 与 resolve 分工明确** - resolve 用于初始加载（含查找），realtime-status 用于已知 ID 的轻量状态轮询（不含套餐流量计算）
+
+---
+
+## 二、现有系统审计结果
+
+### 2.1 接口现状（三端盘点）
+
+| 端 | 卡接口数 | 设备接口数 | 重复停复机 | 套餐接口 |
+|---|---------|-----------|-----------|---------|
+| Admin | 9 | 14 | 3处 | 仅流量详单 |
+| H5 | 4 | 7 | 1处 | 有套餐聚合 |
+| Personal | 2 | 0 | 无 | 无 |
+
+**重复停复机的三处实现：**
+1. Admin 卡端：`POST /iot-cards/:iccid/suspend|resume`（按 ICCID）
+2. Admin 企业卡端：`POST /enterprises/:id/cards/:card_id/suspend|resume`（按 card_id）
+3. H5 企业设备端：`POST /h5/devices/:device_id/cards/:card_id/suspend|resume`（按 card_id）
+
+### 2.2 DTO 缺失分析
+
+#### 卡详情（IotCardDetailResponse）
+
+```go
+// 当前实现 (iot_card_dto.go:134-136)
+type IotCardDetailResponse struct {
+    Code int                      `json:"code"`
+    Msg  string                   `json:"msg"`
+    Data *StandaloneIotCardResponse `json:"data"` // 只是空壳嵌套！
+}
+```
+
+**问题**：详情响应只是列表响应的空包装，完全没有额外信息。无套餐、无所属设备、无聚合流量。
+
+#### 设备详情（DeviceResponse）
+
+```go
+// 当前实现 (device_dto.go:20)
+type DeviceResponse struct {
+    // ... 基本字段
+    BoundCardCount int `json:"bound_card_count"` // 只有一个数字！
+}
+```
+
+**问题**：只返回绑定卡数量，看不到每张卡的实名状态、卡状态、流量使用。
+
+#### H5 端已有参考实现
+
+`EnterpriseDeviceDetailResp`（enterprise_device_authorization_dto.go）是目前唯一有"设备+绑定卡列表"聚合的 DTO，可作为 admin 端改造的参考。
+
+### 2.3 网关接口问题
+
+**6 个网关查询接口全部是纯透传**：
+- `gateway.GetCardStatus`
+- `gateway.GetFlowUsage`
+- `gateway.GetRealNameStatus`
+- `gateway.GetDeviceInfo`
+- `gateway.GetSlotInfo`
+- `gateway.GetDeviceFlowUsage`
+
+**问题**：只读不写，不更新 DB 缓存，无业务封装。
+
+### 2.4 数据模型现状
+
+| 模型 | 虚拟号 | 缓存字段 | 套餐载体 |
+|-----|-------|---------|---------|
+| IotCard | ❌ 无（需新增） | CurrentMonthUsageMB, NetworkStatus, RealNameStatus, LastDataCheckAt | IotCardID |
+| Device | ✅ device_no（需改名为 virtual_no） | 无 | DeviceID |
+
+**关键发现**：
+- `PackageUsage` 模型已支持两种载体：`IotCardID`（单卡）和 `DeviceID`（设备级）
+- `IotCard.IsStandalone` 字段由触发器维护，标识卡是否绑定到设备
+- `DeviceStore.GetByIdentifier` 已实现多字段匹配：`WHERE device_no = ? OR imei = ? OR sn = ?`（改造后改为 virtual_no）
+
+---
+
+## 三、设计方向（已确认）
+
+### 3.1 统一资产入口（resolve）
+
+**接口**：`GET /api/admin/assets/resolve/:identifier`
+
+**查找逻辑**：
+```
+1. 先查 device 表（virtual_no / imei / sn）
+2. 未命中则查 iot_card 表（virtual_no / iccid / msisdn）
+3. 应用数据权限过滤：代理只能看自己及下级店铺的资产，平台账号看所有
+4. 有权限 → 返回资产数据（中等版本）
+5. 无权限 → 返回 HTTP 403
+6. 未找到 → 返回 HTTP 404
+```
+
+**响应结构（已确认）**：
+
+```go
+// AssetResolveResponse 资产解析响应
+type AssetResolveResponse struct {
+    // 基础信息
+    AssetType string `json:"asset_type"`  // "device" 或 "card"
+    AssetID   uint   `json:"asset_id"`    // 对应表的主键
+    VirtualNo string `json:"virtual_no"`  // 统一虚拟号字段（设备/卡均用此字段）
+    ICCID     string `json:"iccid,omitempty"` // 仅 card 类型时有值，供前端调用停复机接口使用
+
+    // 状态信息
+    Status         int `json:"status"`           // 资产状态
+    RealNameStatus int `json:"real_name_status"`  // 实名状态
+
+    // 套餐和流量信息（无套餐时返回空字符串/0）
+    CurrentPackage   string  `json:"current_package"`    // 当前套餐名称
+    PackageTotalMB   float64 `json:"package_total_mb"`   // 真总流量（套餐标称，RealDataMB）
+    PackageVirtualMB float64 `json:"package_virtual_mb"` // 虚总流量（停机阈值，VirtualDataMB）
+    PackageUsedMB    float64 `json:"package_used_mb"`    // 客户端展示已使用流量（经虚流量换算）
+    PackageRemainMB  float64 `json:"package_remain_mb"`  // 客户端展示剩余流量
+
+    // 保护期状态（设备类型，以及绑定该设备的卡均返回）
+    DeviceProtectStatus string `json:"device_protect_status"` // "none" / "stop" / "start"
+
+    // 绑定信息（仅 card 类型，且卡绑定了设备时才有值）
+    BoundDeviceID   *uint  `json:"bound_device_id,omitempty"`
+    BoundDeviceNo   string `json:"bound_device_no,omitempty"`
+    BoundDeviceName string `json:"bound_device_name,omitempty"`
+
+    // 设备类型特有：绑定卡信息
+    BoundCardCount int              `json:"bound_card_count"`
+    Cards          []DeviceCardInfo `json:"cards,omitempty"` // 包含所有状态的卡（含未实名）
+}
+
+// DeviceCardInfo 设备下绑定卡信息
+type DeviceCardInfo struct {
+    IotCardID           uint       `json:"iot_card_id"`
+    ICCID               string     `json:"iccid"`
+    VirtualNo           string     `json:"virtual_no"`
+    RealNameStatus      int        `json:"real_name_status"`
+    NetworkStatus       int        `json:"network_status"`
+    CurrentMonthUsageMB float64    `json:"current_month_usage_mb"`
+    LastSyncAt          *time.Time `json:"last_sync_at"` // 最后与 Gateway 同步时间
+}
+```
+
+**说明**：
+- 卡绑定的设备被软删除时，该卡视为独立卡，不填充绑定信息
+- 设备下的 `cards` 列表包含所有绑定卡（含未实名、已停用）
+
+### 3.2 套餐查询接口
+
+**接口一**：`GET /api/admin/assets/:asset_type/:id/packages`
+- 返回所有套餐记录（含历史和当前生效套餐）
+- 按 asset_type 区分查 PackageUsage.IotCardID 还是 PackageUsage.DeviceID
+- 每条记录包含：套餐名称、真总流量、虚总流量、展示已使用、展示剩余、有效期、状态
+- **排序**：按创建时间倒序（最新套餐在前）
+- **分页**：不分页，全量返回
+- **范围**：包含所有状态（含 status=4 已失效的历史套餐）
+
+**接口二**：`GET /api/admin/assets/:asset_type/:id/current-package`
+- 返回当前生效的**主套餐**（status=1 且 master_usage_id IS NULL）的详细信息
+- 当同时有主套餐 + 加油包生效时，只返回主套餐；需要查看加油包通过接口一的列表查看
+- 包含完整流量明细：真总量、虚总量、展示已使用、展示剩余
+
+### 3.3 实时状态查询接口
+
+**接口**：`GET /api/admin/assets/:asset_type/:id/realtime-status`
+
+**与 resolve 的定位分工**：
+
+> **resolve**：初始加载使用，包含查找逻辑 + 全量聚合数据（套餐/流量/绑定信息），数据较重。
+> **realtime-status**：已知资产 ID 后的轻量状态轮询，**不含套餐流量计算**，专注于网络/实名/保护期状态的快速刷新。
+
+**说明**：
+- **只查询持久化数据（DB/Redis），不调用网关**
+- 返回最近一次轮询/刷新同步到系统的状态
+- "实时性"依赖轮询系统保持数据新鲜（实名 5 分钟，流量/套餐 10 分钟）
+- 需要最新数据时，先调用 refresh 接口手动刷新，再查此接口
+- 设备类型返回：保护期状态 + 每张绑定卡的状态（网络/实名/流量/最后同步时间）
+- 卡类型返回：网络状态 + 实名状态 + 流量使用 + 最后同步时间
+
+### 3.4 手动刷新接口
+
+**接口**：`POST /api/admin/assets/:asset_type/:id/refresh`
+
+**说明**：
+- 调用网关获取最新数据，写回 DB 更新缓存字段，返回刷新后的最新状态
+- 卡类型：调用已有的 `SyncCardStatusFromGateway(iccid)` 方法
+- 设备类型：批量刷新所有绑定卡（遍历调用 `SyncCardStatusFromGateway`）
+- **设备类型需要频率限制**：通过 Redis 记录最后刷新时间，同一设备冷却期内（建议 30 秒）不允许重复触发，防止前端多次快速点击打爆网关
+
+### 3.5 设备停复机保护期机制
+
+**背景**：
+设备本身没有停机/复机概念，对设备停机 = 批量停用其下所有已实名卡。保护期机制确保操作期间所有卡的状态一致性，防止单卡被误操作破坏整体状态。
+
+**接口**：
+- `POST /api/admin/assets/device/:device_id/stop`
+- `POST /api/admin/assets/device/:device_id/start`
+
+**保护期规则**：
+
+| 规则 | 说明 |
+|------|------|
+| 保护期时长 | **1 小时**（硬编码在代码常量中） |
+| 存储方式 | Redis Key `protect:device:{device_id}:stop` 或 `protect:device:{device_id}:start`，TTL=1小时 |
+| 未实名的卡 | **不参与停复机操作**，未实名卡永远是停机状态，跳过不处理 |
+| 重叠操作 | 设备在保护期内不允许再次发起相同或相反的停复机操作，返回 HTTP 403 |
+| 批量停机部分失败 | 部分卡调网关失败时，**仍设置 Redis 保护期**；已成功停机的卡不回滚；失败的卡记录错误日志 |
+
+**stop 保护期（设备停机后 1 小时内）**：
+- 对某张已实名卡手动发起复机 → **不允许**（HTTP 403，设备处于停机保护期）
+- 对某张已实名卡手动发起停机 → 允许（本已是停机，无冲突）
+- 轮询系统发现某张已实名卡处于开机状态 → **强制调网关停机**，保持一致
+
+**start 保护期（设备复机后 1 小时内）**：
+- 对某张已实名卡手动发起停机 → **允许**（用户可主动停单张卡）
+- 对某张已实名卡手动发起复机 → 允许（本已是复机，无冲突）
+- 轮询系统发现某张已实名卡处于停机状态 → **强制调网关复机**，保持一致
+
+**保护期状态对外暴露**：
+- resolve 接口的 `device_protect_status` 字段返回当前保护期状态
+- 卡绑定的设备有保护期时，该卡的 resolve 结果也返回 `device_protect_status`
+
+### 3.6 接口去重（废弃清单）
+
+**废弃接口**（直接删除，不保留向后兼容）：
+
+| 废弃接口 | 替代接口 |
+|---------|---------|
+| `POST /enterprises/:id/cards/:card_id/suspend` | `POST /api/admin/assets/card/:iccid/stop` |
+| `POST /enterprises/:id/cards/:card_id/resume` | `POST /api/admin/assets/card/:iccid/start` |
+| `POST /h5/devices/:device_id/cards/:card_id/suspend` | `POST /api/admin/assets/device/:device_id/stop` |
+| `POST /h5/devices/:device_id/cards/:card_id/resume` | `POST /api/admin/assets/device/:device_id/start` |
+| 旧 Admin 卡停复机接口（按 ICCID） | `POST /api/admin/assets/card/:iccid/stop|start` |
+| `GET /devices/:id` | `GET /api/admin/assets/device/:id` |
+
+### 3.7 数据层变更
+
+**变更一：设备表字段改名（全量重构）**
+```sql
+ALTER TABLE tb_device RENAME COLUMN device_no TO virtual_no;
+ALTER TABLE tb_personal_customer_device RENAME COLUMN device_no TO virtual_no;
+```
+涉及改动范围：Model 定义、DTO 响应、Store 查询、所有引用 `device_no` 的代码，以及 `tb_personal_customer_device` 表的 `device_no` 字段（一并改名为 `virtual_no`），确保系统中不再有 `device_no` 的身影。
+
+**变更二：卡表新增 virtual_no 字段**
+```sql
+ALTER TABLE tb_iot_card ADD COLUMN virtual_no VARCHAR(50);
+CREATE UNIQUE INDEX idx_iot_card_virtual_no
+    ON tb_iot_card (virtual_no) WHERE deleted_at IS NULL;
+```
+- 允许为空（老数据无虚拟号）
+- 允许手动修改
+- 全局唯一（导入时检测重复，重复则全批失败并告知具体冲突数据）
+
+**变更三：套餐表新增 virtual_ratio 字段**
+```sql
+ALTER TABLE tb_package ADD COLUMN virtual_ratio DECIMAL(10,6) DEFAULT 1.0;
+```
+- 创建套餐时计算并存储：`virtual_ratio = real_data_mb / virtual_data_mb`
+- 用于客户端展示的流量换算（见第六节）
+- 未启用虚流量时（`enable_virtual_data=false`），virtual_ratio = 1.0
+
+---
+
+## 四、完整接口清单
+
+| # | 方法 | 路径 | 说明 |
+|---|------|------|------|
+| 1 | GET | `/api/admin/assets/resolve/:identifier` | 资产解析（通过任意标识符） |
+| 1 | GET | `/api/admin/assets/resolve/:identifier` | 资产解析（通过任意标识符） |
+| 2 | GET | `/api/admin/assets/:asset_type/:id/packages` | 套餐记录（历史+当前） |
+| 3 | GET | `/api/admin/assets/:asset_type/:id/current-package` | 当前生效主套餐详情 |
+| 4 | GET | `/api/admin/assets/:asset_type/:id/realtime-status` | 当前持久化状态查询（轻量） |
+| 5 | POST | `/api/admin/assets/:asset_type/:id/refresh` | 手动刷新（调网关写回 DB） |
+| 6 | POST | `/api/admin/assets/device/:device_id/stop` | 设备停机（批量停所有已实名卡） |
+| 7 | POST | `/api/admin/assets/device/:device_id/start` | 设备复机（批量开所有已实名卡） |
+| 8 | POST | `/api/admin/assets/card/:iccid/stop` | 卡停机 |
+| 9 | POST | `/api/admin/assets/card/:iccid/start` | 卡复机 |
+
+> `:asset_type` 取值：`device` 或 `card`
+
+---
+
+## 五、流程图
+
+### 5.1 资产查找（resolve）流程
+
+```mermaid
+flowchart TD
+    A["GET /api/admin/assets/resolve/:identifier"] --> B{"查询设备表\nvirtual_no / imei / sn"}
+    B -->|找到| C{"应用数据权限过滤\n代理:仅自己及下级店铺\n平台:所有资产"}
+    B -->|未找到| D{"查询卡表\nvirtual_no / iccid / msisdn"}
+    D -->|找到| C
+    D -->|未找到| E["返回 HTTP 404\n资产不存在"]
+    C -->|有权限| F["聚合资产数据\n基础信息 + 状态 + 套餐流量 + 保护期 + 绑定信息"]
+    C -->|无权限| G["返回 HTTP 403\n无权限查看该资产"]
+    F --> H["返回 AssetResolveResponse"]
+```
+
+### 5.2 设备停机/复机流程
+
+```mermaid
+flowchart TD
+    subgraph 设备停机
+        A1["POST /assets/device/:id/stop"] --> B1{"设备是否存在?"}
+        B1 -->|否| C1["HTTP 404"]
+        B1 -->|是| D1{"设备是否在保护期?"}
+        D1 -->|是| E1["HTTP 403\n设备处于保护期，不允许操作"]
+        D1 -->|否| F1["获取所有已实名下属卡"]
+        F1 --> G1["批量调网关停机"]
+        G1 --> H1["更新各卡 NetworkStatus=停机\n（部分失败时已成功的卡不回滚）"]
+        H1 --> I1["Redis SET protect:device:id:stop\nTTL = 1 小时（部分失败时仍设置）"]
+        I1 --> J1["返回成功（附带失败卡日志）"]
+    end
+
+    subgraph 设备复机
+        A2["POST /assets/device/:id/start"] --> B2{"设备是否存在?"}
+        B2 -->|否| C2["HTTP 404"]
+        B2 -->|是| D2{"设备是否在保护期?"}
+        D2 -->|是| E2["HTTP 403\n设备处于保护期，不允许操作"]
+        D2 -->|否| F2["获取所有已实名下属卡"]
+        F2 --> G2["批量调网关复机"]
+        G2 --> H2["更新各卡 NetworkStatus=开机"]
+        H2 --> I2["Redis SET protect:device:id:start\nTTL = 1 小时"]
+        I2 --> J2["返回成功"]
+    end
+```
+
+### 5.3 手动操作单卡 + 保护期检查
+
+```mermaid
+flowchart TD
+    subgraph 手动停机单卡
+        A1["POST /assets/card/:iccid/stop"] --> B1{"卡是否存在?"}
+        B1 -->|否| C1["HTTP 404"]
+        B1 -->|是| D1{"卡是否已实名?"}
+        D1 -->|未实名| E1["HTTP 403\n未实名卡不允许停复机"]
+        D1 -->|已实名| F1{"卡是否绑定设备?"}
+        F1 -->|未绑定| G1["正常执行停机"]
+        F1 -->|已绑定| H1{"设备有 start 保护期?"}
+        H1 -->|是| I1["允许停机\n与 start 保护期方向一致"]
+        H1 -->|否| G1
+    end
+
+    subgraph 手动复机单卡
+        A2["POST /assets/card/:iccid/start"] --> B2{"卡是否存在?"}
+        B2 -->|否| C2["HTTP 404"]
+        B2 -->|是| D2{"卡是否已实名?"}
+        D2 -->|未实名| E2["HTTP 403\n未实名卡不允许停复机"]
+        D2 -->|已实名| F2{"卡是否绑定设备?"}
+        F2 -->|未绑定| G2["正常执行复机"]
+        F2 -->|已绑定| H2{"设备有 stop 保护期?"}
+        H2 -->|是| I2["HTTP 403\n设备处于停机保护期\n不允许手动复机"]
+        H2 -->|否| G2
+    end
+```
+
+### 5.4 轮询系统与保护期交互
+
+```mermaid
+flowchart TD
+    A["轮询任务触发：检查卡状态"] --> B{"卡是否已实名?"}
+    B -->|未实名| C["跳过，未实名卡不参与停复机逻辑"]
+    B -->|已实名| D{"卡是否绑定设备?"}
+    D -->|未绑定| E["按卡自身逻辑正常处理"]
+    D -->|已绑定| F{"设备是否有保护期?"}
+    F -->|无保护期| E
+    F -->|"stop 保护期"| G{"卡当前网络状态?"}
+    G -->|开机| H["强制调网关停机\n保持与设备保护期一致"]
+    G -->|停机| I["已一致，跳过"]
+    F -->|"start 保护期"| J{"卡当前网络状态?"}
+    J -->|停机| K["强制调网关复机\n保持与设备保护期一致"]
+    J -->|开机| L["已一致，跳过"]
+```
+
+### 5.5 手动刷新（refresh）流程
+
+```mermaid
+flowchart TD
+    A["POST /api/admin/assets/:type/:id/refresh"] --> B{"资产类型"}
+    B -->|card| C["调用 SyncCardStatusFromGateway(iccid)"]
+    C --> D["更新 iot_card 表\nNetworkStatus / RealNameStatus\nCurrentMonthUsageMB / LastSyncTime"]
+    D --> H["返回刷新后的最新状态"]
+    B -->|device| E["检查 Redis 限频（冷却期 30 秒）"]
+    E -->|冷却中| Z["HTTP 429 请勿频繁刷新"]
+    E -->|可刷新| F["查询所有绑定卡列表"]
+    F --> G["遍历每张卡\n调用 SyncCardStatusFromGateway"]
+    G --> H
+```
+
+### 5.6 实时状态查询（realtime-status）流程
+
+```mermaid
+flowchart TD
+    A["GET /api/admin/assets/:type/:id/realtime-status"] --> B{"资产类型"}
+    B -->|card| C["从 DB/Redis 读取持久化的卡状态"]
+    C --> D["返回卡状态\n网络状态 / 实名状态 / 本月已用流量\n最后同步时间"]
+    B -->|device| E["从 DB/Redis 读取持久化的设备数据"]
+    E --> F["读取所有绑定卡的持久化状态"]
+    F --> G["返回设备状态\n保护期状态 + 各绑定卡当前状态 + 最后同步时间"]
+```
+
+> **注意**：此接口**不调用网关**，展示的是最近一次轮询/刷新写入的持久化数据。
+> 如需获取最新数据，请先调用 `POST /refresh` 接口，再查询此接口。
+
+### 5.7 虚流量计算规则
+
+```mermaid
+flowchart TD
+    subgraph 创建["套餐创建时 - 存储比例"]
+        A1["RealDataMB = 10G 真总流量"] --> C1
+        A2["VirtualDataMB = 9G 虚总流量/停机阈值"] --> C1
+        C1["virtual_ratio = RealDataMB / VirtualDataMB\n= 10 / 9 ≈ 1.111\n存储到 tb_package.virtual_ratio"]
+    end
+
+    subgraph 停机["系统内部 - 停机判断"]
+        D1["真已使用\nCurrentMonthUsageMB"] --> E1{"真已使用 >= VirtualDataMB?"}
+        D2["VirtualDataMB = 9G"] --> E1
+        E1 -->|是| F1["触发停机"]
+        E1 -->|否| F2["正常运行"]
+    end
+
+    subgraph 展示["客户端展示 - 流量换算"]
+        G1["真已使用 = 9G"] --> H1
+        H1["展示已使用 = 真已使用 x virtual_ratio\n= 9G x 1.111 = 10G"]
+        G2["展示总量 = RealDataMB = 10G"]
+        H1 --> I1["客户看到 已用10G/共10G = 100% 已停机"]
+    end
+```
+
+---
+
+## 六、虚流量计算规则详解
+
+### 6.1 概念说明
+
+| 字段 | 含义 | 来源 |
+|------|------|------|
+| 真总流量（RealDataMB） | 套餐标称总流量，用户购买的名义流量 | `Package.real_data_mb` |
+| 虚总流量（VirtualDataMB） | 停机阈值，始终小于真总流量 | `Package.virtual_data_mb` |
+| virtual_ratio | 换算比例 = RealDataMB / VirtualDataMB | `Package.virtual_ratio`（套餐创建时存储） |
+| 真已使用 | 网关报告的实际用量 | `IotCard.current_month_usage_mb` |
+| 展示已使用 | 客户看到的用量 = 真已使用 × virtual_ratio | 计算得出 |
+| 展示剩余 | 客户看到的剩余 = 真总流量 − 展示已使用 | 计算得出 |
+
+### 6.2 设计意图
+
+虚总流量（VirtualDataMB）是系统内部的停机保护阈值。由于网关数据同步存在延迟，若以真总流量作为停机阈值，客户可能在用完 10G 后继续用到 10.5G 才被停机，产生超用。因此系统设置一个比真总流量略小的虚总流量（如 9G）作为实际停机阈值，保证不超用。
+
+客户端展示时，系统将真实用量按比例换算回真总流量的尺度，使客户的体感与购买的套餐一致：
+- 当真用量达到 9G（VirtualDataMB）时，卡被停机
+- 此时展示用量 = 9G × (10G/9G) = 10G，客户看到"已用 10G / 共 10G = 100%"
+
+### 6.3 计算示例
+
+| 场景 | 真总 | 虚总（停机阈值） | 真已使用 | 展示已使用 | 展示剩余 | 是否停机 |
+|------|------|----------------|---------|-----------|---------|---------|
+| 刚开始 | 10G | 9G | 0G | 0G | 10G | 否 |
+| 用了一半 | 10G | 9G | 4.5G | 5G | 5G | 否 |
+| 接近阈值 | 10G | 9G | 8G | ≈8.89G | ≈1.11G | 否 |
+| 触发停机 | 10G | 9G | 9G | 10G | 0G | **是** |
+
+### 6.4 未启用虚流量时
+
+当 `Package.enable_virtual_data = false` 时：
+- `virtual_ratio = 1.0`
+- 停机阈值 = 真总流量（RealDataMB）
+- 展示已使用 = 真已使用（无换算）
+
+---
+
+## 七、用户的思考与担忧（已全部解决）
+
+### 7.1 关于接口粒度
+
+**已确认**：resolve 返回中等版本，多接口组合，前端按需调用。
+
+### 7.2 关于网关封装程度
+
+**已确认**：
+- realtime-status：只查持久化数据，不调用网关
+- refresh：调用网关并写回 DB，更新缓存字段
+
+### 7.3 关于停复机去重
+
+**已确认**：所有停复机统一迁移到 assets 路径，旧接口直接删除。
+
+### 7.4 关于虚拟号
+
+**已确认**：
+- 卡的虚拟号给客服和客户用
+- 人工填写/批量导入，无格式规范，允许修改
+- 设备 device_no 全量重命名为 virtual_no
+- 导入重复时全批失败，告知具体冲突数据
+
+### 7.5 关于套餐查询
+
+**已确认**：套餐查询分两个接口，历史套餐接口包含当前套餐，同时单独提供当前套餐接口。
+
+### 7.6 关于停复机保护期
+
+**已确认**：保护期 1 小时，Redis 存储，未实名卡不参与，stop 保护期内禁止手动复机，start 保护期内允许手动停机。
+
+---
+
+## 八、设计决策确认清单
+
+| 序号 | 问题 | 确认结果 |
+|-----|------|---------|
+| 1 | resolve 返回数据范围 | 中等版本，含状态/套餐/流量/绑定信息/保护期 |
+| 2 | realtime-status 和 refresh 区别 | realtime-status=查持久化数据（轻量），refresh=调网关写回DB |
+| 3 | 实时状态封装 | 持久化数据展示，不调网关 |
+| 4 | 手动刷新复用 SyncCardStatusFromGateway | 是，设备时批量刷新所有绑定卡 |
+| 5 | 停复机统一 | 统一迁移到 /assets 路径，旧接口直接删除 |
+| 6 | 卡虚拟号生成方式 | 人工填写/批量导入，无格式规范 |
+| 7 | 废弃接口处理 | 直接删除 |
+| 8 | 套餐查询接口 | 两个接口：历史套餐列表 + 当前套餐详情 |
+| 9 | 权限不足的返回 | HTTP 403，明确告知无权限 |
+| 10 | 保护期时长 | 1 小时，硬编码常量 |
+| 11 | 虚流量计算 | virtual_ratio=RealDataMB/VirtualDataMB，套餐创建时存储 |
+| 12 | device_no 改名 | 全量改为 virtual_no，数据库+代码全部更新 |
+| 13 | 设备下卡列表 | 包含所有状态的卡（含未实名、已停用） |
+| 14 | 卡绑定设备被软删除时 | 视为独立卡，不填充绑定信息 |
+| 15 | 未实名卡参与停复机 | 不参与，永远是停机状态，保护期跳过 |
+| 16 | 数据权限规则 | 代理:仅自己及下级店铺，平台账号:所有资产 |
+| 17 | 查找失败 404 还是 403 | 资产不存在=404，有资产但无权限=403 |
+| 18 | 设备卡列表排序 | 无要求 |
+| 19 | resolve 中 current_package 无套餐时 | 返回空字符串/0 |
+| 20 | 虚拟号唯一索引 | 需要，允许为空，允许手动修改 |
+| 21 | 企业账号能否用 resolve | 暂不支持；企业账号未来开新接口 |
+| 22 | 接口 #2（按主键查详情）的设计 | 已确认删除，与 resolve 功能重叠，无独立价值 |
+| 23 | resolve 响应是否含 ICCID | 是，card 类型时返回 ICCID，供停复机接口使用 |
+| 24 | 设备批量停机部分失败策略 | 仍设置 Redis 保护期；已成功停机的卡不回滚；失败的卡记录日志 |
+| 25 | 流量数据汇总逻辑 | 统一用专门汇总逻辑，从 PackageUsage 读取；设备级套餐汇总所有绑定卡 |
+| 26 | 套餐历史列表排序和范围 | 按创建时间倒序，不分页，包含所有状态（含 status=4 已失效） |
+| 27 | current-package 多套餐时返回哪个 | 返回主套餐（master_usage_id IS NULL） |
+| 28 | 轮询系统保护期检查实现方式 | 新增独立的第四种轮询任务类型，不修改现有三种任务 |
+| 29 | 卡虚拟号导入规则 | 只允许为空白虚拟号的卡填入；与现存数据重复则全批失败 |
+| 30 | 设备批量刷新频率限制 | 需要；Redis 限频，同一设备冷却期（建议 30 秒）内不允许重复触发 |
+| 31 | PersonalCustomerDevice.device_no 改名 | 是，统一改为 virtual_no，与 tb_device 保持语义一致 |
+| 32 | DeviceCardInfo 需要 last_sync_time | 是，添加 last_sync_at 字段 |
+
+---
+
+## 九、轮询系统补充说明
+
+### 9.1 整体架构
+
+轮询系统是君鸿卡管系统维护卡数据实时性的核心机制：
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Worker 服务（后台）                            │
+├─────────────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐       │
+│  │ Scheduler    │────▶│ Asynq 队列   │────▶│ Handler      │       │
+│  │ (调度器)     │     │ (任务队列)   │     │ (处理器)     │       │
+│  └──────────────┘     └──────────────┘     └──────────────┘       │
+│         │                                               │          │
+│         │ 定时循环 (每秒)                                 │          │
+│         ▼                                               ▼          │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │              Redis Sorted Set 轮询队列                       │   │
+│  │  - polling:queue:realname  (实名检查)                      │   │
+│  │  - polling:queue:carddata  (流量检查)                      │   │
+│  │  - polling:queue:package   (套餐检查)                       │   │
+│  │  - polling:queue:protect   (保护期一致性检查)               │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+                                │
+                                │ 调用网关 API
+                                ▼
+                    ┌──────────────────────┐
+                    │ Gateway 网关        │
+                    │ (第三方运营商)      │
+                    └──────────────────────┘
+```
+
+### 9.2 四种轮询任务
+
+| 任务类型 | 触发频率 | 作用 | 更新字段 |
+|---------|---------|------|---------|
+| **实名检查** | 默认 5 分钟 | 调用网关查实名状态 | real_name_status |
+| **流量检查** | 默认 10 分钟 | 调用网关查流量，更新套餐 | current_month_usage_mb |
+| **套餐检查** | 默认 10 分钟 | 检查是否超额，触发停机 | network_status |
+| **保护期检查** | 同流量检查频率 | 检查绑定设备保护期，强制同步卡的网络状态 | network_status |
+
+> **第四种任务设计说明**：保护期一致性检查封装为独立任务类型，不嵌入现有三种任务内部。只检查"已绑定设备且设备当前有保护期"的卡，范围小，可与流量检查同频触发。
+
+### 9.3 关键特点
+
+1. **启动时渐进式初始化**：系统启动时把卡分批加载到 Redis 队列（每批 10 万张）
+2. **按时间排序**：Redis Sorted Set 的 score 是下次检查的时间戳，到期自动被调度器取出
+3. **并发控制**：通过 Redis 信号量限制并发数（默认 50），防止打爆网关
+4. **失败重试**：任务失败后重新入队
+5. **缓存优化**：优先从 Redis 读取卡信息，避免频繁查 DB
+
+### 9.4 与手动刷新接口的关系
+
+- **轮询是后台自动跑**：所有卡都会按配置的时间间隔被检查，保证日常数据更新
+- **手动刷新是前台客服主动用**：只更新这一张卡（或设备的所有绑定卡），满足客户急用场景
+- **两者是互补关系**：轮询保证数据不会太旧，手动刷新满足实时性要求高的场景
+
+### 9.5 与设备保护期的交互
+
+轮询系统在处理设备的绑定卡时，需要检查设备是否有保护期（见 5.4 流程图）：
+- 发现设备有 stop 保护期，且卡为开机状态 → 强制调网关停机
+- 发现设备有 start 保护期，且卡为停机状态 → 强制调网关复机
+- 未实名的卡跳过，不参与保护期逻辑
+
+关键代码位置：
+- `internal/task/polling_handler.go` - 轮询任务处理器（需新增独立的第四种任务：保护期一致性检查处理函数）
+- `pkg/constants/redis.go` - 需新增 `RedisDeviceProtectKey()` 函数
+
+### 9.6 涉及的关键代码
+
+- `internal/polling/scheduler.go` - 轮询调度器（把卡加入队列）
+- `internal/task/polling_handler.go` - 任务处理器（实际调网关更新数据）
+- `internal/service/iot_card/service.go:799` - SyncCardStatusFromGateway 方法
+
+---
+
+## 十、下一步行动
+
+### 10.1 当前阶段
+
+**设计讨论** - 已完成，所有关键决策已确认，可进入 openspec 提案阶段
+
+### 10.2 进入 openspec 提案后的任务拆分建议
+
+**数据层（优先）**：
+1. 数据库迁移：设备表 `device_no` → `virtual_no`（同步更新 `tb_personal_customer_device.device_no` → `virtual_no`）
+2. 数据库迁移：卡表新增 `virtual_no` 字段（唯一索引，允许空）
+3. 数据库迁移：套餐表新增 `virtual_ratio` 字段
+4. 更新 Device Model 和所有引用 `device_no` 的代码（全量替换，含 PersonalCustomerDevice）
+5. 更新 Package Service，创建/更新套餐时自动计算并存储 `virtual_ratio`
+
+**接口层（依次实现）**：
+6. 实现资产入口 `GET /assets/resolve/:identifier`
+7. 实现当前状态查询 `GET /assets/:type/:id/realtime-status`
+8. 实现手动刷新 `POST /assets/:type/:id/refresh`（含设备批量刷新 + Redis 限频）
+9. 实现套餐记录查询 `GET /assets/:type/:id/packages`
+10. 实现当前套餐查询 `GET /assets/:type/:id/current-package`
+11. 实现设备停机 `POST /assets/device/:id/stop`（含保护期逻辑 + 部分失败策略）
+12. 实现设备复机 `POST /assets/device/:id/start`（含保护期逻辑）
+13. 实现卡停机 `POST /assets/card/:iccid/stop`（含保护期检查）
+14. 实现卡复机 `POST /assets/card/:iccid/start`（含保护期检查）
+
+**轮询系统**：
+15. 新增第四种轮询任务：保护期一致性检查（独立任务类型，不修改现有三种任务内部逻辑）
+
+**清理**：
+16. 删除废弃的停复机接口（见 3.6 废弃清单）
+17. 丰富现有卡/设备 DTO（IotCardDetailResponse、DeviceResponse）
+18. 更新 API 文档生成器（docs.go 和 gendocs/main.go）
+
+### 10.3 涉及的关键代码文件
+
+**Handler 层**：
+- `internal/handler/admin/iot_card.go`
+- `internal/handler/admin/device.go`
+- `internal/handler/h5/enterprise_device.go`（待删除的废弃接口）
+
+**Service 层**：
+- `internal/service/iot_card/service.go`（含 SyncCardStatusFromGateway:799）
+- `internal/service/iot_card/stop_resume_service.go`（停复机逻辑，需扩展）
+- `internal/service/device/service.go`（含 GetByIdentifier:177）
+- `internal/service/package/customer_view_service.go`（套餐聚合，需复用）
+- `internal/service/package/service.go`（创建套餐时存储 virtual_ratio）
+
+**Store 层**：
+- `internal/store/postgres/device_store.go`（GetByIdentifier:62，改用 virtual_no）
+- `internal/store/postgres/iot_card_store.go`
+- `internal/store/postgres/personal_customer_device_store.go`（device_no → virtual_no）
+
+**Model 层**：
+- `internal/model/iot_card.go`（新增 virtual_no 字段）
+- `internal/model/device.go`（device_no → virtual_no）
+- `internal/model/package.go`（新增 virtual_ratio 字段）
+- `internal/model/personal_customer_device.go`（device_no → virtual_no）
+
+**DTO 层**：
+- `internal/model/dto/iot_card_dto.go`（需重构）
+- `internal/model/dto/device_dto.go`（需丰富）
+
+**常量层**：
+- `pkg/constants/redis.go`（新增 `RedisDeviceProtectKey()` 函数）
+
+**轮询层**：
+- `internal/task/polling_handler.go`（新增保护期一致性检查独立任务处理函数）
+
+---
+
+## 十一、附录：关键代码片段
+
+### 11.1 现有空壳详情 DTO
+
+```go
+// internal/model/dto/iot_card_dto.go:134-136
+type IotCardDetailResponse struct {
+    StandaloneIotCardResponse // 只是列表响应的空包装
+}
+```
+
+### 11.2 设备详情 DTO
+
+```go
+// internal/model/dto/device_dto.go:20
+type DeviceResponse struct {
+    ID          uint   `json:"id"`
+    DeviceNo    string `json:"device_no"` // 改名为 virtual_no
+    // ...
+    BoundCardCount int `json:"bound_card_count"` // 只有数字，需丰富
+}
+```
+
+### 11.3 设备多字段查找 Store
+
+```go
+// internal/store/postgres/device_store.go:62
+// 改造后：device_no → virtual_no
+func (s *Store) GetByIdentifier(db *gorm.DB, identifier string) (*model.Device, error) {
+    var device model.Device
+    err := db.Where("virtual_no = ? OR imei = ? OR sn = ?", identifier, identifier, identifier).
+        First(&device).Error
+    return &device, err
+}
+```
+
+### 11.4 手动刷新方法（待暴露为接口）
+
+```go
+// internal/service/iot_card/service.go:799
+func (s *Service) SyncCardStatusFromGateway(ctx context.Context, iccid string) error {
+    // 已有实现，需作为接口暴露，并支持设备批量刷新
+}
+```
+
+### 11.5 新增 Redis Key 常量
+
+```go
+// pkg/constants/redis.go
+// RedisDeviceProtectKey 设备停复机保护期 Key
+// action: "stop" 或 "start"，TTL = 1 小时
+func RedisDeviceProtectKey(deviceID uint, action string) string {
+    return fmt.Sprintf("protect:device:%d:%s", deviceID, action)
+}
+
+// RedisDeviceRefreshCooldownKey 设备手动刷新冷却期 Key，TTL = 冷却时长（建议 30 秒）
+func RedisDeviceRefreshCooldownKey(deviceID uint) string {
+    return fmt.Sprintf("refresh:cooldown:device:%d", deviceID)
+}
+```
+
+### 11.6 virtual_ratio 计算位置
+
+```go
+// internal/service/package/service.go
+// 创建/更新套餐时计算并存储 virtual_ratio
+if pkg.EnableVirtualData && pkg.VirtualDataMB > 0 {
+    pkg.VirtualRatio = float64(pkg.RealDataMB) / float64(pkg.VirtualDataMB)
+} else {
+    pkg.VirtualRatio = 1.0
+}
+```
+
+---
+
+> **文档结束**
+>
+> 所有设计决策已确认，可进入 openspec 提案阶段。