feat: 实现物联网卡独立管理和批量导入功能
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m42s

新增物联网卡独立管理模块,支持单卡查询、批量导入和状态管理。主要变更包括:

功能特性:
- 新增物联网卡 CRUD 接口(查询、分页列表、删除)
- 支持 CSV/Excel 批量导入物联网卡
- 实现异步导入任务处理和进度跟踪
- 新增 ICCID 号码格式校验器(支持 Luhn 算法)
- 新增 CSV 文件解析工具(支持编码检测和错误处理)

数据库变更:
- 移除 iot_card 和 device 表的 owner_id/owner_type 字段
- 新增 iot_card_import_task 导入任务表
- 为导入任务添加运营商类型字段

测试覆盖:
- 新增 IoT 卡 Store 层单元测试
- 新增 IoT 卡导入任务单元测试
- 新增 IoT 卡集成测试(包含导入流程测试)
- 新增 CSV 工具和 ICCID 校验器测试

文档更新:
- 更新 OpenAPI 文档(新增 7 个 IoT 卡接口)
- 归档 OpenSpec 变更提案
- 更新 API 文档规范和生成器指南

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-01-24 11:03:43 +08:00
parent 6821e5abcf
commit a924e63e68
49 changed files with 7983 additions and 284 deletions

View File

@@ -0,0 +1,56 @@
# Change: IoT 卡单卡管理与所有权模型重构
## Why
当前 IoT 卡和设备模型中使用 `owner_type` + `owner_id` 表示所有权,与数据权限使用的 `shop_id` 字段存在冗余,且语义不清晰:
- 代理分销给下级时所有权实际是转移到下级店铺shop_id 变化)
- 企业用户没有"所有权"是通过授权表EnterpriseCardAuthorization管理
- 个人客户完全没有所有权概念,是基于 ICCID/设备号操作
同时,业务需要"单卡管理"功能:查看和导入未绑定设备的 IoT 卡,支持大批量 CSV 导入(几万条)并跟踪导入任务状态。
## What Changes
### 模型重构(**BREAKING**
- **移除 IotCard 的 owner_type/owner_id 字段**:改用 shop_id 表示所有权NULL=平台所有,有值=店铺所有)
- **移除 Device 的 owner_type/owner_id 字段**:同上
- 保留 AssetAllocationRecord 和 CardReplacementRecord 中的 Owner 字段(历史记录追溯用)
### 新增功能
- **单卡列表 API**:查询未绑定设备的 IoT 卡,支持多维度筛选
- **批量导入 ICCID API**:支持 CSV 文件上传,异步处理,支持几万条数据
- **导入任务记录表**:跟踪导入进度、成功/跳过/失败统计及详情
### ICCID 校验规则调整
- 电信:严格 19 位
- 联通/移动/广电:严格 20 位
- 支持字母数字混合(移动 ICCID 有字母)
## Capabilities
### New Capabilities
- `iot-card-import-task`: IoT 卡导入任务管理,包含导入任务模型、进度跟踪、结果详情记录
### Modified Capabilities
- `iot-card`: 移除 owner_type/owner_id 字段,改用 shop_id新增单卡列表查询调整 ICCID 校验规则
- `iot-device`: 移除 owner_type/owner_id 字段,改用 shop_id
## Impact
### 数据库变更
- `tb_iot_card` 表:删除 owner_type、owner_id 列
- `tb_device` 表:删除 owner_type、owner_id 列
- 新增 `tb_iot_card_import_task`
### 代码影响
- `internal/model/iot_card.go`:移除 OwnerType、OwnerID 字段
- `internal/model/device.go`:移除 OwnerType、OwnerID 字段
- `internal/model/iot_card_import_task.go`:新增
- `openspec/specs/iot-card/spec.md`:修改所有权相关描述
- `openspec/specs/iot-device/spec.md`:修改所有权相关描述
### API 影响
- 新增:`GET /api/admin/iot-cards/standalone` - 单卡列表
- 新增:`POST /api/admin/iot-cards/import` - 发起导入任务
- 新增:`GET /api/admin/iot-cards/import-tasks` - 导入任务列表
- 新增:`GET /api/admin/iot-cards/import-tasks/:id` - 导入任务详情