feat: 实现 IoT 卡轮询系统（支持千万级卡规模）

实现功能： - 实名状态检查轮询（可配置间隔） - 卡流量检查轮询（支持跨月流量追踪） - 套餐检查与超额自动停机 - 分布式并发控制（Redis 信号量） - 手动触发轮询（单卡/批量/条件筛选） - 数据清理配置与执行 - 告警规则与历史记录 - 实时监控统计（队列/性能/并发）性能优化： - Redis 缓存卡信息，减少 DB 查询 - Pipeline 批量写入 Redis - 异步流量记录写入 - 渐进式初始化（10万卡/批）压测工具（scripts/benchmark/）： - Mock Gateway 模拟上游服务 - 测试卡生成器 - 配置初始化脚本 - 实时监控脚本 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-05 17:32:44 +08:00
parent b11edde720
commit 931e140e8e
104 changed files with 16883 additions and 87 deletions
--- a/docs/polling-system/README.md
+++ b/docs/polling-system/README.md
@@ -0,0 +1,196 @@
+# 轮询系统
+
+## 概述
+
+轮询系统是 IoT 卡管理平台的核心模块，负责定期检查卡的实名状态、流量使用情况和套餐流量余额。系统采用分布式架构，支持高并发处理和动态配置。
+
+## 核心功能
+
+### 1. 实名检查轮询（Realname Check）
+
+- 定期查询卡的实名认证状态
+- 自动跳过行业卡（无需实名）
+- 状态变化时重新匹配配置
+
+### 2. 流量检查轮询（Carddata Check）
+
+- 定期查询卡的流量使用情况
+- 支持跨月流量自动重置
+- 记录流量使用历史
+
+### 3. 套餐检查轮询（Package Check）
+
+- 监控套餐流量使用率
+- 超额自动停机（>100%）
+- 临近超额预警（>=95%）
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Worker 进程                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
+│   │   Scheduler  │     │ AlertChecker │     │ CleanupTask  │    │
+│   │   调度器     │     │  告警检查器  │     │  清理任务    │    │
+│   └──────┬───────┘     └──────────────┘     └──────────────┘    │
+│          │                                                       │
+│          ▼                                                       │
+│   ┌──────────────────────────────────────────────────────────┐  │
+│   │                    Asynq 任务队列                         │  │
+│   └──────────────────────────────────────────────────────────┘  │
+│          │                                                       │
+│          ▼                                                       │
+│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
+│   │  Realname    │     │  Carddata    │     │  Package     │    │
+│   │  Handler     │     │  Handler     │     │  Handler     │    │
+│   └──────────────┘     └──────────────┘     └──────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+            ┌─────────────────────────────────────┐
+            │          Redis                       │
+            │  - 轮询队列 (Sorted Set)             │
+            │  - 手动触发队列 (List)               │
+            │  - 卡信息缓存 (Hash)                 │
+            │  - 配置缓存                          │
+            │  - 并发信号量                        │
+            │  - 监控统计                          │
+            └─────────────────────────────────────┘
+                              │
+                              ▼
+            ┌─────────────────────────────────────┐
+            │         PostgreSQL                   │
+            │  - tb_polling_config                 │
+            │  - tb_polling_concurrency_config     │
+            │  - tb_polling_alert_rule             │
+            │  - tb_polling_alert_history          │
+            │  - tb_data_cleanup_config            │
+            │  - tb_data_cleanup_log               │
+            │  - tb_polling_manual_trigger_log     │
+            │  - tb_data_usage_record              │
+            └─────────────────────────────────────┘
+```
+
+## 快速启动
+
+### 1. 数据库迁移
+
+```bash
+make migrate-up
+```
+
+### 2. 初始化配置
+
+```bash
+psql $DATABASE_URL -f scripts/init_polling_config.sql
+```
+
+### 3. 启动 Worker
+
+```bash
+go run cmd/worker/main.go
+```
+
+## 配置说明
+
+### 轮询配置（tb_polling_config）
+
+| 字段 | 说明 | 默认值 |
+|------|------|--------|
+| name | 配置名称 | - |
+| priority | 优先级（数字越大越优先） | 0 |
+| carrier_id | 运营商 ID（可选） | - |
+| status | 卡状态条件（可选） | - |
+| card_category | 卡类别条件（可选） | - |
+| realname_check_interval | 实名检查间隔（秒） | 3600 |
+| carddata_check_interval | 流量检查间隔（秒） | 7200 |
+| package_check_interval | 套餐检查间隔（秒） | 14400 |
+| is_enabled | 是否启用 | true |
+
+### 并发控制配置（tb_polling_concurrency_config）
+
+| 任务类型 | 默认并发数 | 说明 |
+|----------|-----------|------|
+| realname | 50 | 实名检查并发数 |
+| carddata | 100 | 流量检查并发数 |
+| package | 30 | 套餐检查并发数 |
+
+## API 接口
+
+### 轮询配置管理
+
+- `POST /api/admin/polling-configs` - 创建配置
+- `GET /api/admin/polling-configs` - 配置列表
+- `GET /api/admin/polling-configs/:id` - 配置详情
+- `PUT /api/admin/polling-configs/:id` - 更新配置
+- `DELETE /api/admin/polling-configs/:id` - 删除配置
+
+### 并发控制管理
+
+- `GET /api/admin/polling-concurrency` - 获取并发配置
+- `PUT /api/admin/polling-concurrency/:type` - 更新并发数
+- `POST /api/admin/polling-concurrency/reset` - 重置信号量
+
+### 监控面板
+
+- `GET /api/admin/polling-stats` - 总览统计
+- `GET /api/admin/polling-stats/queues` - 队列状态
+- `GET /api/admin/polling-stats/tasks` - 任务统计
+- `GET /api/admin/polling-stats/init-progress` - 初始化进度
+
+### 告警管理
+
+- `POST /api/admin/polling-alert-rules` - 创建告警规则
+- `GET /api/admin/polling-alert-rules` - 规则列表
+- `PUT /api/admin/polling-alert-rules/:id` - 更新规则
+- `DELETE /api/admin/polling-alert-rules/:id` - 删除规则
+- `GET /api/admin/polling-alert-history` - 告警历史
+
+### 数据清理
+
+- `POST /api/admin/data-cleanup-configs` - 创建清理配置
+- `GET /api/admin/data-cleanup-configs` - 配置列表
+- `PUT /api/admin/data-cleanup-configs/:id` - 更新配置
+- `DELETE /api/admin/data-cleanup-configs/:id` - 删除配置
+- `POST /api/admin/data-cleanup/trigger` - 手动触发清理
+- `GET /api/admin/data-cleanup/preview` - 清理预览
+- `GET /api/admin/data-cleanup/progress` - 清理进度
+
+### 手动触发
+
+- `POST /api/admin/polling-manual-trigger/single` - 单卡触发
+- `POST /api/admin/polling-manual-trigger/batch` - 批量触发
+- `POST /api/admin/polling-manual-trigger/by-condition` - 条件触发
+- `GET /api/admin/polling-manual-trigger/status` - 触发状态
+- `GET /api/admin/polling-manual-trigger/history` - 触发历史
+- `POST /api/admin/polling-manual-trigger/cancel` - 取消触发
+
+## Redis Key 说明
+
+| Key 模式 | 类型 | 说明 |
+|----------|------|------|
+| polling:queue:realname | Sorted Set | 实名检查队列 |
+| polling:queue:carddata | Sorted Set | 流量检查队列 |
+| polling:queue:package | Sorted Set | 套餐检查队列 |
+| polling:manual:{type} | List | 手动触发队列 |
+| polling:card:{card_id} | Hash | 卡信息缓存 |
+| polling:configs | Hash | 配置缓存 |
+| polling:concurrency:config:{type} | String | 并发配置 |
+| polling:concurrency:current:{type} | String | 当前并发数 |
+| polling:stats:{type} | Hash | 监控统计 |
+| polling:init:progress | Hash | 初始化进度 |
+
+## 性能指标
+
+- Worker 启动时间：< 10 秒
+- 渐进式初始化：每批 10 万张卡，间隔 1 秒
+- API 响应时间：P95 < 200ms
+- 数据库查询：< 50ms
+
+## 相关文档
+
+- [部署文档](deployment.md)
+- [运维文档](operations.md)