feat: 添加设备IMEI和单卡ICCID查询接口
Some checks failed
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Has been cancelled
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>
This commit is contained in:
84
CLAUDE.md
84
CLAUDE.md
@@ -31,11 +31,25 @@ Keep this managed block so 'openspec update' can refresh the instructions.
|
||||
|---------|-----------|------|
|
||||
| 创建/修改 DTO 文件 | `dto-standards` | description 标签、枚举字段、验证标签规范 |
|
||||
| 创建/修改 Model 模型 | `model-standards` | GORM 模型结构、字段标签、TableName 规范 |
|
||||
| 注册 API 路由 | `api-routing` | Register() 函数、RouteSpec 必填项 |
|
||||
| 注册 API 路由 / **新增 Handler** | `api-routing` | Register() 函数、RouteSpec、**文档生成器更新** |
|
||||
| 测试接口/验证数据 | `db-validation` | PostgreSQL MCP 使用方法和验证示例 |
|
||||
| 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 |
|
||||
| 维护规范文档 | `doc-management` | 规范文档流程和维护规则 |
|
||||
|
||||
### ⚠️ 新增 Handler 时必须同步更新文档生成器
|
||||
|
||||
新增 Handler 后，接口不会自动出现在 OpenAPI 文档中。**必须手动更新以下两个文件**：
|
||||
|
||||
```go
|
||||
// cmd/api/docs.go 和 cmd/gendocs/main.go
|
||||
handlers := &bootstrap.Handlers{
|
||||
// ... 添加新 Handler
|
||||
NewHandler: admin.NewXxxHandler(nil),
|
||||
}
|
||||
```
|
||||
|
||||
**完整检查清单**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md#新增-handler-检查清单)
|
||||
|
||||
---
|
||||
|
||||
## 语言要求
|
||||
@@ -137,6 +151,58 @@ Handler → Service → Store → Model
|
||||
- 使用 table-driven tests
|
||||
- 单元测试 < 100ms，集成测试 < 1s
|
||||
|
||||
### ⚠️ 测试真实性原则（严格遵守）
|
||||
|
||||
**测试必须真正验证功能，禁止绕过核心逻辑：**
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| ❌ 禁止传递 nil 绕过依赖 | 如果功能依赖外部服务（如对象存储、第三方 API），测试必须验证该依赖的调用 |
|
||||
| ❌ 禁止只测试部分流程 | 如果功能包含 A → B → C 三步，不能只测试 B 而跳过 A 和 C |
|
||||
| ❌ 禁止声称"测试通过"但未验证核心逻辑 | 测试通过必须意味着功能真正可用 |
|
||||
| ❌ 禁止擅自使用 Mock | 尽量使用真实服务进行集成测试，如需使用 Mock 必须先询问用户并获得同意 |
|
||||
| ✅ 必须验证端到端流程 | 新增功能必须有完整的集成测试覆盖整个调用链 |
|
||||
| ✅ 缺少配置时必须询问 | 如果测试需要的配置（如 API Key、环境变量）缺失，必须询问用户而非跳过测试 |
|
||||
|
||||
**反面案例**：
|
||||
```go
|
||||
// ❌ 错误：传递 nil 绕过 storageService，只测试了 processImport
|
||||
handler := NewIotCardImportHandler(db, redis, store1, store2, nil, logger)
|
||||
result := handler.processImport(ctx, task) // 跳过了 downloadAndParseCSV
|
||||
|
||||
// ✅ 正确：使用真实服务测试完整流程
|
||||
handler := NewIotCardImportHandler(db, redis, store1, store2, realStorageService, logger)
|
||||
handler.HandleIotCardImport(ctx, asynqTask) // 测试完整流程，验证真实上传/下载
|
||||
```
|
||||
|
||||
**测试超时 = 生产超时**：
|
||||
- 集成测试超时意味着生产环境也可能超时
|
||||
- 发现超时必须排查原因，不能简单跳过或增加超时时间
|
||||
|
||||
### 测试连接管理（必读）
|
||||
|
||||
**详细规范**: [docs/testing/test-connection-guide.md](docs/testing/test-connection-guide.md)
|
||||
|
||||
**标准模板**:
|
||||
```go
|
||||
func TestXxx(t *testing.T) {
|
||||
tx := testutils.NewTestTransaction(t)
|
||||
rdb := testutils.GetTestRedis(t)
|
||||
testutils.CleanTestRedisKeys(t, rdb)
|
||||
|
||||
store := postgres.NewXxxStore(tx, rdb)
|
||||
// 测试代码...
|
||||
}
|
||||
```
|
||||
|
||||
**核心函数**:
|
||||
- `NewTestTransaction(t)`: 创建测试事务，自动回滚
|
||||
- `GetTestRedis(t)`: 获取全局 Redis 连接
|
||||
- `CleanTestRedisKeys(t, rdb)`: 自动清理测试 Redis 键
|
||||
|
||||
**禁止使用（已移除）**:
|
||||
- ❌ `SetupTestDB` / `TeardownTestDB` / `SetupTestDBWithStore`
|
||||
|
||||
## 性能要求
|
||||
|
||||
- API P95 响应时间 < 200ms
|
||||
@@ -179,4 +245,20 @@ Handler → Service → Store → Model
|
||||
8. ✅ 文档更新计划
|
||||
9. ✅ 中文优先
|
||||
|
||||
### ⚠️ 任务执行规范（必须遵守）
|
||||
|
||||
**提案中的 tasks.md 是契约，不可擅自变更：**
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| ❌ 禁止跳过任务 | 每个任务都是经过规划的，不能因为"简单"或"显而易见"而跳过 |
|
||||
| ❌ 禁止简化任务 | 不能将多个任务合并或简化执行，除非获得明确许可 |
|
||||
| ❌ 禁止自作主张优化 | 发现可以优化的地方，必须先询问是否可以调整 |
|
||||
| ✅ 必须逐项完成 | 按照 tasks.md 中的顺序逐一执行并标记完成 |
|
||||
| ✅ 必须询问后变更 | 如需调整任务（简化/跳过/合并/优化），先询问用户确认 |
|
||||
|
||||
**询问示例**：
|
||||
> "我注意到任务 2.1 和 2.2 可以合并为一步完成，是否可以这样优化？"
|
||||
> "任务 3.1 在当前实现中可能不需要，是否可以跳过？"
|
||||
|
||||
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
|
||||
|
||||
@@ -1085,6 +1085,15 @@ components:
|
||||
total_count:
|
||||
description: 总数
|
||||
type: integer
|
||||
warning_count:
|
||||
description: 警告数(部分成功的设备数量)
|
||||
type: integer
|
||||
warning_items:
|
||||
description: 警告记录详情(部分成功的设备及其卡绑定失败原因)
|
||||
items:
|
||||
$ref: '#/components/schemas/DtoDeviceImportResultItemDTO'
|
||||
nullable: true
|
||||
type: array
|
||||
type: object
|
||||
DtoDeviceImportTaskResponse:
|
||||
properties:
|
||||
@@ -1136,6 +1145,9 @@ components:
|
||||
total_count:
|
||||
description: 总数
|
||||
type: integer
|
||||
warning_count:
|
||||
description: 警告数(部分成功的设备数量)
|
||||
type: integer
|
||||
type: object
|
||||
DtoDeviceResponse:
|
||||
properties:
|
||||
@@ -1577,6 +1589,83 @@ components:
|
||||
description: 总数
|
||||
type: integer
|
||||
type: object
|
||||
DtoIotCardDetailResponse:
|
||||
properties:
|
||||
activated_at:
|
||||
description: 激活时间
|
||||
format: date-time
|
||||
nullable: true
|
||||
type: string
|
||||
activation_status:
|
||||
description: 激活状态 (0:未激活, 1:已激活)
|
||||
type: integer
|
||||
batch_no:
|
||||
description: 批次号
|
||||
type: string
|
||||
card_category:
|
||||
description: 卡业务类型 (normal:普通卡, industry:行业卡)
|
||||
type: string
|
||||
card_type:
|
||||
description: 卡类型
|
||||
type: string
|
||||
carrier_id:
|
||||
description: 运营商ID
|
||||
minimum: 0
|
||||
type: integer
|
||||
carrier_name:
|
||||
description: 运营商名称
|
||||
type: string
|
||||
cost_price:
|
||||
description: 成本价(分)
|
||||
type: integer
|
||||
created_at:
|
||||
description: 创建时间
|
||||
format: date-time
|
||||
type: string
|
||||
data_usage_mb:
|
||||
description: 累计流量使用(MB)
|
||||
type: integer
|
||||
distribute_price:
|
||||
description: 分销价(分)
|
||||
type: integer
|
||||
iccid:
|
||||
description: ICCID
|
||||
type: string
|
||||
id:
|
||||
description: 卡ID
|
||||
minimum: 0
|
||||
type: integer
|
||||
imsi:
|
||||
description: IMSI
|
||||
type: string
|
||||
msisdn:
|
||||
description: 卡接入号
|
||||
type: string
|
||||
network_status:
|
||||
description: 网络状态 (0:停机, 1:开机)
|
||||
type: integer
|
||||
real_name_status:
|
||||
description: 实名状态 (0:未实名, 1:已实名)
|
||||
type: integer
|
||||
shop_id:
|
||||
description: 店铺ID
|
||||
minimum: 0
|
||||
nullable: true
|
||||
type: integer
|
||||
shop_name:
|
||||
description: 店铺名称
|
||||
type: string
|
||||
status:
|
||||
description: 状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)
|
||||
type: integer
|
||||
supplier:
|
||||
description: 供应商
|
||||
type: string
|
||||
updated_at:
|
||||
description: 更新时间
|
||||
format: date-time
|
||||
type: string
|
||||
type: object
|
||||
DtoListAssetAllocationRecordResponse:
|
||||
properties:
|
||||
list:
|
||||
@@ -4904,6 +4993,52 @@ paths:
|
||||
summary: 批量分配设备
|
||||
tags:
|
||||
- 设备管理
|
||||
/api/admin/devices/by-imei/{imei}:
|
||||
get:
|
||||
parameters:
|
||||
- description: 设备号(IMEI)
|
||||
in: path
|
||||
name: imei
|
||||
required: true
|
||||
schema:
|
||||
description: 设备号(IMEI)
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DtoDeviceResponse'
|
||||
description: OK
|
||||
"400":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 请求参数错误
|
||||
"401":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 未认证或认证已过期
|
||||
"403":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 无权访问
|
||||
"500":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 服务器内部错误
|
||||
security:
|
||||
- BearerAuth: []
|
||||
summary: 通过设备号查询设备详情
|
||||
tags:
|
||||
- 设备管理
|
||||
/api/admin/devices/import:
|
||||
post:
|
||||
description: |-
|
||||
@@ -5709,6 +5844,52 @@ paths:
|
||||
summary: 启用/禁用企业
|
||||
tags:
|
||||
- 企业客户管理
|
||||
/api/admin/iot-cards/by-iccid/{iccid}:
|
||||
get:
|
||||
parameters:
|
||||
- description: ICCID
|
||||
in: path
|
||||
name: iccid
|
||||
required: true
|
||||
schema:
|
||||
description: ICCID
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DtoIotCardDetailResponse'
|
||||
description: OK
|
||||
"400":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 请求参数错误
|
||||
"401":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 未认证或认证已过期
|
||||
"403":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 无权访问
|
||||
"500":
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
description: 服务器内部错误
|
||||
security:
|
||||
- BearerAuth: []
|
||||
summary: 通过ICCID查询单卡详情
|
||||
tags:
|
||||
- IoT卡管理
|
||||
/api/admin/iot-cards/import:
|
||||
post:
|
||||
description: |-
|
||||
|
||||
@@ -52,6 +52,20 @@ func (h *DeviceHandler) GetByID(c *fiber.Ctx) error {
|
||||
return response.Success(c, result)
|
||||
}
|
||||
|
||||
func (h *DeviceHandler) GetByIMEI(c *fiber.Ctx) error {
|
||||
imei := c.Params("imei")
|
||||
if imei == "" {
|
||||
return errors.New(errors.CodeInvalidParam, "设备号不能为空")
|
||||
}
|
||||
|
||||
result, err := h.service.GetByDeviceNo(c.UserContext(), imei)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
return response.Success(c, result)
|
||||
}
|
||||
|
||||
func (h *DeviceHandler) Delete(c *fiber.Ctx) error {
|
||||
userType := middleware.GetUserTypeFromContext(c.UserContext())
|
||||
if userType != constants.UserTypeSuperAdmin && userType != constants.UserTypePlatform {
|
||||
|
||||
@@ -33,6 +33,20 @@ func (h *IotCardHandler) ListStandalone(c *fiber.Ctx) error {
|
||||
return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
|
||||
}
|
||||
|
||||
func (h *IotCardHandler) GetByICCID(c *fiber.Ctx) error {
|
||||
iccid := c.Params("iccid")
|
||||
if iccid == "" {
|
||||
return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
|
||||
}
|
||||
|
||||
result, err := h.service.GetByICCID(c.UserContext(), iccid)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
return response.Success(c, result)
|
||||
}
|
||||
|
||||
func (h *IotCardHandler) AllocateCards(c *fiber.Ctx) error {
|
||||
var req dto.AllocateStandaloneCardsRequest
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
|
||||
@@ -47,6 +47,10 @@ type GetDeviceRequest struct {
|
||||
ID uint `path:"id" description:"设备ID" required:"true"`
|
||||
}
|
||||
|
||||
type GetDeviceByIMEIRequest struct {
|
||||
DeviceNo string `path:"imei" description:"设备号(IMEI)" required:"true"`
|
||||
}
|
||||
|
||||
type DeleteDeviceRequest struct {
|
||||
ID uint `path:"id" description:"设备ID" required:"true"`
|
||||
}
|
||||
|
||||
@@ -116,3 +116,11 @@ type ImportTaskDetailResponse struct {
|
||||
type GetImportTaskRequest struct {
|
||||
ID uint `path:"id" description:"任务ID" required:"true"`
|
||||
}
|
||||
|
||||
type GetIotCardByICCIDRequest struct {
|
||||
ICCID string `path:"iccid" description:"ICCID" required:"true"`
|
||||
}
|
||||
|
||||
type IotCardDetailResponse struct {
|
||||
StandaloneIotCardResponse
|
||||
}
|
||||
|
||||
@@ -28,6 +28,14 @@ func registerDeviceRoutes(router fiber.Router, handler *admin.DeviceHandler, imp
|
||||
Auth: true,
|
||||
})
|
||||
|
||||
Register(devices, doc, groupPath, "GET", "/by-imei/:imei", handler.GetByIMEI, RouteSpec{
|
||||
Summary: "通过设备号查询设备详情",
|
||||
Tags: []string{"设备管理"},
|
||||
Input: new(dto.GetDeviceByIMEIRequest),
|
||||
Output: new(dto.DeviceResponse),
|
||||
Auth: true,
|
||||
})
|
||||
|
||||
Register(devices, doc, groupPath, "DELETE", "/:id", handler.Delete, RouteSpec{
|
||||
Summary: "删除设备",
|
||||
Description: "仅平台用户可操作。删除设备时自动解绑所有卡（卡不会被删除）。",
|
||||
|
||||
@@ -20,6 +20,14 @@ func registerIotCardRoutes(router fiber.Router, handler *admin.IotCardHandler, i
|
||||
Auth: true,
|
||||
})
|
||||
|
||||
Register(iotCards, doc, groupPath, "GET", "/by-iccid/:iccid", handler.GetByICCID, RouteSpec{
|
||||
Summary: "通过ICCID查询单卡详情",
|
||||
Tags: []string{"IoT卡管理"},
|
||||
Input: new(dto.GetIotCardByICCIDRequest),
|
||||
Output: new(dto.IotCardDetailResponse),
|
||||
Auth: true,
|
||||
})
|
||||
|
||||
Register(iotCards, doc, groupPath, "POST", "/import", importHandler.Import, RouteSpec{
|
||||
Summary: "批量导入IoT卡（ICCID+MSISDN）",
|
||||
Description: `## ⚠️ 接口变更说明（BREAKING CHANGE）
|
||||
|
||||
@@ -134,6 +134,25 @@ func (s *Service) Get(ctx context.Context, id uint) (*dto.DeviceResponse, error)
|
||||
return s.toDeviceResponse(device, shopMap, bindingCounts), nil
|
||||
}
|
||||
|
||||
// GetByDeviceNo 通过设备号获取设备详情
|
||||
func (s *Service) GetByDeviceNo(ctx context.Context, deviceNo string) (*dto.DeviceResponse, error) {
|
||||
device, err := s.deviceStore.GetByDeviceNo(ctx, deviceNo)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return nil, errors.New(errors.CodeNotFound, "设备不存在")
|
||||
}
|
||||
return nil, err
|
||||
}
|
||||
|
||||
shopMap := s.loadShopData(ctx, []*model.Device{device})
|
||||
bindingCounts, err := s.getBindingCounts(ctx, []uint{device.ID})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
return s.toDeviceResponse(device, shopMap, bindingCounts), nil
|
||||
}
|
||||
|
||||
func (s *Service) Delete(ctx context.Context, id uint) error {
|
||||
device, err := s.deviceStore.GetByID(ctx, id)
|
||||
if err != nil {
|
||||
|
||||
@@ -110,6 +110,24 @@ func (s *Service) ListStandalone(ctx context.Context, req *dto.ListStandaloneIot
|
||||
}, nil
|
||||
}
|
||||
|
||||
// GetByICCID 通过 ICCID 获取单卡详情
|
||||
func (s *Service) GetByICCID(ctx context.Context, iccid string) (*dto.IotCardDetailResponse, error) {
|
||||
card, err := s.iotCardStore.GetByICCID(ctx, iccid)
|
||||
if err != nil {
|
||||
if err == gorm.ErrRecordNotFound {
|
||||
return nil, errors.New(errors.CodeNotFound, "IoT卡不存在")
|
||||
}
|
||||
return nil, err
|
||||
}
|
||||
|
||||
carrierMap, shopMap := s.loadRelatedData(ctx, []*model.IotCard{card})
|
||||
standaloneResp := s.toStandaloneResponse(card, carrierMap, shopMap)
|
||||
|
||||
return &dto.IotCardDetailResponse{
|
||||
StandaloneIotCardResponse: *standaloneResp,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func (s *Service) loadRelatedData(ctx context.Context, cards []*model.IotCard) (map[uint]string, map[uint]string) {
|
||||
carrierIDs := make([]uint, 0)
|
||||
shopIDs := make([]uint, 0)
|
||||
|
||||
@@ -3,9 +3,7 @@
|
||||
## Purpose
|
||||
|
||||
管理资产（IoT 卡、设备）在平台与代理商之间的流转记录，支持分配和回收操作的完整追溯。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 资产分配记录查询
|
||||
|
||||
系统 SHALL 提供资产分配记录的查询功能，支持查看卡和设备在平台与代理商之间的流转历史。
|
||||
@@ -16,7 +14,7 @@
|
||||
|
||||
**资产类型**:
|
||||
- `iot_card`: 物联网卡（单卡）
|
||||
- `device`: 设备（未来扩展）
|
||||
- `device`: 设备
|
||||
|
||||
**查询条件**:
|
||||
- `allocation_type`（可选）: 分配类型，枚举值 "allocate" | "recall"
|
||||
@@ -48,6 +46,8 @@
|
||||
- `asset_type_name`: 资产类型名称（物联网卡/设备）
|
||||
- `asset_id`: 资产 ID
|
||||
- `asset_identifier`: 资产标识符
|
||||
- `related_device_id`: 关联设备 ID（单卡分配时，如果卡绑定了设备）
|
||||
- `related_card_ids`: 关联卡 ID 列表（设备分配时，包含设备绑定的所有卡 ID）
|
||||
- `from_owner_type`: 来源所有者类型
|
||||
- `from_owner_id`: 来源所有者 ID
|
||||
- `from_owner_name`: 来源所有者名称
|
||||
@@ -69,6 +69,11 @@
|
||||
- **WHEN** 管理员查询资产类型为 "iot_card" 的记录
|
||||
- **THEN** 系统只返回物联网卡的分配/回收记录，不包含设备记录
|
||||
|
||||
#### Scenario: 按资产类型筛选设备记录
|
||||
|
||||
- **WHEN** 管理员查询资产类型为 "device" 的记录
|
||||
- **THEN** 系统只返回设备的分配/回收记录，不包含单卡记录
|
||||
|
||||
#### Scenario: 按分配类型筛选记录
|
||||
|
||||
- **WHEN** 管理员查询分配类型为 "allocate" 的记录
|
||||
@@ -79,6 +84,11 @@
|
||||
- **WHEN** 管理员输入 asset_identifier = "8986001"
|
||||
- **THEN** 系统返回 ICCID 包含 "8986001" 的所有分配记录
|
||||
|
||||
#### Scenario: 按设备号模糊查询
|
||||
|
||||
- **WHEN** 管理员输入 asset_identifier = "GPS"
|
||||
- **THEN** 系统返回设备号包含 "GPS" 的所有分配记录
|
||||
|
||||
#### Scenario: 代理查询自己相关的记录
|
||||
|
||||
- **WHEN** 代理用户（店铺 ID=10）查询分配记录
|
||||
@@ -94,14 +104,20 @@
|
||||
|
||||
**响应**:
|
||||
- 包含记录的所有字段
|
||||
- 关联卡 ID 列表（如果是设备分配，包含设备下的所有卡 ID）
|
||||
- `related_card_ids`: 关联卡 ID 列表（设备分配时，包含设备绑定的所有卡 ID）
|
||||
|
||||
#### Scenario: 查询分配记录详情
|
||||
|
||||
- **WHEN** 管理员查询分配记录详情（ID=1）
|
||||
- **THEN** 系统返回该记录的完整信息，包括来源/目标所有者名称、操作人名称等
|
||||
|
||||
#### Scenario: 查询设备分配记录详情
|
||||
|
||||
- **WHEN** 管理员查询设备分配记录详情
|
||||
- **THEN** 系统返回该记录的完整信息，包括 related_card_ids（设备绑定的所有卡 ID）
|
||||
|
||||
#### Scenario: 查询不存在的记录
|
||||
|
||||
- **WHEN** 管理员查询不存在的分配记录（ID=999）
|
||||
- **THEN** 系统返回 404 错误，提示"分配记录不存在"
|
||||
|
||||
|
||||
191
openspec/specs/device-import/spec.md
Normal file
191
openspec/specs/device-import/spec.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# device-import Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change add-device-management. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: 设备批量导入
|
||||
|
||||
系统 SHALL 提供设备批量导入功能，通过 CSV 文件导入设备并自动绑定卡，仅平台用户可操作。
|
||||
|
||||
**API 端点**: `POST /api/admin/devices/import`
|
||||
|
||||
**请求参数**:
|
||||
- `batch_no`: 批次号（必填）
|
||||
- `file_key`: 对象存储文件路径（必填，通过 /storage/upload-url 获取）
|
||||
|
||||
**CSV 格式**:
|
||||
```
|
||||
device_no,device_name,device_model,device_type,max_sim_slots,manufacturer,iccid_1,iccid_2,iccid_3,iccid_4
|
||||
DEV-001,GPS追踪器A,GT06N,GPS Tracker,4,Concox,8986001234567890001,8986001234567890002,,
|
||||
DEV-002,GPS追踪器B,GT06N,GPS Tracker,4,Concox,8986001234567890003,,,
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `device_no`: 设备号（必填，唯一）
|
||||
- `device_name`: 设备名称（可选）
|
||||
- `device_model`: 设备型号（可选）
|
||||
- `device_type`: 设备类型（可选）
|
||||
- `max_sim_slots`: 最大插槽数（可选，默认 4，范围 1-4）
|
||||
- `manufacturer`: 制造商（可选）
|
||||
- `iccid_1` ~ `iccid_4`: 对应插槽 1-4 的 ICCID（可选，空值表示该插槽无卡）
|
||||
|
||||
**导入规则**:
|
||||
- 导入的设备 shop_id = NULL（平台库存）
|
||||
- 导入的设备 status = 1（在库）
|
||||
- 设备号重复则该行跳过
|
||||
- ICCID 必须已存在于系统中（先导入卡，再导入设备）
|
||||
- ICCID 不存在则该行失败
|
||||
- ICCID 已绑定其他设备则该行失败
|
||||
- 导入通过异步任务处理，立即返回任务 ID
|
||||
|
||||
**权限**: 仅平台用户
|
||||
|
||||
**响应**:
|
||||
- `task_id`: 导入任务 ID
|
||||
- `task_no`: 任务编号
|
||||
- `message`: 提示信息
|
||||
|
||||
#### Scenario: 提交设备导入任务
|
||||
|
||||
- **WHEN** 平台管理员上传 CSV 文件并提交导入请求
|
||||
- **THEN** 系统创建导入任务，返回任务 ID，开始异步处理
|
||||
|
||||
#### Scenario: 代理尝试导入设备
|
||||
|
||||
- **WHEN** 代理用户尝试导入设备
|
||||
- **THEN** 系统返回 403 错误，提示"无权限执行此操作"
|
||||
|
||||
#### Scenario: 文件格式错误
|
||||
|
||||
- **WHEN** 平台管理员上传非 CSV 格式或格式不正确的文件
|
||||
- **THEN** 系统创建任务但处理失败，任务状态为"失败"，记录错误信息
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 设备导入任务执行
|
||||
|
||||
系统 SHALL 异步执行设备导入任务，逐行处理 CSV 数据。
|
||||
|
||||
**处理规则**:
|
||||
- 逐行解析 CSV 文件
|
||||
- 对每行数据执行以下校验：
|
||||
1. 设备号是否已存在（已存在则跳过）
|
||||
2. ICCID 是否存在于系统中（不存在则失败）
|
||||
3. ICCID 是否已绑定其他设备（已绑定则失败）
|
||||
- 校验通过后：
|
||||
1. 创建设备记录
|
||||
2. 创建设备-卡绑定记录
|
||||
- 记录处理结果（成功/跳过/失败）
|
||||
|
||||
**任务状态**:
|
||||
- 1: 待处理
|
||||
- 2: 处理中
|
||||
- 3: 已完成
|
||||
- 4: 失败
|
||||
|
||||
#### Scenario: 导入成功
|
||||
|
||||
- **WHEN** CSV 中所有设备号不重复且 ICCID 有效
|
||||
- **THEN** 系统创建所有设备和绑定记录，任务状态为"已完成"
|
||||
|
||||
#### Scenario: 部分导入成功
|
||||
|
||||
- **WHEN** CSV 中部分设备号已存在或部分 ICCID 无效
|
||||
- **THEN** 系统只导入有效的行，记录跳过和失败的详情，任务状态为"已完成"
|
||||
|
||||
#### Scenario: ICCID 不存在
|
||||
|
||||
- **WHEN** CSV 中某行的 ICCID 在系统中不存在
|
||||
- **THEN** 该行导入失败，记录失败原因"ICCID 不存在"
|
||||
|
||||
#### Scenario: ICCID 已绑定其他设备
|
||||
|
||||
- **WHEN** CSV 中某行的 ICCID 已绑定到其他设备
|
||||
- **THEN** 该行导入失败，记录失败原因"ICCID 已绑定其他设备"
|
||||
|
||||
#### Scenario: 设备号重复
|
||||
|
||||
- **WHEN** CSV 中某行的设备号在系统中已存在
|
||||
- **THEN** 该行被跳过，记录跳过原因"设备号已存在"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 设备导入任务列表查询
|
||||
|
||||
系统 SHALL 提供设备导入任务列表查询功能，仅平台用户可操作。
|
||||
|
||||
**API 端点**: `GET /api/admin/devices/import/tasks`
|
||||
|
||||
**查询条件**:
|
||||
- `status`（可选）: 任务状态 1-4
|
||||
- `batch_no`（可选）: 批次号，模糊匹配
|
||||
- `start_time`（可选）: 创建时间起始
|
||||
- `end_time`（可选）: 创建时间结束
|
||||
|
||||
**分页**:
|
||||
- 默认每页 20 条，最大每页 100 条
|
||||
|
||||
**响应字段**:
|
||||
- `id`: 任务 ID
|
||||
- `task_no`: 任务编号
|
||||
- `status`: 任务状态
|
||||
- `status_text`: 任务状态文本
|
||||
- `batch_no`: 批次号
|
||||
- `file_name`: 文件名
|
||||
- `total_count`: 总数
|
||||
- `success_count`: 成功数
|
||||
- `skip_count`: 跳过数
|
||||
- `fail_count`: 失败数
|
||||
- `started_at`: 开始时间
|
||||
- `completed_at`: 完成时间
|
||||
- `error_message`: 错误信息
|
||||
- `created_at`: 创建时间
|
||||
|
||||
**权限**: 仅平台用户
|
||||
|
||||
#### Scenario: 查询导入任务列表
|
||||
|
||||
- **WHEN** 平台管理员查询导入任务列表
|
||||
- **THEN** 系统返回所有导入任务，按创建时间倒序排列
|
||||
|
||||
#### Scenario: 按状态筛选任务
|
||||
|
||||
- **WHEN** 平台管理员查询状态为 3（已完成）的任务
|
||||
- **THEN** 系统只返回已完成的任务
|
||||
|
||||
#### Scenario: 代理尝试查询导入任务
|
||||
|
||||
- **WHEN** 代理用户尝试查询导入任务
|
||||
- **THEN** 系统返回 403 错误，提示"无权限执行此操作"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 设备导入任务详情查询
|
||||
|
||||
系统 SHALL 提供设备导入任务详情查询功能，包含跳过和失败记录的详细信息。
|
||||
|
||||
**API 端点**: `GET /api/admin/devices/import/tasks/:id`
|
||||
|
||||
**响应字段**:
|
||||
- 包含任务列表的所有字段
|
||||
- `skipped_items`: 跳过记录详情列表
|
||||
- `line`: 行号
|
||||
- `device_no`: 设备号
|
||||
- `reason`: 跳过原因
|
||||
- `failed_items`: 失败记录详情列表
|
||||
- `line`: 行号
|
||||
- `device_no`: 设备号
|
||||
- `reason`: 失败原因
|
||||
|
||||
**权限**: 仅平台用户
|
||||
|
||||
#### Scenario: 查询导入任务详情
|
||||
|
||||
- **WHEN** 平台管理员查询导入任务详情（ID=1）
|
||||
- **THEN** 系统返回任务的完整信息，包括跳过和失败记录详情
|
||||
|
||||
#### Scenario: 查询不存在的任务
|
||||
|
||||
- **WHEN** 平台管理员查询不存在的任务（ID=999）
|
||||
- **THEN** 系统返回 404 错误，提示"导入任务不存在"
|
||||
|
||||
325
openspec/specs/device/spec.md
Normal file
325
openspec/specs/device/spec.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# device Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change add-device-management. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: 设备列表查询
|
||||
|
||||
系统 SHALL 提供设备列表查询功能，支持多维度筛选和分页。
|
||||
|
||||
**查询条件**:
|
||||
- `device_no`（可选）: 设备号，支持模糊匹配
|
||||
- `device_name`（可选）: 设备名称，支持模糊匹配
|
||||
- `status`（可选）: 设备状态，枚举值 1-在库 | 2-已分销 | 3-已激活 | 4-已停用
|
||||
- `shop_id`（可选）: 店铺 ID，NULL 表示平台库存
|
||||
- `batch_no`（可选）: 批次号，精确匹配
|
||||
- `device_type`（可选）: 设备类型
|
||||
- `manufacturer`（可选）: 制造商，支持模糊匹配
|
||||
- `created_at_start`（可选）: 创建时间起始
|
||||
- `created_at_end`（可选）: 创建时间结束
|
||||
|
||||
**分页**:
|
||||
- 默认每页 20 条，最大每页 100 条
|
||||
- 返回总记录数和总页数
|
||||
|
||||
**数据权限**:
|
||||
- 平台用户可查看所有设备
|
||||
- 代理用户只能查看自己店铺及下级店铺的设备
|
||||
|
||||
**API 端点**: `GET /api/admin/devices`
|
||||
|
||||
**响应字段**:
|
||||
- `id`: 设备 ID
|
||||
- `device_no`: 设备号
|
||||
- `device_name`: 设备名称
|
||||
- `device_model`: 设备型号
|
||||
- `device_type`: 设备类型
|
||||
- `max_sim_slots`: 最大插槽数
|
||||
- `manufacturer`: 制造商
|
||||
- `batch_no`: 批次号
|
||||
- `shop_id`: 店铺 ID
|
||||
- `shop_name`: 店铺名称
|
||||
- `status`: 状态
|
||||
- `status_name`: 状态名称
|
||||
- `bound_card_count`: 已绑定卡数量
|
||||
- `activated_at`: 激活时间
|
||||
- `created_at`: 创建时间
|
||||
- `updated_at`: 更新时间
|
||||
|
||||
#### Scenario: 平台查询所有设备
|
||||
|
||||
- **WHEN** 平台管理员查询设备列表，不带任何筛选条件
|
||||
- **THEN** 系统返回所有设备，按创建时间倒序排列
|
||||
|
||||
#### Scenario: 按设备号模糊查询
|
||||
|
||||
- **WHEN** 管理员输入 device_no = "GPS"
|
||||
- **THEN** 系统返回设备号包含 "GPS" 的所有设备
|
||||
|
||||
#### Scenario: 按状态筛选设备
|
||||
|
||||
- **WHEN** 管理员查询状态为 1（在库）的设备
|
||||
- **THEN** 系统只返回在库状态的设备
|
||||
|
||||
#### Scenario: 代理查询自己店铺的设备
|
||||
|
||||
- **WHEN** 代理用户（店铺 ID=10）查询设备列表
|
||||
- **THEN** 系统只返回 shop_id 为 10 及其下级店铺的设备
|
||||
|
||||
#### Scenario: 查询平台库存设备
|
||||
|
||||
- **WHEN** 平台管理员查询 shop_id 为空的设备
|
||||
- **THEN** 系统返回所有平台库存设备（shop_id = NULL）
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 设备详情查询
|
||||
|
||||
系统 SHALL 提供设备详情查询功能，返回设备的基本信息。
|
||||
|
||||
**API 端点**: `GET /api/admin/devices/:id`
|
||||
|
||||
**响应字段**:
|
||||
- 包含设备的所有基本字段
|
||||
- `shop_name`: 店铺名称（如果有）
|
||||
|
||||
**数据权限**:
|
||||
- 平台用户可查看所有设备
|
||||
- 代理用户只能查看自己店铺及下级店铺的设备
|
||||
|
||||
#### Scenario: 查询设备详情成功
|
||||
|
||||
- **WHEN** 管理员查询设备详情（ID=1）
|
||||
- **THEN** 系统返回该设备的完整基本信息
|
||||
|
||||
#### Scenario: 查询不存在的设备
|
||||
|
||||
- **WHEN** 管理员查询不存在的设备（ID=999）
|
||||
- **THEN** 系统返回 404 错误，提示"设备不存在"
|
||||
|
||||
#### Scenario: 代理查询无权限的设备
|
||||
|
||||
- **WHEN** 代理用户（店铺 ID=10）查询其他店铺的设备（shop_id=20，非下级）
|
||||
- **THEN** 系统返回 404 错误，提示"设备不存在"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 删除设备
|
||||
|
||||
系统 SHALL 提供删除设备功能，仅平台用户可操作，执行软删除。
|
||||
|
||||
**API 端点**: `DELETE /api/admin/devices/:id`
|
||||
|
||||
**业务规则**:
|
||||
- 仅平台用户可删除设备
|
||||
- 删除设备时自动解绑该设备上的所有卡
|
||||
- 执行软删除（设置 deleted_at）
|
||||
|
||||
**权限**: 仅平台用户
|
||||
|
||||
#### Scenario: 平台删除设备成功
|
||||
|
||||
- **WHEN** 平台管理员删除设备（ID=1）
|
||||
- **THEN** 系统软删除该设备，并解绑设备上的所有卡
|
||||
|
||||
#### Scenario: 代理尝试删除设备
|
||||
|
||||
- **WHEN** 代理用户尝试删除设备
|
||||
- **THEN** 系统返回 403 错误，提示"无权限执行此操作"
|
||||
|
||||
#### Scenario: 删除不存在的设备
|
||||
|
||||
- **WHEN** 平台管理员删除不存在的设备（ID=999）
|
||||
- **THEN** 系统返回 404 错误，提示"设备不存在"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 获取设备绑定的卡列表
|
||||
|
||||
系统 SHALL 提供查询设备绑定的 IoT 卡列表功能。
|
||||
|
||||
**API 端点**: `GET /api/admin/devices/:id/cards`
|
||||
|
||||
**响应字段**:
|
||||
- `bindings`: 绑定列表，每个元素包含：
|
||||
- `id`: 绑定记录 ID
|
||||
- `slot_position`: 插槽位置（1-4）
|
||||
- `iot_card_id`: IoT 卡 ID
|
||||
- `iccid`: ICCID
|
||||
- `msisdn`: 接入号
|
||||
- `carrier_name`: 运营商名称
|
||||
- `status`: 卡状态
|
||||
- `bind_time`: 绑定时间
|
||||
|
||||
#### Scenario: 查询设备绑定的卡
|
||||
|
||||
- **WHEN** 管理员查询设备（ID=1）绑定的卡
|
||||
- **THEN** 系统返回该设备所有已绑定的卡信息，按插槽位置排序
|
||||
|
||||
#### Scenario: 查询无绑定卡的设备
|
||||
|
||||
- **WHEN** 管理员查询没有绑定卡的设备
|
||||
- **THEN** 系统返回空的绑定列表
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 绑定卡到设备
|
||||
|
||||
系统 SHALL 提供将 IoT 卡绑定到设备指定插槽的功能，仅平台用户可操作。
|
||||
|
||||
**API 端点**: `POST /api/admin/devices/:id/cards`
|
||||
|
||||
**请求参数**:
|
||||
- `iot_card_id`: IoT 卡 ID（必填）
|
||||
- `slot_position`: 插槽位置 1-4（必填）
|
||||
|
||||
**业务规则**:
|
||||
- 仅平台用户可操作
|
||||
- 插槽位置不能超过设备的 max_sim_slots
|
||||
- 该插槽必须为空（无已绑定的卡）
|
||||
- 该卡不能已绑定到其他设备
|
||||
- 绑定操作不改变卡的 shop_id
|
||||
|
||||
**权限**: 仅平台用户
|
||||
|
||||
#### Scenario: 绑定卡到设备成功
|
||||
|
||||
- **WHEN** 平台管理员将 IoT 卡（ID=101）绑定到设备（ID=1）的插槽 2
|
||||
- **THEN** 系统创建绑定记录，返回绑定成功信息
|
||||
|
||||
#### Scenario: 绑定到已占用的插槽
|
||||
|
||||
- **WHEN** 平台管理员尝试绑定卡到已有卡的插槽
|
||||
- **THEN** 系统返回错误，提示"该插槽已有绑定的卡"
|
||||
|
||||
#### Scenario: 绑定已被绑定的卡
|
||||
|
||||
- **WHEN** 平台管理员尝试绑定已绑定到其他设备的卡
|
||||
- **THEN** 系统返回错误，提示"该卡已绑定到其他设备"
|
||||
|
||||
#### Scenario: 插槽位置超出范围
|
||||
|
||||
- **WHEN** 平台管理员尝试绑定卡到插槽 5（设备 max_sim_slots=4）
|
||||
- **THEN** 系统返回错误，提示"插槽位置超出设备最大插槽数"
|
||||
|
||||
#### Scenario: 代理尝试绑定卡
|
||||
|
||||
- **WHEN** 代理用户尝试绑定卡到设备
|
||||
- **THEN** 系统返回 403 错误，提示"无权限执行此操作"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 解绑设备上的卡
|
||||
|
||||
系统 SHALL 提供解绑设备上指定卡的功能，仅平台用户可操作。
|
||||
|
||||
**API 端点**: `DELETE /api/admin/devices/:id/cards/:cardId`
|
||||
|
||||
**业务规则**:
|
||||
- 仅平台用户可操作
|
||||
- 更新绑定记录的 bind_status 为 2（已解绑），记录 unbind_time
|
||||
- 解绑操作不改变卡的 shop_id
|
||||
|
||||
**权限**: 仅平台用户
|
||||
|
||||
#### Scenario: 解绑卡成功
|
||||
|
||||
- **WHEN** 平台管理员解绑设备（ID=1）上的卡（ID=101）
|
||||
- **THEN** 系统更新绑定记录状态为已解绑，返回成功信息
|
||||
|
||||
#### Scenario: 解绑不存在的绑定关系
|
||||
|
||||
- **WHEN** 平台管理员尝试解绑不存在的绑定关系
|
||||
- **THEN** 系统返回错误，提示"该卡未绑定到此设备"
|
||||
|
||||
#### Scenario: 代理尝试解绑卡
|
||||
|
||||
- **WHEN** 代理用户尝试解绑设备上的卡
|
||||
- **THEN** 系统返回 403 错误，提示"无权限执行此操作"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 批量分配设备
|
||||
|
||||
系统 SHALL 提供批量分配设备给下级店铺的功能，分配时自动同步绑定卡的归属。
|
||||
|
||||
**API 端点**: `POST /api/admin/devices/allocate`
|
||||
|
||||
**请求参数**:
|
||||
- `target_shop_id`: 目标店铺 ID（必填）
|
||||
- `device_ids`: 设备 ID 列表（必填，最多 100 个）
|
||||
- `remark`: 备注（可选）
|
||||
|
||||
**业务规则**:
|
||||
- 只能分配给直属下级店铺，不可跨级
|
||||
- 平台只能分配 shop_id=NULL 的设备
|
||||
- 代理只能分配自己店铺的设备
|
||||
- 分配后：
|
||||
- 设备的 shop_id 变更为目标店铺 ID
|
||||
- 设备绑定的所有卡的 shop_id 也变更为目标店铺 ID
|
||||
- 设备状态变为「已分销」(2)
|
||||
- 创建资产分配记录（asset_type='device'）
|
||||
|
||||
**响应**:
|
||||
- `success_count`: 成功数量
|
||||
- `fail_count`: 失败数量
|
||||
- `failed_items`: 失败详情列表
|
||||
|
||||
#### Scenario: 平台分配设备给一级代理
|
||||
|
||||
- **WHEN** 平台管理员将 5 台设备分配给一级代理店铺（ID=10）
|
||||
- **THEN** 系统更新这 5 台设备及其绑定卡的 shop_id 为 10，创建分配记录，返回成功数量
|
||||
|
||||
#### Scenario: 代理分配设备给下级
|
||||
|
||||
- **WHEN** 代理（店铺 ID=10）将 3 台设备分配给直属下级店铺（ID=101）
|
||||
- **THEN** 系统更新这 3 台设备及其绑定卡的 shop_id 为 101，创建分配记录
|
||||
|
||||
#### Scenario: 分配给非直属下级
|
||||
|
||||
- **WHEN** 代理（店铺 ID=10）尝试分配设备给非直属下级店铺（ID=1011，是 101 的下级）
|
||||
- **THEN** 系统返回错误，提示"只能分配给直属下级店铺"
|
||||
|
||||
#### Scenario: 分配不属于自己的设备
|
||||
|
||||
- **WHEN** 代理（店铺 ID=10）尝试分配其他店铺的设备
|
||||
- **THEN** 系统跳过这些设备，只分配属于自己的设备
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 批量回收设备
|
||||
|
||||
系统 SHALL 提供批量回收已分配设备的功能，回收时自动同步绑定卡的归属。
|
||||
|
||||
**API 端点**: `POST /api/admin/devices/recall`
|
||||
|
||||
**请求参数**:
|
||||
- `device_ids`: 设备 ID 列表（必填，最多 100 个）
|
||||
- `remark`: 备注（可选）
|
||||
|
||||
**业务规则**:
|
||||
- 只能回收直属下级店铺的设备，不可跨级
|
||||
- 平台回收后：设备和绑定卡的 shop_id 变为 NULL
|
||||
- 代理回收后：设备和绑定卡的 shop_id 变为执行回收的店铺 ID
|
||||
- 创建资产回收记录（asset_type='device'）
|
||||
|
||||
**响应**:
|
||||
- `success_count`: 成功数量
|
||||
- `fail_count`: 失败数量
|
||||
- `failed_items`: 失败详情列表
|
||||
|
||||
#### Scenario: 平台回收一级代理的设备
|
||||
|
||||
- **WHEN** 平台管理员回收一级代理店铺（ID=10）的 3 台设备
|
||||
- **THEN** 系统更新这 3 台设备及其绑定卡的 shop_id 为 NULL，创建回收记录
|
||||
|
||||
#### Scenario: 代理回收下级的设备
|
||||
|
||||
- **WHEN** 代理（店铺 ID=10）回收下级店铺（ID=101）的 2 台设备
|
||||
- **THEN** 系统更新这 2 台设备及其绑定卡的 shop_id 为 10，创建回收记录
|
||||
|
||||
#### Scenario: 回收非直属下级的设备
|
||||
|
||||
- **WHEN** 代理（店铺 ID=10）尝试回收非直属下级的设备
|
||||
- **THEN** 系统返回错误，提示"只能回收直属下级店铺的设备"
|
||||
|
||||
@@ -102,8 +102,9 @@ This capability supports:
|
||||
- 绑定时记录插槽位置(slot_position: 1, 2, 3, 4)
|
||||
- 绑定时记录绑定时间和绑定状态(1-已绑定 2-已解绑)
|
||||
- 绑定/解绑操作不改变 IoT 卡的 shop_id(所有权由分销操作管理,而非绑定操作)
|
||||
- **新增**: 同一设备的同一插槽同一时间只能绑定一张卡(数据库唯一约束)
|
||||
|
||||
**中间表 device_sim_bindings**:
|
||||
**中间表 tb_device_sim_binding**:
|
||||
- `id`: 绑定记录 ID(主键,BIGINT)
|
||||
- `device_id`: 设备 ID(BIGINT)
|
||||
- `iot_card_id`: IoT 卡 ID(BIGINT)
|
||||
@@ -113,6 +114,17 @@ This capability supports:
|
||||
- `unbind_time`: 解绑时间(TIMESTAMP,可空)
|
||||
- `created_at`: 创建时间(TIMESTAMP,自动填充)
|
||||
- `updated_at`: 更新时间(TIMESTAMP,自动填充)
|
||||
- `deleted_at`: 软删除时间(TIMESTAMP,可空)
|
||||
- `creator`: 创建人 ID(BIGINT)
|
||||
- `updater`: 更新人 ID(BIGINT)
|
||||
|
||||
**数据库约束**:
|
||||
- `idx_device_sim_bindings_active_card`: 唯一索引 (iot_card_id) WHERE bind_status = 1,防止同一张卡绑定到多个设备
|
||||
- **新增** `idx_active_device_slot`: 唯一索引 (device_id, slot_position) WHERE bind_status = 1 AND deleted_at IS NULL,防止同一插槽绑定多张卡
|
||||
|
||||
**并发安全**:
|
||||
- 系统 SHALL 在数据库层面通过唯一约束防止并发绑定导致的数据不一致
|
||||
- 系统 SHALL 正确处理唯一约束冲突错误,返回友好的用户提示而非通用数据库错误
|
||||
|
||||
#### Scenario: 绑定 IoT 卡到设备
|
||||
|
||||
@@ -124,6 +136,16 @@ This capability supports:
|
||||
- **WHEN** 用户解绑设备的 IoT 卡(绑定记录 ID 为 10)
|
||||
- **THEN** 系统将绑定记录的 `bind_status` 从 1(已绑定) 变更为 2(已解绑),`unbind_time` 记录解绑时间,IoT 卡的 `shop_id` 保持不变
|
||||
|
||||
#### Scenario: 并发绑定同一张卡到不同设备
|
||||
|
||||
- **WHEN** 两个请求同时尝试将同一张 IoT 卡(ID 为 101)绑定到不同设备
|
||||
- **THEN** 第一个请求成功,第二个请求返回错误"该卡已绑定到其他设备"
|
||||
|
||||
#### Scenario: 并发绑定不同卡到同一设备插槽
|
||||
|
||||
- **WHEN** 两个请求同时尝试将不同 IoT 卡绑定到同一设备(ID 为 1001)的同一插槽(slot_position 为 1)
|
||||
- **THEN** 第一个请求成功,第二个请求返回错误"该插槽已有绑定的卡"
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 设备套餐购买和流量共享
|
||||
@@ -217,29 +239,64 @@ This capability supports:
|
||||
|
||||
**导入字段**:
|
||||
- 设备编号(必填)
|
||||
- 设备名称(必填)
|
||||
- 设备型号(必填)
|
||||
- 设备类型(必填)
|
||||
- 设备名称(可选)
|
||||
- 设备型号(可选)
|
||||
- 设备类型(可选)
|
||||
- 最大插槽数(可选,默认 4)
|
||||
- 设备制造商(可选)
|
||||
- 批次号(必填)
|
||||
- 批次号(可选,由任务自动生成)
|
||||
- **ICCID 1-4**(可选,用于绑定 IoT 卡)
|
||||
|
||||
**导入规则**:
|
||||
- 设备编号必须唯一,重复编号将被拒绝
|
||||
- 导入的设备默认 `owner_type` 为 "platform",`owner_id` 为 0,状态为 1(未激活)
|
||||
- 设备编号必须唯一,重复编号将被跳过
|
||||
- 导入的设备默认 `shop_id` 为 NULL(平台库存),状态为 1(在库)
|
||||
- 导入成功后记录操作日志
|
||||
|
||||
**IoT 卡绑定规则**(新增):
|
||||
- 系统 SHALL 校验 ICCID 对应的卡是否存在
|
||||
- 系统 SHALL 校验卡是否已绑定到其他设备
|
||||
- **新增**: 系统 SHALL 校验卡的归属权,只允许绑定平台库存的卡(shop_id = NULL)
|
||||
- 如果卡已分配给店铺(shop_id != NULL),系统 SHALL 拒绝绑定并记录原因
|
||||
|
||||
**导入结果分类**(新增):
|
||||
- **完全成功**: 设备创建且所有指定的卡都绑定成功
|
||||
- **部分成功**: 设备创建但部分卡绑定失败(新增 warning 状态)
|
||||
- **跳过**: 设备编号已存在
|
||||
- **失败**: 设备创建失败或所有指定的卡都不可用
|
||||
|
||||
**导入任务模型扩展**(新增):
|
||||
- `warning_count`: 警告数量(部分成功的设备数)
|
||||
- `warning_items`: 警告记录详情(JSONB,记录哪些卡绑定失败及原因)
|
||||
|
||||
#### Scenario: 批量导入设备成功
|
||||
|
||||
- **WHEN** 平台上传包含 50 条设备数据的 CSV 文件
|
||||
- **THEN** 系统创建 50 条设备记录,`owner_type` 为 "platform",`owner_id` 为 0,状态为 1(未激活),返回导入成功消息
|
||||
- **THEN** 系统创建 50 条设备记录,`shop_id` 为 NULL(平台库存),状态为 1(在库),返回导入成功消息
|
||||
|
||||
#### Scenario: 批量导入包含重复编号
|
||||
|
||||
- **WHEN** 平台上传的 CSV 文件中包含已存在的设备编号
|
||||
- **THEN** 系统拒绝重复编号的设备,返回错误信息并列出重复编号,其他有效设备正常导入
|
||||
- **THEN** 系统跳过重复编号的设备,记录到 skipped_items 并列出重复编号,其他有效设备正常导入
|
||||
|
||||
---
|
||||
#### Scenario: 导入时绑定平台库存的卡
|
||||
|
||||
- **WHEN** CSV 行指定了 ICCID,且该卡为平台库存(shop_id = NULL)且未绑定其他设备
|
||||
- **THEN** 系统创建设备并绑定该卡,记录为完全成功
|
||||
|
||||
#### Scenario: 导入时尝试绑定已分配给店铺的卡
|
||||
|
||||
- **WHEN** CSV 行指定了 ICCID,但该卡已分配给店铺(shop_id != NULL)
|
||||
- **THEN** 系统创建设备但不绑定该卡,将该设备记录到 warning_items,原因为"ICCID-XXX 已分配给店铺,不能绑定到平台库存设备"
|
||||
|
||||
#### Scenario: 导入时部分卡绑定成功
|
||||
|
||||
- **WHEN** CSV 行指定了 4 张卡,其中 2 张为平台库存且未绑定,1 张已分配给店铺,1 张不存在
|
||||
- **THEN** 系统创建设备并绑定 2 张有效的卡,将该设备记录到 warning_items,原因为"部分卡绑定失败: ICCID-001 已分配给店铺,不能绑定到平台库存设备; ICCID-002 不存在",success_count 和 warning_count 各加 1
|
||||
|
||||
#### Scenario: 导入时所有指定的卡都不可用
|
||||
|
||||
- **WHEN** CSV 行指定了 2 张卡,但都已绑定到其他设备
|
||||
- **THEN** 系统不创建设备,将该行记录到 failed_items,原因为"所有指定的卡都不可用: ICCID-001 已绑定其他设备, ICCID-002 已绑定其他设备"
|
||||
|
||||
### Requirement: 设备查询和筛选
|
||||
|
||||
@@ -299,3 +356,36 @@ This capability supports:
|
||||
- **WHEN** 用户创建设备,设备编号为已存在的 "DEV-001"
|
||||
- **THEN** 系统拒绝创建,返回错误信息"设备编号已存在"
|
||||
|
||||
### Requirement: DeviceSimBinding 模型组织
|
||||
|
||||
系统 SHALL 将 DeviceSimBinding 模型定义在独立的文件中,遵循项目代码组织规范。
|
||||
|
||||
**文件位置**:
|
||||
- 从: `internal/model/package.go`
|
||||
- 到: `internal/model/device_sim_binding.go`
|
||||
|
||||
**模型内容**:
|
||||
```go
|
||||
// DeviceSimBinding 设备-IoT卡绑定关系模型
|
||||
// 管理设备与 IoT 卡的多对多绑定关系(1 设备绑定 1-4 张 IoT 卡)
|
||||
type DeviceSimBinding struct {
|
||||
gorm.Model
|
||||
BaseModel `gorm:"embedded"`
|
||||
DeviceID uint `gorm:"column:device_id;index:idx_device_slot;not null;comment:设备ID"`
|
||||
IotCardID uint `gorm:"column:iot_card_id;index;not null;comment:IoT卡ID"`
|
||||
SlotPosition int `gorm:"column:slot_position;type:int;index:idx_device_slot;comment:插槽位置(1, 2, 3, 4)"`
|
||||
BindStatus int `gorm:"column:bind_status;type:int;default:1;comment:绑定状态 1-已绑定 2-已解绑"`
|
||||
BindTime *time.Time `gorm:"column:bind_time;comment:绑定时间"`
|
||||
UnbindTime *time.Time `gorm:"column:unbind_time;comment:解绑时间"`
|
||||
}
|
||||
|
||||
func (DeviceSimBinding) TableName() string {
|
||||
return "tb_device_sim_binding"
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 模型文件独立
|
||||
|
||||
- **WHEN** 开发者需要查找或修改 DeviceSimBinding 模型
|
||||
- **THEN** 模型定义位于 `internal/model/device_sim_binding.go` 文件中,而非混杂在 `package.go` 中
|
||||
|
||||
|
||||
@@ -40,8 +40,17 @@ type deviceTestEnv struct {
|
||||
func setupDeviceTestEnv(t *testing.T) *deviceTestEnv {
|
||||
t.Helper()
|
||||
|
||||
t.Setenv("CONFIG_ENV", "dev")
|
||||
t.Setenv("CONFIG_PATH", "../../configs/config.dev.yaml")
|
||||
// 设置测试环境变量
|
||||
t.Setenv("JUNHONG_DATABASE_HOST", "cxd.whcxd.cn")
|
||||
t.Setenv("JUNHONG_DATABASE_PORT", "16159")
|
||||
t.Setenv("JUNHONG_DATABASE_USER", "erp_pgsql")
|
||||
t.Setenv("JUNHONG_DATABASE_PASSWORD", "erp_2025")
|
||||
t.Setenv("JUNHONG_DATABASE_DBNAME", "junhong_cmp_test")
|
||||
t.Setenv("JUNHONG_REDIS_ADDRESS", "cxd.whcxd.cn")
|
||||
t.Setenv("JUNHONG_REDIS_PORT", "16299")
|
||||
t.Setenv("JUNHONG_REDIS_PASSWORD", "cpNbWtAaqgo1YJmbMp3h")
|
||||
t.Setenv("JUNHONG_JWT_SECRET_KEY", "test_secret_key_for_integration_tests")
|
||||
|
||||
cfg, err := config.Load()
|
||||
require.NoError(t, err)
|
||||
err = config.Set(cfg)
|
||||
@@ -331,3 +340,69 @@ func TestDeviceImport_TaskList(t *testing.T) {
|
||||
assert.Equal(t, 0, result.Code)
|
||||
})
|
||||
}
|
||||
|
||||
func TestDevice_GetByIMEI(t *testing.T) {
|
||||
env := setupDeviceTestEnv(t)
|
||||
defer env.teardown()
|
||||
|
||||
// 创建测试设备
|
||||
device := &model.Device{
|
||||
DeviceNo: "TEST_IMEI_001",
|
||||
DeviceName: "测试IMEI查询设备",
|
||||
DeviceType: "router",
|
||||
MaxSimSlots: 4,
|
||||
Status: constants.DeviceStatusInStock,
|
||||
}
|
||||
require.NoError(t, env.db.Create(device).Error)
|
||||
|
||||
t.Run("通过IMEI查询设备详情-成功", func(t *testing.T) {
|
||||
url := fmt.Sprintf("/api/admin/devices/by-imei/%s", device.DeviceNo)
|
||||
req := httptest.NewRequest("GET", url, nil)
|
||||
req.Header.Set("Authorization", "Bearer "+env.adminToken)
|
||||
|
||||
resp, err := env.app.Test(req, -1)
|
||||
require.NoError(t, err)
|
||||
defer resp.Body.Close()
|
||||
|
||||
assert.Equal(t, 200, resp.StatusCode)
|
||||
|
||||
var result response.Response
|
||||
err = json.NewDecoder(resp.Body).Decode(&result)
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, 0, result.Code)
|
||||
|
||||
// 验证返回数据
|
||||
dataMap, ok := result.Data.(map[string]interface{})
|
||||
require.True(t, ok)
|
||||
assert.Equal(t, "TEST_IMEI_001", dataMap["device_no"])
|
||||
assert.Equal(t, "测试IMEI查询设备", dataMap["device_name"])
|
||||
})
|
||||
|
||||
t.Run("通过不存在的IMEI查询-应返回错误", func(t *testing.T) {
|
||||
req := httptest.NewRequest("GET", "/api/admin/devices/by-imei/NONEXISTENT_IMEI", nil)
|
||||
req.Header.Set("Authorization", "Bearer "+env.adminToken)
|
||||
|
||||
resp, err := env.app.Test(req, -1)
|
||||
require.NoError(t, err)
|
||||
defer resp.Body.Close()
|
||||
|
||||
var result response.Response
|
||||
err = json.NewDecoder(resp.Body).Decode(&result)
|
||||
require.NoError(t, err)
|
||||
assert.NotEqual(t, 0, result.Code, "不存在的IMEI应返回错误码")
|
||||
})
|
||||
|
||||
t.Run("未认证请求-应返回错误", func(t *testing.T) {
|
||||
url := fmt.Sprintf("/api/admin/devices/by-imei/%s", device.DeviceNo)
|
||||
req := httptest.NewRequest("GET", url, nil)
|
||||
|
||||
resp, err := env.app.Test(req, -1)
|
||||
require.NoError(t, err)
|
||||
defer resp.Body.Close()
|
||||
|
||||
var result response.Response
|
||||
err = json.NewDecoder(resp.Body).Decode(&result)
|
||||
require.NoError(t, err)
|
||||
assert.NotEqual(t, 0, result.Code, "未认证请求应返回错误码")
|
||||
})
|
||||
}
|
||||
|
||||
@@ -42,8 +42,17 @@ type iotCardTestEnv struct {
|
||||
func setupIotCardTestEnv(t *testing.T) *iotCardTestEnv {
|
||||
t.Helper()
|
||||
|
||||
t.Setenv("CONFIG_ENV", "dev")
|
||||
t.Setenv("CONFIG_PATH", "../../configs/config.dev.yaml")
|
||||
// 设置测试环境变量
|
||||
t.Setenv("JUNHONG_DATABASE_HOST", "cxd.whcxd.cn")
|
||||
t.Setenv("JUNHONG_DATABASE_PORT", "16159")
|
||||
t.Setenv("JUNHONG_DATABASE_USER", "erp_pgsql")
|
||||
t.Setenv("JUNHONG_DATABASE_PASSWORD", "erp_2025")
|
||||
t.Setenv("JUNHONG_DATABASE_DBNAME", "junhong_cmp_test")
|
||||
t.Setenv("JUNHONG_REDIS_ADDRESS", "cxd.whcxd.cn")
|
||||
t.Setenv("JUNHONG_REDIS_PORT", "16299")
|
||||
t.Setenv("JUNHONG_REDIS_PASSWORD", "cpNbWtAaqgo1YJmbMp3h")
|
||||
t.Setenv("JUNHONG_JWT_SECRET_KEY", "test_secret_key_for_integration_tests")
|
||||
|
||||
cfg, err := config.Load()
|
||||
require.NoError(t, err)
|
||||
err = config.Set(cfg)
|
||||
@@ -565,3 +574,81 @@ func startTestWorker(t *testing.T, db *gorm.DB, rdb *redis.Client, logger *zap.L
|
||||
t.Logf("测试 Worker 服务器已启动")
|
||||
return workerServer
|
||||
}
|
||||
|
||||
func TestIotCard_GetByICCID(t *testing.T) {
|
||||
env := setupIotCardTestEnv(t)
|
||||
defer env.teardown()
|
||||
|
||||
// 创建测试运营商
|
||||
carrier := &model.Carrier{
|
||||
CarrierCode: "TEST001",
|
||||
CarrierName: "测试运营商",
|
||||
CarrierType: "CMCC",
|
||||
Status: 1,
|
||||
}
|
||||
require.NoError(t, env.db.Create(carrier).Error)
|
||||
|
||||
// 创建测试 IoT 卡
|
||||
card := &model.IotCard{
|
||||
ICCID: "TEST_ICCID_001",
|
||||
CarrierID: carrier.ID,
|
||||
MSISDN: "13800000001",
|
||||
CardType: "physical",
|
||||
CardCategory: "normal",
|
||||
CostPrice: 1000,
|
||||
DistributePrice: 1500,
|
||||
Status: 1,
|
||||
}
|
||||
require.NoError(t, env.db.Create(card).Error)
|
||||
|
||||
t.Run("通过ICCID查询单卡详情-成功", func(t *testing.T) {
|
||||
url := fmt.Sprintf("/api/admin/iot-cards/by-iccid/%s", card.ICCID)
|
||||
req := httptest.NewRequest("GET", url, nil)
|
||||
req.Header.Set("Authorization", "Bearer "+env.adminToken)
|
||||
|
||||
resp, err := env.app.Test(req, -1)
|
||||
require.NoError(t, err)
|
||||
defer resp.Body.Close()
|
||||
|
||||
assert.Equal(t, 200, resp.StatusCode)
|
||||
|
||||
var result response.Response
|
||||
err = json.NewDecoder(resp.Body).Decode(&result)
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, 0, result.Code)
|
||||
|
||||
// 验证返回数据
|
||||
dataMap, ok := result.Data.(map[string]interface{})
|
||||
require.True(t, ok)
|
||||
assert.Equal(t, "TEST_ICCID_001", dataMap["iccid"])
|
||||
assert.Equal(t, "13800000001", dataMap["msisdn"])
|
||||
})
|
||||
|
||||
t.Run("通过不存在的ICCID查询-应返回错误", func(t *testing.T) {
|
||||
req := httptest.NewRequest("GET", "/api/admin/iot-cards/by-iccid/NONEXISTENT_ICCID", nil)
|
||||
req.Header.Set("Authorization", "Bearer "+env.adminToken)
|
||||
|
||||
resp, err := env.app.Test(req, -1)
|
||||
require.NoError(t, err)
|
||||
defer resp.Body.Close()
|
||||
|
||||
var result response.Response
|
||||
err = json.NewDecoder(resp.Body).Decode(&result)
|
||||
require.NoError(t, err)
|
||||
assert.NotEqual(t, 0, result.Code, "不存在的ICCID应返回错误码")
|
||||
})
|
||||
|
||||
t.Run("未认证请求-应返回错误", func(t *testing.T) {
|
||||
url := fmt.Sprintf("/api/admin/iot-cards/by-iccid/%s", card.ICCID)
|
||||
req := httptest.NewRequest("GET", url, nil)
|
||||
|
||||
resp, err := env.app.Test(req, -1)
|
||||
require.NoError(t, err)
|
||||
defer resp.Body.Close()
|
||||
|
||||
var result response.Response
|
||||
err = json.NewDecoder(resp.Body).Decode(&result)
|
||||
require.NoError(t, err)
|
||||
assert.NotEqual(t, 0, result.Code, "未认证请求应返回错误码")
|
||||
})
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user