junhong_cmp_fiber/openspec/changes/fix-realname-activation-logic/specs/package-realname-activation/spec.md

MODIFIED Requirements

Requirement: 支持未实名状态购买套餐

系统 SHALL 允许后台管理端为未实名的载体（设备/卡）购买套餐，套餐状态为"待生效"(status=0)。对于 expiry_base=from_activation 的套餐，系统 SHALL 在创建 PackageUsage 时检查载体当前实名状态：若已实名则直接激活；若未实名则标记 pending_realname_activation=true 等待实名触发。

实名状态判定规则：

• iot_card 载体：查询该卡的 real_name_status 字段
• device 载体：通过 tb_device_sim_binding（bind_status=1）查询是否存在任意已实名（real_name_status=1）的绑定卡；存在任意一张即视为设备已实名

Scenario: 后台为未实名设备购买 from_activation 套餐——待生效

• GIVEN 设备 ID=2，绑定的所有卡 real_name_status=0（均未实名）
• AND 套餐 expiry_base=from_activation，购买者为代理商（非 C 端）
• WHEN 管理员通过后台为该设备购买套餐
• THEN 系统创建 PackageUsage：status=0，pending_realname_activation=true，activated_at=NULL，expires_at=NULL

Scenario: 后台为已有实名卡的设备购买 from_activation 套餐——直接激活并触发复机

• GIVEN 设备 ID=2，至少一张绑定卡 real_name_status=1（已实名），且设备下有卡因无套餐停机（stop_reason=no_package）
• AND 套餐 expiry_base=from_activation，购买者为代理商（非 C 端）
• WHEN 管理员通过后台为该设备购买套餐
• THEN 系统创建 PackageUsage：status=1，pending_realname_activation=false，activated_at=购买时间，expires_at 按套餐配置计算
• AND tryResumeAfterPayment 检测到 activatedCount=1，异步调用 ResumeCardIfStopped("device", 2)
• AND 设备下已实名且因 no_package 停机的卡自动开机

Scenario: 后台为已实名单卡购买 from_activation 套餐——直接激活

• GIVEN IoT 卡 ID=10，real_name_status=1（已实名）
• AND 套餐 expiry_base=from_activation，购买者为代理商（非 C 端）
• WHEN 管理员通过后台为该卡购买套餐
• THEN 系统创建 PackageUsage：status=1，pending_realname_activation=false，activated_at=购买时间，expires_at 按套餐配置计算

Scenario: 后台为未实名单卡购买 from_activation 套餐——待生效

• GIVEN IoT 卡 ID=10，real_name_status=0（未实名）
• AND 套餐 expiry_base=from_activation，购买者为代理商（非 C 端）
• WHEN 管理员通过后台为该卡购买套餐
• THEN 系统创建 PackageUsage：status=0，pending_realname_activation=true，activated_at=NULL，expires_at=NULL

Scenario: from_purchase 套餐不检查实名状态——始终直接激活

• GIVEN 设备 ID=2，所有绑定卡均未实名（real_name_status=0）
• AND 套餐 expiry_base=from_purchase
• WHEN 管理员通过后台为该设备购买套餐
• THEN 系统创建 PackageUsage：status=1，pending_realname_activation=false，立即生效

Scenario: 客户端购买套餐——必须先实名（不受本次变更影响）

• GIVEN 设备 ID=2，购买者为个人客户（C 端）
• WHEN 客户通过 H5/小程序购买套餐
• THEN 系统前置检查已实名，行为不变

ADDED Requirements

Requirement: 卡首次实名时同时触发所属设备的设备级套餐激活

当轮询系统检测到某张 IoT 卡的实名状态从 0 变为 1（首次实名），系统 SHALL 除提交该卡的 TaskTypePackageFirstActivation 任务外，额外查询该卡是否属于某个设备（通过 tb_device_sim_binding），若存在有效绑定则同时提交以该设备为载体（carrier_type=device）的 TaskTypePackageFirstActivation 任务。

设计约束：

• 若卡未绑定任何设备（GetActiveBindingByCardID 返回 ErrRecordNotFound）则静默跳过，不报错
• 提交任务失败记录 Warn 日志，不阻塞卡级激活流程
• 任务幂等：ActivateByRealname(ctx, "device", deviceID) 若查不到 pending_realname_activation=true 的套餐则直接返回 nil

Scenario: 设备下某张卡首次实名——同时触发设备级套餐激活与复机

• GIVEN IoT 卡 ID=4，绑定于设备 ID=2（tb_device_sim_binding 中存在有效绑定）
• AND 设备 ID=2 存在 status=0, pending_realname_activation=true 的设备级 PackageUsage
• AND 设备下有卡因 not_realname 停机（stop_reason=not_realname）
• WHEN 轮询系统检测到卡 ID=4 实名状态 0→1
• THEN 系统提交两个 Asynq 任务：
  1. carrier_type=iot_card, carrier_id=4（卡级激活）
  2. carrier_type=device, carrier_id=2（设备级激活）
• AND 设备级 PackageUsage 最终 status=1, pending_realname_activation=false, activated_at 已设置
• AND ActivateByRealname 激活成功后异步调用 ResumeCardIfStopped("device", 2)，设备下已实名的停机卡自动开机

Scenario: 独立卡（未绑定设备）首次实名——仅触发卡级激活

• GIVEN IoT 卡 ID=10，未绑定任何设备（tb_device_sim_binding 中无有效记录）
• WHEN 轮询系统检测到卡 ID=10 实名状态 0→1
• THEN 系统仅提交卡级 Asynq 任务（carrier_type=iot_card, carrier_id=10）
• AND 不报错，不记录 Error 日志

Scenario: 设备下某张卡实名但设备无待激活套餐——任务执行幂等返回

• GIVEN IoT 卡 ID=4，绑定于设备 ID=2
• AND 设备 ID=2 无 pending_realname_activation=true 的套餐
• WHEN 轮询系统检测到卡 ID=4 实名状态 0→1，并提交设备级激活任务
• THEN 任务 Worker 执行 ActivateByRealname(ctx, "device", 2)，查询结果为空，直接返回 nil（无错误）