feat: 实现设备管理和设备导入功能,修复测试问题
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 5m30s

主要变更:
- 实现设备管理模块(创建、查询、列表、更新状态、删除)
- 实现设备批量导入功能(CSV 解析、ICCID 绑定、异步任务处理)
- 添加设备-SIM 卡绑定约束(部分唯一索引防止并发问题)
- 修复 fee_rate 数据库字段类型(numeric -> bigint)
- 修复测试数据隔离问题(基于增量断言)
- 修复集成测试中间件顺序问题
- 清理无用测试文件(PersonalCustomer、Email 相关)
- 归档 enterprise-card-authorization 变更
This commit is contained in:
2026-01-26 18:05:12 +08:00
parent fdcff33058
commit ce0783f96e
68 changed files with 6400 additions and 1482 deletions

View File

@@ -0,0 +1,89 @@
# Change: 设备管理功能
## Why
平台需要管理物联网设备(如 GPS 追踪器、智能传感器),支持设备与 IoT 卡的绑定关系、设备批量导入和分销。当前系统已有单卡管理功能,但缺少设备维度的管理能力。设备是比单卡更高一层的管理维度:设备可绑定 1-4 张卡,分配设备时自动带走绑定的所有卡。
## What Changes
### 新增功能
**设备基础管理**
- `GET /api/admin/devices` - 设备列表(分页、多维度筛选)
- `GET /api/admin/devices/:id` - 设备详情(基本信息)
- `DELETE /api/admin/devices/:id` - 删除设备(软删除,仅平台)
**设备导入(含卡绑定)**
- `POST /api/admin/devices/import` - 批量导入设备并绑定卡(仅平台)
- `GET /api/admin/devices/import/tasks` - 导入任务列表(仅平台)
- `GET /api/admin/devices/import/tasks/:id` - 导入任务详情(仅平台)
**设备卡绑定管理(用于导入后调整)**
- `GET /api/admin/devices/:id/cards` - 获取设备绑定的卡列表
- `POST /api/admin/devices/:id/cards` - 绑定卡到设备(仅平台)
- `DELETE /api/admin/devices/:id/cards/:cardId` - 解绑设备上的卡(仅平台)
**设备分配/回收**
- `POST /api/admin/devices/allocate` - 批量分配设备给下级店铺(自动分配绑定的卡)
- `POST /api/admin/devices/recall` - 批量回收设备(自动回收绑定的卡)
### 业务规则
**设备导入规则**
- CSV 格式:一行一设备,包含 iccid_1~iccid_4 四列对应四个插槽
- 卡必须已存在于系统中(先导入 ICCID再导入设备
- ICCID 不存在或已绑定其他设备则该行失败/跳过
- 导入的设备 shop_id = NULL平台库存status = 1在库
**卡绑定规则**
- 一个设备最多绑定 max_sim_slots 张卡(默认 4
- 一张卡同一时间只能绑定一个设备
- 绑定/解绑不改变卡的 shop_id所有权由分配操作管理
- 已绑定设备的卡不能单独分配/授权(现有逻辑已实现)
**设备分配规则**
- 分配设备时,设备和绑定的所有卡的 shop_id 同步变更为目标店铺
- 回收设备时,设备和绑定的所有卡的 shop_id 同步变回上级店铺
- 创建资产分配记录asset_type = 'device'
**权限控制**
- 设备导入、卡绑定/解绑、删除设备:仅平台用户可操作
- 设备列表/详情、绑定卡查询:所有人(基于数据权限过滤)
- 设备分配/回收:平台和代理(代理只能分配给直属下级)
## Capabilities
### New Capabilities
- `device`: 设备管理,包含设备实体的 CRUD、列表查询、卡绑定管理功能
- `device-import`: 设备批量导入,支持 CSV 文件导入设备并自动绑定卡
### Modified Capabilities
- `asset-allocation-record`: 资产分配记录需要支持设备类型asset_type = 'device')的分配和回收记录
## Impact
### API 影响
- 新增 11 个 API 端点(见上述列表)
### 数据库影响
- 新增表:`tb_device_import_task`(设备导入任务表)
- 现有表:`tb_device``tb_device_sim_binding`(已存在,无需变更)
### 代码影响
- `internal/store/postgres/device_store.go`:新增
- `internal/store/postgres/device_sim_binding_store.go`:新增
- `internal/store/postgres/device_import_task_store.go`:新增
- `internal/service/device/service.go`:新增
- `internal/service/device/binding.go`:新增
- `internal/service/device_import/service.go`:新增
- `internal/handler/admin/device.go`:新增
- `internal/handler/admin/device_import.go`:新增
- `internal/model/device_import_task.go`:新增
- `internal/model/dto/device_dto.go`:新增
- `internal/model/dto/device_import_dto.go`:新增
- `internal/routes/device.go`:新增
- `internal/task/device_import.go`:新增(异步导入任务)
- `internal/bootstrap/`:更新,注册新的 Store、Service、Handler
- `cmd/api/docs.go``cmd/gendocs/main.go`:更新,注册新 Handler 生成文档