junhong_cmp_fiber/openspec/changes/archive/2026-04-07-asset-identifier-standardization/design.md

Context

当前系统中，资产（IoT 卡和设备）的操作接口混用两套参数规范：

• B 端大多数接口：使用数据库主键 ID（/assets/:asset_type/:id/、/devices/:id/），前端持有无业务含义的整数 ID
• 部分接口：使用业务标识符（/assets/card/:iccid/stop、/devices/by-identifier/:identifier/wifi），但命名不一致
• C 端接口：已规范使用 identifier query 参数（ICCID/VirtualNo）

主要问题：

1. IoT 卡和设备各自表内有 VirtualNo 唯一索引，但跨表没有全局唯一约束，理论上可写入相同虚拟号
2. 订单创建接口传入 iot_card_id/device_id 主键，响应也只返回 ID，不含标识符
3. purchase_validation 未校验绑定设备的卡，允许对非独立卡（is_standalone=false）单独购买套餐
4. Resolve 服务对两张表做 OR 多字段查询，性能随数据量增长有退化风险

Goals / Non-Goals

Goals:

• 建立全局资产标识符注册表（tb_asset_identifier），数据库层保证 VirtualNo/ICCID 跨表全局唯一
• B 端所有资产操作接口统一使用 :identifier 路径参数（ICCID 或 VirtualNo）
• Resolve 主查询路径改走注册表，降低查询复杂度
• 订单接口改用 identifier 传参，响应补充标识符快照字段
• 修复绑定设备的卡可单独购买套餐的 Bug

Non-Goals:

• IoT 卡导入强制 VirtualNo（属于提案三，独立推进）
• 资产往期订单查询接口（属于提案二，独立推进）
• C 端接口变更（C 端已规范，本次不动）
• Resolve 接口的 IMEI/SN/MSISDN fallback 查询（保留现有逻辑）

Decisions

决策 1：使用独立注册表（tb_asset_identifier）实现跨表全局唯一

选择：新增 tb_asset_identifier 表，identifier 字段加 UNIQUE 约束

备选方案：

• 应用层检查：插入前先查两张表，存在则拒绝。问题：高并发下存在竞态窗口，同一标识符可能被两个并发请求同时通过检查
• 数据库触发器：在 tb_device 和 tb_iot_card 上建触发器查对方表。问题：触发器调试困难，项目中无此先例，违背"逻辑在代码层"原则

理由：注册表方案通过数据库 UNIQUE 约束消除竞态——两个并发写入同一标识符时，数据库只允许一个成功，另一个收到约束冲突错误并回滚事务，安全可靠且符合项目"禁止外键，关联在代码层维护"的原则。

表结构：

CREATE TABLE tb_asset_identifier (
    id          BIGSERIAL PRIMARY KEY,
    identifier  VARCHAR(100) NOT NULL,
    asset_type  VARCHAR(20)  NOT NULL,  -- 'iot_card' | 'device'
    asset_id    BIGINT       NOT NULL,
    created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_asset_identifier UNIQUE (identifier)
);
CREATE INDEX idx_asset_identifier_asset ON tb_asset_identifier(asset_type, asset_id);

写入时机：

• 创建设备/IoT 卡时，在同一事务内写入注册表
• 软删除时，同步从注册表删除（或标记 deleted_at，避免已删除的标识符阻塞复用）
• VirtualNo 更新时（目前无此场景，预留），先删旧记录再插新记录

决策 2：Resolve 主路径改走注册表，保留 fallback

选择：Resolve 方法优先查 tb_asset_identifier（精确匹配），未命中再 fallback 到原有跨表 OR 查询（处理 IMEI/SN/MSISDN 等非注册标识符）

理由：注册表只存 VirtualNo 和 ICCID（全局唯一的标识符），IMEI/SN/MSISDN 因非唯一不写入注册表。Resolve 接口仍需支持这些模糊标识符（方便管理员查找），但精确路径走注册表可大幅提升性能。

Resolve(identifier) 逻辑：
  1. 查 tb_asset_identifier WHERE identifier = ?
     → 命中：得到 asset_type + asset_id，按 type 查完整记录
     → 未命中：fallback 到原有逻辑（OR 多字段查 device/iot_card）

决策 3：B 端接口统一 :identifier，不区分 card/device 类型

选择：路由改为 /admin/assets/:identifier/*，系统内部通过 Resolve 得到 asset_type，无需路径中显式传类型

备选方案：

• 保留 :asset_type 前缀：/admin/assets/card/:iccid/packages。问题：调用方需要知道"这是卡还是设备"才能构造 URL，而 identifier 本身已能唯一定位
• 两段式 Resolve + ID：前端先调 Resolve 拿 ID 再操作。问题：前端耦合两个接口，且 ID 无业务含义

理由：identifier 已能唯一定位资产（通过注册表），asset_type 冗余；URL 语义更自然（/assets/ICCID-001/packages 而非 /assets/card/ICCID-001/packages）。

注意：仅操作类接口（packages/realtime/stop/start 等）使用统一 :identifier。设备绑卡管理（/devices/:virtual_no/cards）因属于设备专属操作，路径保留 devices 前缀但改用 VirtualNo。

决策 4：订单创建改用 identifier，系统内部解析 asset_type

选择：CreateOrderRequest 去掉 iot_card_id/device_id，改为 identifier 字段，order_type 字段同时废弃（由 identifier 解析结果决定）

理由：与接口统一规范一致；同时自然修复"绑定设备的卡可单独购买"Bug——解析 identifier 后得到 is_standalone=false 的卡，直接在 purchase_validation 层拦截。

Order 模型快照：订单记录中增加 asset_identifier VARCHAR(100) 字段，存储下单时资产的标识符快照（类似 order_no 的快照思路），便于历史查询而不依赖关联查询。

Risks / Trade-offs

风险	缓解措施
Breaking 变更：B 端所有资产路由改变，前端需全量更新	系统处于测试阶段，前端可同步切换；通过 OpenAPI 文档明确新路由
存量资产未在注册表：现有 tb_device 和 tb_iot_card 数据需回填注册表	提供数据迁移脚本，回填时检查 VirtualNo 跨表唯一性；直接清库（测试阶段）则无此问题
注册表成为热点：资产创建时额外写一张表	注册表操作在事务内，单次 INSERT；正常导入批量处理，影响极小
Resolve fallback 性能：IMEI/SN 仍走全表 OR 查询	fallback 路径为次要场景，精确路径（注册表）已涵盖主要查询；长期可为 IMEI/SN 建索引
order_type 废弃兼容：历史订单含 order_type 字段	历史数据保留，新创建订单由系统根据 identifier 填入 order_type；API 不再接受 order_type 输入

Migration Plan

步骤一：数据库迁移

1. 创建迁移文件，建立 tb_asset_identifier 表
2. 执行回填脚本：将所有现有设备的 VirtualNo 和 IoT 卡的 ICCID/VirtualNo 写入注册表
3. 测试阶段：直接清库则跳过步骤 2

步骤二：后端实现（可分 PR 推进）

1. 新增 AssetIdentifier 模型和 asset_identifier_store
2. 改造 Resolve 服务，注册表主路径 + fallback
3. 更新 purchase_validation，增加 is_standalone 校验
4. 更新 Order 模型，增加 asset_identifier 快照字段
5. 重写 B 端路由：asset.go、device.go、iot_card.go、order.go
6. 更新 DTO：asset_dto.go、order_dto.go、client_order_dto.go
7. 更新 Handler 层参数解析
8. 更新 gendocs 文档生成

步骤三：验证

1. 全量 API 回归测试
2. 并发写入同一 VirtualNo 压测（验证注册表唯一约束）
3. Resolve fallback 路径验证（IMEI/SN 查询）

回滚方案：保留旧路由映射（别名路由）72 小时，确认前端切换完毕后删除

Open Questions

• 已解决：VirtualNo 跨表全局唯一策略（独立注册表）
• 已解决：B 端路由统一方案（方案 B，统一 :identifier）
• 已解决：订单传参方式（identifier，不传 asset_type）
• 待确认：Order 模型中 asset_identifier 快照字段的数据库类型选 VARCHAR(100) 是否满足所有标识符长度（ICCID 最长 20 位，VirtualNo 最长 100 位）