# 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 生成文档