docs: 归档 excel-import-refactor，同步更新主 specs

- 将变更目录移至 archive/2026-04-09-excel-import-refactor - device-import spec：更新为固定列位置读取（IMEI 调整至第5列），新增 MaxSimSlots 范围校验说明 - iot-card-import-task spec：更新为固定列位置读取，新增"导入批次支持卡业务类型"需求 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-09 17:37:44 +08:00
parent cd807e58e3
commit afc6d7fc76
8 changed files with 417 additions and 76 deletions
--- a/openspec/specs/device-import/spec.md
+++ b/openspec/specs/device-import/spec.md
@@ -5,7 +5,7 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 ## Requirements
 ### Requirement: 设备批量导入

-系统 SHALL 提供设备批量导入功能，通过 Excel 文件导入设备并自动绑定卡，仅平台用户可操作。
+系统 SHALL 提供设备批量导入功能，通过 Excel 文件导入设备并自动绑定卡，按固定列位置读取，表头行内容不影响解析结果，仅平台用户可操作。

 **API 端点**: `POST /api/admin/devices/import`

@@ -15,37 +15,32 @@ TBD - created by archiving change add-device-management. Update Purpose after ar

 **Excel 格式**:
 - **文件格式**: 仅支持 `.xlsx` (Excel 2007+)
- **Sheet**: 读取第一个sheet,或优先读取名为"导入数据"的sheet
- **表头行**: 第1行,列名如下(顺序可任意):
+- **Sheet**: 读取第一个sheet，或优先读取名为"导入数据"的sheet
+- **表头行**: 第1行固定为表头，永远跳过，内容不限（中文、英文均可）
+- **列位置（固定，不可变）**:
  ```
-  device_no, device_name, device_model, device_type, 
-  max_sim_slots, manufacturer, virtual_no, iccid_1, iccid_2, iccid_3, iccid_4
+  第1列（索引0）: 虚拟号（必填，全局唯一）
+  第2列（索引1）: 设备名称（可选）
+  第3列（索引2）: 设备型号（可选）
+  第4列（索引3）: 设备类型（可选）
+  第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（可选）
  ```
- **数据行**: 从第2行开始
- **列格式**: 所有列应设置为文本格式(避免数字被转为科学记数法)
-
-**示例Excel内容**:
-```
-| device_no | device_name  | device_model | device_type | max_sim_slots | manufacturer | virtual_no | iccid_1              | iccid_2              | iccid_3 | iccid_4 |
-|-----------|--------------|--------------|-------------|---------------|--------------|------------|----------------------|----------------------|---------|---------|
-| DEV-001   | GPS追踪器A   | GT06N        | GPS Tracker | 4             | Concox       | VNO-001    | 8986001234567890001  | 8986001234567890002  |         |         |
-| DEV-002   | GPS追踪器B   | GT06N        | GPS Tracker | 4             | Concox       | VNO-002    | 8986001234567890003  |                      |         |         |
-```
-
-**字段说明**:
- `device_no`: 设备号（必填，唯一）
- `virtual_no`: 虚拟号（**必填**，全局唯一）；**[BREAKING]** 为空时不再静默跳过，改为记录为失败行
- `device_name`: 设备名称（可选）
- `device_model`: 设备型号（可选）
- `device_type`: 设备类型（可选）
- `max_sim_slots`: 最大插槽数（可选，默认 4，范围 1-4）
- `manufacturer`: 制造商（可选）
- `iccid_1` ~ `iccid_4`: 对应插槽 1-4 的 ICCID（可选，空值表示该插槽无卡）
+- **列格式**: 所有列应设置为文本格式（避免数字被转为科学记数法）

 **失败原因文本**:
 - VirtualNo 为空：`"设备虚拟号(virtual_no)不能为空"`
+- MaxSimSlots 越界：`"最大SIM槽数必须在1-4之间"`

 **导入规则**:
+- 按列索引取值，不识别列名，第一行永远跳过
+- 若整行目标列皆为空，视为空行跳过，不计入 total，不计入失败
+- MaxSimSlots 为空或 0 回填默认值 4；非空且不在 [1,4] 记录为失败
 - 导入的设备 shop_id = NULL（平台库存）
 - 导入的设备 status = 1（在库）
 - 设备号重复则该行跳过
@@ -66,6 +61,12 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 - **WHEN** 平台管理员上传 Excel 文件并提交导入请求
 - **THEN** 系统创建导入任务，返回任务 ID，开始异步处理

+#### Scenario: 中文表头正常导入
+
+- **GIVEN** Excel 文件第1行表头为 `虚拟号 | 设备名称 | 设备型号 | 设备类型 | IMEI | 制造商 | 最大SIM槽数 | 卡1 | 卡2 | 卡3 | 卡4`
+- **WHEN** 系统解析该 Excel 文件
+- **THEN** 系统跳过第1行，从第2行开始按列位置解析数据
+
 #### Scenario: 代理尝试导入设备

 - **WHEN** 代理用户尝试导入设备
@@ -74,13 +75,19 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 #### Scenario: 文件格式错误

 - **WHEN** 平台管理员上传非 Excel 格式(.xlsx)的文件
- **THEN** 系统创建任务但处理失败，任务状态为"失败"，错误信息为"不支持的文件格式 .csv,请上传Excel文件(.xlsx)"
+- **THEN** 系统创建任务但处理失败，任务状态为"失败"，错误信息为"不支持的文件格式 .csv，请上传Excel文件(.xlsx)"

 #### Scenario: Excel结构错误

 - **WHEN** 平台管理员上传的Excel文件无工作表或无数据行
 - **THEN** 系统创建任务但处理失败，任务状态为"失败"，记录相应错误信息

+#### Scenario: VirtualNo 为空的行记录为失败
+
+- **WHEN** Excel 中某行第1列（虚拟号）为空
+- **THEN** 该行计入失败（`fail_count++`），失败原因为"设备虚拟号(virtual_no)不能为空"
+- **THEN** 其他合法行继续导入，不因此行中断
+
 ---

 ### Requirement: 设备导入任务执行
@@ -88,8 +95,9 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 系统 SHALL 异步执行设备导入任务，逐行处理 Excel 数据。

 **处理规则**:
- 打开Excel文件,选择第一个sheet(或优先"导入数据"sheet)
- 读取表头行,识别列索引
+- 打开Excel文件，选择第一个sheet（或优先"导入数据"sheet）
+- 跳过第1行（表头行），从第2行开始按固定列位置解析数据
+- 若整行目标列皆为空，视为空行跳过，不计入 total
 - 逐行解析数据
 - 对每行数据执行以下校验：
  1. 设备号是否已存在（已存在则跳过）
@@ -131,11 +139,10 @@ TBD - created by archiving change add-device-management. Update Purpose after ar
 - **WHEN** Excel 中某行的设备号在系统中已存在
 - **THEN** 该行被跳过，记录跳过原因"设备号已存在"

-#### Scenario: VirtualNo 为空的行记录为失败（原为跳过）
+#### Scenario: VirtualNo 为空的行记录为失败

- **WHEN** Excel 中某行 virtual_no 列为空或未填写
+- **WHEN** Excel 中某行第1列（虚拟号）为空
 - **THEN** 该行计入失败（`fail_count++`），失败原因为"设备虚拟号(virtual_no)不能为空"
- **THEN** 该行不再计入 `skip_count`
 - **THEN** 其他合法行继续导入，不因此行中断

 #### Scenario: 导入任务结果报告包含 VirtualNo 失败原因
--- a/openspec/specs/iot-card-import-task/spec.md
+++ b/openspec/specs/iot-card-import-task/spec.md
@@ -192,73 +192,56 @@ TBD - created by archiving change iot-card-standalone-management. Update Purpose

 ### Requirement: Excel 文件格式规范

-系统 SHALL 要求 Excel 文件必须包含 ICCID 和 MSISDN 两列，并支持可选的 `virtual_no` 列。
+系统 SHALL 要求 Excel 文件必须包含 ICCID、MSISDN、虚拟号三列，按固定列位置读取，表头行内容不影响解析结果。

 **文件格式要求**:
 - **文件格式**: 仅支持 `.xlsx` (Excel 2007+)
 - **Sheet**: 读取第一个sheet，或优先读取名为"导入数据"的sheet
- **表头行**: 第1行（可选，但建议包含）
- **表头识别关键字**:
-  - ICCID 列: iccid/ICCID/卡号/号码
-  - MSISDN 列: msisdn/MSISDN/接入号/手机号/电话/号码
-  - virtual_no 列（**必填**）: virtual_no/VirtualNo/虚拟号/设备号
- **列数要求**: 至少 3 列（ICCID、MSISDN、virtual_no），virtual_no 为必填列
+- **表头行**: 第1行固定为表头，永远跳过，内容不限（中文、英文均可）
+- **列位置（固定，不可变）**:
+  - 第1列（索引0）: ICCID
+  - 第2列（索引1）: MSISDN
+  - 第3列（索引2）: 虚拟号（必填）
 - **列格式**: 应设置为文本格式（避免长数字被转为科学记数法）

 **解析规则**:
- 自动检测表头（第1行包含识别关键字则跳过）
+- 按列索引取值，不识别列名，第一行永远跳过
 - 自动去除单元格首尾空格
- 跳过空行
- ICCID 为空的行记录为失败
- MSISDN 为空的行记录为失败
- virtual_no 为空的行：**[BREAKING]** 记录为失败行，失败原因为"虚拟号(virtual_no)不能为空"（原行为为跳过该列）
- Excel 中不包含 virtual_no 列时：所有数据行均因 VirtualNo 为空而失败，返回错误提示"Excel 文件缺少 virtual_no 列，请使用最新模板"
+- 若 ICCID、MSISDN、virtual_no 三列皆为空，视为空行跳过，不计入 total，不计入失败
+- ICCID 为空（但其他列非空）的行记录为失败，失败原因为"ICCID 不能为空"
+- MSISDN 为空（但其他列非空）的行记录为失败，失败原因为"MSISDN 不能为空"
+- virtual_no（第3列）为空的行记录为失败，失败原因为"虚拟号(virtual_no)不能为空"

 **virtual_no 导入规则**:
- virtual_no 为必填列，为空则该行记录为失败
+- virtual_no 为必填，为空则该行记录为失败
 - virtual_no 全局唯一（跨卡和设备），重复则失败，原因为"虚拟号已被占用: <值>"
- **批次级唯一性检查**：在执行导入前，先检查整批中所有 virtual_no 是否与数据库现存值重复；有任意冲突则**整批失败**，响应中返回冲突的 virtual_no 及行号列表
-
-**示例 Excel 内容**:
-```
-| ICCID                | MSISDN      | 虚拟号    |
-|----------------------|-------------|-----------|
-| 89860012345678901234 | 13800000001 | CARD-001  |
-| 89860012345678901235 | 13800000002 |           |
-```

 #### Scenario: 正常导入（ICCID 和 VirtualNo 均有值）

- **WHEN** Excel 中某行 ICCID="898600XXXXX"，virtual_no="CARD-001"，msisdn="13800000001"
+- **WHEN** Excel 中某行第1列 ICCID="898600XXXXX"，第3列 virtual_no="CARD-001"，第2列 msisdn="13800000001"
 - **THEN** 导入成功，卡记录写入数据库，VirtualNo 和 ICCID 同步注册到 `tb_asset_identifier`

+#### Scenario: 中文表头正常导入
+
+- **GIVEN** Excel 文件第1行表头为 `ICCID | 接入号 | 虚拟号`（任意中文或英文内容）
+- **WHEN** 系统解析该 Excel 文件
+- **THEN** 系统跳过第1行，从第2行开始按列位置解析数据
+
 #### Scenario: VirtualNo 为空的行被拒绝

- **WHEN** Excel 中某行 ICCID="898600YYYYY"，virtual_no 列为空或未填写
+- **WHEN** Excel 中某行第3列为空
 - **THEN** 该行计入失败，失败原因为"虚拟号(virtual_no)不能为空"
 - **THEN** 其他合法行继续导入，不因此行中断

 #### Scenario: VirtualNo 重复被拒绝

- **WHEN** Excel 中某行的 virtual_no 与已有卡/设备的 VirtualNo 重复（跨表）
+- **WHEN** Excel 中某行第3列的值与已有卡/设备的 VirtualNo 重复（跨表）
 - **THEN** 该行计入失败，原因为"虚拟号已被占用: <值>"

-#### Scenario: Excel 文件中无 VirtualNo 列
+#### Scenario: 三列皆空时跳过不计入 total

- **WHEN** Excel 表头中不包含 `virtual_no`/`虚拟号`/`设备号` 等可识别列名
- **THEN** 所有数据行均因 VirtualNo 为空而失败，导入结果中 `fail_count = 总行数`，`success_count = 0`
- **THEN** 返回错误提示："Excel 文件缺少 virtual_no 列，请使用最新模板"
-
-#### Scenario: 批次中有 virtual_no 与现存数据重复
-
- **WHEN** Excel 中某行 virtual_no = "CARD-001"，但数据库中另一张卡已有 virtual_no = "CARD-001"
- **THEN** 系统拒绝整批导入，响应返回冲突的 virtual_no 值和行号，提示"虚拟号重复，整批导入已终止"
-
-#### Scenario: 支持中文表头
-
- **GIVEN** Excel 文件表头为 `卡号 | 接入号 | 虚拟号`
- **WHEN** 系统解析该 Excel 文件
- **THEN** 系统正确识别三列，按规则处理 virtual_no
+- **WHEN** Excel 中某行 ICCID、MSISDN、virtual_no 三列均为空
+- **THEN** 该行视为空行跳过，不计入 total，不计入失败

 #### Scenario: 导入任务完成后的结果报告

@@ -274,13 +257,12 @@ TBD - created by archiving change iot-card-standalone-management. Update Purpose

 #### Scenario: MSISDN 为空的行记录失败

- **GIVEN** Excel 文件第二行 MSISDN 为空
- **WHEN** 系统解析该 Excel 文件
- **THEN** 第一条记录解析成功，第二条记录标记为失败，原因为"MSISDN 不能为空"
+- **WHEN** Excel 中某行第2列为空
+- **THEN** 该行标记为失败，原因为"MSISDN 不能为空"

 #### Scenario: 长数字无损解析

- **GIVEN** Excel 文件中 ICCID 列设置为文本格式，包含 20 位数字 "89860012345678901234"
+- **GIVEN** Excel 文件中第1列设置为文本格式，包含 20 位数字 "89860012345678901234"
 - **WHEN** 系统解析该 Excel 文件
 - **THEN** ICCID 完整保留为 "89860012345678901234"，无精度损失，无科学记数法

@@ -324,3 +306,33 @@ TBD - created by archiving change iot-card-standalone-management. Update Purpose
 - **WHEN** 管理员创建物联网卡导入任务
 - **THEN** 系统根据 carrier_id 查询 Carrier 表，将 carrier_name 写入导入任务记录

+---
+
+### Requirement: 导入批次支持卡业务类型
+
+系统 SHALL 在 IoT 卡导入请求中支持 `card_category` 参数，以批次为单位指定导入卡的业务类型，默认为普通卡。
+
+**请求字段**:
+- `card_category`: 卡业务类型（枚举：`normal` / `industry`，可选，默认 `normal`）
+
+**任务字段**:
+- `IotCardImportTask` 新增 `card_category` 字段（VARCHAR(20)，默认 `normal`）
+
+**导入行为**:
+- 导入任务中所有卡统一使用 `card_category` 的值，不支持同一批次混用
+
+#### Scenario: 不传 card_category 时默认为普通卡
+
+- **WHEN** 导入请求未包含 `card_category` 字段
+- **THEN** 导入的所有卡 `card_category` 为 `normal`
+
+#### Scenario: 指定行业卡导入
+
+- **WHEN** 导入请求中 `card_category` = `industry`
+- **THEN** 该批次导入的所有卡 `card_category` 均为 `industry`
+
+#### Scenario: 传入无效 card_category
+
+- **WHEN** 导入请求中 `card_category` = `unknown`（非枚举值）
+- **THEN** 系统返回参数校验错误，提示卡业务类型无效
+