junhong_cmp_fiber/openspec/changes/archive/2026-02-10-polling-system-implementation/proposal.md

Why

当前系统管理百万级别（1000万+）的 IoT 卡资产，需要定期检查卡的实名状态、流量使用情况和套餐流量消耗，以实现自动化监控、及时停机和状态同步。现有系统缺乏轮询机制，无法高效处理大规模卡的定期检查需求，导致需要人工干预或依赖外部触发，运营成本高且响应不及时。本变更实现基于 Redis Sorted Set 的高性能轮询调度系统，支持灵活配置、动态并发控制、监控告警和数据清理，满足百万级卡量的自动化管理需求。

What Changes

• 新增轮询调度系统：基于 Redis Sorted Set 实现时间驱动的轮询队列，支持百万级卡的高效调度
• 新增三种轮询处理器：
  • 实名检查轮询：定期调用 Gateway API 查询卡的实名状态，支持梯度配置（未实名卡高频、已实名卡低频）
  • 卡流量检查轮询：定期查询卡的流量使用情况，处理跨月流量计算（自然月重置），记录流量历史
  • 套餐流量检查轮询：检查套餐使用情况（单卡套餐、设备级套餐），超额自动停机
• 新增轮询配置管理：支持按卡状态、卡类型、运营商配置不同的轮询策略和间隔时间
• 新增并发控制机制：基于 Redis 实现动态并发数调整，支持通过管理接口实时修改，无需重启 Worker
• 新增监控面板接口：实时查看轮询队列状态、任务执行统计、成功率、平均耗时等监控指标
• 新增告警系统：支持配置告警规则（队列积压、成功率、耗时），多种通知渠道（邮件、短信、Webhook）
• 新增数据清理机制：定期清理流量历史记录、操作日志等数据，支持配置保留天数
• 新增手动触发接口：支持手动触发单张或批量卡的立即检查，最高优先级处理
• 修改 IotCard 模型：增加月流量追踪字段（current_month_usage_mb, current_month_start_date, last_month_total_mb），用于处理跨月流量计算
• 修改 Worker 进程：集成轮询调度器，支持渐进式初始化（10秒启动，后台异步加载卡数据）
• 新增管理接口：提供轮询配置 CRUD、并发控制调整、手动触发、监控面板、告警管理等完整的管理接口

Capabilities

New Capabilities

• polling-configuration: 轮询配置管理 - 支持创建、查询、更新、删除轮询配置，配置卡匹配条件（卡状态、卡类型、运营商）和检查间隔（实名、流量、套餐），支持优先级和启用/禁用控制
• polling-scheduler: 轮询调度器 - 核心调度引擎，负责读取配置、匹配卡、计算下次检查时间、生成 Asynq 任务、管理 Redis 队列，支持渐进式初始化和懒加载机制
• polling-realname-check: 实名检查轮询 - 定期调用 Gateway API 查询卡实名状态，更新数据库和 Redis 缓存，支持状态变更时自动切换轮询配置，处理行业卡无需实名的特殊逻辑
• polling-carddata-check: 卡流量检查轮询 - 定期查询卡流量使用情况，处理跨月流量计算（自然月重置），记录流量历史到 data_usage_records 表，触发关联套餐的流量检查
• polling-package-check: 套餐流量检查轮询 - 检查套餐流量使用（单卡套餐直接读取、设备级套餐汇总所有卡），判断是否超额（基于虚流量），超额自动调用 Gateway 停机并更新卡状态
• polling-concurrency-control: 并发控制管理 - 基于 Redis 信号量实现动态并发数控制，支持分类型配置（实名、流量、套餐、停复机），提供管理接口实时调整并发数，无需重启 Worker
• polling-monitoring: 监控面板 - 提供轮询系统监控接口，查询队列状态（队列长度、逾期任务数、下个待处理任务）、任务执行统计（成功率、平均耗时、总执行次数）、实时并发数等监控指标
• polling-alert: 告警系统 - 支持配置告警规则（队列积压、成功率、平均耗时、正在处理任务数），支持多种告警级别（info/warning/error/critical）和通知渠道（邮件、短信、Webhook），定期检查规则并发送告警通知
• data-cleanup: 数据清理 - 定期清理流量历史记录（data_usage_records）、操作日志等数据，支持配置保留天数，使用定时任务每日凌晨执行清理
• polling-manual-trigger: 手动触发 - 提供手动触发接口，支持单张或批量卡的立即检查（实名、流量、套餐），使用独立的高优先级队列，确保立即处理

Modified Capabilities

• iot-card: IoT 卡管理 - 增加月流量追踪字段（current_month_usage_mb：本月已用流量，current_month_start_date：本月开始日期，last_month_total_mb：上月结束时总流量），用于处理 Gateway 返回的自然月流量总量并计算增量，支持跨月流量计算

Impact

数据模型变更

新增表：

• tb_polling_config：轮询配置表，存储轮询策略（卡匹配条件、检查间隔、优先级）
• tb_polling_concurrency_config：并发控制配置表，存储各类型任务的最大并发数
• tb_polling_alert_rule：告警规则表，存储告警配置（指标类型、阈值、通知渠道）
• tb_data_cleanup_config：数据清理配置表，存储各表的保留天数

修改表：

• tb_iot_card：增加字段 current_month_usage_mb、current_month_start_date、last_month_total_mb

Redis 数据结构

• 轮询队列（Sorted Set）：
  • polling:queue:realname：实名检查队列
  • polling:queue:carddata：卡流量检查队列
  • polling:queue:package：套餐流量检查队列
• 卡信息缓存（Hash）：polling:card:{card_id}，缓存卡的基本信息和轮询状态
• 配置缓存（String）：polling:configs，缓存所有轮询配置（JSON 格式）
• 配置匹配索引（Set）：polling:config:cards:{config_id}，记录匹配该配置的所有卡 ID
• 并发控制（String）：polling:concurrency:config:{type} 和 polling:concurrency:current:{type}
• 手动触发队列（List）：polling:manual:{type}，高优先级手动触发队列
• 监控统计（Hash）：polling:stats:{type}，存储监控指标

系统集成

• Worker 进程：集成轮询调度器 Goroutine，启动时快速初始化（10秒），后台异步加载卡数据（20-30分钟）
• Asynq 任务队列：新增任务类型 iot:realname:check、iot:carddata:check、iot:package:check，新增队列 iot_polling_realname、iot_polling_carddata、iot_polling_package
• Gateway 集成：调用已有的 Gateway HTTP 接口（QueryRealnameStatus、QueryFlow、StopCard、StartCard）

API 接口

新增管理接口（/api/admin/polling-*）：

• 轮询配置管理：CRUD、启用/禁用
• 并发控制管理：查询、更新并发数
• 手动触发：单卡/批量立即检查
• 监控面板：总览统计、队列状态、任务详情
• 告警管理：CRUD 告警规则

性能影响

• 内存占用：Redis 增加约 3-5 GB 内存（1000万卡 × 200字节缓存 + Sorted Set 队列）
• 数据库负载：渐进式初始化平缓负载（每秒10万行 + 1秒休息），运行时查询负载分散到轮询周期
• 网络带宽：Gateway API 调用频率可控（通过并发数和轮询间隔配置）
• Worker 进程：新增 1 个调度器 Goroutine，Asynq Worker 并发数可配置

依赖项

• 已有依赖：Gateway Client（internal/gateway）、Asynq（pkg/queue）、Redis、PostgreSQL
• 无新增外部依赖

测试影响

• 单元测试：轮询配置匹配逻辑、跨月流量计算逻辑、并发控制逻辑
• 集成测试：轮询处理器端到端测试（含 Gateway Mock）、配置变更影响测试、手动触发测试
• 性能测试：百万级卡初始化性能测试、Redis 队列性能测试、并发控制压力测试

运维影响

• 部署要求：Worker 进程需要访问 Gateway API（网络连通性）
• 配置管理：新增轮询配置、并发控制配置、告警规则配置（通过管理接口或数据库初始化）
• 监控告警：需要配置告警通知渠道（邮件、短信、Webhook）
• 数据备份：轮询配置表、告警规则表需要备份

向后兼容性

• ✅ 完全向后兼容，不影响现有 API 和业务逻辑
• ✅ 新增字段有默认值，不影响已有数据
• ✅ 轮询系统可独立启用/禁用（通过配置）