huang
477a9fc98d
Some checks failed
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Has been cancelled
- 新增 GET /api/admin/devices/by-imei/:imei 接口，支持通过设备号查询设备详情 - 新增 GET /api/admin/iot-cards/by-iccid/:iccid 接口，支持通过ICCID查询单卡详情 - 添加对应的 Service 层方法和 Handler - 更新 OpenAPI 文档 - 添加集成测试并修复测试环境配置（使用环境变量） - 归档已完成的 OpenSpec 变更记录 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# 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 生成文档
|