分裂iccid长度

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
+
+（无）