junhong_cmp_fiber/openspec/changes/asset-realname-policy/design.md

Context

系统存在一段注释掉的实名拦截代码（REALNAME-03，位于 internal/service/client_order/service.go 第 143 行），原逻辑为"普通卡（card_category=normal）需实名才能购买套餐，行业卡（industry）无需实名"。由于业务还未明确，该逻辑被整体注释，由网关侧临时托管。

现在业务明确了两种场景：先实名后充值（充值/购买前拦截未实名资产）与先充值后实名（充值/购买放行，实名链接在未充值前拦截）。且行业卡在特定业务下也可能需要实名，原来依赖 card_category 的硬编码逻辑不够灵活。

需要在资产层面（IotCard 和 Device）引入可配置的 realname_policy 字段，取代原有硬编码逻辑，支持导入时批量初始化策略、后台管理接口修改策略、所有查询接口返回策略字段、以及 C 端三接口按策略执行拦截。

Goals / Non-Goals

Goals:

• 在 IotCard 和 Device 模型上新增 realname_policy 字段（string 枚举）
• IoT 卡导入和设备导入支持批量初始化 realname_policy
• 后台新增 PATCH /api/admin/assets/:identifier/realname-mode 接口修改单资产策略
• C 端充值（C3/C4）、购买套餐/订单（D1/D4）、实名链接（E1）按策略拦截
• 所有涉及卡/设备/资产的查询接口返回 realname_policy 字段
• 存量数据迁移默认值为 none，不影响现有行为

Non-Goals:

• 不修改登录层的实名检查（已有机制，由网关托管）
• 不实现用户通知（after_order 实名提醒等）
• 不修改 Carrier 层的 realname_link_type（运营商提供实名链接的方式，是另一个维度）
• 不实现按套餐粒度的实名策略（只到资产粒度）

Decisions

决策 1：realname_policy 使用 string 枚举而非 bool

选 string 而非 bool（如 realname_required）：业务存在三种状态（无需实名 / 先实名后充值 / 先充值后实名），bool 只能表达两种。枚举值：none / before_order / after_order。

决策 2：设备卡场景以 Device.realname_policy 为准

当一张卡绑定到设备时（设备卡），取 Device.realname_policy；未绑定设备时（单卡），取 IotCard.realname_policy。这与现有系统中"设备层面的验证规则高于卡层面"的设计一致（登录前的设备验证已体现此原则）。

判断逻辑封装在 Service 层公共方法 GetEffectiveRealnamePolicy(card *model.IotCard, device *model.Device) string，避免在多个 Service 中重复实现。

决策 3：after_order 场景下实名链接的前置条件

after_order 模式下，用户调用 GET /api/c/v1/realname/link 时，系统检查该资产是否存在有效充值或已支付订单记录（status=2 的订单或 status=2 的充值单）。无记录则拦截；有记录则放行。

逻辑：先充值才有资格实名，避免用户跳过充值直接实名。检查范围：该资产当前 generation 内的充值记录或套餐订单记录。

决策 4：后台更新接口复用现有资产解析器

遵循 UpdatePollingStatus 的模式（PATCH /api/admin/assets/:identifier/polling-status）：

• 接口路径：PATCH /api/admin/assets/:identifier/realname-mode
• 通过 assetService.Resolve() 将标识符解析为 asset_type + asset_id
• asset_type=card → 更新 IotCard.realname_policy
• asset_type=device → 更新 Device.realname_policy
• 单接口覆盖两种资产类型，与现有模式完全一致

决策 5：存量数据默认值为 none

迁移时所有存量卡和设备的 realname_policy 默认值为 none（无需实名），保持与现有行为完全一致（目前实名拦截已被注释，等于放行）。运营方后续按需批量更新。

决策 6：命名区分

RealnamePolicy（资产的实名策略：何时需要实名）与现有 RealnameLinkType（运营商提供实名链接的方式：none/template/gateway）是两个独立维度，字段名不同，不产生混淆。DTO 中 response 字段名为 realname_policy。

Risks / Trade-offs

[风险 1] after_order 拦截查询增加数据库压力 → 缓解：查询只取 COUNT(*) > 0，命中索引（generation + asset_id + status），可加 Redis 缓存（key 为 realname:after_order_eligible:{asset_type}:{asset_id}:{generation}，充值/购买成功时主动写入，TTL 24h）。初期数据量小，可不加缓存，待观察后决定。

[风险 2] DTO 改动面大，遗漏字段 → 缓解：所有涉及卡/设备/资产的 DTO 已在探索阶段完整盘点，tasks.md 按文件逐一列举，不依赖记忆。

[风险 3] 存量数据全为 none，初始化后无法区分"未配置"与"主动设为 none" → 可接受：none 本身是有效业务值（无需实名），与未配置语义相同，不需要额外区分。

Migration Plan

1. 创建数据库迁移文件，为四张表新增 realname_policy 字段：

   ALTER TABLE tb_iot_card ADD COLUMN realname_policy VARCHAR(20) NOT NULL DEFAULT 'none';
   ALTER TABLE tb_device ADD COLUMN realname_policy VARCHAR(20) NOT NULL DEFAULT 'none';
   ALTER TABLE tb_iot_card_import_task ADD COLUMN realname_policy VARCHAR(20) NOT NULL DEFAULT 'none';
   ALTER TABLE tb_device_import_task ADD COLUMN realname_policy VARCHAR(20) NOT NULL DEFAULT 'none';
   

2. 迁移前：REALNAME-03 注释代码继续保持注释（不影响线上）
3. 迁移后：代码上线，实名拦截以新字段为准；存量全为 none，等于放行，行为不变
4. 回滚策略：字段加 DEFAULT，删除新增字段即可，代码回滚到上一版本

Open Questions

无（所有关键问题已在探索阶段与业务方确认）