归档

openspec/specs/device-import/spec.md

@@ -26,21 +26,25 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
   第5列（索引4）: IMEI（可选）
   第6列（索引5）: 制造商（可选）
   第7列（索引6）: 最大SIM槽数（可选，默认4，范围1-4）
-  第8列（索引7）: 卡1 ICCID（可选）
-  第9列（索引8）: 卡2 ICCID（可选）
-  第10列（索引9）: 卡3 ICCID（可选）
-  第11列（索引10）: 卡4 ICCID（可选）
+  第8列（索引7）: 卡1 ICCID（可选，对应槽位1）
+  第9列（索引8）: 卡2 ICCID（可选，对应槽位2）
+  第10列（索引9）: 卡3 ICCID（可选，对应槽位3）
+  第11列（索引10）: 卡4 ICCID（可选，对应槽位4）
   ```
 - **列格式**: 所有列应设置为文本格式（避免数字被转为科学记数法）
 
 **失败原因文本**:
 - VirtualNo 为空：`"设备虚拟号(virtual_no)不能为空"`
 - MaxSimSlots 越界：`"最大SIM槽数必须在1-4之间"`
+- ICCID 填写槽位超出最大槽位：`"卡槽填写超出最大SIM槽数"`
 
 **导入规则**:
 - 按列索引取值，不识别列名，第一行永远跳过
 - 若整行目标列皆为空，视为空行跳过，不计入 total，不计入失败
 - MaxSimSlots 为空或 0 回填默认值 4；非空且不在 [1,4] 记录为失败
+- `卡1~卡4` 的列位本身就是槽位定义，导入时必须保留原始列位信息，不得按非空 ICCID 顺序重排
+- 前置槽位允许为空；如果仅填写 `卡2`、`卡3`，则表示设备只在槽位 2、3 上绑定卡
+- 任一已填写 ICCID 的槽位编号若大于 `max_sim_slots`，则该行导入失败
 - 导入的设备 shop_id = NULL（平台库存）
 - 导入的设备 status = 1（在库）
 - 设备号重复则该行跳过
@@ -67,6 +71,23 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 - **WHEN** 系统解析该 Excel 文件
 - **THEN** 系统跳过第1行，从第2行开始按列位置解析数据
 
+#### Scenario: 仅填写卡2和卡3时保留原始槽位
+
+- **GIVEN** 某行 `最大SIM槽数 = 3`
+- **AND** `卡1` 为空，`卡2 = ICCID_A`，`卡3 = ICCID_B`
+- **WHEN** 系统解析该行
+- **THEN** 系统将 `ICCID_A` 识别为槽位2的卡
+- **AND** 系统将 `ICCID_B` 识别为槽位3的卡
+- **AND** 系统不得将其重排为槽位1和槽位2
+
+#### Scenario: 填写槽位超出最大SIM槽数
+
+- **GIVEN** 某行 `最大SIM槽数 = 2`
+- **AND** `卡3 = ICCID_C`
+- **WHEN** 系统解析该行
+- **THEN** 该行导入失败
+- **AND** 失败原因为"卡槽填写超出最大SIM槽数"
+
 #### Scenario: 代理尝试导入设备
 
 - **WHEN** 代理用户尝试导入设备
@@ -80,13 +101,13 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 #### Scenario: Excel结构错误
 
 - **WHEN** 平台管理员上传的Excel文件无工作表或无数据行
-- **THEN** 系统创建任务但处理失败，任务状态为"失败"，记录相应错误信息
+- **THEN** 系统创建任务但处理失败，记录相应错误信息
 
 #### Scenario: VirtualNo 为空的行记录为失败
 
 - **WHEN** Excel 中某行第1列（虚拟号）为空
 - **THEN** 该行计入失败（`fail_count++`），失败原因为"设备虚拟号(virtual_no)不能为空"
-- **THEN** 其他合法行继续导入，不因此行中断
+- **AND** 其他合法行继续导入，不因此行中断
 
 ---
 
@@ -98,14 +119,15 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 - 打开Excel文件，选择第一个sheet（或优先"导入数据"sheet）
 - 跳过第1行（表头行），从第2行开始按固定列位置解析数据
 - 若整行目标列皆为空，视为空行跳过，不计入 total
-- 逐行解析数据
+- 逐行解析数据，并保留每个 ICCID 对应的原始槽位编号
 - 对每行数据执行以下校验：
   1. 设备号是否已存在（已存在则跳过）
   2. ICCID 是否存在于系统中（不存在则失败）
   3. ICCID 是否已绑定其他设备（已绑定则失败）
+  4. 已填写 ICCID 的槽位是否超出该设备 `max_sim_slots`（超出则失败）
 - 校验通过后：
   1. 创建设备记录
-  2. 创建设备-卡绑定记录
+  2. 按 ICCID 的原始槽位创建 `slot_position` 一致的设备-卡绑定记录
 - 记录处理结果（成功/跳过/失败）
 
 **任务状态**:
@@ -119,6 +141,14 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 - **WHEN** Excel 中所有设备号不重复且 ICCID 有效
 - **THEN** 系统创建所有设备和绑定记录，任务状态为"已完成"
 
+#### Scenario: 前置空槽导入成功
+
+- **GIVEN** 某行 `卡1` 为空，`卡2 = ICCID_A`，`卡3 = ICCID_B`
+- **WHEN** 该行校验通过并执行导入
+- **THEN** 系统创建两条绑定记录
+- **AND** `ICCID_A` 的 `slot_position = 2`
+- **AND** `ICCID_B` 的 `slot_position = 3`
+
 #### Scenario: 部分导入成功
 
 - **WHEN** Excel 中部分设备号已存在或部分 ICCID 无效
@@ -139,11 +169,11 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 - **WHEN** Excel 中某行的设备号在系统中已存在
 - **THEN** 该行被跳过，记录跳过原因"设备号已存在"
 
-#### Scenario: VirtualNo 为空的行记录为失败
+#### Scenario: 填写槽位超出最大SIM槽数时任务记录失败
 
-- **WHEN** Excel 中某行第1列（虚拟号）为空
-- **THEN** 该行计入失败（`fail_count++`），失败原因为"设备虚拟号(virtual_no)不能为空"
-- **THEN** 其他合法行继续导入，不因此行中断
+- **WHEN** Excel 中某行声明 `最大SIM槽数 = 2`，但填写了 `卡3` 或 `卡4`
+- **THEN** 该行计入失败（`fail_count++`）
+- **AND** 失败明细中的 `reason` 字段为"卡槽填写超出最大SIM槽数"
 
 #### Scenario: 导入任务结果报告包含 VirtualNo 失败原因
 
@@ -262,4 +292,3 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 #### Scenario: 设备导入任务响应返回 realname_policy
 - **WHEN** 管理员查询设备导入任务列表或详情
 - **THEN** 响应中包含 `realname_policy` 字段
-