junhong_cmp_fiber/openspec/changes/add-polling-card-status-with-verbose-log/proposal.md

Why

轮询系统目前缺少对卡开停机状态（NetworkStatus）的主动轮询：已有实名状态、流量、套餐、保护期四类轮询，但从未通过 polling:card_status 任务主动向 Gateway 查询卡的实时开停机状态。此外，所有轮询 handler 在成功查询上游数据后均无日志输出，测试和线上排查时无法判断轮询是否正常运转。

What Changes

• 新增 polling:card_status 轮询任务类型：定期调用 Gateway QueryCardStatus 接口，将返回的卡状态（准备/正常/停机）同步到 tb_iot_card.network_status 字段，状态发生变化时触发停复机评估
• 新增 polling.verbose_log 配置开关：开启后，所有轮询 handler 在成功获取上游数据时以 Info 级别输出详细日志（ICCID、返回值、是否发生变化），关闭时保持现有行为（仅记录变更和错误）
• 新增 tb_polling_config.card_status_check_interval 列：配置卡状态检查间隔（秒），NULL 表示不启用该轮询类型
• 新增 tb_iot_card.last_card_status_check_at 列：记录最后一次卡状态检查时间，与其他 last_*_check_at 字段保持一致

Capabilities

New Capabilities

• polling-card-status-task: 卡开停机状态轮询——新的任务类型常量、handler 实现、队列注册、调度器集成、生命周期管理、初始化器支持

Modified Capabilities

• polling-task-handlers: 在所有现有 handler（realname、carddata、package、protect）的成功查询路径上添加 verbose log 支持；PollingBase 新增 verboseLog bool 字段

Impact

• 新文件: internal/task/polling_cardstatus_handler.go
• 修改文件:
  • pkg/constants/constants.go — 新增任务类型常量
  • pkg/config/config.go — 新增 PollingConfig 结构体（含 VerboseLog）
  • pkg/config/defaults/config.yaml — 新增 polling.verbose_log 默认值
  • internal/model/polling.go — PollingConfig 新增 CardStatusCheckInterval
  • internal/model/iot_card.go — 新增 LastCardStatusCheckAt 字段
  • internal/task/polling_base.go — 新增 verboseLog bool 字段
  • internal/task/polling_realname_handler.go — 添加 verbose log
  • internal/task/polling_carddata_handler.go — 添加 verbose log
  • internal/task/polling_package_handler.go — 添加 verbose log
  • internal/task/polling_protect_handler.go — 添加 verbose log
  • internal/task/polling_utils.go — getIntervalByTaskType 新增 case
  • internal/polling/queue_manager.go — allTaskTypes 追加新类型
  • internal/polling/lifecycle_service.go — getEnabledTaskTypes + calcInitialDelay 新增 case
  • internal/polling/initializer.go — 初始化时加入 card_status 队列
  • pkg/queue/handler.go — 注册新 handler
  • cmd/worker/main.go — NewPollingBase 传入 verboseLog 参数
• 数据库迁移: tb_polling_config 加列 + tb_iot_card 加列
• 无 API 变更，无破坏性改动