huang
80c6f6c756
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m21s
主要变更： - 新增 AssetIdentifier 模型及 Store，统一管理资产标识符（ICCID/IMEI/SN 等） - 新增迁移：asset_identifier 表、order 表新增 asset_identifier 字段、iot_card.virtual_no NOT NULL 约束 - 资产 Handler/Service/Route 全面重构，支持标识符路由查询与解析 - 新增资产历史订单查询接口，支持跨设备/卡/钱包维度的订单聚合 - 设备与物联卡导入任务强制校验虚拟号，缺失时直接拒绝 - Excel 工具函数优化，前端导入指引文档同步更新 - 归档三个 OpenSpec 提案：asset-identifier-standardization、asset-historical-orders、import-mandatory-virtual-no - 更新 OpenAPI 文档及相关 DTO Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
5.0 KiB
5.0 KiB
Capability: 资产操作路由标识符标准化
Purpose
定义 B 端资产操作类接口统一使用资产标识符（ICCID 或 VirtualNo）作为路径参数的规范，废弃原有基于数据库主键 ID 的路由，并规定标识符解析的性能要求。
Requirements
Requirement: B 端资产操作接口统一使用标识符路径参数
B 端所有资产操作类接口 SHALL 使用资产标识符（ICCID 或 VirtualNo）作为路径参数，废弃原有基于数据库主键 ID 的路由。系统内部通过注册表将标识符解析为资产实体，Handler 层无需关心 ID。
标识符规则：
- IoT 卡：接受 ICCID 或 VirtualNo（均为全局唯一）
- 设备：接受 VirtualNo（全局唯一）
- 不接受 IMEI/SN/MSISDN（非唯一，仅 Resolve 的 fallback 路径支持）
废弃的旧路由 → 新路由映射：
| 旧路由（废弃） | 新路由 |
|---|---|
GET /api/admin/assets/:asset_type/:id/realtime-status |
GET /api/admin/assets/:identifier/realtime-status |
POST /api/admin/assets/:asset_type/:id/refresh |
POST /api/admin/assets/:identifier/refresh |
GET /api/admin/assets/:asset_type/:id/packages |
GET /api/admin/assets/:identifier/packages |
GET /api/admin/assets/:asset_type/:id/current-package |
GET /api/admin/assets/:identifier/current-package |
GET /api/admin/assets/:asset_type/:id/wallet |
GET /api/admin/assets/:identifier/wallet |
GET /api/admin/assets/:asset_type/:id/wallet/transactions |
GET /api/admin/assets/:identifier/wallet/transactions |
PATCH /api/admin/assets/:asset_type/:id/polling-status |
PATCH /api/admin/assets/:identifier/polling-status |
POST /api/admin/assets/device/:device_id/stop |
POST /api/admin/assets/:identifier/stop |
POST /api/admin/assets/device/:device_id/start |
POST /api/admin/assets/:identifier/start |
POST /api/admin/assets/card/:iccid/stop |
POST /api/admin/assets/:identifier/stop（合并） |
POST /api/admin/assets/card/:iccid/start |
POST /api/admin/assets/:identifier/start（合并） |
DELETE /api/admin/devices/:id |
DELETE /api/admin/devices/:virtual_no |
GET /api/admin/devices/:id/cards |
GET /api/admin/devices/:virtual_no/cards |
POST /api/admin/devices/:id/cards |
POST /api/admin/devices/:virtual_no/cards |
DELETE /api/admin/devices/:id/cards/:cardId |
DELETE /api/admin/devices/:virtual_no/cards/:iccid |
PATCH /api/admin/devices/:id/deactivate |
PATCH /api/admin/assets/:identifier/deactivate |
PATCH /api/admin/iot-cards/:id/deactivate |
PATCH /api/admin/assets/:identifier/deactivate（合并） |
Scenario: 通过 ICCID 操作 IoT 卡
- WHEN 管理员请求
GET /api/admin/assets/898600XXXXXXXX/packages - THEN 系统解析 ICCID，找到对应 IoT 卡，返回该卡的套餐列表
Scenario: 通过 VirtualNo 操作设备
- WHEN 管理员请求
POST /api/admin/assets/DEV-001/stop - THEN 系统解析 VirtualNo，找到对应设备，执行批量停机（停该设备下所有已实名卡）
Scenario: 通过 VirtualNo 操作绑定了设备的 IoT 卡（停机）
- WHEN 管理员请求
POST /api/admin/assets/CARD-001/stop，CARD-001 是 IoT 卡的 VirtualNo - THEN 系统解析 VirtualNo，找到 IoT 卡，执行单卡停机
Scenario: stop/start 接口对卡和设备行为差异
- WHEN identifier 解析为 IoT 卡时调用 stop
- THEN 执行单卡停机
- WHEN identifier 解析为设备时调用 stop
- THEN 执行设备停机（批量停机该设备下所有已实名卡）
Scenario: 标识符不存在
- WHEN 管理员请求的
:identifier在注册表和 fallback 查询中均未找到对应资产 - THEN 返回 HTTP 404，错误消息"资产不存在"
Scenario: 无权限操作该资产
- WHEN 代理用户请求的 identifier 对应的资产不属于该代理的数据权限范围
- THEN 返回 HTTP 403，错误消息"无权限操作该资源或资源不存在"
Scenario: 设备绑卡管理使用设备 VirtualNo
- WHEN 管理员请求
GET /api/admin/devices/DEV-001/cards - THEN 系统通过 VirtualNo 找到设备，返回该设备绑定的卡列表
Scenario: 设备解绑卡使用 ICCID
- WHEN 管理员请求
DELETE /api/admin/devices/DEV-001/cards/898600XXXXXXXX - THEN 系统通过 VirtualNo 找到设备，通过 ICCID 找到卡，执行解绑
Requirement: 新路由下标识符的解析性能
资产操作接口中标识符解析 SHALL 优先走注册表（单次精确查询），保证解析延迟不超过 10ms（在正常数据库负载下）。
Scenario: 注册表命中路径
- WHEN 请求携带的 identifier 存在于
tb_asset_identifier - THEN 系统单次查询注册表得到 asset_type 和 asset_id，无需扫描 tb_device 或 tb_iot_card
Scenario: 注册表未命中（fallback）
- WHEN 请求携带的 identifier 不在注册表（如 IMEI 或旧数据）
- THEN 系统 fallback 到原有多字段 OR 查询，同样能定位资产（性能稍低，为次要路径）