44 lines
3.0 KiB
Markdown
44 lines
3.0 KiB
Markdown
## 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 变更**，无破坏性改动
|