feat: 实现物联网卡独立管理和批量导入功能

新增物联网卡独立管理模块，支持单卡查询、批量导入和状态管理。主要变更包括：

功能特性：
- 新增物联网卡 CRUD 接口（查询、分页列表、删除）
- 支持 CSV/Excel 批量导入物联网卡
- 实现异步导入任务处理和进度跟踪
- 新增 ICCID 号码格式校验器（支持 Luhn 算法）
- 新增 CSV 文件解析工具（支持编码检测和错误处理）

数据库变更：
- 移除 iot_card 和 device 表的 owner_id/owner_type 字段
- 新增 iot_card_import_task 导入任务表
- 为导入任务添加运营商类型字段

测试覆盖：
- 新增 IoT 卡 Store 层单元测试
- 新增 IoT 卡导入任务单元测试
- 新增 IoT 卡集成测试（包含导入流程测试）
- 新增 CSV 工具和 ICCID 校验器测试

文档更新：
- 更新 OpenAPI 文档（新增 7 个 IoT 卡接口）
- 归档 OpenSpec 变更提案
- 更新 API 文档规范和生成器指南

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.claude/skills/api-routing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-routing
-description: API 路由注册规范。注册新 API 路由时使用。包含 Register() 函数用法、RouteSpec 必填项等规范。
+description: API 路由注册规范。注册新 API 路由、添加新 Handler 时使用。包含 Register() 函数用法、RouteSpec 必填项、文档生成器更新等规范。
 ---
 
 # API 路由注册规范
@@ -12,7 +12,29 @@ description: API 路由注册规范。注册新 API 路由时使用。包含 Reg
 在以下情况下必须遵守本规范：
 - 注册新的 API 路由
 - 修改现有路由配置
-- 添加新的 Handler 函数
+- **添加新的 Handler（必须同步更新文档生成器！）**
+
+## 新增 Handler 检查清单（⚠️ 最容易遗漏）
+
+新增 Handler 时，必须完成以下 **4 个步骤**，否则接口不会出现在 OpenAPI 文档中：
+
+| 步骤 | 文件 | 操作 |
+|------|------|------|
+| 1️⃣ | `internal/bootstrap/types.go` | 添加 Handler 字段 |
+| 2️⃣ | `internal/bootstrap/handlers.go` | 实例化 Handler |
+| 3️⃣ | `internal/routes/admin.go` | 调用路由注册函数 |
+| 4️⃣ | `cmd/api/docs.go` + `cmd/gendocs/main.go` | **添加到文档生成器** |
+
+### 步骤 4 详解（最常遗漏！）
+
+```go
+// cmd/api/docs.go 和 cmd/gendocs/main.go 都要改！
+handlers := &bootstrap.Handlers{
+    // ... 现有 Handler
+    IotCard:       admin.NewIotCardHandler(nil),       // 添加
+    IotCardImport: admin.NewIotCardImportHandler(nil), // 添加
+}
+```
 
 ## 核心规则
 
@@ -108,13 +130,22 @@ Register(router, doc, basePath, "GET", "/health", handler.Health, RouteSpec{
 
 ## AI 助手检查清单
 
-注册路由后必须检查：
+### 注册路由时
 
 1. ✅ 是否使用 `Register()` 函数而非直接注册
 2. ✅ `Summary` 是否使用中文简短描述
 3. ✅ `Tags` 是否正确分组
 4. ✅ `Input` 和 `Output` 是否指向正确的 DTO
 5. ✅ `Auth` 是否根据业务需求正确设置
+
+### 新增 Handler 时（⚠️ 必查）
+
+1. ✅ `internal/bootstrap/types.go` 添加了 Handler 字段
+2. ✅ `internal/bootstrap/handlers.go` 实例化了 Handler
+3. ✅ `internal/routes/admin.go` 调用了路由注册函数
+4. ✅ **`cmd/api/docs.go` 添加了 Handler**
+5. ✅ **`cmd/gendocs/main.go` 添加了 Handler**
 6. ✅ 运行 `go run cmd/gendocs/main.go` 验证文档生成
+7. ✅ 运行 `grep "接口路径" docs/admin-openapi.yaml` 确认接口存在
 
 **完整指南**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md)

AGENTS.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-检查清单)
+
 ---
 
 ## 语言要求

cmd/api/docs.go

@@ -38,6 +38,8 @@ func generateOpenAPIDocs(outputPath string, logger *zap.Logger) {
 		EnterpriseCard:              admin.NewEnterpriseCardHandler(nil),
 		CustomerAccount:             admin.NewCustomerAccountHandler(nil),
 		MyCommission:                admin.NewMyCommissionHandler(nil),
+		IotCard:                     admin.NewIotCardHandler(nil),
+		IotCardImport:               admin.NewIotCardImportHandler(nil),
 	}
 
 	// 4. 注册所有路由到文档生成器

cmd/api/main.go

@@ -61,6 +61,7 @@ func main() {
 		JWTManager:          jwtManager,
 		TokenManager:        tokenManager,
 		VerificationService: verificationSvc,
+		QueueClient:         queueClient,
 	})
 	if err != nil {
 		appLogger.Fatal("初始化业务组件失败", zap.Error(err))

cmd/gendocs/main.go

@@ -32,22 +32,23 @@ func generateAdminDocs(outputPath string) error {
 	app := fiber.New()
 
 	// 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构）
-	accHandler := admin.NewAccountHandler(nil)
-	roleHandler := admin.NewRoleHandler(nil)
-	permHandler := admin.NewPermissionHandler(nil)
-	adminAuthHandler := admin.NewAuthHandler(nil, nil)
-	h5AuthHandler := h5.NewAuthHandler(nil, nil)
-	shopHandler := admin.NewShopHandler(nil)
-	shopAccHandler := admin.NewShopAccountHandler(nil)
-
 	handlers := &bootstrap.Handlers{
-		Account:     accHandler,
+		AdminAuth:                   admin.NewAuthHandler(nil, nil),
-		Role:        roleHandler,
+		H5Auth:                      h5.NewAuthHandler(nil, nil),
-		Permission:  permHandler,
+		Account:                     admin.NewAccountHandler(nil),
-		AdminAuth:   adminAuthHandler,
+		Role:                        admin.NewRoleHandler(nil),
-		H5Auth:      h5AuthHandler,
+		Permission:                  admin.NewPermissionHandler(nil),
-		Shop:        shopHandler,
+		Shop:                        admin.NewShopHandler(nil),
-		ShopAccount: shopAccHandler,
+		ShopAccount:                 admin.NewShopAccountHandler(nil),
+		ShopCommission:              admin.NewShopCommissionHandler(nil),
+		CommissionWithdrawal:        admin.NewCommissionWithdrawalHandler(nil),
+		CommissionWithdrawalSetting: admin.NewCommissionWithdrawalSettingHandler(nil),
+		Enterprise:                  admin.NewEnterpriseHandler(nil),
+		EnterpriseCard:              admin.NewEnterpriseCardHandler(nil),
+		CustomerAccount:             admin.NewCustomerAccountHandler(nil),
+		MyCommission:                admin.NewMyCommissionHandler(nil),
+		IotCard:                     admin.NewIotCardHandler(nil),
+		IotCardImport:               admin.NewIotCardImportHandler(nil),
 	}
 
 	// 4. 注册所有路由到文档生成器

docs/api-documentation-guide.md

@@ -1,11 +1,12 @@
 # API 文档生成规范
 
-**版本**: 1.0  
+**版本**: 1.1  
-**最后更新**: 2026-01-21
+**最后更新**: 2026-01-24
 
 ## 目录
 
 - [核心原则](#核心原则)
+- [新增 Handler 检查清单](#新增-handler-检查清单)
 - [路由注册规范](#路由注册规范)
 - [DTO 规范](#dto-规范)
 - [文档生成流程](#文档生成流程)
@@ -42,6 +43,102 @@ router.Post("/path", handler.Method)
 
 ---
 
+## 新增 Handler 检查清单
+
+> ⚠️ **重要**: 新增 Handler 时，必须完成以下所有步骤，否则接口不会出现在 OpenAPI 文档中！
+
+### 必须完成的 4 个步骤
+
+| 步骤 | 文件位置 | 操作 |
+|------|---------|------|
+| 1️⃣ | `internal/bootstrap/types.go` | 在 `Handlers` 结构体中添加新 Handler 字段 |
+| 2️⃣ | `internal/bootstrap/handlers.go` | 实例化新 Handler |
+| 3️⃣ | `internal/routes/admin.go` | 调用路由注册函数 |
+| 4️⃣ | `cmd/api/docs.go` 和 `cmd/gendocs/main.go` | **添加 Handler 到文档生成器** |
+
+### 详细说明
+
+#### 步骤 1: 添加 Handler 字段
+
+```go
+// internal/bootstrap/types.go
+type Handlers struct {
+    // ... 现有 Handler
+    IotCard       *admin.IotCardHandler       // 新增
+    IotCardImport *admin.IotCardImportHandler // 新增
+}
+```
+
+#### 步骤 2: 实例化 Handler
+
+```go
+// internal/bootstrap/handlers.go
+func initHandlers(services *Services) *Handlers {
+    return &Handlers{
+        // ... 现有 Handler
+        IotCard:       admin.NewIotCardHandler(services.IotCard),
+        IotCardImport: admin.NewIotCardImportHandler(services.IotCardImport),
+    }
+}
+```
+
+#### 步骤 3: 调用路由注册
+
+```go
+// internal/routes/admin.go
+func RegisterAdminRoutes(...) {
+    // ... 现有路由
+    if handlers.IotCard != nil {
+        registerIotCardRoutes(authGroup, handlers.IotCard, handlers.IotCardImport, doc, basePath)
+    }
+}
+```
+
+#### 步骤 4: 更新文档生成器 ⚠️ 最容易遗漏！
+
+**必须同时更新两个文件：**
+
+```go
+// cmd/api/docs.go
+func generateOpenAPIDocs(outputPath string, logger *zap.Logger) {
+    handlers := &bootstrap.Handlers{
+        // ... 现有 Handler
+        IotCard:       admin.NewIotCardHandler(nil),       // 添加
+        IotCardImport: admin.NewIotCardImportHandler(nil), // 添加
+    }
+    // ...
+}
+```
+
+```go
+// cmd/gendocs/main.go
+func generateAdminDocs(outputPath string) error {
+    handlers := &bootstrap.Handlers{
+        // ... 现有 Handler
+        IotCard:       admin.NewIotCardHandler(nil),       // 添加
+        IotCardImport: admin.NewIotCardImportHandler(nil), // 添加
+    }
+    // ...
+}
+```
+
+### 验证检查
+
+完成上述步骤后，运行以下命令验证：
+
+```bash
+# 1. 编译检查
+go build ./...
+
+# 2. 重新生成文档
+go run cmd/gendocs/main.go
+
+# 3. 验证接口是否出现在文档中
+grep "你的接口路径" docs/admin-openapi.yaml
+```
+
+---
+
 ## 路由注册规范
 
 ### 1. 基本结构
@@ -265,9 +362,26 @@ handlers := &bootstrap.Handlers{
 
 ### Q1: 为什么我的接口没有出现在文档中？
 
-**检查清单**：
+> ⚠️ **最常见原因**: 忘记在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中添加新 Handler！
 
-1. ✅ 是否使用了 `Register()` 函数？
+**检查清单（按优先级排序）**：
+
+1. ✅ **【最常遗漏】** 是否在文档生成器中添加了 Handler？
+   
+   必须同时检查两个文件：
+   ```go
+   // cmd/api/docs.go
+   handlers := &bootstrap.Handlers{
+       Xxx: admin.NewXxxHandler(nil),  // 是否添加？
+   }
+   
+   // cmd/gendocs/main.go  
+   handlers := &bootstrap.Handlers{
+       Xxx: admin.NewXxxHandler(nil),  // 是否添加？
+   }
+   ```
+
+2. ✅ 是否使用了 `Register()` 函数？
    ```go
    // ❌ 错误
    router.Post("/path", handler.Method)
@@ -276,22 +390,21 @@ handlers := &bootstrap.Handlers{
    Register(router, doc, basePath, "POST", "/path", handler.Method, RouteSpec{...})
    ```
 
-2. ✅ 路由注册函数是否接收了 `doc *openapi.Generator` 参数？
+3. ✅ 路由注册函数是否接收了 `doc *openapi.Generator` 参数？
    ```go
    func registerXxxRoutes(router fiber.Router, handler *admin.XxxHandler, doc *openapi.Generator, basePath string)
    ```
 
-3. ✅ 是否在 `cmd/gendocs/main.go` 中创建了 Handler？
-   ```go
-   handlers := &bootstrap.Handlers{
-       Xxx: admin.NewXxxHandler(nil),
-   }
-   ```
-
 4. ✅ 是否调用了路由注册函数？
    - 检查 `internal/routes/admin.go` 中是否调用了 `registerXxxRoutes()`
    - 检查 `internal/routes/routes.go` 是否调用了 `RegisterAdminRoutes()`
 
+**快速定位问题**：
+```bash
+# 检查 Handler 是否在文档生成器中注册
+grep "NewXxxHandler" cmd/api/docs.go cmd/gendocs/main.go
+```
+
 ### Q2: 文档生成时报错 "undefined path parameter"？
 
 **原因**：路径参数（如 `/:id`）的 DTO 缺少对应字段。
@@ -335,23 +448,51 @@ Register(router, doc, basePath, "PUT", "/:id", handler.Update, RouteSpec{
 
 ### Q4: 如何为新模块添加路由？
 
-**步骤**：
+**完整步骤**（共 6 步）：
 
-1. 创建路由文件 `internal/routes/xxx.go`
+1. **创建 Handler**：`internal/handler/admin/xxx.go`
-2. 定义注册函数：
+
+2. **添加到 Handlers 结构体**：`internal/bootstrap/types.go`
+   ```go
+   type Handlers struct {
+       Xxx *admin.XxxHandler
+   }
+   ```
+
+3. **实例化 Handler**：`internal/bootstrap/handlers.go`
+   ```go
+   Xxx: admin.NewXxxHandler(services.Xxx),
+   ```
+
+4. **创建路由文件**：`internal/routes/xxx.go`
    ```go
    func registerXxxRoutes(api fiber.Router, h *admin.XxxHandler, doc *openapi.Generator, basePath string) {
        // 使用 Register() 注册路由
    }
    ```
-3. 在 `internal/routes/admin.go` 中调用：
+
+5. **调用路由注册**：`internal/routes/admin.go`
    ```go
    if handlers.Xxx != nil {
        registerXxxRoutes(authGroup, handlers.Xxx, doc, basePath)
    }
    ```
-4. 在 `cmd/gendocs/main.go` 中添加 Handler
+
-5. 重新生成文档验证
+6. **更新文档生成器**（⚠️ 两个文件都要改）：
+   - `cmd/api/docs.go`
+   - `cmd/gendocs/main.go`
+   ```go
+   handlers := &bootstrap.Handlers{
+       Xxx: admin.NewXxxHandler(nil),
+   }
+   ```
+
+7. **验证**：
+   ```bash
+   go build ./...
+   go run cmd/gendocs/main.go
+   grep "/api/admin/xxx" docs/admin-openapi.yaml
+   ```
 
 ### Q5: 如何调试文档生成？
 

internal/bootstrap/dependencies.go

@@ -3,6 +3,7 @@ package bootstrap
 import (
 	"github.com/break/junhong_cmp_fiber/internal/service/verification"
 	"github.com/break/junhong_cmp_fiber/pkg/auth"
+	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
@@ -17,4 +18,5 @@ type Dependencies struct {
 	JWTManager          *auth.JWTManager      // JWT 管理器（个人客户认证）
 	TokenManager        *auth.TokenManager    // Token 管理器（后台和H5认证）
 	VerificationService *verification.Service // 验证码服务
+	QueueClient         *queue.Client         // Asynq 任务队列客户端
 }

internal/bootstrap/handlers.go

@@ -26,5 +26,7 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		EnterpriseCard:              admin.NewEnterpriseCardHandler(svc.EnterpriseCard),
 		CustomerAccount:             admin.NewCustomerAccountHandler(svc.CustomerAccount),
 		MyCommission:                admin.NewMyCommissionHandler(svc.MyCommission),
+		IotCard:                     admin.NewIotCardHandler(svc.IotCard),
+		IotCardImport:               admin.NewIotCardImportHandler(svc.IotCardImport),
 	}
 }

internal/bootstrap/services.go

@@ -8,6 +8,8 @@ import (
 	customerAccountSvc "github.com/break/junhong_cmp_fiber/internal/service/customer_account"
 	enterpriseSvc "github.com/break/junhong_cmp_fiber/internal/service/enterprise"
 	enterpriseCardSvc "github.com/break/junhong_cmp_fiber/internal/service/enterprise_card"
+	iotCardSvc "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
+	iotCardImportSvc "github.com/break/junhong_cmp_fiber/internal/service/iot_card_import"
 	myCommissionSvc "github.com/break/junhong_cmp_fiber/internal/service/my_commission"
 	permissionSvc "github.com/break/junhong_cmp_fiber/internal/service/permission"
 	personalCustomerSvc "github.com/break/junhong_cmp_fiber/internal/service/personal_customer"
@@ -32,6 +34,8 @@ type services struct {
 	EnterpriseCard              *enterpriseCardSvc.Service
 	CustomerAccount             *customerAccountSvc.Service
 	MyCommission                *myCommissionSvc.Service
+	IotCard                     *iotCardSvc.Service
+	IotCardImport               *iotCardImportSvc.Service
 }
 
 func initServices(s *stores, deps *Dependencies) *services {
@@ -50,5 +54,7 @@ func initServices(s *stores, deps *Dependencies) *services {
 		EnterpriseCard:              enterpriseCardSvc.New(deps.DB, s.Enterprise, s.EnterpriseCardAuthorization),
 		CustomerAccount:             customerAccountSvc.New(deps.DB, s.Account, s.Shop, s.Enterprise),
 		MyCommission:                myCommissionSvc.New(deps.DB, s.Shop, s.Wallet, s.CommissionWithdrawalRequest, s.CommissionWithdrawalSetting, s.CommissionRecord, s.WalletTransaction),
+		IotCard:                     iotCardSvc.New(deps.DB, s.IotCard),
+		IotCardImport:               iotCardImportSvc.New(deps.DB, s.IotCardImportTask, deps.QueueClient),
 	}
 }

internal/bootstrap/stores.go

@@ -20,6 +20,8 @@ type stores struct {
 	CommissionWithdrawalSetting *postgres.CommissionWithdrawalSettingStore
 	Enterprise                  *postgres.EnterpriseStore
 	EnterpriseCardAuthorization *postgres.EnterpriseCardAuthorizationStore
+	IotCard                     *postgres.IotCardStore
+	IotCardImportTask           *postgres.IotCardImportTaskStore
 }
 
 func initStores(deps *Dependencies) *stores {
@@ -39,5 +41,7 @@ func initStores(deps *Dependencies) *stores {
 		CommissionWithdrawalSetting: postgres.NewCommissionWithdrawalSettingStore(deps.DB, deps.Redis),
 		Enterprise:                  postgres.NewEnterpriseStore(deps.DB, deps.Redis),
 		EnterpriseCardAuthorization: postgres.NewEnterpriseCardAuthorizationStore(deps.DB, deps.Redis),
+		IotCard:                     postgres.NewIotCardStore(deps.DB, deps.Redis),
+		IotCardImportTask:           postgres.NewIotCardImportTaskStore(deps.DB, deps.Redis),
 	}
 }

internal/bootstrap/types.go

@@ -24,6 +24,8 @@ type Handlers struct {
 	EnterpriseCard              *admin.EnterpriseCardHandler
 	CustomerAccount             *admin.CustomerAccountHandler
 	MyCommission                *admin.MyCommissionHandler
+	IotCard                     *admin.IotCardHandler
+	IotCardImport               *admin.IotCardImportHandler
 }
 
 // Middlewares 封装所有中间件

internal/handler/admin/iot_card.go

@@ -0,0 +1,32 @@
+package admin
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	iotCardService "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+)
+
+type IotCardHandler struct {
+	service *iotCardService.Service
+}
+
+func NewIotCardHandler(service *iotCardService.Service) *IotCardHandler {
+	return &IotCardHandler{service: service}
+}
+
+func (h *IotCardHandler) ListStandalone(c *fiber.Ctx) error {
+	var req dto.ListStandaloneIotCardRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+
+	result, err := h.service.ListStandalone(c.UserContext(), &req)
+	if err != nil {
+		return err
+	}
+
+	return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
+}

internal/handler/admin/iot_card_import.go

@@ -0,0 +1,74 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	iotCardImportService "github.com/break/junhong_cmp_fiber/internal/service/iot_card_import"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+)
+
+type IotCardImportHandler struct {
+	service *iotCardImportService.Service
+}
+
+func NewIotCardImportHandler(service *iotCardImportService.Service) *IotCardImportHandler {
+	return &IotCardImportHandler{service: service}
+}
+
+func (h *IotCardImportHandler) Import(c *fiber.Ctx) error {
+	var req dto.ImportIotCardRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+
+	file, err := c.FormFile("file")
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam, "请上传 CSV 文件")
+	}
+
+	f, err := file.Open()
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam, "无法读取上传文件")
+	}
+	defer f.Close()
+
+	result, err := h.service.CreateImportTask(c.UserContext(), &req, f, file.Filename)
+	if err != nil {
+		return err
+	}
+
+	return response.Success(c, result)
+}
+
+func (h *IotCardImportHandler) List(c *fiber.Ctx) error {
+	var req dto.ListImportTaskRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+
+	result, err := h.service.List(c.UserContext(), &req)
+	if err != nil {
+		return err
+	}
+
+	return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
+}
+
+func (h *IotCardImportHandler) GetByID(c *fiber.Ctx) error {
+	idStr := c.Params("id")
+	id, err := strconv.ParseUint(idStr, 10, 64)
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam, "无效的任务ID")
+	}
+
+	result, err := h.service.GetByID(c.UserContext(), uint(id))
+	if err != nil {
+		return err
+	}
+
+	return response.Success(c, result)
+}

internal/model/device.go

@@ -8,7 +8,7 @@ import (
 
 // Device 设备模型
 // 物联网设备(如 GPS 追踪器、智能传感器)
-// 可绑定 1-4 张 IoT 卡,主要用于批量管理和设备操作
+// 通过 shop_id 区分所有权：NULL=平台库存，有值=店铺所有
 type Device struct {
 	gorm.Model
 	BaseModel               `gorm:"embedded"`
@@ -19,9 +19,7 @@ type Device struct {
 	MaxSimSlots             int        `gorm:"column:max_sim_slots;type:int;default:4;comment:最大插槽数量(默认4)" json:"max_sim_slots"`
 	Manufacturer            string     `gorm:"column:manufacturer;type:varchar(255);comment:制造商" json:"manufacturer"`
 	BatchNo                 string     `gorm:"column:batch_no;type:varchar(100);comment:批次号" json:"batch_no"`
-	OwnerType               string     `gorm:"column:owner_type;type:varchar(20);default:'platform';not null;comment:所有者类型 platform-平台 shop-店铺" json:"owner_type"`
+	ShopID                  *uint      `gorm:"column:shop_id;index;comment:店铺ID(NULL=平台库存,有值=店铺所有)" json:"shop_id,omitempty"`
-	OwnerID                 uint       `gorm:"column:owner_id;index;default:0;not null;comment:所有者ID" json:"owner_id"`
-	ShopID                  *uint      `gorm:"column:shop_id;index;comment:店铺ID（冗余字段，方便查询）" json:"shop_id,omitempty"`
 	Status                  int        `gorm:"column:status;type:int;default:1;not null;comment:状态 1-在库 2-已分销 3-已激活 4-已停用" json:"status"`
 	ActivatedAt             *time.Time `gorm:"column:activated_at;comment:激活时间" json:"activated_at"`
 	DeviceUsername          string     `gorm:"column:device_username;type:varchar(100);comment:设备登录用户名" json:"device_username"`

internal/model/dto/iot_card_dto.go

@@ -0,0 +1,116 @@
+package dto
+
+import "time"
+
+type ListStandaloneIotCardRequest struct {
+	Page          int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+	PageSize      int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
+	Status        *int   `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
+	CarrierID     *uint  `json:"carrier_id" query:"carrier_id" description:"运营商ID"`
+	ShopID        *uint  `json:"shop_id" query:"shop_id" description:"分销商ID"`
+	ICCID         string `json:"iccid" query:"iccid" validate:"omitempty,max=20" maxLength:"20" description:"ICCID(模糊查询)"`
+	MSISDN        string `json:"msisdn" query:"msisdn" validate:"omitempty,max=20" maxLength:"20" description:"卡接入号(模糊查询)"`
+	BatchNo       string `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"`
+	PackageID     *uint  `json:"package_id" query:"package_id" description:"套餐ID"`
+	IsDistributed *bool  `json:"is_distributed" query:"is_distributed" description:"是否已分销 (true:已分销, false:未分销)"`
+	IsReplaced    *bool  `json:"is_replaced" query:"is_replaced" description:"是否有换卡记录 (true:有换卡记录, false:无换卡记录)"`
+	ICCIDStart    string `json:"iccid_start" query:"iccid_start" validate:"omitempty,max=20" maxLength:"20" description:"ICCID起始号"`
+	ICCIDEnd      string `json:"iccid_end" query:"iccid_end" validate:"omitempty,max=20" maxLength:"20" description:"ICCID结束号"`
+}
+
+type StandaloneIotCardResponse struct {
+	ID               uint       `json:"id" description:"卡ID"`
+	ICCID            string     `json:"iccid" description:"ICCID"`
+	CardType         string     `json:"card_type" description:"卡类型"`
+	CardCategory     string     `json:"card_category" description:"卡业务类型 (normal:普通卡, industry:行业卡)"`
+	CarrierID        uint       `json:"carrier_id" description:"运营商ID"`
+	CarrierName      string     `json:"carrier_name,omitempty" description:"运营商名称"`
+	IMSI             string     `json:"imsi,omitempty" description:"IMSI"`
+	MSISDN           string     `json:"msisdn,omitempty" description:"卡接入号"`
+	BatchNo          string     `json:"batch_no,omitempty" description:"批次号"`
+	Supplier         string     `json:"supplier,omitempty" description:"供应商"`
+	CostPrice        int64      `json:"cost_price" description:"成本价(分)"`
+	DistributePrice  int64      `json:"distribute_price" description:"分销价(分)"`
+	Status           int        `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"`
+	ShopID           *uint      `json:"shop_id,omitempty" description:"店铺ID"`
+	ShopName         string     `json:"shop_name,omitempty" description:"店铺名称"`
+	ActivatedAt      *time.Time `json:"activated_at,omitempty" description:"激活时间"`
+	ActivationStatus int        `json:"activation_status" description:"激活状态 (0:未激活, 1:已激活)"`
+	RealNameStatus   int        `json:"real_name_status" description:"实名状态 (0:未实名, 1:已实名)"`
+	NetworkStatus    int        `json:"network_status" description:"网络状态 (0:停机, 1:开机)"`
+	DataUsageMB      int64      `json:"data_usage_mb" description:"累计流量使用(MB)"`
+	CreatedAt        time.Time  `json:"created_at" description:"创建时间"`
+	UpdatedAt        time.Time  `json:"updated_at" description:"更新时间"`
+}
+
+type ListStandaloneIotCardResponse struct {
+	List       []*StandaloneIotCardResponse `json:"list" description:"单卡列表"`
+	Total      int64                        `json:"total" description:"总数"`
+	Page       int                          `json:"page" description:"当前页码"`
+	PageSize   int                          `json:"page_size" description:"每页数量"`
+	TotalPages int                          `json:"total_pages" description:"总页数"`
+}
+
+type ImportIotCardRequest struct {
+	CarrierID uint   `json:"carrier_id" form:"carrier_id" validate:"required,min=1" required:"true" minimum:"1" description:"运营商ID"`
+	BatchNo   string `json:"batch_no" form:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"`
+}
+
+type ImportIotCardResponse struct {
+	TaskID  uint   `json:"task_id" description:"导入任务ID"`
+	TaskNo  string `json:"task_no" description:"任务编号"`
+	Message string `json:"message" description:"提示信息"`
+}
+
+type ListImportTaskRequest struct {
+	Page      int        `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+	PageSize  int        `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
+	Status    *int       `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"任务状态 (1:待处理, 2:处理中, 3:已完成, 4:失败)"`
+	CarrierID *uint      `json:"carrier_id" query:"carrier_id" description:"运营商ID"`
+	BatchNo   string     `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号(模糊查询)"`
+	StartTime *time.Time `json:"start_time" query:"start_time" description:"创建时间起始"`
+	EndTime   *time.Time `json:"end_time" query:"end_time" description:"创建时间结束"`
+}
+
+type ImportTaskResponse struct {
+	ID           uint       `json:"id" description:"任务ID"`
+	TaskNo       string     `json:"task_no" description:"任务编号"`
+	Status       int        `json:"status" description:"任务状态 (1:待处理, 2:处理中, 3:已完成, 4:失败)"`
+	StatusText   string     `json:"status_text" description:"任务状态文本"`
+	CarrierID    uint       `json:"carrier_id" description:"运营商ID"`
+	CarrierName  string     `json:"carrier_name,omitempty" description:"运营商名称"`
+	BatchNo      string     `json:"batch_no,omitempty" description:"批次号"`
+	FileName     string     `json:"file_name,omitempty" description:"文件名"`
+	TotalCount   int        `json:"total_count" description:"总数"`
+	SuccessCount int        `json:"success_count" description:"成功数"`
+	SkipCount    int        `json:"skip_count" description:"跳过数"`
+	FailCount    int        `json:"fail_count" description:"失败数"`
+	StartedAt    *time.Time `json:"started_at,omitempty" description:"开始处理时间"`
+	CompletedAt  *time.Time `json:"completed_at,omitempty" description:"完成时间"`
+	ErrorMessage string     `json:"error_message,omitempty" description:"错误信息"`
+	CreatedAt    time.Time  `json:"created_at" description:"创建时间"`
+}
+
+type ListImportTaskResponse struct {
+	List       []*ImportTaskResponse `json:"list" description:"任务列表"`
+	Total      int64                 `json:"total" description:"总数"`
+	Page       int                   `json:"page" description:"当前页码"`
+	PageSize   int                   `json:"page_size" description:"每页数量"`
+	TotalPages int                   `json:"total_pages" description:"总页数"`
+}
+
+type ImportResultItemDTO struct {
+	Line   int    `json:"line" description:"行号"`
+	ICCID  string `json:"iccid" description:"ICCID"`
+	Reason string `json:"reason" description:"原因"`
+}
+
+type ImportTaskDetailResponse struct {
+	ImportTaskResponse
+	SkippedItems []*ImportResultItemDTO `json:"skipped_items" description:"跳过记录详情"`
+	FailedItems  []*ImportResultItemDTO `json:"failed_items" description:"失败记录详情"`
+}
+
+type GetImportTaskRequest struct {
+	ID uint `path:"id" description:"任务ID" required:"true"`
+}

internal/model/iot_card.go

@@ -8,11 +8,11 @@ import (
 
 // IotCard IoT 卡模型
 // 物联网卡/流量卡的统一管理实体
-// 支持平台自营、代理分销等所有权模式
+// 通过 shop_id 区分所有权：NULL=平台所有，有值=店铺所有
 type IotCard struct {
 	gorm.Model
 	BaseModel           `gorm:"embedded"`
-	ICCID               string     `gorm:"column:iccid;type:varchar(50);uniqueIndex:idx_iot_card_iccid,where:deleted_at IS NULL;not null;comment:ICCID(唯一标识)" json:"iccid"`
+	ICCID               string     `gorm:"column:iccid;type:varchar(20);uniqueIndex:idx_iot_card_iccid,where:deleted_at IS NULL;not null;comment:ICCID(唯一标识,电信19位/其他20位)" json:"iccid"`
 	CardType            string     `gorm:"column:card_type;type:varchar(50);not null;comment:卡类型" json:"card_type"`
 	CardCategory        string     `gorm:"column:card_category;type:varchar(20);default:'normal';not null;comment:卡业务类型 normal-普通卡 industry-行业卡" json:"card_category"`
 	CarrierID           uint       `gorm:"column:carrier_id;index;not null;comment:运营商ID" json:"carrier_id"`
@@ -23,9 +23,7 @@ type IotCard struct {
 	CostPrice           int64      `gorm:"column:cost_price;type:bigint;default:0;comment:成本价(分为单位)" json:"cost_price"`
 	DistributePrice     int64      `gorm:"column:distribute_price;type:bigint;default:0;comment:分销价(分为单位)" json:"distribute_price"`
 	Status              int        `gorm:"column:status;type:int;default:1;not null;comment:状态 1-在库 2-已分销 3-已激活 4-已停用" json:"status"`
-	OwnerType           string     `gorm:"column:owner_type;type:varchar(20);default:'platform';not null;comment:所有者类型 platform-平台 shop-店铺" json:"owner_type"`
+	ShopID              *uint      `gorm:"column:shop_id;index;comment:店铺ID(NULL=平台所有,有值=店铺所有)" json:"shop_id,omitempty"`
-	OwnerID             uint       `gorm:"column:owner_id;index;default:0;not null;comment:所有者ID" json:"owner_id"`
-	ShopID              *uint      `gorm:"column:shop_id;index;comment:店铺ID（冗余字段，方便查询）" json:"shop_id,omitempty"`
 	ActivatedAt         *time.Time `gorm:"column:activated_at;comment:激活时间" json:"activated_at"`
 	ActivationStatus    int        `gorm:"column:activation_status;type:int;default:0;not null;comment:激活状态 0-未激活 1-已激活" json:"activation_status"`
 	RealNameStatus      int        `gorm:"column:real_name_status;type:int;default:0;not null;comment:实名状态 0-未实名 1-已实名(行业卡可以保持0)" json:"real_name_status"`

internal/model/iot_card_import_task.go

@@ -0,0 +1,90 @@
+package model
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+type IotCardImportTask struct {
+	gorm.Model
+	BaseModel    `gorm:"embedded"`
+	TaskNo       string            `gorm:"column:task_no;type:varchar(50);uniqueIndex:idx_import_task_no,where:deleted_at IS NULL;not null;comment:任务编号(IMP-YYYYMMDD-XXXXXX)" json:"task_no"`
+	Status       int               `gorm:"column:status;type:int;default:1;not null;comment:任务状态 1-待处理 2-处理中 3-已完成 4-失败" json:"status"`
+	CarrierID    uint              `gorm:"column:carrier_id;index;not null;comment:运营商ID" json:"carrier_id"`
+	CarrierType  string            `gorm:"column:carrier_type;type:varchar(20);not null;comment:运营商类型(CMCC/CUCC/CTCC/CBN)" json:"carrier_type"`
+	BatchNo      string            `gorm:"column:batch_no;type:varchar(100);comment:批次号" json:"batch_no"`
+	FileName     string            `gorm:"column:file_name;type:varchar(255);comment:原始文件名" json:"file_name"`
+	TotalCount   int               `gorm:"column:total_count;type:int;default:0;not null;comment:总数" json:"total_count"`
+	SuccessCount int               `gorm:"column:success_count;type:int;default:0;not null;comment:成功数" json:"success_count"`
+	SkipCount    int               `gorm:"column:skip_count;type:int;default:0;not null;comment:跳过数" json:"skip_count"`
+	FailCount    int               `gorm:"column:fail_count;type:int;default:0;not null;comment:失败数" json:"fail_count"`
+	SkippedItems ImportResultItems `gorm:"column:skipped_items;type:jsonb;comment:跳过记录详情" json:"skipped_items"`
+	FailedItems  ImportResultItems `gorm:"column:failed_items;type:jsonb;comment:失败记录详情" json:"failed_items"`
+	StartedAt    *time.Time        `gorm:"column:started_at;comment:开始处理时间" json:"started_at"`
+	CompletedAt  *time.Time        `gorm:"column:completed_at;comment:完成时间" json:"completed_at"`
+	ErrorMessage string            `gorm:"column:error_message;type:text;comment:任务级错误信息" json:"error_message"`
+	ShopID       *uint             `gorm:"column:shop_id;index;comment:店铺ID(发起导入的店铺)" json:"shop_id,omitempty"`
+	ICCIDList    ICCIDListJSON     `gorm:"column:iccid_list;type:jsonb;comment:待导入ICCID列表" json:"-"`
+}
+
+type ICCIDListJSON []string
+
+func (list ICCIDListJSON) Value() (driver.Value, error) {
+	if list == nil {
+		return "[]", nil
+	}
+	return json.Marshal(list)
+}
+
+func (list *ICCIDListJSON) Scan(value any) error {
+	if value == nil {
+		*list = ICCIDListJSON{}
+		return nil
+	}
+	bytes, ok := value.([]byte)
+	if !ok {
+		return nil
+	}
+	return json.Unmarshal(bytes, list)
+}
+
+func (IotCardImportTask) TableName() string {
+	return "tb_iot_card_import_task"
+}
+
+type ImportResultItem struct {
+	Line   int    `json:"line"`
+	ICCID  string `json:"iccid"`
+	Reason string `json:"reason"`
+}
+
+type ImportResultItems []ImportResultItem
+
+func (items ImportResultItems) Value() (driver.Value, error) {
+	if items == nil {
+		return "[]", nil
+	}
+	return json.Marshal(items)
+}
+
+func (items *ImportResultItems) Scan(value any) error {
+	if value == nil {
+		*items = ImportResultItems{}
+		return nil
+	}
+	bytes, ok := value.([]byte)
+	if !ok {
+		return nil
+	}
+	return json.Unmarshal(bytes, items)
+}
+
+const (
+	ImportTaskStatusPending    = 1
+	ImportTaskStatusProcessing = 2
+	ImportTaskStatusCompleted  = 3
+	ImportTaskStatusFailed     = 4
+)

internal/routes/admin.go

@@ -52,6 +52,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 	if handlers.MyCommission != nil {
 		registerMyCommissionRoutes(authGroup, handlers.MyCommission, doc, basePath)
 	}
+	if handlers.IotCard != nil {
+		registerIotCardRoutes(authGroup, handlers.IotCard, handlers.IotCardImport, doc, basePath)
+	}
 }
 
 func registerAdminAuthRoutes(router fiber.Router, handler interface{}, authMiddleware fiber.Handler, doc *openapi.Generator, basePath string) {

internal/routes/iot_card.go

@@ -0,0 +1,46 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+func registerIotCardRoutes(router fiber.Router, handler *admin.IotCardHandler, importHandler *admin.IotCardImportHandler, doc *openapi.Generator, basePath string) {
+	iotCards := router.Group("/iot-cards")
+	groupPath := basePath + "/iot-cards"
+
+	Register(iotCards, doc, groupPath, "GET", "/standalone", handler.ListStandalone, RouteSpec{
+		Summary: "单卡列表（未绑定设备）",
+		Tags:    []string{"IoT卡管理"},
+		Input:   new(dto.ListStandaloneIotCardRequest),
+		Output:  new(dto.ListStandaloneIotCardResponse),
+		Auth:    true,
+	})
+
+	Register(iotCards, doc, groupPath, "POST", "/import", importHandler.Import, RouteSpec{
+		Summary: "批量导入ICCID",
+		Tags:    []string{"IoT卡管理"},
+		Input:   new(dto.ImportIotCardRequest),
+		Output:  new(dto.ImportIotCardResponse),
+		Auth:    true,
+	})
+
+	Register(iotCards, doc, groupPath, "GET", "/import-tasks", importHandler.List, RouteSpec{
+		Summary: "导入任务列表",
+		Tags:    []string{"IoT卡管理"},
+		Input:   new(dto.ListImportTaskRequest),
+		Output:  new(dto.ListImportTaskResponse),
+		Auth:    true,
+	})
+
+	Register(iotCards, doc, groupPath, "GET", "/import-tasks/:id", importHandler.GetByID, RouteSpec{
+		Summary: "导入任务详情",
+		Tags:    []string{"IoT卡管理"},
+		Input:   new(dto.GetImportTaskRequest),
+		Output:  new(dto.ImportTaskDetailResponse),
+		Auth:    true,
+	})
+}

internal/service/iot_card/service.go

@@ -0,0 +1,171 @@
+package iot_card
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/internal/store"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"gorm.io/gorm"
+)
+
+type Service struct {
+	db           *gorm.DB
+	iotCardStore *postgres.IotCardStore
+}
+
+func New(db *gorm.DB, iotCardStore *postgres.IotCardStore) *Service {
+	return &Service{
+		db:           db,
+		iotCardStore: iotCardStore,
+	}
+}
+
+func (s *Service) ListStandalone(ctx context.Context, req *dto.ListStandaloneIotCardRequest) (*dto.ListStandaloneIotCardResponse, error) {
+	page := req.Page
+	pageSize := req.PageSize
+	if page == 0 {
+		page = 1
+	}
+	if pageSize == 0 {
+		pageSize = constants.DefaultPageSize
+	}
+
+	opts := &store.QueryOptions{
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	filters := make(map[string]interface{})
+	if req.Status != nil {
+		filters["status"] = *req.Status
+	}
+	if req.CarrierID != nil {
+		filters["carrier_id"] = *req.CarrierID
+	}
+	if req.ShopID != nil {
+		filters["shop_id"] = *req.ShopID
+	}
+	if req.ICCID != "" {
+		filters["iccid"] = req.ICCID
+	}
+	if req.MSISDN != "" {
+		filters["msisdn"] = req.MSISDN
+	}
+	if req.BatchNo != "" {
+		filters["batch_no"] = req.BatchNo
+	}
+	if req.PackageID != nil {
+		filters["package_id"] = *req.PackageID
+	}
+	if req.IsDistributed != nil {
+		filters["is_distributed"] = *req.IsDistributed
+	}
+	if req.ICCIDStart != "" {
+		filters["iccid_start"] = req.ICCIDStart
+	}
+	if req.ICCIDEnd != "" {
+		filters["iccid_end"] = req.ICCIDEnd
+	}
+	if req.IsReplaced != nil {
+		filters["is_replaced"] = *req.IsReplaced
+	}
+
+	cards, total, err := s.iotCardStore.ListStandalone(ctx, opts, filters)
+	if err != nil {
+		return nil, err
+	}
+
+	carrierMap, shopMap := s.loadRelatedData(ctx, cards)
+
+	list := make([]*dto.StandaloneIotCardResponse, 0, len(cards))
+	for _, card := range cards {
+		item := s.toStandaloneResponse(card, carrierMap, shopMap)
+		list = append(list, item)
+	}
+
+	totalPages := int(total) / pageSize
+	if int(total)%pageSize > 0 {
+		totalPages++
+	}
+
+	return &dto.ListStandaloneIotCardResponse{
+		List:       list,
+		Total:      total,
+		Page:       page,
+		PageSize:   pageSize,
+		TotalPages: totalPages,
+	}, 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)
+	carrierIDSet := make(map[uint]bool)
+	shopIDSet := make(map[uint]bool)
+
+	for _, card := range cards {
+		if card.CarrierID > 0 && !carrierIDSet[card.CarrierID] {
+			carrierIDs = append(carrierIDs, card.CarrierID)
+			carrierIDSet[card.CarrierID] = true
+		}
+		if card.ShopID != nil && *card.ShopID > 0 && !shopIDSet[*card.ShopID] {
+			shopIDs = append(shopIDs, *card.ShopID)
+			shopIDSet[*card.ShopID] = true
+		}
+	}
+
+	carrierMap := make(map[uint]string)
+	if len(carrierIDs) > 0 {
+		var carriers []model.Carrier
+		s.db.WithContext(ctx).Where("id IN ?", carrierIDs).Find(&carriers)
+		for _, c := range carriers {
+			carrierMap[c.ID] = c.CarrierName
+		}
+	}
+
+	shopMap := make(map[uint]string)
+	if len(shopIDs) > 0 {
+		var shops []model.Shop
+		s.db.WithContext(ctx).Where("id IN ?", shopIDs).Find(&shops)
+		for _, shop := range shops {
+			shopMap[shop.ID] = shop.ShopName
+		}
+	}
+
+	return carrierMap, shopMap
+}
+
+func (s *Service) toStandaloneResponse(card *model.IotCard, carrierMap map[uint]string, shopMap map[uint]string) *dto.StandaloneIotCardResponse {
+	resp := &dto.StandaloneIotCardResponse{
+		ID:               card.ID,
+		ICCID:            card.ICCID,
+		CardType:         card.CardType,
+		CardCategory:     card.CardCategory,
+		CarrierID:        card.CarrierID,
+		CarrierName:      carrierMap[card.CarrierID],
+		IMSI:             card.IMSI,
+		MSISDN:           card.MSISDN,
+		BatchNo:          card.BatchNo,
+		Supplier:         card.Supplier,
+		CostPrice:        card.CostPrice,
+		DistributePrice:  card.DistributePrice,
+		Status:           card.Status,
+		ShopID:           card.ShopID,
+		ActivatedAt:      card.ActivatedAt,
+		ActivationStatus: card.ActivationStatus,
+		RealNameStatus:   card.RealNameStatus,
+		NetworkStatus:    card.NetworkStatus,
+		DataUsageMB:      card.DataUsageMB,
+		CreatedAt:        card.CreatedAt,
+		UpdatedAt:        card.UpdatedAt,
+	}
+
+	if card.ShopID != nil && *card.ShopID > 0 {
+		resp.ShopName = shopMap[*card.ShopID]
+	}
+
+	return resp
+}

internal/service/iot_card_import/service.go

@@ -0,0 +1,275 @@
+package iot_card_import
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/internal/store"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/pkg/queue"
+	"github.com/break/junhong_cmp_fiber/pkg/utils"
+	"gorm.io/gorm"
+)
+
+type Service struct {
+	db              *gorm.DB
+	importTaskStore *postgres.IotCardImportTaskStore
+	carrierStore    carrierGetter
+	queueClient     *queue.Client
+}
+
+type carrierGetter interface {
+	GetByID(ctx context.Context, id uint) (*model.Carrier, error)
+}
+
+type CarrierStore struct {
+	db *gorm.DB
+}
+
+func NewCarrierStore(db *gorm.DB) *CarrierStore {
+	return &CarrierStore{db: db}
+}
+
+func (s *CarrierStore) GetByID(ctx context.Context, id uint) (*model.Carrier, error) {
+	var carrier model.Carrier
+	if err := s.db.WithContext(ctx).First(&carrier, id).Error; err != nil {
+		return nil, err
+	}
+	return &carrier, nil
+}
+
+func New(db *gorm.DB, importTaskStore *postgres.IotCardImportTaskStore, queueClient *queue.Client) *Service {
+	return &Service{
+		db:              db,
+		importTaskStore: importTaskStore,
+		carrierStore:    NewCarrierStore(db),
+		queueClient:     queueClient,
+	}
+}
+
+type IotCardImportPayload struct {
+	TaskID uint `json:"task_id"`
+}
+
+func (s *Service) CreateImportTask(ctx context.Context, req *dto.ImportIotCardRequest, csvReader io.Reader, fileName string) (*dto.ImportIotCardResponse, error) {
+	userID := middleware.GetUserIDFromContext(ctx)
+	if userID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized, "未授权访问")
+	}
+
+	carrier, err := s.carrierStore.GetByID(ctx, req.CarrierID)
+	if err != nil {
+		return nil, errors.New(errors.CodeInvalidParam, "运营商不存在")
+	}
+
+	parseResult, err := utils.ParseICCIDFromCSV(csvReader)
+	if err != nil {
+		return nil, errors.New(errors.CodeInvalidParam, "CSV 解析失败: "+err.Error())
+	}
+
+	if parseResult.TotalCount == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "CSV 文件中没有有效的 ICCID")
+	}
+
+	taskNo := s.importTaskStore.GenerateTaskNo(ctx)
+
+	task := &model.IotCardImportTask{
+		TaskNo:       taskNo,
+		Status:       model.ImportTaskStatusPending,
+		CarrierID:    req.CarrierID,
+		CarrierType:  carrier.CarrierType,
+		BatchNo:      req.BatchNo,
+		FileName:     fileName,
+		TotalCount:   parseResult.TotalCount,
+		SuccessCount: 0,
+		SkipCount:    0,
+		FailCount:    0,
+		ICCIDList:    model.ICCIDListJSON(parseResult.ICCIDs),
+	}
+	task.Creator = userID
+	task.Updater = userID
+
+	if err := s.importTaskStore.Create(ctx, task); err != nil {
+		return nil, fmt.Errorf("创建导入任务失败: %w", err)
+	}
+
+	payload := IotCardImportPayload{TaskID: task.ID}
+	err = s.queueClient.EnqueueTask(ctx, constants.TaskTypeIotCardImport, payload)
+	if err != nil {
+		s.importTaskStore.UpdateStatus(ctx, task.ID, model.ImportTaskStatusFailed, "任务入队失败: "+err.Error())
+		return nil, fmt.Errorf("任务入队失败: %w", err)
+	}
+
+	return &dto.ImportIotCardResponse{
+		TaskID:  task.ID,
+		TaskNo:  taskNo,
+		Message: fmt.Sprintf("导入任务已创建，共 %d 条 ICCID 待处理", parseResult.TotalCount),
+	}, nil
+}
+
+func (s *Service) List(ctx context.Context, req *dto.ListImportTaskRequest) (*dto.ListImportTaskResponse, error) {
+	page := req.Page
+	pageSize := req.PageSize
+	if page == 0 {
+		page = 1
+	}
+	if pageSize == 0 {
+		pageSize = constants.DefaultPageSize
+	}
+
+	opts := &store.QueryOptions{
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	filters := make(map[string]interface{})
+	if req.Status != nil {
+		filters["status"] = *req.Status
+	}
+	if req.CarrierID != nil {
+		filters["carrier_id"] = *req.CarrierID
+	}
+	if req.BatchNo != "" {
+		filters["batch_no"] = req.BatchNo
+	}
+	if req.StartTime != nil {
+		filters["start_time"] = *req.StartTime
+	}
+	if req.EndTime != nil {
+		filters["end_time"] = *req.EndTime
+	}
+
+	tasks, total, err := s.importTaskStore.List(ctx, opts, filters)
+	if err != nil {
+		return nil, err
+	}
+
+	carrierMap := s.loadCarriers(ctx, tasks)
+
+	list := make([]*dto.ImportTaskResponse, 0, len(tasks))
+	for _, task := range tasks {
+		list = append(list, s.toTaskResponse(task, carrierMap))
+	}
+
+	totalPages := int(total) / pageSize
+	if int(total)%pageSize > 0 {
+		totalPages++
+	}
+
+	return &dto.ListImportTaskResponse{
+		List:       list,
+		Total:      total,
+		Page:       page,
+		PageSize:   pageSize,
+		TotalPages: totalPages,
+	}, nil
+}
+
+func (s *Service) GetByID(ctx context.Context, id uint) (*dto.ImportTaskDetailResponse, error) {
+	task, err := s.importTaskStore.GetByID(ctx, id)
+	if err != nil {
+		return nil, errors.New(errors.CodeNotFound, "导入任务不存在")
+	}
+
+	carrierMap := make(map[uint]string)
+	var carrier model.Carrier
+	if s.db.WithContext(ctx).First(&carrier, task.CarrierID).Error == nil {
+		carrierMap[carrier.ID] = carrier.CarrierName
+	}
+
+	resp := &dto.ImportTaskDetailResponse{
+		ImportTaskResponse: *s.toTaskResponse(task, carrierMap),
+		SkippedItems:       make([]*dto.ImportResultItemDTO, 0),
+		FailedItems:        make([]*dto.ImportResultItemDTO, 0),
+	}
+
+	for _, item := range task.SkippedItems {
+		resp.SkippedItems = append(resp.SkippedItems, &dto.ImportResultItemDTO{
+			Line:   item.Line,
+			ICCID:  item.ICCID,
+			Reason: item.Reason,
+		})
+	}
+
+	for _, item := range task.FailedItems {
+		resp.FailedItems = append(resp.FailedItems, &dto.ImportResultItemDTO{
+			Line:   item.Line,
+			ICCID:  item.ICCID,
+			Reason: item.Reason,
+		})
+	}
+
+	return resp, nil
+}
+
+func (s *Service) loadCarriers(ctx context.Context, tasks []*model.IotCardImportTask) map[uint]string {
+	carrierIDs := make([]uint, 0)
+	carrierIDSet := make(map[uint]bool)
+	for _, task := range tasks {
+		if task.CarrierID > 0 && !carrierIDSet[task.CarrierID] {
+			carrierIDs = append(carrierIDs, task.CarrierID)
+			carrierIDSet[task.CarrierID] = true
+		}
+	}
+
+	carrierMap := make(map[uint]string)
+	if len(carrierIDs) > 0 {
+		var carriers []model.Carrier
+		s.db.WithContext(ctx).Where("id IN ?", carrierIDs).Find(&carriers)
+		for _, c := range carriers {
+			carrierMap[c.ID] = c.CarrierName
+		}
+	}
+	return carrierMap
+}
+
+func (s *Service) toTaskResponse(task *model.IotCardImportTask, carrierMap map[uint]string) *dto.ImportTaskResponse {
+	var startedAt, completedAt *time.Time
+	if task.StartedAt != nil {
+		startedAt = task.StartedAt
+	}
+	if task.CompletedAt != nil {
+		completedAt = task.CompletedAt
+	}
+
+	return &dto.ImportTaskResponse{
+		ID:           task.ID,
+		TaskNo:       task.TaskNo,
+		Status:       task.Status,
+		StatusText:   getStatusText(task.Status),
+		CarrierID:    task.CarrierID,
+		CarrierName:  carrierMap[task.CarrierID],
+		BatchNo:      task.BatchNo,
+		FileName:     task.FileName,
+		TotalCount:   task.TotalCount,
+		SuccessCount: task.SuccessCount,
+		SkipCount:    task.SkipCount,
+		FailCount:    task.FailCount,
+		StartedAt:    startedAt,
+		CompletedAt:  completedAt,
+		ErrorMessage: task.ErrorMessage,
+		CreatedAt:    task.CreatedAt,
+	}
+}
+
+func getStatusText(status int) string {
+	switch status {
+	case model.ImportTaskStatusPending:
+		return "待处理"
+	case model.ImportTaskStatusProcessing:
+		return "处理中"
+	case model.ImportTaskStatusCompleted:
+		return "已完成"
+	case model.ImportTaskStatusFailed:
+		return "失败"
+	default:
+		return "未知"
+	}
+}

internal/store/postgres/iot_card_import_task_store.go

@@ -0,0 +1,133 @@
+package postgres
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/store"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/redis/go-redis/v9"
+	"gorm.io/gorm"
+)
+
+type IotCardImportTaskStore struct {
+	db    *gorm.DB
+	redis *redis.Client
+}
+
+func NewIotCardImportTaskStore(db *gorm.DB, redis *redis.Client) *IotCardImportTaskStore {
+	return &IotCardImportTaskStore{
+		db:    db,
+		redis: redis,
+	}
+}
+
+func (s *IotCardImportTaskStore) Create(ctx context.Context, task *model.IotCardImportTask) error {
+	return s.db.WithContext(ctx).Create(task).Error
+}
+
+func (s *IotCardImportTaskStore) GetByID(ctx context.Context, id uint) (*model.IotCardImportTask, error) {
+	var task model.IotCardImportTask
+	if err := s.db.WithContext(ctx).First(&task, id).Error; err != nil {
+		return nil, err
+	}
+	return &task, nil
+}
+
+func (s *IotCardImportTaskStore) GetByTaskNo(ctx context.Context, taskNo string) (*model.IotCardImportTask, error) {
+	var task model.IotCardImportTask
+	if err := s.db.WithContext(ctx).Where("task_no = ?", taskNo).First(&task).Error; err != nil {
+		return nil, err
+	}
+	return &task, nil
+}
+
+func (s *IotCardImportTaskStore) Update(ctx context.Context, task *model.IotCardImportTask) error {
+	return s.db.WithContext(ctx).Save(task).Error
+}
+
+func (s *IotCardImportTaskStore) UpdateStatus(ctx context.Context, id uint, status int, errorMessage string) error {
+	updates := map[string]interface{}{
+		"status":     status,
+		"updated_at": time.Now(),
+	}
+	if status == model.ImportTaskStatusProcessing {
+		updates["started_at"] = time.Now()
+	}
+	if status == model.ImportTaskStatusCompleted || status == model.ImportTaskStatusFailed {
+		updates["completed_at"] = time.Now()
+	}
+	if errorMessage != "" {
+		updates["error_message"] = errorMessage
+	}
+	return s.db.WithContext(ctx).Model(&model.IotCardImportTask{}).Where("id = ?", id).Updates(updates).Error
+}
+
+func (s *IotCardImportTaskStore) UpdateResult(ctx context.Context, id uint, successCount, skipCount, failCount int, skippedItems, failedItems model.ImportResultItems) error {
+	updates := map[string]interface{}{
+		"success_count": successCount,
+		"skip_count":    skipCount,
+		"fail_count":    failCount,
+		"skipped_items": skippedItems,
+		"failed_items":  failedItems,
+		"updated_at":    time.Now(),
+	}
+	return s.db.WithContext(ctx).Model(&model.IotCardImportTask{}).Where("id = ?", id).Updates(updates).Error
+}
+
+func (s *IotCardImportTaskStore) List(ctx context.Context, opts *store.QueryOptions, filters map[string]interface{}) ([]*model.IotCardImportTask, int64, error) {
+	var tasks []*model.IotCardImportTask
+	var total int64
+
+	query := s.db.WithContext(ctx).Model(&model.IotCardImportTask{})
+
+	if status, ok := filters["status"].(int); ok && status > 0 {
+		query = query.Where("status = ?", status)
+	}
+	if carrierID, ok := filters["carrier_id"].(uint); ok && carrierID > 0 {
+		query = query.Where("carrier_id = ?", carrierID)
+	}
+	if batchNo, ok := filters["batch_no"].(string); ok && batchNo != "" {
+		query = query.Where("batch_no LIKE ?", "%"+batchNo+"%")
+	}
+	if startTime, ok := filters["start_time"].(time.Time); ok && !startTime.IsZero() {
+		query = query.Where("created_at >= ?", startTime)
+	}
+	if endTime, ok := filters["end_time"].(time.Time); ok && !endTime.IsZero() {
+		query = query.Where("created_at <= ?", endTime)
+	}
+
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	if opts == nil {
+		opts = &store.QueryOptions{
+			Page:     1,
+			PageSize: constants.DefaultPageSize,
+		}
+	}
+	offset := (opts.Page - 1) * opts.PageSize
+	query = query.Offset(offset).Limit(opts.PageSize)
+
+	if opts.OrderBy != "" {
+		query = query.Order(opts.OrderBy)
+	} else {
+		query = query.Order("created_at DESC")
+	}
+
+	if err := query.Find(&tasks).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return tasks, total, nil
+}
+
+func (s *IotCardImportTaskStore) GenerateTaskNo(ctx context.Context) string {
+	now := time.Now()
+	dateStr := now.Format("20060102")
+	seq := now.UnixNano() % 1000000
+	return fmt.Sprintf("IMP-%s-%06d", dateStr, seq)
+}

internal/store/postgres/iot_card_store.go

@@ -0,0 +1,218 @@
+package postgres
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/store"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/redis/go-redis/v9"
+	"gorm.io/gorm"
+)
+
+type IotCardStore struct {
+	db    *gorm.DB
+	redis *redis.Client
+}
+
+func NewIotCardStore(db *gorm.DB, redis *redis.Client) *IotCardStore {
+	return &IotCardStore{
+		db:    db,
+		redis: redis,
+	}
+}
+
+func (s *IotCardStore) Create(ctx context.Context, card *model.IotCard) error {
+	return s.db.WithContext(ctx).Create(card).Error
+}
+
+func (s *IotCardStore) CreateBatch(ctx context.Context, cards []*model.IotCard) error {
+	if len(cards) == 0 {
+		return nil
+	}
+	return s.db.WithContext(ctx).CreateInBatches(cards, 100).Error
+}
+
+func (s *IotCardStore) GetByID(ctx context.Context, id uint) (*model.IotCard, error) {
+	var card model.IotCard
+	if err := s.db.WithContext(ctx).First(&card, id).Error; err != nil {
+		return nil, err
+	}
+	return &card, nil
+}
+
+func (s *IotCardStore) GetByICCID(ctx context.Context, iccid string) (*model.IotCard, error) {
+	var card model.IotCard
+	if err := s.db.WithContext(ctx).Where("iccid = ?", iccid).First(&card).Error; err != nil {
+		return nil, err
+	}
+	return &card, nil
+}
+
+func (s *IotCardStore) ExistsByICCID(ctx context.Context, iccid string) (bool, error) {
+	var count int64
+	if err := s.db.WithContext(ctx).Model(&model.IotCard{}).Where("iccid = ?", iccid).Count(&count).Error; err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (s *IotCardStore) ExistsByICCIDBatch(ctx context.Context, iccids []string) (map[string]bool, error) {
+	if len(iccids) == 0 {
+		return make(map[string]bool), nil
+	}
+
+	var existingICCIDs []string
+	if err := s.db.WithContext(ctx).Model(&model.IotCard{}).
+		Where("iccid IN ?", iccids).
+		Pluck("iccid", &existingICCIDs).Error; err != nil {
+		return nil, err
+	}
+
+	result := make(map[string]bool)
+	for _, iccid := range existingICCIDs {
+		result[iccid] = true
+	}
+	return result, nil
+}
+
+func (s *IotCardStore) Update(ctx context.Context, card *model.IotCard) error {
+	return s.db.WithContext(ctx).Save(card).Error
+}
+
+func (s *IotCardStore) Delete(ctx context.Context, id uint) error {
+	return s.db.WithContext(ctx).Delete(&model.IotCard{}, id).Error
+}
+
+func (s *IotCardStore) ListStandalone(ctx context.Context, opts *store.QueryOptions, filters map[string]any) ([]*model.IotCard, int64, error) {
+	var cards []*model.IotCard
+	var total int64
+
+	query := s.db.WithContext(ctx).Model(&model.IotCard{})
+
+	query = query.Where("id NOT IN (?)",
+		s.db.Model(&model.DeviceSimBinding{}).
+			Select("iot_card_id").
+			Where("bind_status = ?", 1))
+
+	if status, ok := filters["status"].(int); ok && status > 0 {
+		query = query.Where("status = ?", status)
+	}
+	if carrierID, ok := filters["carrier_id"].(uint); ok && carrierID > 0 {
+		query = query.Where("carrier_id = ?", carrierID)
+	}
+	if shopID, ok := filters["shop_id"].(uint); ok && shopID > 0 {
+		query = query.Where("shop_id = ?", shopID)
+	}
+	if iccid, ok := filters["iccid"].(string); ok && iccid != "" {
+		query = query.Where("iccid LIKE ?", "%"+iccid+"%")
+	}
+	if msisdn, ok := filters["msisdn"].(string); ok && msisdn != "" {
+		query = query.Where("msisdn LIKE ?", "%"+msisdn+"%")
+	}
+	if batchNo, ok := filters["batch_no"].(string); ok && batchNo != "" {
+		query = query.Where("batch_no = ?", batchNo)
+	}
+	if packageID, ok := filters["package_id"].(uint); ok && packageID > 0 {
+		query = query.Where("id IN (?)",
+			s.db.Table("tb_package_usage").
+				Select("iot_card_id").
+				Where("package_id = ? AND deleted_at IS NULL", packageID))
+	}
+	if isDistributed, ok := filters["is_distributed"].(bool); ok {
+		if isDistributed {
+			query = query.Where("shop_id IS NOT NULL")
+		} else {
+			query = query.Where("shop_id IS NULL")
+		}
+	}
+	if iccidStart, ok := filters["iccid_start"].(string); ok && iccidStart != "" {
+		query = query.Where("iccid >= ?", iccidStart)
+	}
+	if iccidEnd, ok := filters["iccid_end"].(string); ok && iccidEnd != "" {
+		query = query.Where("iccid <= ?", iccidEnd)
+	}
+	if isReplaced, ok := filters["is_replaced"].(bool); ok {
+		if isReplaced {
+			query = query.Where("id IN (?)",
+				s.db.Table("tb_card_replacement_record").
+					Select("old_iot_card_id").
+					Where("deleted_at IS NULL"))
+		} else {
+			query = query.Where("id NOT IN (?)",
+				s.db.Table("tb_card_replacement_record").
+					Select("old_iot_card_id").
+					Where("deleted_at IS NULL"))
+		}
+	}
+
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	if opts == nil {
+		opts = &store.QueryOptions{
+			Page:     1,
+			PageSize: constants.DefaultPageSize,
+		}
+	}
+	offset := (opts.Page - 1) * opts.PageSize
+	query = query.Offset(offset).Limit(opts.PageSize)
+
+	if opts.OrderBy != "" {
+		query = query.Order(opts.OrderBy)
+	} else {
+		query = query.Order("created_at DESC")
+	}
+
+	if err := query.Find(&cards).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return cards, total, nil
+}
+
+func (s *IotCardStore) List(ctx context.Context, opts *store.QueryOptions, filters map[string]any) ([]*model.IotCard, int64, error) {
+	var cards []*model.IotCard
+	var total int64
+
+	query := s.db.WithContext(ctx).Model(&model.IotCard{})
+
+	if status, ok := filters["status"].(int); ok && status > 0 {
+		query = query.Where("status = ?", status)
+	}
+	if carrierID, ok := filters["carrier_id"].(uint); ok && carrierID > 0 {
+		query = query.Where("carrier_id = ?", carrierID)
+	}
+	if shopID, ok := filters["shop_id"].(uint); ok && shopID > 0 {
+		query = query.Where("shop_id = ?", shopID)
+	}
+	if iccid, ok := filters["iccid"].(string); ok && iccid != "" {
+		query = query.Where("iccid LIKE ?", "%"+iccid+"%")
+	}
+
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	if opts == nil {
+		opts = &store.QueryOptions{
+			Page:     1,
+			PageSize: constants.DefaultPageSize,
+		}
+	}
+	offset := (opts.Page - 1) * opts.PageSize
+	query = query.Offset(offset).Limit(opts.PageSize)
+
+	if opts.OrderBy != "" {
+		query = query.Order(opts.OrderBy)
+	} else {
+		query = query.Order("created_at DESC")
+	}
+
+	if err := query.Find(&cards).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return cards, total, nil
+}

internal/store/postgres/iot_card_store_test.go

@@ -0,0 +1,242 @@
+package postgres
+
+import (
+	"context"
+	"testing"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/store"
+	"github.com/break/junhong_cmp_fiber/tests/testutils"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIotCardStore_Create(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	card := &model.IotCard{
+		ICCID:     "89860012345678901234",
+		CardType:  "data_card",
+		CarrierID: 1,
+		Status:    1,
+	}
+
+	err := s.Create(ctx, card)
+	require.NoError(t, err)
+	assert.NotZero(t, card.ID)
+}
+
+func TestIotCardStore_ExistsByICCID(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	card := &model.IotCard{
+		ICCID:     "89860012345678901111",
+		CardType:  "data_card",
+		CarrierID: 1,
+		Status:    1,
+	}
+	require.NoError(t, s.Create(ctx, card))
+
+	exists, err := s.ExistsByICCID(ctx, "89860012345678901111")
+	require.NoError(t, err)
+	assert.True(t, exists)
+
+	exists, err = s.ExistsByICCID(ctx, "89860012345678909999")
+	require.NoError(t, err)
+	assert.False(t, exists)
+}
+
+func TestIotCardStore_ExistsByICCIDBatch(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	cards := []*model.IotCard{
+		{ICCID: "89860012345678902001", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "89860012345678902002", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "89860012345678902003", CardType: "data_card", CarrierID: 1, Status: 1},
+	}
+	require.NoError(t, s.CreateBatch(ctx, cards))
+
+	result, err := s.ExistsByICCIDBatch(ctx, []string{
+		"89860012345678902001",
+		"89860012345678902002",
+		"89860012345678909999",
+	})
+	require.NoError(t, err)
+	assert.True(t, result["89860012345678902001"])
+	assert.True(t, result["89860012345678902002"])
+	assert.False(t, result["89860012345678909999"])
+
+	emptyResult, err := s.ExistsByICCIDBatch(ctx, []string{})
+	require.NoError(t, err)
+	assert.Empty(t, emptyResult)
+}
+
+func TestIotCardStore_ListStandalone(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	standaloneCards := []*model.IotCard{
+		{ICCID: "89860012345678903001", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "89860012345678903002", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "89860012345678903003", CardType: "data_card", CarrierID: 2, Status: 2},
+	}
+	require.NoError(t, s.CreateBatch(ctx, standaloneCards))
+
+	boundCard := &model.IotCard{
+		ICCID:     "89860012345678903004",
+		CardType:  "data_card",
+		CarrierID: 1,
+		Status:    1,
+	}
+	require.NoError(t, s.Create(ctx, boundCard))
+
+	binding := &model.DeviceSimBinding{
+		DeviceID:   1,
+		IotCardID:  boundCard.ID,
+		BindStatus: 1,
+	}
+	require.NoError(t, tx.Create(binding).Error)
+
+	t.Run("查询所有单卡", func(t *testing.T) {
+		cards, total, err := s.ListStandalone(ctx, &store.QueryOptions{Page: 1, PageSize: 20}, nil)
+		require.NoError(t, err)
+		assert.Equal(t, int64(3), total)
+		assert.Len(t, cards, 3)
+
+		for _, card := range cards {
+			assert.NotEqual(t, boundCard.ID, card.ID, "已绑定的卡不应出现在单卡列表中")
+		}
+	})
+
+	t.Run("按运营商ID过滤", func(t *testing.T) {
+		filters := map[string]interface{}{"carrier_id": uint(1)}
+		cards, total, err := s.ListStandalone(ctx, &store.QueryOptions{Page: 1, PageSize: 20}, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(2), total)
+		for _, card := range cards {
+			assert.Equal(t, uint(1), card.CarrierID)
+		}
+	})
+
+	t.Run("按状态过滤", func(t *testing.T) {
+		filters := map[string]interface{}{"status": 2}
+		cards, total, err := s.ListStandalone(ctx, &store.QueryOptions{Page: 1, PageSize: 20}, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(1), total)
+		assert.Len(t, cards, 1)
+		assert.Equal(t, 2, cards[0].Status)
+	})
+
+	t.Run("按ICCID模糊查询", func(t *testing.T) {
+		filters := map[string]interface{}{"iccid": "903001"}
+		cards, total, err := s.ListStandalone(ctx, &store.QueryOptions{Page: 1, PageSize: 20}, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(1), total)
+		assert.Contains(t, cards[0].ICCID, "903001")
+	})
+
+	t.Run("分页查询", func(t *testing.T) {
+		cards, total, err := s.ListStandalone(ctx, &store.QueryOptions{Page: 1, PageSize: 2}, nil)
+		require.NoError(t, err)
+		assert.Equal(t, int64(3), total)
+		assert.Len(t, cards, 2)
+
+		cards2, _, err := s.ListStandalone(ctx, &store.QueryOptions{Page: 2, PageSize: 2}, nil)
+		require.NoError(t, err)
+		assert.Len(t, cards2, 1)
+	})
+
+	t.Run("默认分页选项", func(t *testing.T) {
+		cards, total, err := s.ListStandalone(ctx, nil, nil)
+		require.NoError(t, err)
+		assert.Equal(t, int64(3), total)
+		assert.Len(t, cards, 3)
+	})
+}
+
+func TestIotCardStore_ListStandalone_Filters(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	s := NewIotCardStore(tx, rdb)
+	ctx := context.Background()
+
+	shopID := uint(100)
+	cards := []*model.IotCard{
+		{ICCID: "89860012345678904001", CardType: "data_card", CarrierID: 1, Status: 1, ShopID: &shopID, BatchNo: "BATCH001", MSISDN: "13800000001"},
+		{ICCID: "89860012345678904002", CardType: "data_card", CarrierID: 1, Status: 1, ShopID: nil, BatchNo: "BATCH001", MSISDN: "13800000002"},
+		{ICCID: "89860012345678904003", CardType: "data_card", CarrierID: 1, Status: 1, ShopID: nil, BatchNo: "BATCH002", MSISDN: "13800000003"},
+	}
+	require.NoError(t, s.CreateBatch(ctx, cards))
+
+	t.Run("按店铺ID过滤", func(t *testing.T) {
+		filters := map[string]interface{}{"shop_id": shopID}
+		cards, total, err := s.ListStandalone(ctx, nil, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(1), total)
+		assert.Equal(t, shopID, *cards[0].ShopID)
+	})
+
+	t.Run("按批次号过滤", func(t *testing.T) {
+		filters := map[string]interface{}{"batch_no": "BATCH001"}
+		_, total, err := s.ListStandalone(ctx, nil, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(2), total)
+	})
+
+	t.Run("按MSISDN模糊查询", func(t *testing.T) {
+		filters := map[string]interface{}{"msisdn": "000001"}
+		result, total, err := s.ListStandalone(ctx, nil, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(1), total)
+		assert.Contains(t, result[0].MSISDN, "000001")
+	})
+
+	t.Run("已分销过滤-true", func(t *testing.T) {
+		filters := map[string]interface{}{"is_distributed": true}
+		result, total, err := s.ListStandalone(ctx, nil, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(1), total)
+		assert.NotNil(t, result[0].ShopID)
+	})
+
+	t.Run("已分销过滤-false", func(t *testing.T) {
+		filters := map[string]interface{}{"is_distributed": false}
+		result, total, err := s.ListStandalone(ctx, nil, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(2), total)
+		for _, card := range result {
+			assert.Nil(t, card.ShopID)
+		}
+	})
+
+	t.Run("ICCID范围查询", func(t *testing.T) {
+		filters := map[string]interface{}{
+			"iccid_start": "89860012345678904001",
+			"iccid_end":   "89860012345678904002",
+		}
+		_, total, err := s.ListStandalone(ctx, nil, filters)
+		require.NoError(t, err)
+		assert.Equal(t, int64(2), total)
+	})
+}

internal/task/iot_card_import.go

@@ -0,0 +1,230 @@
+package task
+
+import (
+	"context"
+	"time"
+
+	"github.com/bytedance/sonic"
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	pkggorm "github.com/break/junhong_cmp_fiber/pkg/gorm"
+	"github.com/break/junhong_cmp_fiber/pkg/validator"
+)
+
+const batchSize = 1000
+
+type IotCardImportPayload struct {
+	TaskID uint `json:"task_id"`
+}
+
+type IotCardImportHandler struct {
+	db              *gorm.DB
+	redis           *redis.Client
+	importTaskStore *postgres.IotCardImportTaskStore
+	iotCardStore    *postgres.IotCardStore
+	logger          *zap.Logger
+}
+
+func NewIotCardImportHandler(db *gorm.DB, redis *redis.Client, importTaskStore *postgres.IotCardImportTaskStore, iotCardStore *postgres.IotCardStore, logger *zap.Logger) *IotCardImportHandler {
+	return &IotCardImportHandler{
+		db:              db,
+		redis:           redis,
+		importTaskStore: importTaskStore,
+		iotCardStore:    iotCardStore,
+		logger:          logger,
+	}
+}
+
+func (h *IotCardImportHandler) HandleIotCardImport(ctx context.Context, task *asynq.Task) error {
+	ctx = pkggorm.SkipDataPermission(ctx)
+
+	var payload IotCardImportPayload
+	if err := sonic.Unmarshal(task.Payload(), &payload); err != nil {
+		h.logger.Error("解析 IoT 卡导入任务载荷失败",
+			zap.Error(err),
+			zap.String("task_id", task.ResultWriter().TaskID()),
+		)
+		return asynq.SkipRetry
+	}
+
+	importTask, err := h.importTaskStore.GetByID(ctx, payload.TaskID)
+	if err != nil {
+		h.logger.Error("获取导入任务失败",
+			zap.Uint("task_id", payload.TaskID),
+			zap.Error(err),
+		)
+		return asynq.SkipRetry
+	}
+
+	if importTask.Status != model.ImportTaskStatusPending {
+		h.logger.Info("导入任务已处理，跳过",
+			zap.Uint("task_id", payload.TaskID),
+			zap.Int("status", importTask.Status),
+		)
+		return nil
+	}
+
+	h.importTaskStore.UpdateStatus(ctx, importTask.ID, model.ImportTaskStatusProcessing, "")
+
+	h.logger.Info("开始处理 IoT 卡导入任务",
+		zap.Uint("task_id", importTask.ID),
+		zap.String("task_no", importTask.TaskNo),
+		zap.Int("total_count", importTask.TotalCount),
+	)
+
+	result := h.processImport(ctx, importTask)
+
+	h.importTaskStore.UpdateResult(ctx, importTask.ID, result.successCount, result.skipCount, result.failCount, result.skippedItems, result.failedItems)
+
+	if result.failCount > 0 && result.successCount == 0 {
+		h.importTaskStore.UpdateStatus(ctx, importTask.ID, model.ImportTaskStatusFailed, "所有导入均失败")
+	} else {
+		h.importTaskStore.UpdateStatus(ctx, importTask.ID, model.ImportTaskStatusCompleted, "")
+	}
+
+	h.logger.Info("IoT 卡导入任务完成",
+		zap.Uint("task_id", importTask.ID),
+		zap.Int("success_count", result.successCount),
+		zap.Int("skip_count", result.skipCount),
+		zap.Int("fail_count", result.failCount),
+	)
+
+	return nil
+}
+
+type importResult struct {
+	successCount int
+	skipCount    int
+	failCount    int
+	skippedItems model.ImportResultItems
+	failedItems  model.ImportResultItems
+}
+
+func (h *IotCardImportHandler) processImport(ctx context.Context, task *model.IotCardImportTask) *importResult {
+	result := &importResult{
+		skippedItems: make(model.ImportResultItems, 0),
+		failedItems:  make(model.ImportResultItems, 0),
+	}
+
+	iccids := h.getICCIDsFromTask(task)
+	if len(iccids) == 0 {
+		return result
+	}
+
+	for i := 0; i < len(iccids); i += batchSize {
+		end := min(i+batchSize, len(iccids))
+		batch := iccids[i:end]
+		h.processBatch(ctx, task, batch, i+1, result)
+	}
+
+	return result
+}
+
+func (h *IotCardImportHandler) getICCIDsFromTask(task *model.IotCardImportTask) []string {
+	return []string(task.ICCIDList)
+}
+
+func (h *IotCardImportHandler) processBatch(ctx context.Context, task *model.IotCardImportTask, batch []string, startLine int, result *importResult) {
+	validICCIDs := make([]string, 0)
+	lineMap := make(map[string]int)
+
+	for i, iccid := range batch {
+		line := startLine + i
+		lineMap[iccid] = line
+
+		validationResult := validator.ValidateICCID(iccid, task.CarrierType)
+		if !validationResult.Valid {
+			result.failedItems = append(result.failedItems, model.ImportResultItem{
+				Line:   line,
+				ICCID:  iccid,
+				Reason: validationResult.Message,
+			})
+			result.failCount++
+			continue
+		}
+		validICCIDs = append(validICCIDs, iccid)
+	}
+
+	if len(validICCIDs) == 0 {
+		return
+	}
+
+	existingMap, err := h.iotCardStore.ExistsByICCIDBatch(ctx, validICCIDs)
+	if err != nil {
+		h.logger.Error("批量检查 ICCID 是否存在失败",
+			zap.Error(err),
+			zap.Int("batch_size", len(validICCIDs)),
+		)
+		for _, iccid := range validICCIDs {
+			result.failedItems = append(result.failedItems, model.ImportResultItem{
+				Line:   lineMap[iccid],
+				ICCID:  iccid,
+				Reason: "数据库查询失败",
+			})
+			result.failCount++
+		}
+		return
+	}
+
+	newICCIDs := make([]string, 0)
+	for _, iccid := range validICCIDs {
+		if existingMap[iccid] {
+			result.skippedItems = append(result.skippedItems, model.ImportResultItem{
+				Line:   lineMap[iccid],
+				ICCID:  iccid,
+				Reason: "ICCID 已存在",
+			})
+			result.skipCount++
+		} else {
+			newICCIDs = append(newICCIDs, iccid)
+		}
+	}
+
+	if len(newICCIDs) == 0 {
+		return
+	}
+
+	cards := make([]*model.IotCard, 0, len(newICCIDs))
+	now := time.Now()
+	for _, iccid := range newICCIDs {
+		card := &model.IotCard{
+			ICCID:            iccid,
+			CarrierID:        task.CarrierID,
+			BatchNo:          task.BatchNo,
+			Status:           constants.IotCardStatusInStock,
+			CardCategory:     constants.CardCategoryNormal,
+			ActivationStatus: constants.ActivationStatusInactive,
+			RealNameStatus:   constants.RealNameStatusNotVerified,
+			NetworkStatus:    constants.NetworkStatusOffline,
+		}
+		card.BaseModel.Creator = task.Creator
+		card.BaseModel.Updater = task.Creator
+		card.CreatedAt = now
+		card.UpdatedAt = now
+		cards = append(cards, card)
+	}
+
+	if err := h.iotCardStore.CreateBatch(ctx, cards); err != nil {
+		h.logger.Error("批量创建 IoT 卡失败",
+			zap.Error(err),
+			zap.Int("batch_size", len(cards)),
+		)
+		for _, iccid := range newICCIDs {
+			result.failedItems = append(result.failedItems, model.ImportResultItem{
+				Line:   lineMap[iccid],
+				ICCID:  iccid,
+				Reason: "数据库写入失败",
+			})
+			result.failCount++
+		}
+		return
+	}
+
+	result.successCount += len(newICCIDs)
+}

internal/task/iot_card_import_test.go

@@ -0,0 +1,187 @@
+package task
+
+import (
+	"context"
+	"testing"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/tests/testutils"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+)
+
+func TestIotCardImportHandler_ProcessImport(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	logger := zap.NewNop()
+	importTaskStore := postgres.NewIotCardImportTaskStore(tx, rdb)
+	iotCardStore := postgres.NewIotCardStore(tx, rdb)
+
+	handler := NewIotCardImportHandler(tx, rdb, importTaskStore, iotCardStore, logger)
+	ctx := context.Background()
+
+	t.Run("成功导入新ICCID", func(t *testing.T) {
+		task := &model.IotCardImportTask{
+			CarrierID:   1,
+			CarrierType: constants.CarrierCodeCMCC,
+			BatchNo:     "TEST_BATCH_001",
+			ICCIDList:   model.ICCIDListJSON{"89860012345678905001", "89860012345678905002", "89860012345678905003"},
+			TotalCount:  3,
+		}
+		task.Creator = 1
+
+		result := handler.processImport(ctx, task)
+
+		assert.Equal(t, 3, result.successCount)
+		assert.Equal(t, 0, result.skipCount)
+		assert.Equal(t, 0, result.failCount)
+
+		exists, _ := iotCardStore.ExistsByICCID(ctx, "89860012345678905001")
+		assert.True(t, exists)
+	})
+
+	t.Run("跳过已存在的ICCID", func(t *testing.T) {
+		existingCard := &model.IotCard{
+			ICCID:     "89860012345678906001",
+			CardType:  "data_card",
+			CarrierID: 1,
+			Status:    1,
+		}
+		require.NoError(t, iotCardStore.Create(ctx, existingCard))
+
+		task := &model.IotCardImportTask{
+			CarrierID:   1,
+			CarrierType: constants.CarrierCodeCMCC,
+			BatchNo:     "TEST_BATCH_002",
+			ICCIDList:   model.ICCIDListJSON{"89860012345678906001", "89860012345678906002"},
+			TotalCount:  2,
+		}
+		task.Creator = 1
+
+		result := handler.processImport(ctx, task)
+
+		assert.Equal(t, 1, result.successCount)
+		assert.Equal(t, 1, result.skipCount)
+		assert.Equal(t, 0, result.failCount)
+		assert.Len(t, result.skippedItems, 1)
+		assert.Equal(t, "89860012345678906001", result.skippedItems[0].ICCID)
+		assert.Equal(t, "ICCID 已存在", result.skippedItems[0].Reason)
+	})
+
+	t.Run("ICCID格式校验失败", func(t *testing.T) {
+		task := &model.IotCardImportTask{
+			CarrierID:   1,
+			CarrierType: constants.CarrierCodeCTCC,
+			BatchNo:     "TEST_BATCH_003",
+			ICCIDList:   model.ICCIDListJSON{"89860312345678907001", "898603123456789070"},
+			TotalCount:  2,
+		}
+		task.Creator = 1
+
+		result := handler.processImport(ctx, task)
+
+		assert.Equal(t, 0, result.successCount)
+		assert.Equal(t, 0, result.skipCount)
+		assert.Equal(t, 2, result.failCount)
+		assert.Len(t, result.failedItems, 2)
+	})
+
+	t.Run("混合场景-成功跳过和失败", func(t *testing.T) {
+		existingCard := &model.IotCard{
+			ICCID:     "89860012345678908001",
+			CardType:  "data_card",
+			CarrierID: 1,
+			Status:    1,
+		}
+		require.NoError(t, iotCardStore.Create(ctx, existingCard))
+
+		task := &model.IotCardImportTask{
+			CarrierID:   1,
+			CarrierType: constants.CarrierCodeCMCC,
+			BatchNo:     "TEST_BATCH_004",
+			ICCIDList: model.ICCIDListJSON{
+				"89860012345678908001",
+				"89860012345678908002",
+				"invalid!iccid",
+			},
+			TotalCount: 3,
+		}
+		task.Creator = 1
+
+		result := handler.processImport(ctx, task)
+
+		assert.Equal(t, 1, result.successCount)
+		assert.Equal(t, 1, result.skipCount)
+		assert.Equal(t, 1, result.failCount)
+	})
+
+	t.Run("空ICCID列表", func(t *testing.T) {
+		task := &model.IotCardImportTask{
+			CarrierID:   1,
+			CarrierType: constants.CarrierCodeCMCC,
+			BatchNo:     "TEST_BATCH_005",
+			ICCIDList:   model.ICCIDListJSON{},
+			TotalCount:  0,
+		}
+
+		result := handler.processImport(ctx, task)
+
+		assert.Equal(t, 0, result.successCount)
+		assert.Equal(t, 0, result.skipCount)
+		assert.Equal(t, 0, result.failCount)
+	})
+}
+
+func TestIotCardImportHandler_ProcessBatch(t *testing.T) {
+	tx := testutils.NewTestTransaction(t)
+	rdb := testutils.GetTestRedis(t)
+	testutils.CleanTestRedisKeys(t, rdb)
+
+	logger := zap.NewNop()
+	importTaskStore := postgres.NewIotCardImportTaskStore(tx, rdb)
+	iotCardStore := postgres.NewIotCardStore(tx, rdb)
+
+	handler := NewIotCardImportHandler(tx, rdb, importTaskStore, iotCardStore, logger)
+	ctx := context.Background()
+
+	t.Run("验证行号正确记录", func(t *testing.T) {
+		existingCard := &model.IotCard{
+			ICCID:     "89860012345678909002",
+			CardType:  "data_card",
+			CarrierID: 1,
+			Status:    1,
+		}
+		require.NoError(t, iotCardStore.Create(ctx, existingCard))
+
+		task := &model.IotCardImportTask{
+			CarrierID:   1,
+			CarrierType: constants.CarrierCodeCMCC,
+			BatchNo:     "TEST_BATCH_LINE",
+		}
+		task.Creator = 1
+
+		batch := []string{
+			"89860012345678909001",
+			"89860012345678909002",
+			"invalid",
+		}
+		result := &importResult{
+			skippedItems: make(model.ImportResultItems, 0),
+			failedItems:  make(model.ImportResultItems, 0),
+		}
+
+		handler.processBatch(ctx, task, batch, 100, result)
+
+		assert.Equal(t, 1, result.successCount)
+		assert.Equal(t, 1, result.skipCount)
+		assert.Equal(t, 1, result.failCount)
+
+		assert.Equal(t, 101, result.skippedItems[0].Line)
+		assert.Equal(t, 102, result.failedItems[0].Line)
+	})
+}

migrations/000011_remove_owner_fields_from_iot_card_and_device.down.sql

@@ -0,0 +1,23 @@
+-- 回滚：恢复 tb_iot_card 和 tb_device 表中的 owner_type 和 owner_id 字段
+
+-- 恢复 tb_iot_card.iccid 字段长度
+ALTER TABLE tb_iot_card ALTER COLUMN iccid TYPE varchar(50);
+COMMENT ON COLUMN tb_iot_card.iccid IS 'ICCID(唯一标识)';
+
+-- 恢复 tb_iot_card 的 owner_type 和 owner_id 列
+ALTER TABLE tb_iot_card ADD COLUMN IF NOT EXISTS owner_type varchar(20) NOT NULL DEFAULT 'platform';
+ALTER TABLE tb_iot_card ADD COLUMN IF NOT EXISTS owner_id bigint NOT NULL DEFAULT 0;
+COMMENT ON COLUMN tb_iot_card.owner_type IS '所有者类型 platform-平台 shop-店铺';
+COMMENT ON COLUMN tb_iot_card.owner_id IS '所有者ID';
+CREATE INDEX IF NOT EXISTS idx_iot_card_owner_id ON tb_iot_card(owner_id);
+
+-- 恢复 tb_device 的 owner_type 和 owner_id 列
+ALTER TABLE tb_device ADD COLUMN IF NOT EXISTS owner_type varchar(20) NOT NULL DEFAULT 'platform';
+ALTER TABLE tb_device ADD COLUMN IF NOT EXISTS owner_id bigint NOT NULL DEFAULT 0;
+COMMENT ON COLUMN tb_device.owner_type IS '所有者类型 platform-平台 shop-店铺';
+COMMENT ON COLUMN tb_device.owner_id IS '所有者ID';
+CREATE INDEX IF NOT EXISTS idx_device_owner_id ON tb_device(owner_id);
+
+-- 恢复 shop_id 字段的注释
+COMMENT ON COLUMN tb_iot_card.shop_id IS '店铺ID（冗余字段，方便查询）';
+COMMENT ON COLUMN tb_device.shop_id IS '店铺ID（冗余字段，方便查询）';

migrations/000011_remove_owner_fields_from_iot_card_and_device.up.sql

@@ -0,0 +1,20 @@
+-- 移除 tb_iot_card 和 tb_device 表中的 owner_type 和 owner_id 字段
+-- 原因：所有权模型重构，改用 shop_id 字段表示所有权（NULL=平台所有，有值=店铺所有）
+
+-- 删除 tb_iot_card 的 owner_type 和 owner_id 列
+ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS owner_type;
+ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS owner_id;
+
+-- 删除 tb_device 的 owner_type 和 owner_id 列
+ALTER TABLE tb_device DROP COLUMN IF EXISTS owner_type;
+ALTER TABLE tb_device DROP COLUMN IF EXISTS owner_id;
+
+-- 更新 tb_iot_card 的 shop_id 字段注释
+COMMENT ON COLUMN tb_iot_card.shop_id IS '店铺ID(NULL=平台所有,有值=店铺所有)';
+
+-- 更新 tb_device 的 shop_id 字段注释
+COMMENT ON COLUMN tb_device.shop_id IS '店铺ID(NULL=平台库存,有值=店铺所有)';
+
+-- 修改 tb_iot_card.iccid 字段长度从 varchar(50) 改为 varchar(20)
+ALTER TABLE tb_iot_card ALTER COLUMN iccid TYPE varchar(20);
+COMMENT ON COLUMN tb_iot_card.iccid IS 'ICCID(唯一标识,电信19位/其他20位,支持字母数字混合)';

migrations/000012_create_iot_card_import_task_table.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS tb_iot_card_import_task;

migrations/000012_create_iot_card_import_task_table.up.sql

@@ -0,0 +1,48 @@
+CREATE TABLE IF NOT EXISTS tb_iot_card_import_task (
+    id BIGSERIAL PRIMARY KEY,
+    task_no VARCHAR(50) NOT NULL,
+    status INT NOT NULL DEFAULT 1,
+    carrier_id BIGINT NOT NULL,
+    batch_no VARCHAR(100),
+    file_name VARCHAR(255),
+    total_count INT NOT NULL DEFAULT 0,
+    success_count INT NOT NULL DEFAULT 0,
+    skip_count INT NOT NULL DEFAULT 0,
+    fail_count INT NOT NULL DEFAULT 0,
+    skipped_items JSONB DEFAULT '[]',
+    failed_items JSONB DEFAULT '[]',
+    started_at TIMESTAMP,
+    completed_at TIMESTAMP,
+    error_message TEXT,
+    shop_id BIGINT,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW(),
+    deleted_at TIMESTAMP,
+    creator BIGINT NOT NULL DEFAULT 0,
+    updater BIGINT NOT NULL DEFAULT 0
+);
+
+CREATE UNIQUE INDEX idx_import_task_no ON tb_iot_card_import_task(task_no) WHERE deleted_at IS NULL;
+CREATE INDEX idx_import_task_carrier_id ON tb_iot_card_import_task(carrier_id);
+CREATE INDEX idx_import_task_shop_id ON tb_iot_card_import_task(shop_id);
+CREATE INDEX idx_import_task_status ON tb_iot_card_import_task(status);
+CREATE INDEX idx_import_task_created_at ON tb_iot_card_import_task(created_at);
+
+COMMENT ON TABLE tb_iot_card_import_task IS 'IoT 卡导入任务表';
+COMMENT ON COLUMN tb_iot_card_import_task.task_no IS '任务编号(IMP-YYYYMMDD-XXXXXX)';
+COMMENT ON COLUMN tb_iot_card_import_task.status IS '任务状态 1-待处理 2-处理中 3-已完成 4-失败';
+COMMENT ON COLUMN tb_iot_card_import_task.carrier_id IS '运营商ID';
+COMMENT ON COLUMN tb_iot_card_import_task.batch_no IS '批次号';
+COMMENT ON COLUMN tb_iot_card_import_task.file_name IS '原始文件名';
+COMMENT ON COLUMN tb_iot_card_import_task.total_count IS '总数';
+COMMENT ON COLUMN tb_iot_card_import_task.success_count IS '成功数';
+COMMENT ON COLUMN tb_iot_card_import_task.skip_count IS '跳过数';
+COMMENT ON COLUMN tb_iot_card_import_task.fail_count IS '失败数';
+COMMENT ON COLUMN tb_iot_card_import_task.skipped_items IS '跳过记录详情';
+COMMENT ON COLUMN tb_iot_card_import_task.failed_items IS '失败记录详情';
+COMMENT ON COLUMN tb_iot_card_import_task.started_at IS '开始处理时间';
+COMMENT ON COLUMN tb_iot_card_import_task.completed_at IS '完成时间';
+COMMENT ON COLUMN tb_iot_card_import_task.error_message IS '任务级错误信息';
+COMMENT ON COLUMN tb_iot_card_import_task.shop_id IS '店铺ID(发起导入的店铺)';
+COMMENT ON COLUMN tb_iot_card_import_task.creator IS '创建人ID';
+COMMENT ON COLUMN tb_iot_card_import_task.updater IS '更新人ID';

migrations/000013_add_carrier_type_to_import_task.down.sql

@@ -0,0 +1,2 @@
+ALTER TABLE tb_iot_card_import_task DROP COLUMN IF EXISTS carrier_type;
+ALTER TABLE tb_iot_card_import_task DROP COLUMN IF EXISTS iccid_list;

migrations/000013_add_carrier_type_to_import_task.up.sql

@@ -0,0 +1,5 @@
+ALTER TABLE tb_iot_card_import_task ADD COLUMN IF NOT EXISTS carrier_type VARCHAR(20) NOT NULL DEFAULT 'CMCC';
+ALTER TABLE tb_iot_card_import_task ADD COLUMN IF NOT EXISTS iccid_list JSONB DEFAULT '[]';
+
+COMMENT ON COLUMN tb_iot_card_import_task.carrier_type IS '运营商类型(CMCC/CUCC/CTCC/CBN)';
+COMMENT ON COLUMN tb_iot_card_import_task.iccid_list IS '待导入ICCID列表';

openspec/changes/archive/2026-01-23-iot-card-standalone-management/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-23

openspec/changes/archive/2026-01-23-iot-card-standalone-management/proposal.md

@@ -0,0 +1,56 @@
+# Change: IoT 卡单卡管理与所有权模型重构
+
+## Why
+
+当前 IoT 卡和设备模型中使用 `owner_type` + `owner_id` 表示所有权，与数据权限使用的 `shop_id` 字段存在冗余，且语义不清晰：
+- 代理分销给下级时，所有权实际是转移到下级店铺（shop_id 变化）
+- 企业用户没有"所有权"，是通过授权表（EnterpriseCardAuthorization）管理
+- 个人客户完全没有所有权概念，是基于 ICCID/设备号操作
+
+同时，业务需要"单卡管理"功能：查看和导入未绑定设备的 IoT 卡，支持大批量 CSV 导入（几万条）并跟踪导入任务状态。
+
+## What Changes
+
+### 模型重构（**BREAKING**）
+- **移除 IotCard 的 owner_type/owner_id 字段**：改用 shop_id 表示所有权（NULL=平台所有，有值=店铺所有）
+- **移除 Device 的 owner_type/owner_id 字段**：同上
+- 保留 AssetAllocationRecord 和 CardReplacementRecord 中的 Owner 字段（历史记录追溯用）
+
+### 新增功能
+- **单卡列表 API**：查询未绑定设备的 IoT 卡，支持多维度筛选
+- **批量导入 ICCID API**：支持 CSV 文件上传，异步处理，支持几万条数据
+- **导入任务记录表**：跟踪导入进度、成功/跳过/失败统计及详情
+
+### ICCID 校验规则调整
+- 电信：严格 19 位
+- 联通/移动/广电：严格 20 位
+- 支持字母数字混合（移动 ICCID 有字母）
+
+## Capabilities
+
+### New Capabilities
+- `iot-card-import-task`: IoT 卡导入任务管理，包含导入任务模型、进度跟踪、结果详情记录
+
+### Modified Capabilities
+- `iot-card`: 移除 owner_type/owner_id 字段，改用 shop_id；新增单卡列表查询；调整 ICCID 校验规则
+- `iot-device`: 移除 owner_type/owner_id 字段，改用 shop_id
+
+## Impact
+
+### 数据库变更
+- `tb_iot_card` 表：删除 owner_type、owner_id 列
+- `tb_device` 表：删除 owner_type、owner_id 列
+- 新增 `tb_iot_card_import_task` 表
+
+### 代码影响
+- `internal/model/iot_card.go`：移除 OwnerType、OwnerID 字段
+- `internal/model/device.go`：移除 OwnerType、OwnerID 字段
+- `internal/model/iot_card_import_task.go`：新增
+- `openspec/specs/iot-card/spec.md`：修改所有权相关描述
+- `openspec/specs/iot-device/spec.md`：修改所有权相关描述
+
+### API 影响
+- 新增：`GET /api/admin/iot-cards/standalone` - 单卡列表
+- 新增：`POST /api/admin/iot-cards/import` - 发起导入任务
+- 新增：`GET /api/admin/iot-cards/import-tasks` - 导入任务列表
+- 新增：`GET /api/admin/iot-cards/import-tasks/:id` - 导入任务详情

openspec/changes/archive/2026-01-23-iot-card-standalone-management/specs/iot-card-import-task/spec.md

@@ -0,0 +1,174 @@
+# IoT Card Import Task - Delta Spec
+
+## ADDED Requirements
+
+### Requirement: 导入任务实体定义
+
+系统 SHALL 定义 IoT 卡导入任务(IotCardImportTask)实体,用于跟踪 IoT 卡批量导入的进度和结果。
+
+**实体字段**:
+
+**任务信息**:
+- `id`: 任务 ID(主键,BIGINT)
+- `task_no`: 任务编号(VARCHAR(50),唯一,格式: IMP-YYYYMMDD-XXXXXX)
+- `status`: 任务状态(INT,1-待处理 2-处理中 3-已完成 4-失败)
+
+**导入参数**:
+- `carrier_id`: 运营商 ID(BIGINT,必填)
+- `batch_no`: 批次号(VARCHAR(100),可选)
+- `file_name`: 原始文件名(VARCHAR(255),可选)
+
+**进度统计**:
+- `total_count`: 总数(INT,CSV 文件总行数)
+- `success_count`: 成功数(INT,成功导入的 ICCID 数量)
+- `skip_count`: 跳过数(INT,因重复等原因跳过的数量)
+- `fail_count`: 失败数(INT,因格式错误等原因失败的数量)
+
+**结果详情**:
+- `skipped_items`: 跳过记录详情(JSONB,结构: [{line, iccid, reason}])
+- `failed_items`: 失败记录详情(JSONB,结构: [{line, iccid, reason}])
+
+**时间和错误**:
+- `started_at`: 开始处理时间(TIMESTAMP,可空)
+- `completed_at`: 完成时间(TIMESTAMP,可空)
+- `error_message`: 任务级错误信息(TEXT,可空,如文件解析失败等)
+
+**系统字段**:
+- `shop_id`: 店铺 ID(BIGINT,可空,记录发起导入的店铺)
+- `created_at`: 创建时间(TIMESTAMP,自动填充)
+- `updated_at`: 更新时间(TIMESTAMP,自动填充)
+- `creator`: 创建人 ID(BIGINT)
+- `updater`: 更新人 ID(BIGINT)
+
+#### Scenario: 创建导入任务
+
+- **WHEN** 管理员上传 CSV 文件发起导入
+- **THEN** 系统创建导入任务记录,`status` 为 1(待处理),`total_count` 为 CSV 行数,返回任务 ID
+
+#### Scenario: 导入任务开始处理
+
+- **WHEN** Worker 开始处理导入任务
+- **THEN** 系统将任务 `status` 从 1(待处理) 变更为 2(处理中),`started_at` 记录当前时间
+
+#### Scenario: 导入任务完成
+
+- **WHEN** Worker 完成导入任务处理
+- **THEN** 系统将任务 `status` 变更为 3(已完成),`completed_at` 记录当前时间,更新 `success_count`、`skip_count`、`fail_count`
+
+#### Scenario: 导入任务失败
+
+- **WHEN** Worker 处理导入任务时发生严重错误(如文件损坏)
+- **THEN** 系统将任务 `status` 变更为 4(失败),`error_message` 记录错误信息
+
+---
+
+### Requirement: 导入任务状态流转
+
+系统 SHALL 管理导入任务的状态流转,确保状态变更符合业务规则。
+
+**状态定义**:
+- **1-待处理**: 任务已创建,等待 Worker 处理
+- **2-处理中**: Worker 正在处理导入
+- **3-已完成**: 导入处理完成(可能有部分失败)
+- **4-失败**: 任务级别错误,导入中断
+
+**状态流转规则**:
+- 待处理(1) → 处理中(2): Worker 开始处理
+- 处理中(2) → 已完成(3): 处理完成
+- 处理中(2) → 失败(4): 发生严重错误
+- 待处理(1) → 失败(4): 文件验证失败等
+
+#### Scenario: 正常状态流转
+
+- **WHEN** 导入任务经历完整生命周期
+- **THEN** 状态依次变更: 待处理(1) → 处理中(2) → 已完成(3)
+
+#### Scenario: 异常状态流转
+
+- **WHEN** 导入任务处理过程中发生严重错误
+- **THEN** 状态变更: 待处理(1) → 处理中(2) → 失败(4)
+
+---
+
+### Requirement: 导入任务列表查询
+
+系统 SHALL 支持查询导入任务列表,用于管理和监控导入任务。
+
+**查询条件**:
+- 任务状态(status): 可选,1-待处理 2-处理中 3-已完成 4-失败
+- 运营商 ID(carrier_id): 可选
+- 批次号(batch_no): 可选,模糊匹配
+- 创建时间范围: 可选
+
+**分页**:
+- 默认每页 20 条,最大每页 100 条
+- 默认按创建时间倒序排列
+
+**数据权限**:
+- 基于 shop_id 自动应用数据权限过滤
+- 代理只能看到自己店铺及下级店铺发起的导入任务
+
+#### Scenario: 查询所有导入任务
+
+- **WHEN** 管理员查询导入任务列表
+- **THEN** 系统返回导入任务列表,包含任务编号、状态、运营商、总数、成功数、跳过数、失败数、创建时间
+
+#### Scenario: 按状态筛选导入任务
+
+- **WHEN** 管理员查询状态为 2(处理中) 的导入任务
+- **THEN** 系统返回所有正在处理的导入任务列表
+
+---
+
+### Requirement: 导入任务详情查询
+
+系统 SHALL 支持查询单个导入任务的详细信息,包括跳过/失败记录详情。
+
+**详情信息**:
+- 任务基本信息: 任务编号、状态、运营商、批次号、文件名
+- 进度统计: 总数、成功数、跳过数、失败数
+- 时间信息: 创建时间、开始时间、完成时间
+- 跳过记录详情: 行号、ICCID、原因
+- 失败记录详情: 行号、ICCID、原因
+- 错误信息: 任务级错误(如有)
+
+#### Scenario: 查询导入任务详情
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的详情
+- **THEN** 系统返回任务完整信息,包括跳过和失败记录的详细列表
+
+#### Scenario: 查询导入任务的跳过记录
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的跳过记录
+- **THEN** 系统返回跳过记录列表,每条包含: 行号(line)、ICCID、原因(如"ICCID 已存在")
+
+#### Scenario: 查询导入任务的失败记录
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的失败记录
+- **THEN** 系统返回失败记录列表,每条包含: 行号(line)、ICCID、原因(如"电信 ICCID 必须为 19 位")
+
+---
+
+### Requirement: 导入任务数据校验
+
+系统 SHALL 对导入任务数据进行校验,确保数据完整性和一致性。
+
+**校验规则**:
+- 任务编号(task_no): 必填,系统自动生成,格式 IMP-YYYYMMDD-XXXXXX,唯一
+- 任务状态(status): 必填,枚举值 1(待处理) | 2(处理中) | 3(已完成) | 4(失败)
+- 运营商 ID(carrier_id): 必填,必须是有效的运营商 ID
+- 总数(total_count): 必填,≥ 0
+- 成功数(success_count): 必填,≥ 0,≤ total_count
+- 跳过数(skip_count): 必填,≥ 0,≤ total_count
+- 失败数(fail_count): 必填,≥ 0,≤ total_count
+- 数量一致性: success_count + skip_count + fail_count ≤ total_count
+
+#### Scenario: 创建任务时运营商 ID 无效
+
+- **WHEN** 创建导入任务时 carrier_id 不存在
+- **THEN** 系统拒绝创建,返回错误信息"运营商 ID 无效"
+
+#### Scenario: 更新任务时数量不一致
+
+- **WHEN** 更新导入任务时 success_count + skip_count + fail_count > total_count
+- **THEN** 系统拒绝更新,返回错误信息"统计数量不一致"

openspec/changes/archive/2026-01-23-iot-card-standalone-management/specs/iot-card/spec.md

@@ -0,0 +1,246 @@
+# IoT Card Management - Delta Spec
+
+## MODIFIED Requirements
+
+### Requirement: IoT 卡实体定义
+
+系统 SHALL 定义 IoT 卡(IotCard)实体,包含 IoT 卡(物联网卡/流量卡/SIM卡)的商品属性、状态属性、店铺归属信息和 Gateway 集成字段。
+
+**核心概念**: IoT 卡 = 物联网卡 = SIM 卡 = 网卡 = 流量卡(同一个东西,不同叫法)。系统使用 ICCID 作为 IoT 卡的唯一标识。
+
+**卡业务类型**:
+- **普通卡(normal)**: 需要实名认证才能激活使用,遵循运营商实名制要求
+- **行业卡(industry)**: 不需要实名认证,可以直接激活使用,适用于企业/行业客户批量采购场景
+
+**实体字段**:
+
+**商品属性**:
+- `id`: IoT 卡 ID(主键,BIGINT)
+- `iccid`: ICCID(VARCHAR(20),唯一,IoT卡的唯一标识,电信19位/联通移动广电20位,支持字母数字混合)
+- `card_type`: 卡类型(VARCHAR(50),如 "4G"、"5G"、"NB-IoT")
+- `card_category`: 卡业务类型(VARCHAR(20),枚举值:"normal"-普通卡 | "industry"-行业卡,默认 "normal")
+- `carrier_id`: 运营商 ID(BIGINT,关联 carriers 表,如中国移动、中国联通、中国电信、中国广电)
+- `imsi`: IMSI(VARCHAR(50),可选,国际移动用户识别码)
+- `msisdn`: 手机号码(VARCHAR(20),可选,即卡接入号)
+- `batch_no`: 批次号(VARCHAR(100),用于批量导入追溯)
+- `supplier`: 供应商名称(VARCHAR(255),可选)
+- `cost_price`: 成本价(BIGINT,分为单位,平台进货价)
+- `distribute_price`: 分销价(BIGINT,分为单位,分销给代理的价格)
+
+**店铺归属和状态**:
+- `shop_id`: 店铺 ID(BIGINT,可空,NULL 表示平台所有,有值表示店铺所有)
+- `status`: IoT 卡状态(INT,1-在库 2-已分销 3-已激活 4-已停用)
+- `activated_at`: 激活时间(TIMESTAMP,可空)
+
+**Gateway 集成字段**(从 Gateway 项目同步):
+- `activation_status`: 激活状态(INT,0-未激活 1-已激活)
+- `real_name_status`: 实名状态(INT,0-未实名 1-已实名)
+- `network_status`: 网络状态(INT,0-停机 1-开机)
+- `data_usage_mb`: 累计流量使用(BIGINT,MB 为单位,默认 0)
+- `last_sync_time`: 最后一次与 Gateway 同步时间(TIMESTAMP,可空)
+
+**轮询控制字段**:
+- `enable_polling`: 是否参与轮询(BOOLEAN,默认 true,用于控制是否对该卡进行定时轮询)
+- `last_data_check_at`: 最后一次卡流量检查时间(TIMESTAMP,可空)
+- `last_real_name_check_at`: 最后一次实名检查时间(TIMESTAMP,可空)
+
+**系统字段**:
+- `created_at`: 创建时间(TIMESTAMP,自动填充)
+- `updated_at`: 更新时间(TIMESTAMP,自动填充)
+- `creator`: 创建人 ID(BIGINT)
+- `updater`: 更新人 ID(BIGINT)
+
+#### Scenario: 创建平台库存 IoT 卡
+
+- **WHEN** 平台批量导入 IoT 卡数据,ICCID 为 "89860123456789012345"
+- **THEN** 系统创建 IoT 卡记录,`shop_id` 为 NULL(平台所有),状态为 1(在库),`activation_status` 为 0(未激活)
+
+#### Scenario: 平台分销 IoT 卡给代理店铺
+
+- **WHEN** 平台将在库 IoT 卡分销给代理店铺(店铺 ID 为 10),设置分销价为 5000 分
+- **THEN** 系统将 IoT 卡状态从 1(在库) 变更为 2(已分销),`shop_id` 设置为 10,`distribute_price` 设置为 5000
+
+#### Scenario: 代理店铺分销 IoT 卡给下级店铺
+
+- **WHEN** 代理店铺(ID 为 10)将已分销 IoT 卡分销给下级店铺(ID 为 20)
+- **THEN** 系统将 IoT 卡的 `shop_id` 从 10 变更为 20,状态保持 2(已分销)
+
+---
+
+### Requirement: IoT 卡平台自营和代理分销
+
+系统 SHALL 支持 IoT 卡的平台自营销售和代理分销两种模式,通过 `shop_id` 区分所有者。
+
+**平台自营**:
+- `shop_id` 为 NULL
+- 平台直接销售给终端用户
+- 销售价格由平台自主定价
+
+**代理分销**:
+- `shop_id` 为店铺 ID
+- 代理商可以销售给终端用户或下级代理
+- 分销价格由上级设置(`distribute_price`),代理商可在分销价基础上加价
+
+**企业授权**:
+- 企业用户没有 IoT 卡所有权
+- 通过 `EnterpriseCardAuthorization` 表管理企业对 IoT 卡的访问权限
+- 授权由店铺发起,企业只能操作被授权的卡
+
+#### Scenario: 查询平台自营 IoT 卡库存
+
+- **WHEN** 查询平台自营 IoT 卡库存
+- **THEN** 系统返回 `shop_id` 为 NULL 且 `status` 为 1(在库) 的 IoT 卡列表
+
+#### Scenario: 查询代理店铺 IoT 卡库存
+
+- **WHEN** 代理店铺(ID 为 10)查询自己的 IoT 卡库存
+- **THEN** 系统返回 `shop_id` 为 10 且 `status` 为 2(已分销) 的 IoT 卡列表
+
+---
+
+### Requirement: IoT 卡数据校验
+
+系统 SHALL 对 IoT 卡数据进行校验,确保数据完整性和一致性。
+
+**校验规则**:
+- ICCID(iccid):必填,字母数字混合,长度根据运营商:电信19位,联通/移动/广电20位,唯一
+- 卡类型(card_type):必填,长度 1-50 字符
+- 卡业务类型(card_category):必填,枚举值 "normal"(普通卡) | "industry"(行业卡),默认 "normal"
+- 运营商 ID(carrier_id):必填,≥ 1,必须是有效的运营商 ID
+- 成本价(cost_price):必填,≥ 0,单位为分
+- 分销价(distribute_price):可选,≥ 0,单位为分,≥ 成本价
+- 店铺 ID(shop_id):可选,NULL 表示平台所有,有值必须是有效的店铺 ID
+- 激活状态(activation_status):必填,枚举值 0(未激活) | 1(已激活)
+- 实名状态(real_name_status):必填,枚举值 0(未实名) | 1(已实名),当 card_category 为 "industry"(行业卡)时可以保持 0
+- 网络状态(network_status):必填,枚举值 0(停机) | 1(开机)
+- 轮询开关(enable_polling):必填,布尔值 true | false
+
+#### Scenario: 创建电信 IoT 卡时 ICCID 长度校验
+
+- **WHEN** 创建电信 IoT 卡(carrier_id 对应电信),ICCID 长度为 20
+- **THEN** 系统拒绝创建,返回错误信息"电信 ICCID 必须为 19 位"
+
+#### Scenario: 创建移动 IoT 卡时 ICCID 长度校验
+
+- **WHEN** 创建移动 IoT 卡(carrier_id 对应移动),ICCID 长度为 19
+- **THEN** 系统拒绝创建,返回错误信息"该运营商 ICCID 必须为 20 位"
+
+#### Scenario: 创建 IoT 卡时 ICCID 包含字母
+
+- **WHEN** 创建移动 IoT 卡,ICCID 为 "8986001234567890123A"(包含字母 A)
+- **THEN** 系统允许创建,因为移动 ICCID 支持字母
+
+#### Scenario: 创建 IoT 卡时 ICCID 重复
+
+- **WHEN** 平台创建 IoT 卡,ICCID 为已存在的 "89860123456789012345"
+- **THEN** 系统拒绝创建,返回错误信息"ICCID 已存在"
+
+---
+
+## ADDED Requirements
+
+### Requirement: 单卡列表查询
+
+系统 SHALL 提供单卡列表查询功能,用于管理未绑定设备的 IoT 卡资产。
+
+**单卡定义**: 单卡是指未绑定到任何设备的 IoT 卡,即在 `device_sim_bindings` 表中不存在 `bind_status = 1`(已绑定) 的记录。
+
+**查询条件**:
+- 套餐 ID(package_id): 可选,筛选已购买指定套餐的卡
+- 是否分销(is_distributed): 可选,true-已分销 false-未分销
+- 卡号状态(status): 可选,1-在库 2-已分销 3-已激活 4-已停用
+- 运营商(carrier_id): 可选,运营商 ID
+- 分销商 ID(shop_id): 可选,店铺 ID
+- 网卡号段(iccid_range): 可选,格式 "起始ICCID-结束ICCID"
+- ICCID: 可选,模糊匹配
+- 卡接入号(msisdn): 可选,模糊匹配
+- 是否换卡(is_replaced): 可选,true-有换卡记录 false-无换卡记录
+
+**分页**:
+- 默认每页 20 条,最大每页 100 条
+- 返回总记录数和总页数
+
+**数据权限**:
+- 基于 shop_id 自动应用数据权限过滤
+- 代理只能看到自己店铺及下级店铺的卡
+
+#### Scenario: 查询未绑定设备的单卡列表
+
+- **WHEN** 管理员查询单卡列表
+- **THEN** 系统返回所有未绑定设备的 IoT 卡(在 device_sim_bindings 中无 bind_status=1 记录的卡)
+
+#### Scenario: 按运营商筛选单卡
+
+- **WHEN** 管理员查询运营商 ID 为 1(电信)的单卡
+- **THEN** 系统返回 carrier_id = 1 且未绑定设备的 IoT 卡列表
+
+#### Scenario: 按网卡号段筛选单卡
+
+- **WHEN** 管理员查询 ICCID 号段为 "8986001000000000000-8986001999999999999" 的单卡
+- **THEN** 系统返回 ICCID 在该号段范围内且未绑定设备的 IoT 卡列表
+
+#### Scenario: 按是否换卡筛选单卡
+
+- **WHEN** 管理员查询有换卡记录的单卡(is_replaced=true)
+- **THEN** 系统返回在 card_replacement_records 表中有记录的 IoT 卡列表
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: IoT 卡批量导入
+
+系统 SHALL 支持通过 CSV 文件批量导入 IoT 卡 ICCID,支持大批量数据(几万条),异步处理并跟踪导入进度。
+
+**导入方式**:
+- 上传 CSV 文件,每行一个 ICCID
+- 在界面选择运营商、批次号等公共参数
+- 不支持一次导入多种运营商的卡
+
+**导入参数**:
+- CSV 文件(必填): 仅包含 ICCID 列
+- 运营商 ID(必填): 在界面选择
+- 批次号(可选): 在界面填写
+
+**校验规则**:
+- ICCID 格式校验: 字母数字混合,长度根据运营商(电信19位,其他20位)
+- ICCID 唯一性校验: 重复 ICCID 跳过,不中断导入
+
+**处理规则**:
+- 异步处理: 创建导入任务后立即返回任务 ID
+- 分批处理: 每批 1000 条
+- 重复处理: 跳过已存在的 ICCID,记录跳过原因
+- 格式错误: 记录失败原因,继续处理其他行
+
+**导入结果**:
+- 总数(total_count)
+- 成功数(success_count)
+- 跳过数(skip_count): 因重复等原因跳过
+- 失败数(fail_count): 因格式错误等原因失败
+- 跳过详情: 包含行号、ICCID、原因
+- 失败详情: 包含行号、ICCID、原因
+
+#### Scenario: 发起 IoT 卡批量导入
+
+- **WHEN** 管理员上传包含 10000 个 ICCID 的 CSV 文件,选择运营商为电信,批次号为 "BATCH-2025-001"
+- **THEN** 系统创建导入任务,返回任务 ID,后台异步处理导入
+
+#### Scenario: 导入时跳过重复 ICCID
+
+- **WHEN** CSV 文件中的 ICCID "8986001234567890123" 已存在于系统中
+- **THEN** 系统跳过该 ICCID,记录跳过原因为"ICCID 已存在",继续处理其他 ICCID
+
+#### Scenario: 导入时记录格式错误
+
+- **WHEN** CSV 文件第 100 行的 ICCID "12345" 长度不符合电信卡要求(19位)
+- **THEN** 系统记录失败,原因为"电信 ICCID 必须为 19 位",行号为 100,继续处理其他 ICCID
+
+#### Scenario: 查询导入任务进度
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的进度
+- **THEN** 系统返回任务状态、总数、成功数、跳过数、失败数、开始时间、完成时间
+
+#### Scenario: 查询导入任务失败详情
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的失败详情
+- **THEN** 系统返回失败记录列表,每条包含行号、ICCID、失败原因

openspec/changes/archive/2026-01-23-iot-card-standalone-management/specs/iot-device/spec.md

@@ -0,0 +1,172 @@
+# IoT Device Management - Delta Spec
+
+## MODIFIED Requirements
+
+### Requirement: 设备实体定义
+
+系统 SHALL 定义设备(Device)实体,用于管理用户的物联网设备(如 GPS 追踪器、智能传感器等),支持设备与 IoT 卡的绑定关系、设备批量分配和设备操作。
+
+**核心概念**: 设备不在卡管系统中销售,主要用于:
+1. 用户设备管理(用户添加自己的设备,绑定 IoT 卡)
+2. 方便运营人员管理投诉和代理要求(通过设备维度批量查看绑定的所有 IoT 卡)
+3. 设备操作(重启、修改账号密码、重置等)
+4. 设备批量分配(运营人员在别的系统报单后发货,把设备和绑定的 IoT 卡一起分配给代理)
+
+**实体字段**:
+
+**基本属性**:
+- `id`: 设备 ID(主键,BIGINT)
+- `device_no`: 设备编号(唯一,VARCHAR(100))
+- `device_name`: 设备名称(VARCHAR(255))
+- `device_model`: 设备型号(VARCHAR(100))
+- `device_type`: 设备类型(VARCHAR(50),如 "GPS Tracker"、"Camera"、"Sensor")
+- `max_sim_slots`: 最大 IoT 卡插槽数量(INT,1-4,默认 4)
+- `manufacturer`: 设备制造商(VARCHAR(255),可选)
+- `batch_no`: 批次号(VARCHAR(100),用于批量导入追溯)
+
+**店铺归属和状态**:
+- `shop_id`: 店铺 ID(BIGINT,可空,NULL 表示平台库存,有值表示店铺所有)
+- `status`: 设备状态(INT,1-在库 2-已分销 3-已激活 4-已停用)
+- `activated_at`: 激活时间(TIMESTAMP,可空)
+
+**设备操作配置**(预留字段,用于后续设备操作功能):
+- `device_username`: 设备登录账号(VARCHAR(100),可选)
+- `device_password_encrypted`: 设备登录密码(加密存储,VARCHAR(255),可选)
+- `device_api_endpoint`: 设备 API 接口地址(VARCHAR(500),可选)
+
+**系统字段**:
+- `created_at`: 创建时间(TIMESTAMP,自动填充)
+- `updated_at`: 更新时间(TIMESTAMP,自动填充)
+- `creator`: 创建人 ID(BIGINT)
+- `updater`: 更新人 ID(BIGINT)
+
+#### Scenario: 用户添加设备
+
+- **WHEN** 用户添加自己的设备(设备编号为 "GPS-001",设备名称为 "物流车辆追踪器")
+- **THEN** 系统创建设备记录,根据用户归属设置 `shop_id`,状态为 1(在库)
+
+#### Scenario: 平台导入设备到库存
+
+- **WHEN** 平台批量导入设备数据(准备发货给代理)
+- **THEN** 系统创建设备记录,`shop_id` 为 NULL(平台库存),状态为 1(在库)
+
+#### Scenario: 运营人员批量分配设备给代理店铺
+
+- **WHEN** 运营人员将平台库存设备(ID 为 1001)分配给代理店铺(ID 为 10)
+- **THEN** 系统将设备的 `shop_id` 设置为 10,同时自动将该设备绑定的所有 IoT 卡的 `shop_id` 也设置为 10
+
+---
+
+### Requirement: 设备批量分配
+
+系统 SHALL 支持运营人员批量分配设备给代理店铺,设备分配时自动分配该设备绑定的所有 IoT 卡。
+
+**分配规则**:
+- 只能分配 `shop_id` 为 NULL 的设备(平台库存)
+- 分配时,设备的 `shop_id` 设置为目标店铺 ID
+- 分配时,设备绑定的所有 IoT 卡的 `shop_id` 也设置为目标店铺 ID
+- 分配操作记录到操作日志
+
+#### Scenario: 运营人员批量分配设备
+
+- **WHEN** 运营人员将 10 台设备(平台库存)分配给代理店铺(ID 为 10)
+- **THEN** 系统将这 10 台设备的 `shop_id` 设置为 10,同时将这些设备绑定的所有 IoT 卡的 `shop_id` 也设置为 10
+
+#### Scenario: 分配已分配的设备
+
+- **WHEN** 运营人员尝试分配 `shop_id` 不为 NULL 的设备
+- **THEN** 系统拒绝分配,返回错误信息"该设备已分配给店铺,不能重复分配"
+
+---
+
+### Requirement: 设备与 IoT 卡绑定关系
+
+系统 SHALL 管理设备与 IoT 卡的绑定关系,一个设备可以绑定 1-4 张 IoT 卡。
+
+**绑定规则**:
+- 一个设备最多绑定 4 张 IoT 卡(由 `max_sim_slots` 字段控制)
+- 一个 IoT 卡同一时间只能绑定一个设备
+- 绑定时记录插槽位置(slot_position: 1, 2, 3, 4)
+- 绑定时记录绑定时间和绑定状态(1-已绑定 2-已解绑)
+- 绑定/解绑操作不改变 IoT 卡的 shop_id(所有权由分销操作管理,而非绑定操作)
+
+**中间表 device_sim_bindings**:
+- `id`: 绑定记录 ID(主键,BIGINT)
+- `device_id`: 设备 ID(BIGINT)
+- `iot_card_id`: IoT 卡 ID(BIGINT)
+- `slot_position`: 插槽位置(INT,1-4)
+- `bind_status`: 绑定状态(INT,1-已绑定 2-已解绑)
+- `bind_time`: 绑定时间(TIMESTAMP)
+- `unbind_time`: 解绑时间(TIMESTAMP,可空)
+- `created_at`: 创建时间(TIMESTAMP,自动填充)
+- `updated_at`: 更新时间(TIMESTAMP,自动填充)
+
+#### Scenario: 绑定 IoT 卡到设备
+
+- **WHEN** 用户将 IoT 卡(ID 为 101)绑定到设备(ID 为 1001)的插槽 1
+- **THEN** 系统创建绑定记录,`device_id` 为 1001,`iot_card_id` 为 101,`slot_position` 为 1,`bind_status` 为 1(已绑定),`bind_time` 为当前时间
+
+#### Scenario: 解绑 IoT 卡
+
+- **WHEN** 用户解绑设备的 IoT 卡(绑定记录 ID 为 10)
+- **THEN** 系统将绑定记录的 `bind_status` 从 1(已绑定) 变更为 2(已解绑),`unbind_time` 记录解绑时间,IoT 卡的 `shop_id` 保持不变
+
+---
+
+### Requirement: 设备查询和筛选
+
+系统 SHALL 支持多维度查询和筛选设备,包括状态、店铺归属、批次号、设备类型等。
+
+**查询条件**:
+- 设备编号(精确匹配或模糊匹配)
+- 设备名称(模糊匹配)
+- 设备状态(单选或多选)
+- 店铺 ID(shop_id): 可选,NULL 表示平台库存
+- 批次号(精确匹配)
+- 设备类型(单选或多选)
+- 设备制造商(模糊匹配)
+- 激活时间范围(开始时间 - 结束时间)
+- 创建时间范围(开始时间 - 结束时间)
+
+**分页**:
+- 默认每页 20 条,最大每页 100 条
+- 返回总记录数和总页数
+
+**数据权限**:
+- 基于 shop_id 自动应用数据权限过滤
+- 代理只能看到自己店铺及下级店铺的设备
+
+#### Scenario: 查询平台库存设备
+
+- **WHEN** 运营人员查询平台库存设备
+- **THEN** 系统返回 `shop_id` 为 NULL 的设备列表
+
+#### Scenario: 代理查询自己店铺的设备
+
+- **WHEN** 代理店铺(ID 为 10)查询自己的设备
+- **THEN** 系统返回 `shop_id` 为 10(及其下级店铺)的设备列表
+
+---
+
+### Requirement: 设备数据校验
+
+系统 SHALL 对设备数据进行校验,确保数据完整性和一致性。
+
+**校验规则**:
+- 设备编号(device_no):必填,长度 1-100 字符,唯一
+- 设备名称(device_name):可选,长度 1-255 字符
+- 设备型号(device_model):可选,长度 1-100 字符
+- 设备类型(device_type):可选,长度 1-50 字符
+- 最大插槽数(max_sim_slots):必填,1-4 之间的整数
+- 店铺 ID(shop_id):可选,NULL 表示平台库存,有值必须是有效的店铺 ID
+- 设备状态(status):必填,枚举值 1(在库) | 2(已分销) | 3(已激活) | 4(已停用)
+
+#### Scenario: 创建设备时插槽数超出范围
+
+- **WHEN** 用户创建设备,最大插槽数为 5
+- **THEN** 系统拒绝创建,返回错误信息"最大插槽数必须在 1-4 之间"
+
+#### Scenario: 创建设备时设备编号重复
+
+- **WHEN** 用户创建设备,设备编号为已存在的 "DEV-001"
+- **THEN** 系统拒绝创建,返回错误信息"设备编号已存在"

openspec/changes/archive/2026-01-23-iot-card-standalone-management/tasks.md

@@ -0,0 +1,75 @@
+# Tasks: IoT 卡单卡管理与所有权模型重构
+
+## 1. 模型重构（清理 Owner 字段）
+
+- [x] 1.1 修改 IotCard 模型：移除 OwnerType、OwnerID 字段
+- [x] 1.2 修改 Device 模型：移除 OwnerType、OwnerID 字段
+- [x] 1.3 创建数据库迁移：删除 tb_iot_card 的 owner_type、owner_id 列
+- [x] 1.4 创建数据库迁移：删除 tb_device 的 owner_type、owner_id 列
+- [x] 1.5 更新相关 DTO：移除 OwnerType、OwnerID 相关字段
+- [x] 1.6 更新相关 Service/Store：移除 Owner 相关逻辑，改用 ShopID
+
+## 2. 导入任务模型
+
+- [x] 2.1 创建 IotCardImportTask 模型
+- [x] 2.2 创建数据库迁移：tb_iot_card_import_task 表
+- [x] 2.3 创建 IotCardImportTaskStore
+- [x] 2.4 创建导入任务相关 DTO
+
+## 3. ICCID 校验逻辑
+
+- [x] 3.1 在 pkg/validator 中添加 ICCID 校验函数
+- [x] 3.2 实现根据运营商校验 ICCID 长度（电信19位，其他20位）
+- [x] 3.3 支持字母数字混合校验（移动有字母）
+- [x] 3.4 更新现有导入逻辑使用新校验函数
+
+## 4. 单卡列表 API
+
+- [x] 4.1 创建单卡列表查询 DTO（请求/响应）
+- [x] 4.2 实现 IotCardStore.ListStandalone 方法（未绑定设备的卡）
+- [x] 4.3 实现 IotCardService.ListStandalone 方法
+- [x] 4.4 实现 IotCardHandler.ListStandalone 方法
+- [x] 4.5 注册路由 GET /api/admin/iot-cards/standalone
+
+## 5. 批量导入 API
+
+- [x] 5.1 创建导入请求 DTO（含 CSV 文件上传）
+- [x] 5.2 实现 CSV 解析逻辑
+- [x] 5.3 实现 IotCardImportService.CreateImportTask 方法
+- [x] 5.4 实现 IotCardImportHandler.Import 方法
+- [x] 5.5 注册路由 POST /api/admin/iot-cards/import
+
+## 6. 异步导入 Worker
+
+- [x] 6.1 创建 IotCardImportTask Asynq 任务类型
+- [x] 6.2 实现 IotCardImportHandler（Worker 处理器）
+- [x] 6.3 实现分批处理逻辑（1000条/批）
+- [x] 6.4 实现 ICCID 去重检查
+- [x] 6.5 实现进度更新和结果记录
+
+## 7. 导入任务查询 API
+
+- [x] 7.1 创建导入任务列表查询 DTO
+- [x] 7.2 创建导入任务详情 DTO
+- [x] 7.3 实现 IotCardImportTaskService.List 方法
+- [x] 7.4 实现 IotCardImportTaskService.GetByID 方法
+- [x] 7.5 实现 IotCardImportTaskHandler.List 方法
+- [x] 7.6 实现 IotCardImportTaskHandler.GetByID 方法
+- [x] 7.7 注册路由 GET /api/admin/iot-cards/import-tasks
+- [x] 7.8 注册路由 GET /api/admin/iot-cards/import-tasks/:id
+
+## 8. 测试
+
+- [x] 8.1 IotCardStore.ListStandalone 单元测试
+- [x] 8.2 ICCID 校验函数单元测试
+- [x] 8.3 CSV 解析逻辑单元测试
+- [x] 8.4 导入 Worker 单元测试
+- [x] 8.5 单卡列表 API 集成测试
+- [x] 8.6 批量导入 API 集成测试
+
+## 9. 文档和规范更新
+
+- [x] 9.1 更新 iot-card/spec.md（同步 delta 变更）
+- [x] 9.2 更新 iot-device/spec.md（同步 delta 变更）
+- [x] 9.3 创建 iot-card-import-task/spec.md
+- [x] 9.4 更新 API 文档（通过 openspec archive 自动完成）

openspec/specs/iot-card-import-task/spec.md

@@ -0,0 +1,176 @@
+# iot-card-import-task Specification
+
+## Purpose
+TBD - created by archiving change iot-card-standalone-management. Update Purpose after archive.
+## Requirements
+### Requirement: 导入任务实体定义
+
+系统 SHALL 定义 IoT 卡导入任务(IotCardImportTask)实体,用于跟踪 IoT 卡批量导入的进度和结果。
+
+**实体字段**:
+
+**任务信息**:
+- `id`: 任务 ID(主键,BIGINT)
+- `task_no`: 任务编号(VARCHAR(50),唯一,格式: IMP-YYYYMMDD-XXXXXX)
+- `status`: 任务状态(INT,1-待处理 2-处理中 3-已完成 4-失败)
+
+**导入参数**:
+- `carrier_id`: 运营商 ID(BIGINT,必填)
+- `batch_no`: 批次号(VARCHAR(100),可选)
+- `file_name`: 原始文件名(VARCHAR(255),可选)
+
+**进度统计**:
+- `total_count`: 总数(INT,CSV 文件总行数)
+- `success_count`: 成功数(INT,成功导入的 ICCID 数量)
+- `skip_count`: 跳过数(INT,因重复等原因跳过的数量)
+- `fail_count`: 失败数(INT,因格式错误等原因失败的数量)
+
+**结果详情**:
+- `skipped_items`: 跳过记录详情(JSONB,结构: [{line, iccid, reason}])
+- `failed_items`: 失败记录详情(JSONB,结构: [{line, iccid, reason}])
+
+**时间和错误**:
+- `started_at`: 开始处理时间(TIMESTAMP,可空)
+- `completed_at`: 完成时间(TIMESTAMP,可空)
+- `error_message`: 任务级错误信息(TEXT,可空,如文件解析失败等)
+
+**系统字段**:
+- `shop_id`: 店铺 ID(BIGINT,可空,记录发起导入的店铺)
+- `created_at`: 创建时间(TIMESTAMP,自动填充)
+- `updated_at`: 更新时间(TIMESTAMP,自动填充)
+- `creator`: 创建人 ID(BIGINT)
+- `updater`: 更新人 ID(BIGINT)
+
+#### Scenario: 创建导入任务
+
+- **WHEN** 管理员上传 CSV 文件发起导入
+- **THEN** 系统创建导入任务记录,`status` 为 1(待处理),`total_count` 为 CSV 行数,返回任务 ID
+
+#### Scenario: 导入任务开始处理
+
+- **WHEN** Worker 开始处理导入任务
+- **THEN** 系统将任务 `status` 从 1(待处理) 变更为 2(处理中),`started_at` 记录当前时间
+
+#### Scenario: 导入任务完成
+
+- **WHEN** Worker 完成导入任务处理
+- **THEN** 系统将任务 `status` 变更为 3(已完成),`completed_at` 记录当前时间,更新 `success_count`、`skip_count`、`fail_count`
+
+#### Scenario: 导入任务失败
+
+- **WHEN** Worker 处理导入任务时发生严重错误(如文件损坏)
+- **THEN** 系统将任务 `status` 变更为 4(失败),`error_message` 记录错误信息
+
+---
+
+### Requirement: 导入任务状态流转
+
+系统 SHALL 管理导入任务的状态流转,确保状态变更符合业务规则。
+
+**状态定义**:
+- **1-待处理**: 任务已创建,等待 Worker 处理
+- **2-处理中**: Worker 正在处理导入
+- **3-已完成**: 导入处理完成(可能有部分失败)
+- **4-失败**: 任务级别错误,导入中断
+
+**状态流转规则**:
+- 待处理(1) → 处理中(2): Worker 开始处理
+- 处理中(2) → 已完成(3): 处理完成
+- 处理中(2) → 失败(4): 发生严重错误
+- 待处理(1) → 失败(4): 文件验证失败等
+
+#### Scenario: 正常状态流转
+
+- **WHEN** 导入任务经历完整生命周期
+- **THEN** 状态依次变更: 待处理(1) → 处理中(2) → 已完成(3)
+
+#### Scenario: 异常状态流转
+
+- **WHEN** 导入任务处理过程中发生严重错误
+- **THEN** 状态变更: 待处理(1) → 处理中(2) → 失败(4)
+
+---
+
+### Requirement: 导入任务列表查询
+
+系统 SHALL 支持查询导入任务列表,用于管理和监控导入任务。
+
+**查询条件**:
+- 任务状态(status): 可选,1-待处理 2-处理中 3-已完成 4-失败
+- 运营商 ID(carrier_id): 可选
+- 批次号(batch_no): 可选,模糊匹配
+- 创建时间范围: 可选
+
+**分页**:
+- 默认每页 20 条,最大每页 100 条
+- 默认按创建时间倒序排列
+
+**数据权限**:
+- 基于 shop_id 自动应用数据权限过滤
+- 代理只能看到自己店铺及下级店铺发起的导入任务
+
+#### Scenario: 查询所有导入任务
+
+- **WHEN** 管理员查询导入任务列表
+- **THEN** 系统返回导入任务列表,包含任务编号、状态、运营商、总数、成功数、跳过数、失败数、创建时间
+
+#### Scenario: 按状态筛选导入任务
+
+- **WHEN** 管理员查询状态为 2(处理中) 的导入任务
+- **THEN** 系统返回所有正在处理的导入任务列表
+
+---
+
+### Requirement: 导入任务详情查询
+
+系统 SHALL 支持查询单个导入任务的详细信息,包括跳过/失败记录详情。
+
+**详情信息**:
+- 任务基本信息: 任务编号、状态、运营商、批次号、文件名
+- 进度统计: 总数、成功数、跳过数、失败数
+- 时间信息: 创建时间、开始时间、完成时间
+- 跳过记录详情: 行号、ICCID、原因
+- 失败记录详情: 行号、ICCID、原因
+- 错误信息: 任务级错误(如有)
+
+#### Scenario: 查询导入任务详情
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的详情
+- **THEN** 系统返回任务完整信息,包括跳过和失败记录的详细列表
+
+#### Scenario: 查询导入任务的跳过记录
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的跳过记录
+- **THEN** 系统返回跳过记录列表,每条包含: 行号(line)、ICCID、原因(如"ICCID 已存在")
+
+#### Scenario: 查询导入任务的失败记录
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的失败记录
+- **THEN** 系统返回失败记录列表,每条包含: 行号(line)、ICCID、原因(如"电信 ICCID 必须为 19 位")
+
+---
+
+### Requirement: 导入任务数据校验
+
+系统 SHALL 对导入任务数据进行校验,确保数据完整性和一致性。
+
+**校验规则**:
+- 任务编号(task_no): 必填,系统自动生成,格式 IMP-YYYYMMDD-XXXXXX,唯一
+- 任务状态(status): 必填,枚举值 1(待处理) | 2(处理中) | 3(已完成) | 4(失败)
+- 运营商 ID(carrier_id): 必填,必须是有效的运营商 ID
+- 总数(total_count): 必填,≥ 0
+- 成功数(success_count): 必填,≥ 0,≤ total_count
+- 跳过数(skip_count): 必填,≥ 0,≤ total_count
+- 失败数(fail_count): 必填,≥ 0,≤ total_count
+- 数量一致性: success_count + skip_count + fail_count ≤ total_count
+
+#### Scenario: 创建任务时运营商 ID 无效
+
+- **WHEN** 创建导入任务时 carrier_id 不存在
+- **THEN** 系统拒绝创建,返回错误信息"运营商 ID 无效"
+
+#### Scenario: 更新任务时数量不一致
+
+- **WHEN** 更新导入任务时 success_count + skip_count + fail_count > total_count
+- **THEN** 系统拒绝更新,返回错误信息"统计数量不一致"
+

openspec/specs/iot-card/spec.md

@@ -10,9 +10,7 @@ This capability supports:
 - Integration with Gateway project for real-time status synchronization
 - Batch import and multi-dimensional querying
 - Support for normal cards (require real-name verification) and industry cards (no real-name required)
-
 ## Requirements
-
 ### Requirement: IoT 卡实体定义
 
 系统 SHALL 定义 IoT 卡(IotCard)实体,包含 IoT 卡(物联网卡/流量卡/SIM卡)的商品属性、状态属性、所有权信息和 Gateway 集成字段。
@@ -161,35 +159,60 @@ This capability supports:
 
 ### Requirement: IoT 卡批量导入
 
-系统 SHALL 支持批量导入 IoT 卡数据,用于初始化库存或补充库存。
+系统 SHALL 支持通过 CSV 文件批量导入 IoT 卡 ICCID,支持大批量数据(几万条),异步处理并跟踪导入进度。
 
-**导入字段**:
+**导入方式**:
-- ICCID(必填)
+- 上传 CSV 文件,每行一个 ICCID
-- 卡类型(必填,如 "4G"、"5G"、"NB-IoT")
+- 在界面选择运营商、批次号等公共参数
-- 卡业务类型(可选,枚举值 "normal" | "industry",默认 "normal")
+- 不支持一次导入多种运营商的卡
-- 运营商 ID(必填,从 carriers 表中选择)
-- IMSI(可选)
-- 手机号码(可选)
-- 供应商(可选)
-- 成本价(必填)
-- 批次号(必填)
 
-**导入规则**:
+**导入参数**:
-- ICCID 必须唯一,重复 ICCID 将被拒绝
+- CSV 文件(必填): 仅包含 ICCID 列
-- 导入的 IoT 卡默认状态为 1(在库),所有者为平台(`owner_type` 为 "platform",`owner_id` 为 0)
+- 运营商 ID(必填): 在界面选择
-- 导入成功后记录操作日志
+- 批次号(可选): 在界面填写
 
-#### Scenario: 批量导入 IoT 卡成功
+**校验规则**:
+- ICCID 格式校验: 字母数字混合,长度根据运营商(电信19位,其他20位)
+- ICCID 唯一性校验: 重复 ICCID 跳过,不中断导入
 
-- **WHEN** 平台上传包含 100 条 IoT 卡数据的 CSV 文件
+**处理规则**:
-- **THEN** 系统创建 100 条 IoT 卡记录,状态为 1(在库),所有者为平台,返回导入成功消息
+- 异步处理: 创建导入任务后立即返回任务 ID
+- 分批处理: 每批 1000 条
+- 重复处理: 跳过已存在的 ICCID,记录跳过原因
+- 格式错误: 记录失败原因,继续处理其他行
 
-#### Scenario: 批量导入包含重复 ICCID
+**导入结果**:
+- 总数(total_count)
+- 成功数(success_count)
+- 跳过数(skip_count): 因重复等原因跳过
+- 失败数(fail_count): 因格式错误等原因失败
+- 跳过详情: 包含行号、ICCID、原因
+- 失败详情: 包含行号、ICCID、原因
 
-- **WHEN** 平台上传的 CSV 文件中包含已存在的 ICCID
+#### Scenario: 发起 IoT 卡批量导入
-- **THEN** 系统拒绝重复 ICCID 的 IoT 卡,返回错误信息并列出重复 ICCID,其他有效 IoT 卡正常导入
 
----
+- **WHEN** 管理员上传包含 10000 个 ICCID 的 CSV 文件,选择运营商为电信,批次号为 "BATCH-2025-001"
+- **THEN** 系统创建导入任务,返回任务 ID,后台异步处理导入
+
+#### Scenario: 导入时跳过重复 ICCID
+
+- **WHEN** CSV 文件中的 ICCID "8986001234567890123" 已存在于系统中
+- **THEN** 系统跳过该 ICCID,记录跳过原因为"ICCID 已存在",继续处理其他 ICCID
+
+#### Scenario: 导入时记录格式错误
+
+- **WHEN** CSV 文件第 100 行的 ICCID "12345" 长度不符合电信卡要求(19位)
+- **THEN** 系统记录失败,原因为"电信 ICCID 必须为 19 位",行号为 100,继续处理其他 ICCID
+
+#### Scenario: 查询导入任务进度
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的进度
+- **THEN** 系统返回任务状态、总数、成功数、跳过数、失败数、开始时间、完成时间
+
+#### Scenario: 查询导入任务失败详情
+
+- **WHEN** 管理员查询导入任务(ID 为 1)的失败详情
+- **THEN** 系统返回失败记录列表,每条包含行号、ICCID、失败原因
 
 ### Requirement: IoT 卡查询和筛选
 
@@ -302,3 +325,51 @@ This capability supports:
 
 - **WHEN** 平台创建 IoT 卡,成本价为 50.00,分销价为 40.00
 - **THEN** 系统拒绝创建,返回错误信息"分销价不能低于成本价"
+
+### Requirement: 单卡列表查询
+
+系统 SHALL 提供单卡列表查询功能,用于管理未绑定设备的 IoT 卡资产。
+
+**单卡定义**: 单卡是指未绑定到任何设备的 IoT 卡,即在 `device_sim_bindings` 表中不存在 `bind_status = 1`(已绑定) 的记录。
+
+**查询条件**:
+- 套餐 ID(package_id): 可选,筛选已购买指定套餐的卡
+- 是否分销(is_distributed): 可选,true-已分销 false-未分销
+- 卡号状态(status): 可选,1-在库 2-已分销 3-已激活 4-已停用
+- 运营商(carrier_id): 可选,运营商 ID
+- 分销商 ID(shop_id): 可选,店铺 ID
+- 网卡号段(iccid_range): 可选,格式 "起始ICCID-结束ICCID"
+- ICCID: 可选,模糊匹配
+- 卡接入号(msisdn): 可选,模糊匹配
+- 是否换卡(is_replaced): 可选,true-有换卡记录 false-无换卡记录
+
+**分页**:
+- 默认每页 20 条,最大每页 100 条
+- 返回总记录数和总页数
+
+**数据权限**:
+- 基于 shop_id 自动应用数据权限过滤
+- 代理只能看到自己店铺及下级店铺的卡
+
+#### Scenario: 查询未绑定设备的单卡列表
+
+- **WHEN** 管理员查询单卡列表
+- **THEN** 系统返回所有未绑定设备的 IoT 卡(在 device_sim_bindings 中无 bind_status=1 记录的卡)
+
+#### Scenario: 按运营商筛选单卡
+
+- **WHEN** 管理员查询运营商 ID 为 1(电信)的单卡
+- **THEN** 系统返回 carrier_id = 1 且未绑定设备的 IoT 卡列表
+
+#### Scenario: 按网卡号段筛选单卡
+
+- **WHEN** 管理员查询 ICCID 号段为 "8986001000000000000-8986001999999999999" 的单卡
+- **THEN** 系统返回 ICCID 在该号段范围内且未绑定设备的 IoT 卡列表
+
+#### Scenario: 按是否换卡筛选单卡
+
+- **WHEN** 管理员查询有换卡记录的单卡(is_replaced=true)
+- **THEN** 系统返回在 card_replacement_records 表中有记录的 IoT 卡列表
+
+---
+

openspec/specs/iot-device/spec.md

@@ -10,9 +10,7 @@ This capability supports:
 - Device-level package purchases with shared data pool
 - Batch device allocation to agents
 - Remote device operations (reboot, password change, reset)
-
 ## Requirements
-
 ### Requirement: 设备实体定义
 
 系统 SHALL 定义设备(Device)实体,用于管理用户的物联网设备(如 GPS 追踪器、智能传感器等),支持设备与 IoT 卡的绑定关系、设备批量分配和设备操作。
@@ -27,7 +25,7 @@ This capability supports:
 
 **基本属性**:
 - `id`: 设备 ID(主键,BIGINT)
-- `device_no`: 设备编号(唯一,VARCHAR(50))
+- `device_no`: 设备编号(唯一,VARCHAR(100))
 - `device_name`: 设备名称(VARCHAR(255))
 - `device_model`: 设备型号(VARCHAR(100))
 - `device_type`: 设备类型(VARCHAR(50),如 "GPS Tracker"、"Camera"、"Sensor")
@@ -35,35 +33,36 @@ This capability supports:
 - `manufacturer`: 设备制造商(VARCHAR(255),可选)
 - `batch_no`: 批次号(VARCHAR(100),用于批量导入追溯)
 
-**所有权和状态**:
+**店铺归属和状态**:
-- `owner_type`: 所有者类型(VARCHAR(20),"platform"-平台库存(等待分配) | "agent"-代理商 | "user"-用户)
+- `shop_id`: 店铺 ID(BIGINT,可空,NULL 表示平台库存,有值表示店铺所有)
-- `owner_id`: 所有者 ID(BIGINT,platform 时为 0,agent/user 时为对应的 ID)
+- `status`: 设备状态(INT,1-在库 2-已分销 3-已激活 4-已停用)
-- `status`: 设备状态(INT,1-未激活 2-已激活 3-已停用)
 - `activated_at`: 激活时间(TIMESTAMP,可空)
 
 **设备操作配置**(预留字段,用于后续设备操作功能):
 - `device_username`: 设备登录账号(VARCHAR(100),可选)
-- `device_password_encrypted`: 设备登录密码(加密存储,TEXT,可选)
+- `device_password_encrypted`: 设备登录密码(加密存储,VARCHAR(255),可选)
 - `device_api_endpoint`: 设备 API 接口地址(VARCHAR(500),可选)
 
 **系统字段**:
 - `created_at`: 创建时间(TIMESTAMP,自动填充)
 - `updated_at`: 更新时间(TIMESTAMP,自动填充)
+- `creator`: 创建人 ID(BIGINT)
+- `updater`: 更新人 ID(BIGINT)
 
 #### Scenario: 用户添加设备
 
 - **WHEN** 用户添加自己的设备(设备编号为 "GPS-001",设备名称为 "物流车辆追踪器")
-- **THEN** 系统创建设备记录,`owner_type` 为 "user",`owner_id` 为用户 ID,状态为 1(未激活)
+- **THEN** 系统创建设备记录,根据用户归属设置 `shop_id`,状态为 1(在库)
 
 #### Scenario: 平台导入设备到库存
 
 - **WHEN** 平台批量导入设备数据(准备发货给代理)
-- **THEN** 系统创建设备记录,`owner_type` 为 "platform",`owner_id` 为 0,状态为 1(未激活)
+- **THEN** 系统创建设备记录,`shop_id` 为 NULL(平台库存),状态为 1(在库)
 
-#### Scenario: 运营人员批量分配设备给代理
+#### Scenario: 运营人员批量分配设备给代理店铺
 
-- **WHEN** 运营人员将平台库存设备(ID 为 1001)分配给代理商(用户 ID 为 123)
+- **WHEN** 运营人员将平台库存设备(ID 为 1001)分配给代理店铺(ID 为 10)
-- **THEN** 系统将设备的 `owner_type` 变更为 "agent",`owner_id` 设置为 123,同时自动分配该设备绑定的所有 IoT 卡给代理
+- **THEN** 系统将设备的 `shop_id` 设置为 10,同时自动将该设备绑定的所有 IoT 卡的 `shop_id` 也设置为 10
 
 ---
 
@@ -102,7 +101,7 @@ This capability supports:
 - 一个 IoT 卡同一时间只能绑定一个设备
 - 绑定时记录插槽位置(slot_position: 1, 2, 3, 4)
 - 绑定时记录绑定时间和绑定状态(1-已绑定 2-已解绑)
-- 设备绑定 IoT 卡后,IoT 卡的 `owner_type` 变更为 "device",`owner_id` 变更为设备 ID
+- 绑定/解绑操作不改变 IoT 卡的 shop_id(所有权由分销操作管理,而非绑定操作)
 
 **中间表 device_sim_bindings**:
 - `id`: 绑定记录 ID(主键,BIGINT)
@@ -118,27 +117,12 @@ This capability supports:
 #### Scenario: 绑定 IoT 卡到设备
 
 - **WHEN** 用户将 IoT 卡(ID 为 101)绑定到设备(ID 为 1001)的插槽 1
-- **THEN** 系统创建绑定记录,`device_id` 为 1001,`iot_card_id` 为 101,`slot_position` 为 1,`bind_status` 为 1(已绑定),`bind_time` 为当前时间,IoT 卡的 `owner_type` 变更为 "device",`owner_id` 变更为 1001
+- **THEN** 系统创建绑定记录,`device_id` 为 1001,`iot_card_id` 为 101,`slot_position` 为 1,`bind_status` 为 1(已绑定),`bind_time` 为当前时间
-
-#### Scenario: 绑定超过最大插槽数量
-
-- **WHEN** 用户尝试将第 5 张 IoT 卡绑定到最大插槽数为 4 的设备
-- **THEN** 系统拒绝绑定,返回错误信息"设备插槽已满,最多支持 4 张 IoT 卡"
-
-#### Scenario: 绑定已被占用的 IoT 卡
-
-- **WHEN** 用户尝试绑定已被其他设备绑定的 IoT 卡
-- **THEN** 系统拒绝绑定,返回错误信息"该 IoT 卡已被其他设备绑定"
 
 #### Scenario: 解绑 IoT 卡
 
 - **WHEN** 用户解绑设备的 IoT 卡(绑定记录 ID 为 10)
-- **THEN** 系统将绑定记录的 `bind_status` 从 1(已绑定) 变更为 2(已解绑),`unbind_time` 记录解绑时间,IoT 卡的 `owner_type` 和 `owner_id` 重置
+- **THEN** 系统将绑定记录的 `bind_status` 从 1(已绑定) 变更为 2(已解绑),`unbind_time` 记录解绑时间,IoT 卡的 `shop_id` 保持不变
-
-#### Scenario: 查询设备当前绑定的 IoT 卡
-
-- **WHEN** 用户查询设备(ID 为 1001)当前绑定的 IoT 卡
-- **THEN** 系统返回 `device_id` 为 1001 且 `bind_status` 为 1(已绑定) 的所有绑定记录,包含 IoT 卡信息(ICCID、运营商、激活状态等)和插槽位置
 
 ---
 
@@ -179,23 +163,23 @@ This capability supports:
 
 ### Requirement: 设备批量分配
 
-系统 SHALL 支持运营人员批量分配设备给代理,设备分配时自动分配该设备绑定的所有 IoT 卡。
+系统 SHALL 支持运营人员批量分配设备给代理店铺,设备分配时自动分配该设备绑定的所有 IoT 卡。
 
 **分配规则**:
-- 只能分配 `owner_type` 为 "platform" 的设备(平台库存)
+- 只能分配 `shop_id` 为 NULL 的设备(平台库存)
-- 分配时,设备的 `owner_type` 变更为 "agent",`owner_id` 设置为代理用户 ID
+- 分配时,设备的 `shop_id` 设置为目标店铺 ID
-- 分配时,设备绑定的所有 IoT 卡的 `owner_type` 也变更为 "agent",`owner_id` 设置为代理用户 ID
+- 分配时,设备绑定的所有 IoT 卡的 `shop_id` 也设置为目标店铺 ID
 - 分配操作记录到操作日志
 
 #### Scenario: 运营人员批量分配设备
 
-- **WHEN** 运营人员将 10 台设备(平台库存)分配给代理商(用户 ID 为 123)
+- **WHEN** 运营人员将 10 台设备(平台库存)分配给代理店铺(ID 为 10)
-- **THEN** 系统将这 10 台设备的 `owner_type` 变更为 "agent",`owner_id` 设置为 123,同时将这些设备绑定的所有 IoT 卡也分配给代理 123
+- **THEN** 系统将这 10 台设备的 `shop_id` 设置为 10,同时将这些设备绑定的所有 IoT 卡的 `shop_id` 也设置为 10
 
 #### Scenario: 分配已分配的设备
 
-- **WHEN** 运营人员尝试分配 `owner_type` 为 "agent" 的设备
+- **WHEN** 运营人员尝试分配 `shop_id` 不为 NULL 的设备
-- **THEN** 系统拒绝分配,返回错误信息"该设备已分配给代理,不能重复分配"
+- **THEN** 系统拒绝分配,返回错误信息"该设备已分配给店铺,不能重复分配"
 
 ---
 
@@ -259,14 +243,13 @@ This capability supports:
 
 ### Requirement: 设备查询和筛选
 
-系统 SHALL 支持多维度查询和筛选设备,包括状态、所有者、批次号、设备类型等。
+系统 SHALL 支持多维度查询和筛选设备,包括状态、店铺归属、批次号、设备类型等。
 
 **查询条件**:
 - 设备编号(精确匹配或模糊匹配)
 - 设备名称(模糊匹配)
 - 设备状态(单选或多选)
-- 所有者类型(platform | agent | user)
+- 店铺 ID(shop_id): 可选,NULL 表示平台库存
-- 所有者 ID(仅当所有者类型为 agent/user 时有效)
 - 批次号(精确匹配)
 - 设备类型(单选或多选)
 - 设备制造商(模糊匹配)
@@ -277,25 +260,19 @@ This capability supports:
 - 默认每页 20 条,最大每页 100 条
 - 返回总记录数和总页数
 
+**数据权限**:
+- 基于 shop_id 自动应用数据权限过滤
+- 代理只能看到自己店铺及下级店铺的设备
+
 #### Scenario: 查询平台库存设备
 
 - **WHEN** 运营人员查询平台库存设备
-- **THEN** 系统返回 `owner_type` 为 "platform" 的设备列表
+- **THEN** 系统返回 `shop_id` 为 NULL 的设备列表
 
-#### Scenario: 代理查询自己的设备
+#### Scenario: 代理查询自己店铺的设备
 
-- **WHEN** 代理商(用户 ID 为 123)查询自己的设备
+- **WHEN** 代理店铺(ID 为 10)查询自己的设备
-- **THEN** 系统返回 `owner_type` 为 "agent" 且 `owner_id` 为 123 的设备列表
+- **THEN** 系统返回 `shop_id` 为 10(及其下级店铺)的设备列表
-
-#### Scenario: 用户查询自己的设备
-
-- **WHEN** 用户(用户 ID 为 2001)查询自己的设备
-- **THEN** 系统返回 `owner_type` 为 "user" 且 `owner_id` 为 2001 的设备列表,包含设备绑定的所有 IoT 卡信息
-
-#### Scenario: 运营人员通过设备查看绑定的所有 IoT 卡
-
-- **WHEN** 运营人员需要处理投诉,查询设备(ID 为 1001)绑定的所有 IoT 卡
-- **THEN** 系统返回设备信息和绑定的所有 IoT 卡详细信息(ICCID、运营商、激活状态、流量使用等),方便统一查看和管理
 
 ---
 
@@ -304,14 +281,13 @@ This capability supports:
 系统 SHALL 对设备数据进行校验,确保数据完整性和一致性。
 
 **校验规则**:
-- 设备编号(device_no):必填,长度 1-50 字符,唯一
+- 设备编号(device_no):必填,长度 1-100 字符,唯一
-- 设备名称(device_name):必填,长度 1-255 字符
+- 设备名称(device_name):可选,长度 1-255 字符
-- 设备型号(device_model):必填,长度 1-100 字符
+- 设备型号(device_model):可选,长度 1-100 字符
-- 设备类型(device_type):必填,长度 1-50 字符
+- 设备类型(device_type):可选,长度 1-50 字符
 - 最大插槽数(max_sim_slots):必填,1-4 之间的整数
-- 所有者类型(owner_type):必填,枚举值 "platform" | "agent" | "user"
+- 店铺 ID(shop_id):可选,NULL 表示平台库存,有值必须是有效的店铺 ID
-- 所有者 ID(owner_id):必填,≥ 0,当 owner_type 为 "platform" 时必须为 0
+- 设备状态(status):必填,枚举值 1(在库) | 2(已分销) | 3(已激活) | 4(已停用)
-- 设备状态(status):必填,枚举值 1(未激活) | 2(已激活) | 3(已停用)
 
 #### Scenario: 创建设备时插槽数超出范围
 
@@ -322,3 +298,4 @@ This capability supports:
 
 - **WHEN** 用户创建设备,设备编号为已存在的 "DEV-001"
 - **THEN** 系统拒绝创建,返回错误信息"设备编号已存在"
+

pkg/constants/constants.go

@@ -43,6 +43,7 @@ const (
 	TaskTypeDataSync      = "data:sync"            // 数据同步
 	TaskTypeSIMStatusSync = "sim:status:sync"      // SIM 卡状态同步
 	TaskTypeCommission    = "commission:calculate" // 分佣计算
+	TaskTypeIotCardImport = "iot_card:import"      // IoT 卡批量导入
 )
 
 // 用户状态常量

pkg/queue/handler.go

@@ -6,6 +6,7 @@ import (
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/internal/task"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 )
@@ -30,27 +31,34 @@ func NewHandler(db *gorm.DB, redis *redis.Client, logger *zap.Logger) *Handler {
 
 // RegisterHandlers 注册所有任务处理器
 func (h *Handler) RegisterHandlers() *asynq.ServeMux {
-	// 创建任务处理器实例
 	emailHandler := task.NewEmailHandler(h.redis, h.logger)
 	syncHandler := task.NewSyncHandler(h.db, h.logger)
 	simHandler := task.NewSIMHandler(h.db, h.redis, h.logger)
 
-	// 注册邮件发送任务
 	h.mux.HandleFunc(constants.TaskTypeEmailSend, emailHandler.HandleEmailSend)
 	h.logger.Info("注册邮件发送任务处理器", zap.String("task_type", constants.TaskTypeEmailSend))
 
-	// 注册数据同步任务
 	h.mux.HandleFunc(constants.TaskTypeDataSync, syncHandler.HandleDataSync)
 	h.logger.Info("注册数据同步任务处理器", zap.String("task_type", constants.TaskTypeDataSync))
 
-	// 注册 SIM 卡状态同步任务
 	h.mux.HandleFunc(constants.TaskTypeSIMStatusSync, simHandler.HandleSIMStatusSync)
 	h.logger.Info("注册 SIM 状态同步任务处理器", zap.String("task_type", constants.TaskTypeSIMStatusSync))
 
+	h.registerIotCardImportHandler()
+
 	h.logger.Info("所有任务处理器注册完成")
 	return h.mux
 }
 
+func (h *Handler) registerIotCardImportHandler() {
+	importTaskStore := postgres.NewIotCardImportTaskStore(h.db, h.redis)
+	iotCardStore := postgres.NewIotCardStore(h.db, h.redis)
+	iotCardImportHandler := task.NewIotCardImportHandler(h.db, h.redis, importTaskStore, iotCardStore, h.logger)
+
+	h.mux.HandleFunc(constants.TaskTypeIotCardImport, iotCardImportHandler.HandleIotCardImport)
+	h.logger.Info("注册 IoT 卡导入任务处理器", zap.String("task_type", constants.TaskTypeIotCardImport))
+}
+
 // GetMux 获取 ServeMux（用于启动 Worker 服务器）
 func (h *Handler) GetMux() *asynq.ServeMux {
 	return h.mux

pkg/utils/csv.go

@@ -0,0 +1,70 @@
+package utils
+
+import (
+	"encoding/csv"
+	"io"
+	"strings"
+)
+
+type CSVParseResult struct {
+	ICCIDs      []string
+	TotalCount  int
+	ParseErrors []CSVParseError
+}
+
+type CSVParseError struct {
+	Line   int
+	ICCID  string
+	Reason string
+}
+
+func ParseICCIDFromCSV(reader io.Reader) (*CSVParseResult, error) {
+	csvReader := csv.NewReader(reader)
+	csvReader.FieldsPerRecord = -1
+	csvReader.TrimLeadingSpace = true
+
+	result := &CSVParseResult{
+		ICCIDs:      make([]string, 0),
+		ParseErrors: make([]CSVParseError, 0),
+	}
+
+	lineNum := 0
+	for {
+		record, err := csvReader.Read()
+		if err == io.EOF {
+			break
+		}
+		lineNum++
+
+		if err != nil {
+			result.ParseErrors = append(result.ParseErrors, CSVParseError{
+				Line:   lineNum,
+				Reason: "CSV 解析错误: " + err.Error(),
+			})
+			continue
+		}
+
+		if len(record) == 0 {
+			continue
+		}
+
+		iccid := strings.TrimSpace(record[0])
+		if iccid == "" {
+			continue
+		}
+
+		if lineNum == 1 && isHeader(iccid) {
+			continue
+		}
+
+		result.TotalCount++
+		result.ICCIDs = append(result.ICCIDs, iccid)
+	}
+
+	return result, nil
+}
+
+func isHeader(value string) bool {
+	lower := strings.ToLower(value)
+	return lower == "iccid" || lower == "卡号" || lower == "号码"
+}

pkg/utils/csv_test.go

@@ -0,0 +1,132 @@
+package utils
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseICCIDFromCSV(t *testing.T) {
+	tests := []struct {
+		name           string
+		csvContent     string
+		wantICCIDs     []string
+		wantTotalCount int
+		wantErrorCount int
+	}{
+		{
+			name:           "单列ICCID无表头",
+			csvContent:     "89860012345678901234\n89860012345678901235\n89860012345678901236",
+			wantICCIDs:     []string{"89860012345678901234", "89860012345678901235", "89860012345678901236"},
+			wantTotalCount: 3,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "单列ICCID有表头-iccid",
+			csvContent:     "iccid\n89860012345678901234\n89860012345678901235",
+			wantICCIDs:     []string{"89860012345678901234", "89860012345678901235"},
+			wantTotalCount: 2,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "单列ICCID有表头-ICCID大写",
+			csvContent:     "ICCID\n89860012345678901234",
+			wantICCIDs:     []string{"89860012345678901234"},
+			wantTotalCount: 1,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "单列ICCID有表头-卡号",
+			csvContent:     "卡号\n89860012345678901234",
+			wantICCIDs:     []string{"89860012345678901234"},
+			wantTotalCount: 1,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "单列ICCID有表头-号码",
+			csvContent:     "号码\n89860012345678901234",
+			wantICCIDs:     []string{"89860012345678901234"},
+			wantTotalCount: 1,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "空文件",
+			csvContent:     "",
+			wantICCIDs:     []string{},
+			wantTotalCount: 0,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "只有表头",
+			csvContent:     "iccid",
+			wantICCIDs:     []string{},
+			wantTotalCount: 0,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "包含空行",
+			csvContent:     "89860012345678901234\n\n89860012345678901235\n  \n89860012345678901236",
+			wantICCIDs:     []string{"89860012345678901234", "89860012345678901235", "89860012345678901236"},
+			wantTotalCount: 3,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "ICCID前后有空格",
+			csvContent:     "  89860012345678901234  \n89860012345678901235",
+			wantICCIDs:     []string{"89860012345678901234", "89860012345678901235"},
+			wantTotalCount: 2,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "多列CSV只取第一列",
+			csvContent:     "89860012345678901234,额外数据,更多数据\n89860012345678901235,忽略,忽略",
+			wantICCIDs:     []string{"89860012345678901234", "89860012345678901235"},
+			wantTotalCount: 2,
+			wantErrorCount: 0,
+		},
+		{
+			name:           "Windows换行符CRLF",
+			csvContent:     "89860012345678901234\r\n89860012345678901235\r\n89860012345678901236",
+			wantICCIDs:     []string{"89860012345678901234", "89860012345678901235", "89860012345678901236"},
+			wantTotalCount: 3,
+			wantErrorCount: 0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			reader := strings.NewReader(tt.csvContent)
+			result, err := ParseICCIDFromCSV(reader)
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantICCIDs, result.ICCIDs, "ICCIDs 不匹配")
+			assert.Equal(t, tt.wantTotalCount, result.TotalCount, "TotalCount 不匹配")
+			assert.Equal(t, tt.wantErrorCount, len(result.ParseErrors), "ParseErrors 数量不匹配")
+		})
+	}
+}
+
+func TestIsHeader(t *testing.T) {
+	tests := []struct {
+		value    string
+		expected bool
+	}{
+		{"iccid", true},
+		{"ICCID", true},
+		{"Iccid", true},
+		{"卡号", true},
+		{"号码", true},
+		{"89860012345678901234", false},
+		{"", false},
+		{"id", false},
+		{"card", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.value, func(t *testing.T) {
+			result := isHeader(tt.value)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}

pkg/validator/iccid.go

@@ -0,0 +1,63 @@
+package validator
+
+import (
+	"regexp"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+var iccidRegex = regexp.MustCompile(`^[0-9A-Za-z]+$`)
+
+type ICCIDValidationResult struct {
+	Valid   bool
+	Message string
+}
+
+// ValidateICCID 根据运营商类型验证 ICCID 格式
+// carrierType: 运营商类型编码 (CMCC/CUCC/CTCC/CBN)
+// 电信(CTCC) ICCID 长度为 19 位，其他运营商为 20 位
+func ValidateICCID(iccid string, carrierType string) ICCIDValidationResult {
+	if iccid == "" {
+		return ICCIDValidationResult{Valid: false, Message: "ICCID 不能为空"}
+	}
+
+	if !iccidRegex.MatchString(iccid) {
+		return ICCIDValidationResult{Valid: false, Message: "ICCID 只能包含字母和数字"}
+	}
+
+	length := len(iccid)
+	expectedLength := getExpectedICCIDLength(carrierType)
+
+	if length != expectedLength {
+		if carrierType == constants.CarrierCodeCTCC {
+			return ICCIDValidationResult{Valid: false, Message: "电信 ICCID 必须为 19 位"}
+		}
+		return ICCIDValidationResult{Valid: false, Message: "该运营商 ICCID 必须为 20 位"}
+	}
+
+	return ICCIDValidationResult{Valid: true, Message: ""}
+}
+
+func getExpectedICCIDLength(carrierType string) int {
+	if carrierType == constants.CarrierCodeCTCC {
+		return 19
+	}
+	return 20
+}
+
+func ValidateICCIDWithoutCarrier(iccid string) ICCIDValidationResult {
+	if iccid == "" {
+		return ICCIDValidationResult{Valid: false, Message: "ICCID 不能为空"}
+	}
+
+	if !iccidRegex.MatchString(iccid) {
+		return ICCIDValidationResult{Valid: false, Message: "ICCID 只能包含字母和数字"}
+	}
+
+	length := len(iccid)
+	if length != 19 && length != 20 {
+		return ICCIDValidationResult{Valid: false, Message: "ICCID 长度必须为 19 位或 20 位"}
+	}
+
+	return ICCIDValidationResult{Valid: true, Message: ""}
+}

pkg/validator/iccid_test.go

@@ -0,0 +1,267 @@
+package validator
+
+import (
+	"testing"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValidateICCID(t *testing.T) {
+	tests := []struct {
+		name        string
+		iccid       string
+		carrierType string
+		wantValid   bool
+		wantMessage string
+	}{
+		// 空值测试
+		{
+			name:        "空ICCID应该返回错误",
+			iccid:       "",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   false,
+			wantMessage: "ICCID 不能为空",
+		},
+
+		// 电信 ICCID 测试（19位）
+		{
+			name:        "电信有效ICCID-19位数字",
+			iccid:       "8986031234567890123",
+			carrierType: constants.CarrierCodeCTCC,
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "电信ICCID-20位应该失败",
+			iccid:       "89860312345678901234",
+			carrierType: constants.CarrierCodeCTCC,
+			wantValid:   false,
+			wantMessage: "电信 ICCID 必须为 19 位",
+		},
+		{
+			name:        "电信ICCID-18位应该失败",
+			iccid:       "898603123456789012",
+			carrierType: constants.CarrierCodeCTCC,
+			wantValid:   false,
+			wantMessage: "电信 ICCID 必须为 19 位",
+		},
+
+		// 移动 ICCID 测试（20位）
+		{
+			name:        "移动有效ICCID-20位数字",
+			iccid:       "89860012345678901234",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "移动有效ICCID-含字母",
+			iccid:       "8986001234567890123A",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "移动ICCID-19位应该失败",
+			iccid:       "8986001234567890123",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   false,
+			wantMessage: "该运营商 ICCID 必须为 20 位",
+		},
+
+		// 联通 ICCID 测试（20位）
+		{
+			name:        "联通有效ICCID-20位数字",
+			iccid:       "89860112345678901234",
+			carrierType: constants.CarrierCodeCUCC,
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "联通ICCID-21位应该失败",
+			iccid:       "898601123456789012345",
+			carrierType: constants.CarrierCodeCUCC,
+			wantValid:   false,
+			wantMessage: "该运营商 ICCID 必须为 20 位",
+		},
+
+		// 广电 ICCID 测试（20位）
+		{
+			name:        "广电有效ICCID-20位数字",
+			iccid:       "89860412345678901234",
+			carrierType: constants.CarrierCodeCBN,
+			wantValid:   true,
+			wantMessage: "",
+		},
+
+		// 特殊字符测试
+		{
+			name:        "ICCID包含特殊字符应该失败",
+			iccid:       "8986001234567890123!",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   false,
+			wantMessage: "ICCID 只能包含字母和数字",
+		},
+		{
+			name:        "ICCID包含空格应该失败",
+			iccid:       "8986001234567890123 ",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   false,
+			wantMessage: "ICCID 只能包含字母和数字",
+		},
+		{
+			name:        "ICCID包含中划线应该失败",
+			iccid:       "8986001234-678901234",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   false,
+			wantMessage: "ICCID 只能包含字母和数字",
+		},
+
+		// 大小写字母测试
+		{
+			name:        "ICCID包含小写字母有效",
+			iccid:       "8986001234567890123a",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "ICCID包含大写字母有效",
+			iccid:       "8986001234567890123A",
+			carrierType: constants.CarrierCodeCMCC,
+			wantValid:   true,
+			wantMessage: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := ValidateICCID(tt.iccid, tt.carrierType)
+			assert.Equal(t, tt.wantValid, result.Valid, "Valid 不匹配")
+			assert.Equal(t, tt.wantMessage, result.Message, "Message 不匹配")
+		})
+	}
+}
+
+func TestValidateICCIDWithoutCarrier(t *testing.T) {
+	tests := []struct {
+		name        string
+		iccid       string
+		wantValid   bool
+		wantMessage string
+	}{
+		// 空值测试
+		{
+			name:        "空ICCID应该返回错误",
+			iccid:       "",
+			wantValid:   false,
+			wantMessage: "ICCID 不能为空",
+		},
+
+		// 有效长度测试（19位或20位）
+		{
+			name:        "19位ICCID有效",
+			iccid:       "8986031234567890123",
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "20位ICCID有效",
+			iccid:       "89860012345678901234",
+			wantValid:   true,
+			wantMessage: "",
+		},
+
+		// 无效长度测试
+		{
+			name:        "18位ICCID无效",
+			iccid:       "898603123456789012",
+			wantValid:   false,
+			wantMessage: "ICCID 长度必须为 19 位或 20 位",
+		},
+		{
+			name:        "21位ICCID无效",
+			iccid:       "898600123456789012345",
+			wantValid:   false,
+			wantMessage: "ICCID 长度必须为 19 位或 20 位",
+		},
+
+		// 特殊字符测试
+		{
+			name:        "包含特殊字符应该失败",
+			iccid:       "8986001234567890123!",
+			wantValid:   false,
+			wantMessage: "ICCID 只能包含字母和数字",
+		},
+
+		// 字母数字混合测试
+		{
+			name:        "20位含字母有效",
+			iccid:       "8986001234567890AB12",
+			wantValid:   true,
+			wantMessage: "",
+		},
+		{
+			name:        "19位含字母有效",
+			iccid:       "898603123456789AB12",
+			wantValid:   true,
+			wantMessage: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := ValidateICCIDWithoutCarrier(tt.iccid)
+			assert.Equal(t, tt.wantValid, result.Valid, "Valid 不匹配")
+			assert.Equal(t, tt.wantMessage, result.Message, "Message 不匹配")
+		})
+	}
+}
+
+// TestGetExpectedICCIDLength 测试获取期望的 ICCID 长度
+func TestGetExpectedICCIDLength(t *testing.T) {
+	tests := []struct {
+		name           string
+		carrierType    string
+		expectedLength int
+	}{
+		{
+			name:           "电信应该返回19",
+			carrierType:    constants.CarrierCodeCTCC,
+			expectedLength: 19,
+		},
+		{
+			name:           "移动应该返回20",
+			carrierType:    constants.CarrierCodeCMCC,
+			expectedLength: 20,
+		},
+		{
+			name:           "联通应该返回20",
+			carrierType:    constants.CarrierCodeCUCC,
+			expectedLength: 20,
+		},
+		{
+			name:           "广电应该返回20",
+			carrierType:    constants.CarrierCodeCBN,
+			expectedLength: 20,
+		},
+		{
+			name:           "未知运营商应该返回20",
+			carrierType:    "UNKNOWN",
+			expectedLength: 20,
+		},
+		{
+			name:           "空运营商应该返回20",
+			carrierType:    "",
+			expectedLength: 20,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := getExpectedICCIDLength(tt.carrierType)
+			assert.Equal(t, tt.expectedLength, result)
+		})
+	}
+}

tests/integration/iot_card_test.go

@@ -0,0 +1,567 @@
+package integration
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"mime/multipart"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
+	internalMiddleware "github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/routes"
+	"github.com/break/junhong_cmp_fiber/pkg/auth"
+	"github.com/break/junhong_cmp_fiber/pkg/config"
+	pkggorm "github.com/break/junhong_cmp_fiber/pkg/gorm"
+	"github.com/break/junhong_cmp_fiber/pkg/queue"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+	"github.com/break/junhong_cmp_fiber/tests/testutil"
+	"github.com/gofiber/fiber/v2"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+type iotCardTestEnv struct {
+	db           *gorm.DB
+	rdb          *redis.Client
+	tokenManager *auth.TokenManager
+	app          *fiber.App
+	adminToken   string
+	t            *testing.T
+}
+
+func setupIotCardTestEnv(t *testing.T) *iotCardTestEnv {
+	t.Helper()
+
+	t.Setenv("CONFIG_ENV", "dev")
+	t.Setenv("CONFIG_PATH", "../../configs/config.dev.yaml")
+	cfg, err := config.Load()
+	require.NoError(t, err)
+	err = config.Set(cfg)
+	require.NoError(t, err)
+
+	zapLogger, _ := zap.NewDevelopment()
+
+	dsn := "host=cxd.whcxd.cn port=16159 user=erp_pgsql password=erp_2025 dbname=junhong_cmp_test sslmode=disable TimeZone=Asia/Shanghai"
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	require.NoError(t, err)
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr:     "cxd.whcxd.cn:16299",
+		Password: "cpNbWtAaqgo1YJmbMp3h",
+		DB:       15,
+	})
+
+	ctx := context.Background()
+	err = rdb.Ping(ctx).Err()
+	require.NoError(t, err)
+
+	testPrefix := fmt.Sprintf("test:%s:", t.Name())
+	keys, _ := rdb.Keys(ctx, testPrefix+"*").Result()
+	if len(keys) > 0 {
+		rdb.Del(ctx, keys...)
+	}
+
+	tokenManager := auth.NewTokenManager(rdb, 24*time.Hour, 7*24*time.Hour)
+	superAdmin := testutil.CreateSuperAdmin(t, db)
+	adminToken, _ := testutil.GenerateTestToken(t, rdb, superAdmin, "web")
+
+	queueClient := queue.NewClient(rdb, zapLogger)
+
+	deps := &bootstrap.Dependencies{
+		DB:           db,
+		Redis:        rdb,
+		Logger:       zapLogger,
+		TokenManager: tokenManager,
+		QueueClient:  queueClient,
+	}
+
+	result, err := bootstrap.Bootstrap(deps)
+	require.NoError(t, err)
+
+	app := fiber.New(fiber.Config{
+		ErrorHandler: internalMiddleware.ErrorHandler(zapLogger),
+	})
+
+	routes.RegisterRoutes(app, result.Handlers, result.Middlewares)
+
+	return &iotCardTestEnv{
+		db:           db,
+		rdb:          rdb,
+		tokenManager: tokenManager,
+		app:          app,
+		adminToken:   adminToken,
+		t:            t,
+	}
+}
+
+func (e *iotCardTestEnv) teardown() {
+	e.db.Exec("DELETE FROM tb_iot_card WHERE iccid LIKE 'TEST%'")
+	e.db.Exec("DELETE FROM tb_iot_card_import_task WHERE task_no LIKE 'TEST%'")
+
+	ctx := context.Background()
+	testPrefix := fmt.Sprintf("test:%s:", e.t.Name())
+	keys, _ := e.rdb.Keys(ctx, testPrefix+"*").Result()
+	if len(keys) > 0 {
+		e.rdb.Del(ctx, keys...)
+	}
+
+	e.rdb.Close()
+}
+
+func TestIotCard_ListStandalone(t *testing.T) {
+	env := setupIotCardTestEnv(t)
+	defer env.teardown()
+
+	cards := []*model.IotCard{
+		{ICCID: "TEST0012345678901001", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "TEST0012345678901002", CardType: "data_card", CarrierID: 1, Status: 1},
+		{ICCID: "TEST0012345678901003", CardType: "data_card", CarrierID: 2, Status: 2},
+	}
+	for _, card := range cards {
+		require.NoError(t, env.db.Create(card).Error)
+	}
+
+	t.Run("获取单卡列表-无过滤", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/api/admin/iot-cards/standalone?page=1&page_size=20", 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)
+	})
+
+	t.Run("获取单卡列表-按运营商过滤", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/api/admin/iot-cards/standalone?carrier_id=1", 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)
+	})
+
+	t.Run("获取单卡列表-按ICCID模糊查询", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/api/admin/iot-cards/standalone?iccid=901001", 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)
+	})
+
+	t.Run("未认证请求应返回错误", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/api/admin/iot-cards/standalone", 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, "未认证请求应返回错误码")
+	})
+}
+
+func TestIotCard_Import(t *testing.T) {
+	env := setupIotCardTestEnv(t)
+	defer env.teardown()
+
+	t.Run("导入CSV文件", func(t *testing.T) {
+		body := &bytes.Buffer{}
+		writer := multipart.NewWriter(body)
+
+		part, err := writer.CreateFormFile("file", "test.csv")
+		require.NoError(t, err)
+		csvContent := "iccid\nTEST0012345678902001\nTEST0012345678902002\nTEST0012345678902003"
+		_, err = part.Write([]byte(csvContent))
+		require.NoError(t, err)
+
+		_ = writer.WriteField("carrier_id", "1")
+		_ = writer.WriteField("carrier_type", "CMCC")
+		_ = writer.WriteField("batch_no", "TEST_BATCH_001")
+		writer.Close()
+
+		req := httptest.NewRequest("POST", "/api/admin/iot-cards/import", body)
+		req.Header.Set("Content-Type", writer.FormDataContentType())
+		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)
+
+		t.Logf("Import response: code=%d, message=%s", result.Code, result.Message)
+
+		assert.Equal(t, 200, resp.StatusCode)
+		assert.Equal(t, 0, result.Code)
+	})
+
+	t.Run("导入无文件应返回错误", func(t *testing.T) {
+		body := &bytes.Buffer{}
+		writer := multipart.NewWriter(body)
+		_ = writer.WriteField("carrier_id", "1")
+		_ = writer.WriteField("carrier_type", "CMCC")
+		writer.Close()
+
+		req := httptest.NewRequest("POST", "/api/admin/iot-cards/import", body)
+		req.Header.Set("Content-Type", writer.FormDataContentType())
+		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)
+
+		t.Logf("No file response: code=%d, message=%s, data=%v", result.Code, result.Message, result.Data)
+		assert.NotEqual(t, 0, result.Code, "无文件时应返回错误码")
+	})
+}
+
+func TestIotCard_ImportTaskList(t *testing.T) {
+	env := setupIotCardTestEnv(t)
+	defer env.teardown()
+
+	task := &model.IotCardImportTask{
+		TaskNo:      "TEST20260123001",
+		Status:      model.ImportTaskStatusCompleted,
+		CarrierID:   1,
+		CarrierType: "CMCC",
+		TotalCount:  100,
+	}
+	require.NoError(t, env.db.Create(task).Error)
+
+	t.Run("获取导入任务列表", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/api/admin/iot-cards/import-tasks?page=1&page_size=20", 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)
+	})
+
+	t.Run("获取导入任务详情", func(t *testing.T) {
+		url := fmt.Sprintf("/api/admin/iot-cards/import-tasks/%d", task.ID)
+		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)
+	})
+}
+
+// TestIotCard_ImportE2E 端到端测试：API提交 -> Worker处理 -> 数据验证
+func TestIotCard_ImportE2E(t *testing.T) {
+	t.Setenv("CONFIG_ENV", "dev")
+	t.Setenv("CONFIG_PATH", "../../configs/config.dev.yaml")
+	cfg, err := config.Load()
+	require.NoError(t, err)
+	err = config.Set(cfg)
+	require.NoError(t, err)
+
+	zapLogger, _ := zap.NewDevelopment()
+
+	dsn := "host=cxd.whcxd.cn port=16159 user=erp_pgsql password=erp_2025 dbname=junhong_cmp_test sslmode=disable TimeZone=Asia/Shanghai"
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	require.NoError(t, err)
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr:     "cxd.whcxd.cn:16299",
+		Password: "cpNbWtAaqgo1YJmbMp3h",
+		DB:       15,
+	})
+	defer rdb.Close()
+
+	ctx := context.Background()
+	err = rdb.Ping(ctx).Err()
+	require.NoError(t, err)
+
+	// 清理测试数据（包括之前运行遗留的数据）
+	testICCIDPrefix := "E2ETEST"
+	testBatchNo1 := fmt.Sprintf("E2E_BATCH_%d_001", time.Now().UnixNano())
+	testBatchNo2 := fmt.Sprintf("E2E_BATCH_%d_002", time.Now().UnixNano())
+	db.Exec("DELETE FROM tb_iot_card WHERE iccid LIKE ?", testICCIDPrefix+"%")
+	db.Exec("DELETE FROM tb_iot_card_import_task WHERE batch_no LIKE ?", "E2E_BATCH%")
+
+	cleanAsynqQueues(t, rdb)
+
+	t.Cleanup(func() {
+		db.Exec("DELETE FROM tb_iot_card WHERE iccid LIKE ?", testICCIDPrefix+"%")
+		db.Exec("DELETE FROM tb_iot_card_import_task WHERE batch_no LIKE ?", "E2E_BATCH%")
+		cleanAsynqQueues(t, rdb)
+	})
+
+	// 启动 Worker 服务器
+	workerServer := startTestWorker(t, db, rdb, zapLogger)
+	defer workerServer.Shutdown()
+
+	// 等待 Worker 启动
+	time.Sleep(500 * time.Millisecond)
+
+	// 设置 API 服务
+	tokenManager := auth.NewTokenManager(rdb, 24*time.Hour, 7*24*time.Hour)
+	superAdmin := testutil.CreateSuperAdmin(t, db)
+	adminToken, _ := testutil.GenerateTestToken(t, rdb, superAdmin, "web")
+	queueClient := queue.NewClient(rdb, zapLogger)
+
+	deps := &bootstrap.Dependencies{
+		DB:           db,
+		Redis:        rdb,
+		Logger:       zapLogger,
+		TokenManager: tokenManager,
+		QueueClient:  queueClient,
+	}
+	result, err := bootstrap.Bootstrap(deps)
+	require.NoError(t, err)
+
+	app := fiber.New(fiber.Config{
+		ErrorHandler: internalMiddleware.ErrorHandler(zapLogger),
+	})
+	routes.RegisterRoutes(app, result.Handlers, result.Middlewares)
+
+	// 准备测试用的 ICCID（20位，满足 CMCC 要求）
+	testICCIDs := []string{
+		testICCIDPrefix + "1234567890123",
+		testICCIDPrefix + "1234567890124",
+		testICCIDPrefix + "1234567890125",
+	}
+
+	t.Run("完整导入流程验证", func(t *testing.T) {
+		// Step 1: 通过 API 提交导入任务
+		body := &bytes.Buffer{}
+		writer := multipart.NewWriter(body)
+
+		part, err := writer.CreateFormFile("file", "e2e_test.csv")
+		require.NoError(t, err)
+		csvContent := "iccid\n" + testICCIDs[0] + "\n" + testICCIDs[1] + "\n" + testICCIDs[2]
+		_, err = part.Write([]byte(csvContent))
+		require.NoError(t, err)
+
+		_ = writer.WriteField("carrier_id", "1")
+		_ = writer.WriteField("carrier_type", "CMCC")
+		_ = writer.WriteField("batch_no", testBatchNo1)
+		writer.Close()
+
+		req := httptest.NewRequest("POST", "/api/admin/iot-cards/import", body)
+		req.Header.Set("Content-Type", writer.FormDataContentType())
+		req.Header.Set("Authorization", "Bearer "+adminToken)
+
+		resp, err := app.Test(req, -1)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		var apiResult response.Response
+		err = json.NewDecoder(resp.Body).Decode(&apiResult)
+		require.NoError(t, err)
+		require.Equal(t, 0, apiResult.Code, "API 应返回成功: %s", apiResult.Message)
+
+		// 从响应中提取 task_id
+		dataMap, ok := apiResult.Data.(map[string]interface{})
+		require.True(t, ok, "响应数据应为 map")
+		taskIDFloat, ok := dataMap["task_id"].(float64)
+		require.True(t, ok, "task_id 应存在")
+		taskID := uint(taskIDFloat)
+		t.Logf("创建的导入任务 ID: %d", taskID)
+
+		// Step 2: 等待 Worker 处理完成（轮询检查任务状态）
+		var importTask model.IotCardImportTask
+		maxWaitTime := 30 * time.Second
+		pollInterval := 500 * time.Millisecond
+		startTime := time.Now()
+
+		skipCtx := pkggorm.SkipDataPermission(ctx)
+		for {
+			if time.Since(startTime) > maxWaitTime {
+				t.Fatalf("等待超时：任务 %d 未在 %v 内完成", taskID, maxWaitTime)
+			}
+
+			err = db.WithContext(skipCtx).First(&importTask, taskID).Error
+			require.NoError(t, err)
+
+			t.Logf("任务状态: %d (1=pending, 2=processing, 3=completed, 4=failed)", importTask.Status)
+
+			if importTask.Status == model.ImportTaskStatusCompleted || importTask.Status == model.ImportTaskStatusFailed {
+				break
+			}
+
+			time.Sleep(pollInterval)
+		}
+
+		// Step 3: 验证任务完成状态
+		assert.Equal(t, model.ImportTaskStatusCompleted, importTask.Status, "任务应完成")
+		assert.Equal(t, 3, importTask.TotalCount, "总数应为3")
+		assert.Equal(t, 3, importTask.SuccessCount, "成功数应为3")
+		assert.Equal(t, 0, importTask.SkipCount, "跳过数应为0")
+		assert.Equal(t, 0, importTask.FailCount, "失败数应为0")
+		t.Logf("任务完成: total=%d, success=%d, skip=%d, fail=%d",
+			importTask.TotalCount, importTask.SuccessCount, importTask.SkipCount, importTask.FailCount)
+
+		// Step 4: 验证 IoT 卡已入库
+		var cards []model.IotCard
+		err = db.WithContext(skipCtx).Where("iccid IN ?", testICCIDs).Find(&cards).Error
+		require.NoError(t, err)
+		assert.Len(t, cards, 3, "应创建3张 IoT 卡")
+
+		for _, card := range cards {
+			assert.Equal(t, uint(1), card.CarrierID, "运营商ID应为1")
+			assert.Equal(t, testBatchNo1, card.BatchNo, "批次号应匹配")
+			assert.Equal(t, 1, card.Status, "状态应为在库(1)")
+			t.Logf("已创建 IoT 卡: ICCID=%s, ID=%d", card.ICCID, card.ID)
+		}
+	})
+
+	t.Run("重复导入应跳过已存在的ICCID", func(t *testing.T) {
+		// 再次导入相同的 ICCID，应该全部跳过
+		body := &bytes.Buffer{}
+		writer := multipart.NewWriter(body)
+
+		part, err := writer.CreateFormFile("file", "e2e_test_dup.csv")
+		require.NoError(t, err)
+		csvContent := "iccid\n" + testICCIDs[0] + "\n" + testICCIDs[1]
+		_, err = part.Write([]byte(csvContent))
+		require.NoError(t, err)
+
+		_ = writer.WriteField("carrier_id", "1")
+		_ = writer.WriteField("carrier_type", "CMCC")
+		_ = writer.WriteField("batch_no", testBatchNo2)
+		writer.Close()
+
+		req := httptest.NewRequest("POST", "/api/admin/iot-cards/import", body)
+		req.Header.Set("Content-Type", writer.FormDataContentType())
+		req.Header.Set("Authorization", "Bearer "+adminToken)
+
+		resp, err := app.Test(req, -1)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		var apiResult response.Response
+		err = json.NewDecoder(resp.Body).Decode(&apiResult)
+		require.NoError(t, err)
+		require.Equal(t, 0, apiResult.Code)
+
+		dataMap := apiResult.Data.(map[string]interface{})
+		taskID := uint(dataMap["task_id"].(float64))
+
+		// 等待处理完成
+		var importTask model.IotCardImportTask
+		maxWaitTime := 30 * time.Second
+		startTime := time.Now()
+		skipCtx := pkggorm.SkipDataPermission(ctx)
+
+		for {
+			if time.Since(startTime) > maxWaitTime {
+				t.Fatalf("等待超时")
+			}
+			db.WithContext(skipCtx).First(&importTask, taskID)
+			if importTask.Status == model.ImportTaskStatusCompleted || importTask.Status == model.ImportTaskStatusFailed {
+				break
+			}
+			time.Sleep(500 * time.Millisecond)
+		}
+
+		// 验证：2条应该全部跳过
+		assert.Equal(t, model.ImportTaskStatusCompleted, importTask.Status)
+		assert.Equal(t, 2, importTask.TotalCount)
+		assert.Equal(t, 0, importTask.SuccessCount, "成功数应为0（全部跳过）")
+		assert.Equal(t, 2, importTask.SkipCount, "跳过数应为2")
+		t.Logf("重复导入结果: success=%d, skip=%d", importTask.SuccessCount, importTask.SkipCount)
+	})
+}
+
+func cleanAsynqQueues(t *testing.T, rdb *redis.Client) {
+	t.Helper()
+	ctx := context.Background()
+
+	keys, err := rdb.Keys(ctx, "asynq:*").Result()
+	if err != nil {
+		t.Logf("获取 asynq 队列键失败: %v", err)
+		return
+	}
+	if len(keys) > 0 {
+		deleted, err := rdb.Del(ctx, keys...).Result()
+		if err != nil {
+			t.Logf("删除 asynq 队列键失败: %v", err)
+		} else {
+			t.Logf("清理了 %d 个 asynq 队列键", deleted)
+		}
+	}
+}
+
+func startTestWorker(t *testing.T, db *gorm.DB, rdb *redis.Client, logger *zap.Logger) *queue.Server {
+	t.Helper()
+
+	queueCfg := &config.QueueConfig{
+		Concurrency: 2,
+		Queues: map[string]int{
+			"default": 1,
+		},
+	}
+
+	workerServer := queue.NewServer(rdb, queueCfg, logger)
+	taskHandler := queue.NewHandler(db, rdb, logger)
+	taskHandler.RegisterHandlers()
+
+	go func() {
+		if err := workerServer.Start(taskHandler.GetMux()); err != nil {
+			t.Logf("Worker 服务器启动错误: %v", err)
+		}
+	}()
+
+	t.Logf("测试 Worker 服务器已启动")
+	return workerServer
+}