feat: 实现单卡资产分配与回收功能
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m45s

- 新增单卡分配/回收 API(支持 ICCID 列表、号段范围、筛选条件三种选卡方式)
- 新增资产分配记录查询 API(支持多条件筛选和分页)
- 新增 AssetAllocationRecord 模型、Store、Service、Handler 完整实现
- 扩展 IotCardStore 新增批量更新、号段查询、筛选查询等方法
- 修复 GORM Callback 处理 slice 类型(BatchCreate)的问题
- 新增完整的单元测试和集成测试
- 同步 OpenSpec 规范并归档 change
This commit is contained in:
2026-01-24 15:46:15 +08:00
parent a924e63e68
commit 194078674a
33 changed files with 2785 additions and 92 deletions

View File

@@ -0,0 +1,82 @@
# Change: 单卡资产分配功能
## Why
平台和代理商需要将单卡(未绑定设备的 IoT 卡)分销给下级代理,实现资产的层级流转。当前系统只有企业卡授权功能(授权企业可见特定卡),缺少代理商之间的卡所有权转移功能。
业务场景:
- 平台批量导入卡后,分销给一级代理
- 一级代理继续分销给二级代理
- 上级可以回收已分销的卡
- 查看卡的分配/回收历史记录
## What Changes
### 新增功能
**单卡分配 API**
- `POST /api/admin/iot-cards/standalone/allocate` - 批量分配单卡给直属下级店铺
- `POST /api/admin/iot-cards/standalone/recall` - 批量回收已分配的单卡
**分配记录查询 API**
- `GET /api/admin/asset-allocation-records` - 分配记录列表(支持分页和筛选)
- `GET /api/admin/asset-allocation-records/:id` - 分配记录详情
**分配方式支持**
- ICCID 列表选择
- ICCID 号段范围(起始~结束)
- 筛选条件批量(运营商、批次号等)
### 业务规则
**分配规则**
- 只能分配给直属下级店铺,不可跨级
- 平台只能分配在库(status=1)的卡
- 代理可以分配已分销(status=2)的卡(继续往下分销)
- 分配后状态变更:在库(1)→已分销(2),已分销(2)保持不变
- 分配后 shop_id 变更为目标店铺 ID
**回收规则**
- 只有上级可以回收,代理不能主动退回
- 平台回收shop_id 变为 NULL
- 店铺回收shop_id 变为执行回收的店铺 ID
- 只能回收直属下级的卡,不可跨级回收
**可见性**
- 分配后上级仍能看到和管理(通过数据权限机制实现)
**注意**
- 本次只做单卡分配,设备卡分配暂不实现
- 分配不涉及费用,纯资产所有权转移
## Capabilities
### New Capabilities
- `asset-allocation-record`: 资产分配记录管理,包含分配记录的查询功能
### Modified Capabilities
- `iot-card`: 新增单卡分配和回收功能
## Impact
### API 影响
- 新增:`POST /api/admin/iot-cards/standalone/allocate`
- 新增:`POST /api/admin/iot-cards/standalone/recall`
- 新增:`GET /api/admin/asset-allocation-records`
- 新增:`GET /api/admin/asset-allocation-records/:id`
### 代码影响
- `internal/handler/admin/iot_card.go`:新增 AllocateCards、RecallCards 方法
- `internal/handler/admin/asset_allocation_record.go`:新增(分配记录 Handler
- `internal/service/iot_card/service.go`:新增分配、回收业务逻辑
- `internal/service/asset_allocation_record/service.go`:新增(分配记录 Service
- `internal/store/postgres/iot_card_store.go`:新增批量更新 shop_id 方法
- `internal/store/postgres/asset_allocation_record_store.go`:新增(分配记录 Store
- `internal/model/dto/iot_card_dto.go`:新增分配、回收相关 DTO
- `internal/model/dto/asset_allocation_record_dto.go`:新增(分配记录 DTO
- `internal/routes/asset_allocation_record.go`:新增(分配记录路由)
### 数据库影响
- 无表结构变更(使用现有 `tb_iot_card``tb_asset_allocation_record` 表)