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

Context

轮询系统采用分片 Redis Sorted Set + Asynq 任务队列的架构，支持 4 种轮询类型（realname / carddata / package / protect）。每种类型对应一个 Asynq handler，所有 handler 通过 PollingBase 共享并发控制、缓存和重入队逻辑。

Gateway 已提供 QueryCardStatus 接口（返回 CardStatus: "准备" | "正常" | "停机"），IotCard model 已有 NetworkStatus int（0=停机，1=开机），但轮询系统从未主动调用该接口同步状态。

Goals / Non-Goals

Goals:

• 新增第 5 种轮询类型 polling:card_status，与现有 4 种类型完全对等集成
• PollingBase 新增 verboseLog bool 字段，所有 handler 在成功查询到上游数据后可选输出详细日志
• 保持向后兼容：现有轮询配置不受影响，card_status_check_interval 为 NULL 时该类型不参与轮询

Non-Goals:

• 不修改停复机决策逻辑（EvaluateAndAct 已处理）
• 不新增 HTTP API（纯后台轮询任务）
• 不对现有 4 种 handler 做任何功能性改动，只追加 verbose log 调用

Decisions

决策 1：Gateway 状态映射规则

• "准备" → NetworkStatusOnline (1)：卡已就绪，视为开机
• "正常" → NetworkStatusOnline (1)：正常使用
• "停机" → NetworkStatusOffline (0)：停机
• 理由：与现有 realname handler 的布尔映射风格一致，映射逻辑内联在 handler 内，不引入额外函数

决策 2：状态变更后触发 EvaluateAndAct

• 上游报告状态变化时，先更新 DB + 缓存，再调用 stopResumeSvc.EvaluateAndAct(freshCard)
• 理由：与 realname/carddata handler 行为完全一致，停复机决策集中在 EvaluateAndAct 中
• 替代方案：仅写 DB 不触发评估 —— 拒绝，因为状态变化后不及时评估可能导致卡停复机延迟

决策 3：verboseLog 通过配置文件控制

• 在 pkg/config/config.go 新增 PollingConfig.VerboseLog bool，NewPollingBase 接受该参数
• verboseLog 开启时，每次成功从 Gateway 获取数据后以 Info 级别输出日志
• 理由：配置文件方式符合项目 Viper 规范，比 Redis key 实现简单，重启代价可接受（轮询系统重启本身就有初始化流程）
• 替代方案：Redis key 动态开关 —— 额外的 Redis 查询开销，且 key 管理增加运维复杂度

决策 4：allTaskTypes 驱动初始化和出队

• queue_manager.go 中的 allTaskTypes slice 控制：初始化时写入哪些队列、RemoveFromAllQueues 清理哪些队列、Scheduler 出队哪些类型
• 新类型追加到该 slice 即可自动接入所有相关流程，无需修改调度器核心逻辑

决策 5：数据库迁移

• tb_polling_config 新增 card_status_check_interval INT NULL，NULL 表示不启用
• tb_iot_card 新增 last_card_status_check_at TIMESTAMPTZ NULL，与其他 last_*_check_at 字段保持一致
• 两列均 DEFAULT NULL，完全向后兼容，无需数据迁移

Risks / Trade-offs

• [风险] card_status 轮询调用量增加约 25%（原 4 种 → 5 种） → 缓解：card_status_check_interval 可配置，初期设置较长间隔（如 300 秒），观察 Gateway 负载后调整
• [风险] verbose_log 开启后日志量大幅增加 → 缓解：默认关闭（false），生产环境仅在排查问题时临时开启；日志文件已配置 Lumberjack 轮转
• [权衡] 状态以上游为准 → 若上游短暂故障返回异常状态（如误报"停机"），handler 查询失败时会 warn 并重新入队，不更新状态；只有成功响应才触发写 DB

Migration Plan

1. 执行数据库迁移（make migrate-up）
2. 更新 Worker 二进制并重启（无需 API 服务重启）
3. 在轮询配置后台为需要卡状态轮询的配置项设置 card_status_check_interval 值
4. 初始化器将在 Worker 启动时自动将全量卡写入新的 polling:card_status 队列
5. 如需回滚：将 card_status_check_interval 设置为 NULL 即可停止该类型轮询，无需重启

Open Questions

无。