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>

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** 系统拒绝创建,返回错误信息"设备编号已存在"