提案

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

@@ -0,0 +1,43 @@
+## 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 变更**，无破坏性改动