# 轮询系统

## 概述

轮询系统是 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)