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/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(必填)
-- 卡类型(必填,如 "4G"、"5G"、"NB-IoT")
-- 卡业务类型(可选,枚举值 "normal" | "industry",默认 "normal")
-- 运营商 ID(必填,从 carriers 表中选择)
-- IMSI(可选)
-- 手机号码(可选)
-- 供应商(可选)
-- 成本价(必填)
-- 批次号(必填)
+**导入方式**:
+- 上传 CSV 文件,每行一个 ICCID
+- 在界面选择运营商、批次号等公共参数
+- 不支持一次导入多种运营商的卡
 
-**导入规则**:
-- ICCID 必须唯一,重复 ICCID 将被拒绝
-- 导入的 IoT 卡默认状态为 1(在库),所有者为平台(`owner_type` 为 "platform",`owner_id` 为 0)
-- 导入成功后记录操作日志
+**导入参数**:
+- CSV 文件(必填): 仅包含 ICCID 列
+- 运营商 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
-- **THEN** 系统拒绝重复 ICCID 的 IoT 卡,返回错误信息并列出重复 ICCID,其他有效 IoT 卡正常导入
+#### 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、失败原因
 
 ### 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"-用户)
-- `owner_id`: 所有者 ID(BIGINT,platform 时为 0,agent/user 时为对应的 ID)
-- `status`: 设备状态(INT,1-未激活 2-已激活 3-已停用)
+**店铺归属和状态**:
+- `shop_id`: 店铺 ID(BIGINT,可空,NULL 表示平台库存,有值表示店铺所有)
+- `status`: 设备状态(INT,1-在库 2-已分销 3-已激活 4-已停用)
 - `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)
-- **THEN** 系统将设备的 `owner_type` 变更为 "agent",`owner_id` 设置为 123,同时自动分配该设备绑定的所有 IoT 卡给代理
+- **WHEN** 运营人员将平台库存设备(ID 为 1001)分配给代理店铺(ID 为 10)
+- **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
-
-#### Scenario: 绑定超过最大插槽数量
-
-- **WHEN** 用户尝试将第 5 张 IoT 卡绑定到最大插槽数为 4 的设备
-- **THEN** 系统拒绝绑定,返回错误信息"设备插槽已满,最多支持 4 张 IoT 卡"
-
-#### Scenario: 绑定已被占用的 IoT 卡
-
-- **WHEN** 用户尝试绑定已被其他设备绑定的 IoT 卡
-- **THEN** 系统拒绝绑定,返回错误信息"该 IoT 卡已被其他设备绑定"
+- **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 卡的 `owner_type` 和 `owner_id` 重置
-
-#### Scenario: 查询设备当前绑定的 IoT 卡
-
-- **WHEN** 用户查询设备(ID 为 1001)当前绑定的 IoT 卡
-- **THEN** 系统返回 `device_id` 为 1001 且 `bind_status` 为 1(已绑定) 的所有绑定记录,包含 IoT 卡信息(ICCID、运营商、激活状态等)和插槽位置
+- **THEN** 系统将绑定记录的 `bind_status` 从 1(已绑定) 变更为 2(已解绑),`unbind_time` 记录解绑时间,IoT 卡的 `shop_id` 保持不变
 
 ---
 
@@ -179,23 +163,23 @@ This capability supports:
 
 ### Requirement: 设备批量分配
 
-系统 SHALL 支持运营人员批量分配设备给代理,设备分配时自动分配该设备绑定的所有 IoT 卡。
+系统 SHALL 支持运营人员批量分配设备给代理店铺,设备分配时自动分配该设备绑定的所有 IoT 卡。
 
 **分配规则**:
-- 只能分配 `owner_type` 为 "platform" 的设备(平台库存)
-- 分配时,设备的 `owner_type` 变更为 "agent",`owner_id` 设置为代理用户 ID
-- 分配时,设备绑定的所有 IoT 卡的 `owner_type` 也变更为 "agent",`owner_id` 设置为代理用户 ID
+- 只能分配 `shop_id` 为 NULL 的设备(平台库存)
+- 分配时,设备的 `shop_id` 设置为目标店铺 ID
+- 分配时,设备绑定的所有 IoT 卡的 `shop_id` 也设置为目标店铺 ID
 - 分配操作记录到操作日志
 
 #### Scenario: 运营人员批量分配设备
 
-- **WHEN** 运营人员将 10 台设备(平台库存)分配给代理商(用户 ID 为 123)
-- **THEN** 系统将这 10 台设备的 `owner_type` 变更为 "agent",`owner_id` 设置为 123,同时将这些设备绑定的所有 IoT 卡也分配给代理 123
+- **WHEN** 运营人员将 10 台设备(平台库存)分配给代理店铺(ID 为 10)
+- **THEN** 系统将这 10 台设备的 `shop_id` 设置为 10,同时将这些设备绑定的所有 IoT 卡的 `shop_id` 也设置为 10
 
 #### Scenario: 分配已分配的设备
 
-- **WHEN** 运营人员尝试分配 `owner_type` 为 "agent" 的设备
-- **THEN** 系统拒绝分配,返回错误信息"该设备已分配给代理,不能重复分配"
+- **WHEN** 运营人员尝试分配 `shop_id` 不为 NULL 的设备
+- **THEN** 系统拒绝分配,返回错误信息"该设备已分配给店铺,不能重复分配"
 
 ---
 
@@ -259,14 +243,13 @@ This capability supports:
 
 ### Requirement: 设备查询和筛选
 
-系统 SHALL 支持多维度查询和筛选设备,包括状态、所有者、批次号、设备类型等。
+系统 SHALL 支持多维度查询和筛选设备,包括状态、店铺归属、批次号、设备类型等。
 
 **查询条件**:
 - 设备编号(精确匹配或模糊匹配)
 - 设备名称(模糊匹配)
 - 设备状态(单选或多选)
-- 所有者类型(platform | agent | user)
-- 所有者 ID(仅当所有者类型为 agent/user 时有效)
+- 店铺 ID(shop_id): 可选,NULL 表示平台库存
 - 批次号(精确匹配)
 - 设备类型(单选或多选)
 - 设备制造商(模糊匹配)
@@ -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)查询自己的设备
-- **THEN** 系统返回 `owner_type` 为 "agent" 且 `owner_id` 为 123 的设备列表
-
-#### Scenario: 用户查询自己的设备
-
-- **WHEN** 用户(用户 ID 为 2001)查询自己的设备
-- **THEN** 系统返回 `owner_type` 为 "user" 且 `owner_id` 为 2001 的设备列表,包含设备绑定的所有 IoT 卡信息
-
-#### Scenario: 运营人员通过设备查看绑定的所有 IoT 卡
-
-- **WHEN** 运营人员需要处理投诉,查询设备(ID 为 1001)绑定的所有 IoT 卡
-- **THEN** 系统返回设备信息和绑定的所有 IoT 卡详细信息(ICCID、运营商、激活状态、流量使用等),方便统一查看和管理
+- **WHEN** 代理店铺(ID 为 10)查询自己的设备
+- **THEN** 系统返回 `shop_id` 为 10(及其下级店铺)的设备列表
 
 ---
 
@@ -304,14 +281,13 @@ This capability supports:
 系统 SHALL 对设备数据进行校验,确保数据完整性和一致性。
 
 **校验规则**:
-- 设备编号(device_no):必填,长度 1-50 字符,唯一
-- 设备名称(device_name):必填,长度 1-255 字符
-- 设备型号(device_model):必填,长度 1-100 字符
-- 设备类型(device_type):必填,长度 1-50 字符
+- 设备编号(device_no):必填,长度 1-100 字符,唯一
+- 设备名称(device_name):可选,长度 1-255 字符
+- 设备型号(device_model):可选,长度 1-100 字符
+- 设备类型(device_type):可选,长度 1-50 字符
 - 最大插槽数(max_sim_slots):必填,1-4 之间的整数
-- 所有者类型(owner_type):必填,枚举值 "platform" | "agent" | "user"
-- 所有者 ID(owner_id):必填,≥ 0,当 owner_type 为 "platform" 时必须为 0
-- 设备状态(status):必填,枚举值 1(未激活) | 2(已激活) | 3(已停用)
+- 店铺 ID(shop_id):可选,NULL 表示平台库存,有值必须是有效的店铺 ID
+- 设备状态(status):必填,枚举值 1(在库) | 2(已分销) | 3(已激活) | 4(已停用)
 
 #### Scenario: 创建设备时插槽数超出范围
 
@@ -322,3 +298,4 @@ This capability supports:
 
 - **WHEN** 用户创建设备,设备编号为已存在的 "DEV-001"
 - **THEN** 系统拒绝创建,返回错误信息"设备编号已存在"
+