分裂iccid长度

openspec/changes/iccid-dual-column-lookup/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-20

openspec/changes/iccid-dual-column-lookup/design.md

@@ -0,0 +1,186 @@
+## Context
+
+`tb_iot_card.iccid` 是 varchar(20) 的全局唯一字段，所有精确查询均基于它。物联网平台上有两类运营商：
+
+- **19 位运营商**（如中国电信）：ICCID 本身为 19 位，是唯一标识符
+- **20 位运营商**（如移动部分号段）：ICCID 需要完整 20 位才唯一，第 20 位是真实业务数据而非 Luhn 校验码
+
+上游 IoT 平台返回的 ICCID **格式不固定**：同一张卡，不同时候可能传回 19 位或 20 位。当前代码使用 `WHERE iccid = ?` 精确匹配，格式不一致时静默失败（`iotCardID == 0`，函数返回 nil），导致 `is_current` 状态更新无效。这是不可观测的数据错乱。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 无论上游传入 19 位还是 20 位，均能正确命中对应卡记录
+- 查询性能不降级：每次查询仍走单列精确索引，不引入模糊查询或 OR 条件
+- Miss 可观测：上游格式与存储不一致时，记录 Warn 日志暴露数据质量问题
+- 覆盖 `tb_personal_customer_iccid` 的同类问题
+
+**Non-Goals:**
+- 不修复上游数据质量问题（这是运营侧职责）
+- 不实现跨列降级匹配（19 位 Miss 不去查 20 位列，防止错误命中）
+- 不修改 ICCID 的展示逻辑和 Response DTO
+- 不影响模糊查询（LIKE）和范围查询（`>=` / `<=`），这类查询语义上不依赖唯一性
+- 不改造个人客户发起的 ICCID 查询路径（`client_auth/service.go`、`exchange/service.go`、`asset/service.go` 中的 `OR iccid = ?` 条件）：这三处查询的 ICCID 来自个人客户手动输入（扫码/手动填写），输入格式与数据库存储格式一致，不存在上游平台的 19/20 位不一致问题；其架构违规（Service 层直接写 SQL）留待专项重构处理
+
+## Decisions
+
+### 决策 1：双列存储（iccid_19 / iccid_20）而非前缀 LIKE
+
+**选项 A（选定）**：新增 `iccid_19 varchar(19)` 和 `iccid_20 varchar(20)`，分别建 Partial Index。查询时按上游传入长度路由。
+
+**选项 B（否决）**：保留原列，所有精确查询改用 `iccid LIKE 'prefix%'`。
+
+否决原因：
+- PostgreSQL 在非 C locale 下 B-tree 索引不支持 LIKE，需要额外 `varchar_pattern_ops` 索引
+- LIKE 仍是范围扫描，效率低于等值查找
+- 不解决 20 位运营商 19 位前缀不唯一的根本问题（可能错误命中另一张卡）
+
+**选项 C（否决）**：全量标准化为 19 位存储。
+
+否决原因：部分运营商的 19 位前缀不唯一，截断 20 位 ICCID 会造成数据冲突，存量迁移存在数据丢失风险。
+
+---
+
+### 决策 2：按长度路由，禁止跨列降级
+
+```
+len(upstream_iccid) == 19  →  WHERE iccid_19 = ?
+len(upstream_iccid) == 20  →  WHERE iccid_20 = ?
+其他长度                    →  拒绝，记录 Error 日志
+Miss 时                    →  记录 Warn 日志，不更新数据，不降级查另一列
+```
+
+**禁止降级的原因**：若 20 位上游 miss 后降级查 iccid_19（前 19 位），可能命中另一个运营商的 19 位卡，造成 `is_current` 被更新到错误卡上——**错误命中比 Miss 危险得多，且不可观测**。
+
+---
+
+### 决策 3：Partial Index 而非全量索引
+
+```sql
+-- iccid_19：所有卡都有值，过滤软删除
+CREATE INDEX idx_iot_card_iccid_19 ON tb_iot_card (iccid_19) WHERE deleted_at IS NULL;
+
+-- iccid_20：仅 20 位卡有值，额外过滤 NULL
+CREATE INDEX idx_iot_card_iccid_20 ON tb_iot_card (iccid_20)
+    WHERE deleted_at IS NULL AND iccid_20 IS NOT NULL;
+```
+
+Partial Index 体积更小（排除软删除记录和 NULL 记录），查询效率更高。
+
+---
+
+### 决策 3.5：`iccid_20` 模型字段必须使用指针类型 `*string`
+
+Go 中 `string` 类型的零值是 `""`（空字符串）。GORM 不会将空字符串自动映射为 SQL `NULL`，写入结果是 `''`，导致：
+
+1. Partial Index `WHERE iccid_20 IS NOT NULL` 会把所有 19 位卡行纳入索引，体积膨胀，优化失效
+2. 任何 `WHERE iccid_20 = ?` 查询不受影响（`'' != 任何合法 ICCID`），但 miss 率虚高，触发大量误 Warn 告警
+
+**正确声明**：
+```go
+ICCID20 *string `gorm:"column:iccid_20;type:varchar(20);comment:完整20位ICCID(仅20位运营商卡有值)"`
+```
+
+`SplitICCID` 工具函数签名须对应：
+```go
+func SplitICCID(iccid string) (iccid19 string, iccid20 *string)
+// 19 位：返回 (iccid, nil)
+// 20 位：返回 (iccid[:19], &iccid)
+// 其他：返回 ("", nil)
+```
+
+---
+
+### 决策 4：写入路径在 Task 层赋值，不修改 Store 层
+
+IotCard 记录只有一个创建入口（`iot_card_import.go` 的 `processBatch()`）。在 IotCard 初始化时计算并赋值 `ICCID19` / `ICCID20`，Store 层的 `Create`/`CreateBatch` 无需感知新字段（GORM 自动处理）。
+
+---
+
+### 决策 5.5：`GetBoundICCIDs` 混合长度路由实现方案
+
+当调用方传入 iccids 混合 19 位和 20 位时，禁止用 OR 条件（`c.iccid_19 IN ? OR c.iccid_20 IN ?`），因为 OR 会导致全表扫描，无法走 Partial Index。
+
+**采用两次独立查询 + 应用层合并**：
+
+```go
+func (s *DeviceSimBindingStore) GetBoundICCIDs(ctx context.Context, iccids []string) (map[string]bool, error) {
+    var list19, list20 []string
+    for _, id := range iccids {
+        if len(id) == 19 { list19 = append(list19, id) }
+        if len(id) == 20 { list20 = append(list20, id) }
+    }
+    result := make(map[string]bool)
+    // 19 位组查 iccid_19，SELECT c.iccid_19 AS iccid
+    // 20 位组查 iccid_20，SELECT c.iccid_20 AS iccid
+    // 合并两组结果到 result
+}
+```
+
+同样规则适用于 `IotCardStore.GetByICCIDs`（分组后分别 Find，合并 `[]*model.IotCard` 并去重）。
+
+---
+
+### 决策 6：enterprise_card/service.go 的内联 SQL 移交 Store 层
+
+该文件有两处（第 46 行、第 185 行）`WHERE iccid IN ?` 内联 SQL 直接绕过了 Store 层，且同时绕过了数据权限过滤（`middleware.ApplyShopFilter`）。此次改造中将其重构为调用 `IotCardStore.GetByICCIDs()`，消除架构违规并恢复数据权限过滤。
+
+**依赖注入变更**：`enterprise_card.Service` struct 需新增 `iotCardStore *postgres.IotCardStore` 字段，`New()` 签名增加该参数，`internal/bootstrap/services.go` 调用处同步传入 `s.IotCard`。
+
+## Risks / Trade-offs
+
+**[风险] 存量数据中可能存在 19/20 位冲突记录** → 迁移前先执行冲突检测 SQL；若有冲突，人工处理后再执行回填。
+
+**[风险] 迁移期间（已加列、未更新代码）查询仍走旧 iccid 列** → 迁移分两阶段：先上线代码（新代码查新列），再回填存量数据；或先回填数据再上线代码。推荐先回填数据再发布代码，避免窗口期数据不一致。
+
+**[Trade-off] 两次查询 vs 一次查询**：正常路径仍是一次精确索引查询。Miss 场景不发起第二次查询，直接记录日志，无性能影响。
+
+**[Trade-off] 存储空间**：每张卡多存约 39 字节（19 + 20），百万卡约 39MB，可接受。
+
+## Migration Plan
+
+**第一步（迁移文件）**：
+
+> **注意**：`CREATE INDEX CONCURRENTLY` 不能在事务块内执行，而 golang-migrate 默认每个迁移文件在事务中运行。迁移文件中使用 `CREATE INDEX IF NOT EXISTS`（非 CONCURRENTLY），生产环境若需零停机建索引，可在发布窗口期**手动**执行 CONCURRENTLY 版本后再合并代码。（与本项目 `000058_add_covering_index_for_deep_pagination.up.sql` 范式一致。）
+
+```sql
+-- 1. 加列（允许 NULL，不阻塞写入）
+ALTER TABLE tb_iot_card ADD COLUMN IF NOT EXISTS iccid_19 varchar(19);
+ALTER TABLE tb_iot_card ADD COLUMN IF NOT EXISTS iccid_20 varchar(20);
+
+-- 2. 冲突检测（执行后人工确认均为 0 行，否则停止迁移人工处理）
+-- 2a. 检测 19 位前缀重复（19 位运营商卡的 iccid_19 必须唯一）
+SELECT LEFT(iccid, 19), COUNT(*)
+FROM tb_iot_card WHERE deleted_at IS NULL
+GROUP BY LEFT(iccid, 19) HAVING COUNT(*) > 1;
+
+-- 2b. 检测异常长度 ICCID（长度既非 19 也非 20 的记录，回填后将永远无法通过新查询路径命中）
+SELECT id, iccid, LENGTH(iccid) AS len
+FROM tb_iot_card WHERE deleted_at IS NULL AND LENGTH(iccid) NOT IN (19, 20);
+
+-- 3. 回填存量数据
+UPDATE tb_iot_card SET
+    iccid_19 = LEFT(iccid, 19),
+    iccid_20 = CASE WHEN LENGTH(iccid) = 20 THEN iccid ELSE NULL END;
+
+-- 4. 建索引（迁移文件中不用 CONCURRENTLY，避免事务冲突）
+-- 生产零停机版本（手动执行）：
+--   CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_iot_card_iccid_19
+--       ON tb_iot_card (iccid_19) WHERE deleted_at IS NULL;
+--   CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_iot_card_iccid_20
+--       ON tb_iot_card (iccid_20) WHERE deleted_at IS NULL AND iccid_20 IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_iot_card_iccid_19
+    ON tb_iot_card (iccid_19) WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_iot_card_iccid_20
+    ON tb_iot_card (iccid_20) WHERE deleted_at IS NULL AND iccid_20 IS NOT NULL;
+```
+
+`tb_personal_customer_iccid` 同理，仅加 `iccid_19` 一列（该表只需要按19位匹配）。
+
+**第二步（代码发布）**：更新 Model、Store 查询方法、Task 写入逻辑。
+
+**回滚方案**：新列加 NULL 约束可随时 DROP，代码回滚至旧版本恢复 `WHERE iccid = ?` 查询即可。旧 iccid 列全程保留，不做变更。
+
+## Open Questions
+
+（无）

openspec/changes/iccid-dual-column-lookup/proposal.md

@@ -0,0 +1,39 @@
+## Why
+
+上游 IoT 平台返回的 ICCID 格式不固定（部分运营商 19 位为唯一标识，部分运营商需要完整 20 位才能唯一标识一张卡），而当前 `tb_iot_card.iccid` 仅支持精确匹配查询。当上游传入的位数与数据库存储的位数不一致时，查询静默失败（返回空结果但不报错），导致设备当前使用卡的 `is_current` 状态更新失效，产生不可观测的数据错乱。
+
+## What Changes
+
+- 在 `tb_iot_card` 表新增 `iccid_19`（varchar(19)）和 `iccid_20`（varchar(20)）两列，分别存储 ICCID 的前 19 位和完整 20 位（19 位卡的 `iccid_20` 为 NULL）
+- 在 `tb_personal_customer_iccid` 表新增 `iccid_19` 列，采用相同策略
+- 所有 ICCID 精确查询改为**按上游传入长度路由**：19 位查 `iccid_19`，20 位查 `iccid_20`，Miss 时记录告警而非降级
+- 不降级、不跨列匹配——上游数据质量问题在日志层暴露，不在查询层消化
+
+## Capabilities
+
+### New Capabilities
+
+（无新增业务能力）
+
+### Modified Capabilities
+
+- `iot-card`：`tb_iot_card` 存储结构变更，新增两列及对应索引；IotCardStore 的所有精确查询方法（GetByICCID、GetByICCIDs、ExistsByICCID、ExistsByICCIDBatch）改用新列路由
+- `iot-card-import-task`：导入任务在写入 IotCard 时同步填充 `iccid_19` / `iccid_20` 两列
+
+## Impact
+
+**数据库**
+- `tb_iot_card`：新增 `iccid_19`、`iccid_20` 两列 + Partial Index（过滤软删除）
+- `tb_personal_customer_iccid`：新增 `iccid_19` 列 + 索引
+- 存量数据一次性回填脚本（迁移文件中执行）
+
+**Store 层**（共 3 个文件，~10 个方法）
+- `iot_card_store.go`：GetByICCID、GetByICCIDs、ExistsByICCID、ExistsByICCIDBatch
+- `personal_customer_iccid_store.go`：GetByICCID、GetByCustomerAndICCID
+- `device_sim_binding_store.go`：UpdateIsCurrentByDeviceID（内部子查询）、GetBoundICCIDs
+
+**Service 层**（1 处内联 SQL）
+- `enterprise_card/service.go`：`WHERE iccid IN ?` 直接 SQL 改为调用 Store 方法或适配新列
+
+**Task 层**（1 处写入路径）
+- `iot_card_import.go`：processBatch() 中 IotCard 初始化时赋值新字段

openspec/changes/iccid-dual-column-lookup/specs/iot-card-import-task/spec.md

@@ -0,0 +1,73 @@
+## MODIFIED 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，必填）
+- `carrier_type`: 运营商类型（VARCHAR(10)，CMCC/CUCC/CTCC/CBN）
+- `batch_no`: 批次号（VARCHAR(100)，可选）
+- `file_name`: 原始文件名（VARCHAR(255)，可选）
+
+**待导入数据**:
+- `card_list`: 待导入卡列表（JSONB，结构: [{iccid, msisdn}]，替代原 iccid_list）
+
+**进度统计**:
+- `total_count`: 总数（INT，CSV 文件总行数）
+- `success_count`: 成功数（INT，成功导入的卡数量）
+- `skip_count`: 跳过数（INT，因重复等原因跳过的数量）
+- `fail_count`: 失败数（INT，因格式错误等原因失败的数量）
+
+**结果详情**:
+- `skipped_items`: 跳过记录详情（JSONB，结构: [{line, iccid, msisdn, reason}]）
+- `failed_items`: 失败记录详情（JSONB，结构: [{line, iccid, msisdn, 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: 创建导入任务
+
+- **GIVEN** 管理员上传包含 ICCID 和 MSISDN 两列的 CSV 文件
+- **WHEN** 系统解析 CSV 并创建导入任务
+- **THEN** 系统创建导入任务记录，`card_list` 包含 [{iccid, msisdn}] 结构，`status` 为 1（待处理）
+
+---
+
+### Requirement: IotCard 写入时同步填充 ICCID 双列
+`processBatch()` 在初始化 `model.IotCard` 时，SHALL 调用 `utils.SplitICCID` 赋值 `ICCID19` 和 `ICCID20` 两个字段。
+
+- `ICCID19 string` = `iccid19`（`SplitICCID` 返回值第一个，所有合法卡必填）
+- `ICCID20 *string` = `iccid20`（`SplitICCID` 返回值第二个，**指针类型**；19 位卡返回 `nil`，GORM 写入 SQL NULL；禁止赋空字符串 `""`）
+- 若 `SplitICCID` 返回 `iccid19 == ""`（异常长度 ICCID），不写入数据库，标记为 fail（此情况在 `ValidateICCID` 长度校验后理论上不应出现，作防御性保留）
+
+`SplitICCID` 函数签名：
+```go
+func SplitICCID(iccid string) (iccid19 string, iccid20 *string)
+// 19 位：返回 (iccid, nil)
+// 20 位：返回 (iccid[:19], &iccid)
+// 其他：返回 ("", nil)
+```
+
+#### Scenario: 导入 19 位卡时填充双列
+- **WHEN** 批量导入时某张卡的 ICCID 长度为 19 位
+- **THEN** 写入数据库时 `iccid_19` = ICCID 原值，`iccid_20` 为 **SQL NULL**（通过 `*string` 赋值 `nil` 实现）
+
+#### Scenario: 导入 20 位卡时填充双列
+- **WHEN** 批量导入时某张卡的 ICCID 长度为 20 位
+- **THEN** 写入数据库时 `iccid_19` = ICCID 前 19 位，`iccid_20` = ICCID 原值（通过 `*string` 赋非 nil 指针实现）

openspec/changes/iccid-dual-column-lookup/specs/iot-card/spec.md

@@ -0,0 +1,121 @@
+## ADDED Requirements
+
+### Requirement: ICCID 双列存储
+`tb_iot_card` SHALL 新增 `iccid_19 varchar(19)` 和 `iccid_20 varchar(20)` 两列。
+
+- `iccid_19`：存储 ICCID 前 19 位（所有卡均有值，对应 19 位运营商卡即为完整 ICCID）
+- `iccid_20`：存储完整 20 位 ICCID（仅 20 位运营商卡有值，19 位运营商卡为 **SQL NULL**）
+- 两列均建立 Partial Index（过滤 `deleted_at IS NULL`），`iccid_20` 额外过滤 NULL
+
+**Go Model 类型约束**：
+- `ICCID19` 字段类型为 `string`（非指针，所有卡必填）
+- `ICCID20` 字段类型为 **`*string`**（指针，19 位卡赋值 `nil` → GORM 写入 NULL；禁止赋空字符串 `""`，GORM 不会将其转为 NULL，会破坏 Partial Index 语义）
+
+#### Scenario: 导入 19 位运营商卡
+- **WHEN** 导入 ICCID 长度为 19 位的卡
+- **THEN** `iccid_19` = ICCID 原值，`iccid_20` = NULL
+
+#### Scenario: 导入 20 位运营商卡
+- **WHEN** 导入 ICCID 长度为 20 位的卡
+- **THEN** `iccid_19` = ICCID 前 19 位，`iccid_20` = ICCID 原值
+
+---
+
+### Requirement: ICCID 按长度路由查询
+系统 SHALL 根据上游传入 ICCID 的字符串长度，路由到对应列进行精确查询。
+
+- 上游传入 19 位 → 查询 `WHERE iccid_19 = ?`
+- 上游传入 20 位 → 查询 `WHERE iccid_20 = ?`
+- 上游传入其他长度 → 记录 Error 日志，返回未找到，不执行查询
+- 禁止跨列降级：任意列 Miss 时直接记录 Warn 日志，不再查另一列
+
+#### Scenario: 上游传入 19 位命中 19 位卡
+- **WHEN** 上游传入 19 位 ICCID，数据库存在对应 19 位卡
+- **THEN** 系统查询 `iccid_19` 列，精确命中，返回卡记录
+
+#### Scenario: 上游传入 20 位命中 20 位卡
+- **WHEN** 上游传入 20 位 ICCID，数据库存在对应 20 位卡
+- **THEN** 系统查询 `iccid_20` 列，精确命中，返回卡记录
+
+#### Scenario: 上游传入 19 位但数据库无对应记录
+- **WHEN** 上游传入 19 位 ICCID，数据库中不存在匹配的 `iccid_19`
+- **THEN** 系统记录 Warn 日志（含 ICCID 和 deviceID），返回未找到，不修改任何数据
+
+#### Scenario: 上游传入 20 位但数据库无对应记录
+- **WHEN** 上游传入 20 位 ICCID，数据库中不存在匹配的 `iccid_20`
+- **THEN** 系统记录 Warn 日志（含 ICCID 和 deviceID），返回未找到，不修改任何数据
+
+#### Scenario: 上游传入异常长度 ICCID
+- **WHEN** 上游传入长度既非 19 也非 20 的 ICCID
+- **THEN** 系统记录 Error 日志，直接返回未找到，不执行数据库查询
+
+---
+
+### Requirement: IotCard 精确查询方法适配
+`IotCardStore` 的精确查询方法 SHALL 全部适配双列查询路由策略。
+
+受影响方法：`GetByICCID`、`GetByICCIDs`、`ExistsByICCID`、`ExistsByICCIDBatch`。
+
+#### Scenario: GetByICCID 单卡精确查询
+- **WHEN** 调用 `GetByICCID(ctx, iccid)` 且 ICCID 长度为 19 或 20 位
+- **THEN** 系统 SHALL 根据长度路由到 `iccid_19` 或 `iccid_20` 列查询，走 Partial Index
+
+#### Scenario: GetByICCIDs 批量精确查询
+- **WHEN** 调用 `GetByICCIDs(ctx, iccids)` 且 iccids 中所有 ICCID 长度一致（均为 19 或均为 20）
+- **THEN** 系统 SHALL 路由到对应列使用 `IN ?` 查询
+
+#### Scenario: GetByICCIDs 混合长度输入
+- **WHEN** 调用 `GetByICCIDs(ctx, iccids)` 且 iccids 中同时包含 19 位和 20 位 ICCID
+- **THEN** 系统 SHALL 按长度分组，分别查询 `iccid_19 IN ?` 和 `iccid_20 IN ?`，合并结果返回
+
+---
+
+### Requirement: DeviceSimBinding 按 ICCID 查询适配
+`DeviceSimBindingStore` 中涉及 ICCID 查询的方法 SHALL 适配双列路由策略。
+
+#### Scenario: UpdateIsCurrentByDeviceID 子查询适配
+- **WHEN** 调用 `UpdateIsCurrentByDeviceID(ctx, deviceID, currentIccid)` 且 currentIccid 非空
+- **THEN** 子查询 SHALL 根据 currentIccid 长度路由到 `iccid_19` 或 `iccid_20` 列查询 iot_card_id
+- **AND** Miss 时记录 Warn 日志，不更新 is_current，不降级
+
+#### Scenario: GetBoundICCIDs JOIN 查询适配
+- **WHEN** 调用 `GetBoundICCIDs(ctx, iccids)` 查询已绑定设备的 ICCID 列表
+- **THEN** JOIN 条件 SHALL 按传入 iccids 长度路由到对应列
+
+---
+
+### Requirement: PersonalCustomerICCIDStore 查询适配
+`PersonalCustomerICCIDStore` 的精确查询方法 SHALL 适配双列查询路由策略。
+
+`tb_personal_customer_iccid` 表 SHALL 新增 `iccid_19 varchar(19)` 列及对应索引。
+
+受影响方法：`GetByICCID`、`GetByCustomerAndICCID`、`ExistsByCustomerAndICCID`、`CreateOrUpdateLastUsed`。
+
+#### Scenario: 个人客户 ICCID 记录写入时同步回填
+- **WHEN** 系统创建或更新 PersonalCustomerICCID 记录
+- **THEN** `iccid_19` SHALL 同步赋值为 ICCID 前 19 位
+
+#### Scenario: 个人客户 ICCID 查询按长度路由
+- **WHEN** 调用 `GetByICCID(ctx, iccid)` 或 `GetByCustomerAndICCID(ctx, customerID, iccid)`
+- **THEN** 系统 SHALL 根据 iccid 长度路由到 `iccid_19` 列（19 位）或原 `iccid` 列（20 位）查询
+
+#### Scenario: 个人客户 ICCID 绑定存在性校验按长度路由
+- **WHEN** 调用 `ExistsByCustomerAndICCID(ctx, customerID, iccid)` 检查客户是否已绑定该 ICCID
+- **THEN** 系统 SHALL 根据 iccid 长度路由到 `iccid_19` 列（19 位）或原 `iccid` 列（20 位）查询，与 `GetByCustomerAndICCID` 保持一致的路由策略
+- **AND** 若路由结果 Miss，返回 `false`（未绑定），不降级查另一列
+
+> **设计说明**：`tb_personal_customer_iccid` 仅新增 `iccid_19` 列而不添加 `iccid_20` 列。原因：该表的 ICCID 来自**个人客户手动输入**（扫码/手动填写），而非上游 IoT 平台回调。上游平台才是 19/20 位格式不一致问题的来源；个人客户输入的格式与数据库存储格式一致，因此 20 位查询走原 `iccid` 列即可，无需双列适配。
+
+---
+
+### Requirement: 内联 ICCID SQL 归还 Store 层
+`enterprise_card/service.go` 中两处直接拼写 `WHERE iccid IN ?` 的内联 SQL SHALL 重构为调用 `IotCardStore.GetByICCIDs()`，消除架构违规并恢复数据权限过滤。
+
+该重构需要同步变更：
+1. `enterprise_card.Service` struct 新增 `iotCardStore *postgres.IotCardStore` 字段
+2. `New()` 函数签名增加 `iotCardStore *postgres.IotCardStore` 参数
+3. `internal/bootstrap/services.go` 调用处传入 `s.IotCard`
+
+#### Scenario: 企业卡分配预览调用 Store 层查询
+- **WHEN** 执行企业卡分配预览或分配操作，需要按 ICCIDs 查询卡列表
+- **THEN** 系统 SHALL 通过 `IotCardStore.GetByICCIDs()` 查询，不允许 Service 层直接拼写 ICCID 过滤 SQL

openspec/changes/iccid-dual-column-lookup/tasks.md

@@ -0,0 +1,82 @@
+## 1. 数据库迁移
+
+> **注意**：1.1–1.5 全部写在**同一个迁移文件**中，保持原子性；执行迁移后再发布代码。
+>
+> **索引注意**：`CREATE INDEX CONCURRENTLY` 不能在事务块内执行，golang-migrate 默认开启事务，迁移文件中必须使用 `CREATE INDEX IF NOT EXISTS`（不带 CONCURRENTLY）。生产环境若需零停机建索引，可在发布窗口期手动执行 CONCURRENTLY 版本。（与本项目 `000058_add_covering_index_for_deep_pagination.up.sql` 范式一致。）
+
+- [x] 1.1 新建迁移文件，给 `tb_iot_card` 添加 `iccid_19 varchar(19)` 和 `iccid_20 varchar(20)` 两列（允许 NULL，使用 `ADD COLUMN IF NOT EXISTS`）
+- [x] 1.1a 迁移文件中执行冲突检测（结果须为 0 行，否则停止迁移人工处理）：
+  - 检测 19 位前缀重复：`SELECT LEFT(iccid, 19), COUNT(*) FROM tb_iot_card WHERE deleted_at IS NULL GROUP BY LEFT(iccid, 19) HAVING COUNT(*) > 1`
+  - 检测异常长度 ICCID：`SELECT id, iccid, LENGTH(iccid) AS len FROM tb_iot_card WHERE deleted_at IS NULL AND LENGTH(iccid) NOT IN (19, 20)`（异常记录回填后将永远无法通过新查询路径命中）
+- [x] 1.2 迁移文件中回填存量数据：`iccid_19 = LEFT(iccid, 19)`，`iccid_20 = iccid`（仅当 LENGTH(iccid)=20，否则 NULL）
+- [x] 1.3 迁移文件中为 `iccid_19` 创建 Partial Index：`CREATE INDEX IF NOT EXISTS idx_iot_card_iccid_19 ON tb_iot_card (iccid_19) WHERE deleted_at IS NULL`（**禁止** CONCURRENTLY，原因见上方注意事项）
+- [x] 1.4 迁移文件中为 `iccid_20` 创建 Partial Index：`CREATE INDEX IF NOT EXISTS idx_iot_card_iccid_20 ON tb_iot_card (iccid_20) WHERE deleted_at IS NULL AND iccid_20 IS NOT NULL`（**禁止** CONCURRENTLY）
+- [x] 1.5 同一迁移文件中，给 `tb_personal_customer_iccid` 添加 `iccid_19 varchar(19)` 列（允许 NULL）并回填数据（`iccid_19 = LEFT(iccid, 19)`），创建对应 Partial Index：`CREATE INDEX IF NOT EXISTS idx_personal_customer_iccid_19 ON tb_personal_customer_iccid (iccid_19) WHERE deleted_at IS NULL`
+- [x] 1.6 执行迁移，验证所有卡记录的 `iccid_19` 和 `iccid_20` 已正确回填（使用 PostgreSQL MCP 查询验证）
+
+## 2. Model 层更新
+
+- [x] 2.1 在 `internal/model/iot_card.go` 的 `IotCard` 结构体中新增以下两个字段，补充 gorm 标签和中文注释：
+  - `ICCID19 string`（非指针，所有卡必填，gorm tag 示例：`gorm:"column:iccid_19;type:varchar(19);comment:ICCID前19位"`）
+  - `ICCID20 *string`（**指针类型**，19 位卡为 `nil`，GORM 写入 NULL；20 位卡为非 nil 指针，gorm tag 示例：`gorm:"column:iccid_20;type:varchar(20);comment:完整20位ICCID(仅20位运营商卡有值)"`）
+  - 禁止使用 `string` 类型存 `ICCID20`：GORM 不会将空字符串自动转为 NULL，会破坏 `WHERE iccid_20 IS NOT NULL` 索引语义
+- [x] 2.2 在 `internal/model/personal_customer_iccid.go` 的 `PersonalCustomerICCID` 结构体中新增 `ICCID19` 字段，补充 gorm 标签和中文注释
+- [x] 2.3 运行 `lsp_diagnostics` 确认 model 文件无编译错误
+
+## 3. 工具函数与校验
+
+- [x] 3.1 在 `pkg/utils/iccid.go` 中实现 `SplitICCID` 函数，签名和语义如下：
+  ```go
+  // SplitICCID 按 ICCID 长度拆分为双列存储值
+  // 19 位卡：返回 (iccid, nil)
+  // 20 位卡：返回 (iccid[:19], &iccid)
+  // 其他长度：返回 ("", nil)，调用方应将对应卡标记为失败
+  func SplitICCID(iccid string) (iccid19 string, iccid20 *string)
+  ```
+  **禁止**返回空字符串 `""` 作为 `iccid20`：ICCID20 字段类型为 `*string`，19 位卡必须返回 `nil`，GORM 才会写入 NULL。
+
+- [x] 3.2 更新 `pkg/validator/iccid.go` 的 `ValidateICCID` 函数，增加长度校验：ICCID 长度必须为 19 或 20 位，否则返回 `ICCIDValidationResult{Valid: false, Message: "ICCID 长度必须为19或20位"}`；防止非法长度 ICCID 通过导入写入数据库后永远 miss
+
+## 4. IotCard 写入路径适配
+
+- [x] 4.1 在 `internal/task/iot_card_import.go` 的 `processBatch()` 中，IotCard 初始化时调用 `utils.SplitICCID` 赋值 `ICCID19` 和 `ICCID20` 字段（此步骤在 task 3.2 的长度校验之后，理论上不会出现异常长度，但防御性保留：若 `iccid19 == ""`，标记 fail 并跳过，不写入数据库）
+- [x] 4.2 使用 PostgreSQL MCP 验证导入后新记录的 `iccid_19` 和 `iccid_20` 字段已正确写入
+
+## 5. IotCardStore 精确查询方法适配
+
+- [x] 5.1 改造 `GetByICCID(ctx, iccid)`：按 iccid 长度路由到 `iccid_19` 或 `iccid_20` 列查询；异常长度记录 Error 日志；Miss 记录 Warn 日志
+- [x] 5.2 改造 `GetByICCIDs(ctx, iccids)`：按长度分组，分别查询 `iccid_19 IN ?` 和 `iccid_20 IN ?`，合并去重结果
+- [x] 5.3 改造 `ExistsByICCID(ctx, iccid)`：按长度路由到对应列
+- [x] 5.4 改造 `ExistsByICCIDBatch(ctx, iccids)`：按长度分组查询（19 位组 `Pluck("iccid_19", &list19)`，20 位组 `Pluck("iccid_20", &list20)`），合并结果；因各分组内 Pluck 返回值恰好等于原始 ICCID（19 位组：`iccid_19 == 原始 ICCID`；20 位组：`iccid_20 == 原始 ICCID`），直接以 Pluck 值为 map key，调用方 `existingMap[card.ICCID]` 逻辑无需修改
+- [x] 5.5 运行 `lsp_diagnostics` 确认 `iot_card_store.go` 无编译错误
+
+## 6. DeviceSimBindingStore 查询方法适配
+
+- [x] 6.1 改造 `UpdateIsCurrentByDeviceID` 内部子查询：按 currentIccid 长度路由到 `iccid_19` 或 `iccid_20` 列查询 iot_card_id；Miss 时记录 Warn 日志（日志字段：`iccid`、`device_id`、`column_used`，该方法持有 `deviceID` 参数可直接记录），不更新数据，不降级
+- [x] 6.2 改造 `GetBoundICCIDs`：按传入 iccids 长度**分组**，分别执行两次 JOIN 查询后在应用层合并：
+  - 19 位组：`JOIN tb_iot_card c ON c.id = b.iot_card_id WHERE c.iccid_19 IN ? AND b.bind_status = 1 AND c.deleted_at IS NULL`，SELECT `c.iccid_19 AS iccid`
+  - 20 位组：`JOIN tb_iot_card c ON c.id = b.iot_card_id WHERE c.iccid_20 IN ? AND b.bind_status = 1 AND c.deleted_at IS NULL`，SELECT `c.iccid_20 AS iccid`
+  - 两组结果合并为 `map[string]bool`，key 使用各组 SELECT 的 iccid 值（即原始 ICCID）
+- [x] 6.3 运行 `lsp_diagnostics` 确认 `device_sim_binding_store.go` 无编译错误
+
+## 7. PersonalCustomerICCIDStore 查询方法适配
+
+- [x] 7.1 改造 `GetByICCID(ctx, iccid)`：按 iccid 长度路由，19 位查 `iccid_19`，20 位查原 `iccid` 列
+- [x] 7.2 改造 `GetByCustomerAndICCID(ctx, customerID, iccid)`：同上，按长度路由
+- [x] 7.3 改造 `CreateOrUpdateLastUsed(ctx, customerID, iccid)`：写入时同步赋值 `ICCID19` 字段
+- [x] 7.3.5 改造 `ExistsByCustomerAndICCID(ctx, customerID, iccid)`：按 iccid 长度路由，19 位查 `iccid_19`，20 位查原 `iccid` 列；路由策略与 `GetByCustomerAndICCID` 保持一致；Miss 时直接返回 `false`，不降级
+- [x] 7.4 运行 `lsp_diagnostics` 确认 `personal_customer_iccid_store.go` 无编译错误
+
+## 8. 架构违规修复
+
+- [x] 8.1 在 `internal/service/enterprise_card/service.go` 的 `Service` struct 中新增 `iotCardStore *postgres.IotCardStore` 字段，并更新 `New()` 函数签名增加 `iotCardStore *postgres.IotCardStore` 参数
+- [x] 8.2 更新 `internal/bootstrap/services.go` 第 191 行 `enterpriseCardSvc.New()` 调用，传入 `s.IotCard`（IotCardStore 实例）
+- [x] 8.3 将 `enterprise_card/service.go` 中两处直接拼写 `WHERE iccid IN ?` 的内联 SQL（第 46 行、第 185 行）重构为调用 `s.iotCardStore.GetByICCIDs()`
+- [x] 8.4 运行 `lsp_diagnostics` 确认 `enterprise_card/service.go` 和 `bootstrap/services.go` 无编译错误
+
+## 9. 整体验证
+
+- [x] 9.1 执行 `go build ./...` 确认全量编译通过
+- [x] 9.2 使用 PostgreSQL MCP 模拟上游场景验证：上游传入 19 位 ICCID，确认正确命中 19 位卡的 `is_current` 更新
+- [x] 9.3 使用 PostgreSQL MCP 模拟上游场景验证：上游传入 20 位 ICCID，确认正确命中 20 位卡的 `is_current` 更新
+- [x] 9.4 确认日志中 Miss 场景正确输出 Warn 日志（可通过修改测试数据触发）