huang
8980e6d999
问题一：protect 轮询任务从未被调度器初始化入队 PollingConfig 新增 protect_check_interval 字段（NULL=不参与）， 调度器 initCardsBatch/initCardPolling/requeueCard 补全 protect 队列 初始化逻辑，IotCard 新增 last_protect_check_at 记录上次检查时间。 迁移文件：000102_add_polling_protect_fields 问题二：设备套餐流量耗尽时绑定卡未被停机 UsageService.checkAndTriggerSuspension 新增 carrier_type=device 分支， 通过 DeviceSimBindingStore.ListByDeviceID 查询绑定卡，对每张卡异步 触发 CheckAndStopCard，同步注入 Bootstrap 依赖。 问题三：主套餐过期后不立即停机，依赖下次轮询兜底 PackageActivationHandler.processExpiredPackage 在 updateCarrierSuspended Status 后，若载体无后续生效套餐，立即异步调用 CheckAndStopCard（iot_card 类型直接触发，device 类型遍历绑定卡），消除停机延迟窗口。 Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
5.7 KiB
polling-protect-consistency Specification
Purpose
新增第四种轮询任务类型（保护期一致性检查），用于确保设备保护期内绑定卡的网络状态与保护期方向保持一致，防止状态漂移。
Requirements
Requirement: 保护期一致性检查轮询任务
系统 SHALL 新增第四种轮询任务类型（保护期一致性检查），作为独立任务处理器，不修改现有三种任务（实名检查/流量检查/套餐检查）的内部逻辑。
任务类型标识: protect（与现有 realname、carddata、package 并列）
Redis 队列 Key: RedisPollingQueueProtectKey() → "polling:queue:protect"
触发频率: 与流量检查任务同频（默认 10 分钟）
任务范围: 仅检查"已绑定设备且设备当前有保护期"的卡，范围小，不会对未绑定设备的卡产生影响
处理逻辑:
- 检查卡是否已实名（
real_name_status = 0则跳过，未实名卡不参与保护期逻辑） - 检查卡是否绑定设备（
is_standalone = true则跳过） - 读取设备保护期 Redis Key
- 若设备有 stop 保护期，且卡当前网络状态为开机：强制调网关停机，更新卡
network_status = 0 - 若设备有 start 保护期，且卡当前网络状态为停机：强制调网关复机，更新卡
network_status = 1 - 状态已一致（开机 + stop 保护期已停 / 停机 + start 保护期已开）：跳过
Scenario: stop 保护期内卡状态异常（开机）
- WHEN 轮询任务检查一张已实名卡，发现绑定设备有 stop 保护期，但卡当前 network_status=1（开机）
- THEN 任务强制调网关停机，更新卡 network_status=0，记录 Info 日志
Scenario: start 保护期内卡状态异常（停机）
- WHEN 轮询任务检查一张已实名卡，发现绑定设备有 start 保护期，但卡当前 network_status=0（停机）
- THEN 任务强制调网关复机，更新卡 network_status=1，记录 Info 日志
Scenario: 状态已一致，跳过
- WHEN 轮询任务检查一张卡，设备有 stop 保护期，卡已是停机状态
- THEN 任务跳过，不调网关，不更新 DB
Scenario: 未实名卡跳过保护期逻辑
- WHEN 轮询任务遇到 real_name_status=0 的卡
- THEN 任务直接跳过，不检查保护期，不调网关
Scenario: 独立卡（未绑定设备）跳过
- WHEN 轮询任务遇到 is_standalone=true 的卡
- THEN 任务直接跳过，不查询设备保护期
迭代更新（fix-polling-coverage-gaps）
MODIFIED Requirement: 保护期一致性检查轮询任务
系统 SHALL 通过轮询调度器定时执行保护期一致性检查任务（polling:protect），检查绑定设备有保护期的已实名卡的网络状态，并在状态不一致时强制调网关修正。
任务类型标识: protect（与现有 realname、carddata、package 并列）
Redis 队列 Key: RedisPollingQueueProtectKey() → "polling:queue:protect"
触发频率（变更）: 由 PollingConfig.ProtectCheckInterval（新增字段，单位秒）控制，NULL 或 0 表示该配置不参与 protect 检查，建议默认 600s（原：与流量检查任务同频固定 10 分钟）
初始化：调度器启动时，initCardsBatch 和 initCardPolling SHALL 读取匹配配置的 ProtectCheckInterval，将卡加入 polling:queue:protect Sorted Set；任务完成后通过 requeueCard 按间隔重新入队，并更新 last_protect_check_at
数据模型变更：
tb_polling_config新增protect_check_interval INT NULL字段tb_iot_card新增last_protect_check_at TIMESTAMP NULL字段（记录上次检查时间，用于计算下次入队 score）
处理逻辑（与原 spec 一致，不变）:
- 卡未实名（
real_name_status = 0）→ 跳过 - 卡未绑定设备（
is_standalone = true）→ 跳过 - 设备有 stop 保护期且卡在线（
network_status = 1）→ 调网关停机，更新network_status = 0 - 设备有 start 保护期且卡停机（
network_status = 0）→ 调网关复机，更新network_status = 1 - 状态已一致 → 跳过
Scenario: stop 保护期内卡状态异常（开机）
- WHEN protect 轮询任务检查一张已实名、已绑定设备的卡，发现设备有 stop 保护期，且卡当前
network_status = 1（开机） - THEN 任务调网关停机，更新卡
network_status = 0，更新last_protect_check_at，记录 Info 日志
Scenario: start 保护期内卡状态异常（停机）
- WHEN protect 轮询任务检查一张已实名、已绑定设备的卡，发现设备有 start 保护期，且卡当前
network_status = 0（停机） - THEN 任务调网关复机，更新卡
network_status = 1，更新last_protect_check_at，记录 Info 日志
Scenario: 状态已一致，跳过
- WHEN protect 轮询任务检查一张卡，设备有 stop 保护期，卡已是停机状态（
network_status = 0） - THEN 任务跳过，不调网关，不更新 DB，更新
last_protect_check_at
Scenario: 未实名卡跳过保护期逻辑
- WHEN protect 轮询任务遇到
real_name_status = 0的卡 - THEN 任务直接跳过，不检查保护期，不调网关
Scenario: 独立卡（未绑定设备）跳过
- WHEN protect 轮询任务遇到
is_standalone = true的卡 - THEN 任务直接跳过，不查询设备保护期
Scenario: PollingConfig 未配置 ProtectCheckInterval，卡不入 protect 队列
- WHEN 调度器初始化时，卡匹配到的 PollingConfig 的
protect_check_interval为 NULL 或 0 - THEN 该卡不被加入
polling:queue:protect，protect 任务不对该卡执行