chore: 归档轮询系统实现变更 (polling-system-implementation)

已完成千万级卡规模轮询系统的完整实现和集成测试验证，将变更归档到 openspec/changes/archive/2026-02-10-polling-system-implementation/ 主要成果： - 三大轮询任务：实名检查、卡流量检查、套餐流量检查 - 快速启动（<10秒）和渐进式初始化 - 完整运营工具：配置管理、并发控制、监控面板、告警系统、数据清理、手动触发 - 任务完成度：215/216（99.5%） - 所有 24 个新增接口已生成 OpenAPI 文档 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-10 10:28:47 +08:00
parent 931e140e8e
commit 804145332b
15 changed files with 0 additions and 0 deletions
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/data-cleanup/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/data-cleanup/spec.md
@@ -0,0 +1,315 @@
+## ADDED Requirements
+
+### Requirement: 清理配置管理
+
+系统 SHALL 允许管理员配置各表的数据保留天数。
+
+#### Scenario: 创建清理配置
+
+- **WHEN** 管理员创建清理配置，指定表名为 data_usage_records，保留天数为 90 天
+- **THEN** 系统创建清理配置并返回配置ID
+
+#### Scenario: 配置多表清理策略
+
+- **WHEN** 管理员为不同表配置不同保留天数（data_usage_records 90天、operation_logs 180天、polling_alert_history 30天）
+- **THEN** 系统保存各表的清理配置
+
+#### Scenario: 表名重复
+
+- **WHEN** 管理员创建清理配置，表名与已有配置重复
+- **THEN** 系统返回错误，提示该表已有清理配置
+
+#### Scenario: 保留天数无效
+
+- **WHEN** 管理员创建清理配置，保留天数小于 1 或大于 3650（10年）
+- **THEN** 系统返回错误，提示保留天数无效
+
+### Requirement: 清理配置查询
+
+系统 SHALL 提供接口查询清理配置列表和详情。
+
+#### Scenario: 查询所有清理配置
+
+- **WHEN** 管理员请求查询清理配置列表
+- **THEN** 系统返回所有配置，包含配置ID、表名、保留天数、启用状态、最后清理时间
+
+#### Scenario: 查询启用的配置
+
+- **WHEN** 管理员请求查询启用的清理配置
+- **THEN** 系统只返回状态为启用的配置
+
+#### Scenario: 查询单个配置详情
+
+- **WHEN** 管理员请求查询配置ID为 1 的详情
+- **THEN** 系统返回配置的完整信息，包含历史清理记录
+
+#### Scenario: 配置不存在
+
+- **WHEN** 管理员请求查询不存在的配置ID
+- **THEN** 系统返回错误，提示配置不存在
+
+### Requirement: 清理配置更新
+
+系统 SHALL 允许管理员更新清理配置。
+
+#### Scenario: 更新保留天数
+
+- **WHEN** 管理员更新配置，将保留天数从 90 天修改为 180 天
+- **THEN** 系统更新配置，下次清理使用新保留天数
+
+#### Scenario: 更新不存在的配置
+
+- **WHEN** 管理员尝试更新不存在的配置ID
+- **THEN** 系统返回错误，提示配置不存在
+
+### Requirement: 清理配置删除
+
+系统 SHALL 允许管理员删除清理配置（软删除）。
+
+#### Scenario: 删除配置
+
+- **WHEN** 管理员删除清理配置
+- **THEN** 系统软删除配置，停止清理该表
+
+#### Scenario: 删除不存在的配置
+
+- **WHEN** 管理员尝试删除不存在的配置ID
+- **THEN** 系统返回错误，提示配置不存在
+
+### Requirement: 启用/禁用清理配置
+
+系统 SHALL 提供接口快捷启用或禁用清理配置。
+
+#### Scenario: 禁用配置
+
+- **WHEN** 管理员禁用配置ID为 1 的配置
+- **THEN** 系统更新配置状态为禁用，停止清理该表
+
+#### Scenario: 启用配置
+
+- **WHEN** 管理员启用配置ID为 1 的配置
+- **THEN** 系统更新配置状态为启用，恢复清理该表
+
+### Requirement: 定时清理任务
+
+系统 SHALL 每日凌晨 2 点执行数据清理任务。
+
+#### Scenario: 定时触发清理
+
+- **WHEN** 每日凌晨 2 点
+- **THEN** 系统自动触发清理任务（使用 Cron 定时任务）
+
+#### Scenario: 遍历所有启用配置
+
+- **WHEN** 清理任务执行
+- **THEN** 系统从数据库读取所有启用的清理配置，逐个执行清理
+
+#### Scenario: 跳过禁用配置
+
+- **WHEN** 清理到某配置状态为禁用
+- **THEN** 系统跳过该配置，继续清理下一个
+
+### Requirement: 流量历史记录清理
+
+系统 SHALL 清理 data_usage_records 表的过期数据。
+
+#### Scenario: 计算清理截止时间
+
+- **WHEN** 清理配置保留天数为 90 天
+- **THEN** 系统计算截止时间为 NOW() - 90天
+
+#### Scenario: 删除过期记录
+
+- **WHEN** 执行清理，截止时间为 2024-01-01
+- **THEN** 系统执行 `DELETE FROM data_usage_records WHERE recorded_at < '2024-01-01'`
+
+#### Scenario: 分批删除
+
+- **WHEN** 过期记录数量巨大（如 1000 万条）
+- **THEN** 系统分批删除（每批 10 万条），避免长时间锁表，每批删除后 sleep 1秒
+
+#### Scenario: 记录清理数量
+
+- **WHEN** 清理完成
+- **THEN** 系统记录本次清理删除的记录数量
+
+### Requirement: 操作日志清理
+
+系统 SHALL 清理 operation_logs 表的过期数据。
+
+#### Scenario: 清理过期操作日志
+
+- **WHEN** 执行清理，保留天数为 180 天
+- **THEN** 系统删除 created_at < NOW() - 180天 的操作日志
+
+#### Scenario: 保留关键操作日志
+
+- **WHEN** 清理操作日志，某些关键操作（如删除账号、权限变更）需要永久保留
+- **THEN** 系统在删除条件中排除这些操作类型
+
+### Requirement: 告警历史清理
+
+系统 SHALL 清理 polling_alert_history 表的过期数据。
+
+#### Scenario: 清理过期告警历史
+
+- **WHEN** 执行清理，保留天数为 30 天
+- **THEN** 系统删除 triggered_at < NOW() - 30天 的告警历史
+
+#### Scenario: 保留统计数据
+
+- **WHEN** 清理告警历史后
+- **THEN** 系统保留月度/年度统计数据（聚合表）
+
+### Requirement: 手动触发清理
+
+系统 SHALL 支持管理员手动触发清理任务。
+
+#### Scenario: 手动清理单表
+
+- **WHEN** 管理员请求手动清理 data_usage_records 表
+- **THEN** 系统立即执行该表的清理任务，使用当前配置的保留天数
+
+#### Scenario: 手动清理所有表
+
+- **WHEN** 管理员请求手动清理所有表
+- **THEN** 系统遍历所有启用的清理配置，逐个执行清理
+
+#### Scenario: 手动清理异步执行
+
+- **WHEN** 管理员触发手动清理
+- **THEN** 系统返回任务ID，清理任务异步执行（Asynq 队列），管理员可查询进度
+
+#### Scenario: 手动清理指定时间范围
+
+- **WHEN** 管理员请求清理 2023-01-01 到 2023-12-31 的数据
+- **THEN** 系统使用指定时间范围执行清理，忽略配置的保留天数
+
+### Requirement: 清理任务监控
+
+系统 SHALL 记录清理任务的执行情况。
+
+#### Scenario: 记录清理开始
+
+- **WHEN** 清理任务开始执行
+- **THEN** 系统插入清理记录到 tb_data_cleanup_log 表，包含配置ID、表名、开始时间
+
+#### Scenario: 记录清理完成
+
+- **WHEN** 清理任务完成
+- **THEN** 系统更新清理记录，包含删除记录数、结束时间、耗时
+
+#### Scenario: 记录清理失败
+
+- **WHEN** 清理任务因错误失败
+- **THEN** 系统更新清理记录，标记状态为失败，记录错误信息
+
+#### Scenario: 记录清理跳过
+
+- **WHEN** 清理配置被禁用，跳过清理
+- **THEN** 系统记录清理记录，标记状态为跳过
+
+### Requirement: 清理进度查询
+
+系统 SHALL 提供接口查询清理任务的进度。
+
+#### Scenario: 查询正在执行的清理
+
+- **WHEN** 管理员查询清理进度，清理任务正在执行
+- **THEN** 系统返回当前清理的表名、已删除记录数、预计剩余时间
+
+#### Scenario: 查询清理历史
+
+- **WHEN** 管理员查询清理历史
+- **THEN** 系统返回最近 30 次清理记录，包含表名、删除数量、耗时、状态
+
+#### Scenario: 清理未开始
+
+- **WHEN** 管理员查询清理进度，清理任务未开始
+- **THEN** 系统返回状态为"未开始"
+
+#### Scenario: 清理已完成
+
+- **WHEN** 管理员查询清理进度，清理任务已完成
+- **THEN** 系统返回状态为"已完成"，包含总删除数量、总耗时
+
+### Requirement: 清理预览
+
+系统 SHALL 提供接口预览清理将删除的数据量，不实际执行删除。
+
+#### Scenario: 预览单表清理
+
+- **WHEN** 管理员请求预览 data_usage_records 表的清理
+- **THEN** 系统执行 `SELECT COUNT(*) FROM data_usage_records WHERE recorded_at < ?`，返回将删除的记录数
+
+#### Scenario: 预览所有表清理
+
+- **WHEN** 管理员请求预览所有表的清理
+- **THEN** 系统返回各表将删除的记录数和占比
+
+#### Scenario: 预览不同保留天数
+
+- **WHEN** 管理员请求预览使用不同保留天数（如 30、60、90 天）的清理效果
+- **THEN** 系统返回各保留天数对应的删除记录数
+
+### Requirement: 清理安全防护
+
+系统 SHALL 提供安全防护机制，避免误删重要数据。
+
+#### Scenario: 防止清理最近数据
+
+- **WHEN** 清理配置的保留天数为 7 天，少于最小保留天数（30 天）
+- **THEN** 系统拒绝执行清理，返回错误
+
+#### Scenario: 防止全表删除
+
+- **WHEN** 计算清理截止时间大于当前时间（配置错误）
+- **THEN** 系统拒绝执行清理，返回错误，提示配置异常
+
+#### Scenario: 二次确认
+
+- **WHEN** 管理员手动触发清理，预计删除数量超过 100 万
+- **THEN** 系统要求管理员二次确认
+
+#### Scenario: 备份提醒
+
+- **WHEN** 执行清理前
+- **THEN** 系统在日志中记录提醒，建议管理员确认已备份重要数据
+
+### Requirement: 清理回滚
+
+系统 SHALL 支持清理操作的回滚（如果数据已备份）。
+
+#### Scenario: 记录清理详情
+
+- **WHEN** 执行清理
+- **THEN** 系统记录被删除数据的ID范围、时间范围，便于后续恢复
+
+#### Scenario: 从备份恢复
+
+- **WHEN** 管理员发现误删数据
+- **THEN** 管理员可从数据库备份中恢复指定时间范围的数据
+
+### Requirement: 日志记录
+
+系统 SHALL 记录清理任务的详细日志。
+
+#### Scenario: 记录清理开始日志
+
+- **WHEN** 清理任务开始
+- **THEN** 系统记录 Info 日志，包含配置ID、表名、保留天数、截止时间
+
+#### Scenario: 记录清理完成日志
+
+- **WHEN** 清理任务完成
+- **THEN** 系统记录 Info 日志，包含删除记录数、耗时
+
+#### Scenario: 记录清理失败日志
+
+- **WHEN** 清理任务失败
+- **THEN** 系统记录 Error 日志，包含错误详情
+
+#### Scenario: 记录分批进度日志
+
+- **WHEN** 清理大量数据，分批执行
+- **THEN** 系统每批次记录 Debug 日志，包含已删除数量、剩余数量
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/iot-card/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/iot-card/spec.md
@@ -0,0 +1,199 @@
+## MODIFIED Requirements
+
+### Requirement: 月流量追踪字段
+
+系统 SHALL 在 IoT 卡模型中增加月流量追踪字段，用于处理跨月流量计算。
+
+#### Scenario: 新增字段定义
+
+- **WHEN** 系统需要追踪卡的月度流量使用情况
+- **THEN** 系统在 tb_iot_card 表增加以下字段：
+  - `current_month_usage_mb` (DECIMAL): 本月已用流量（MB），默认值 0
+  - `current_month_start_date` (DATE): 本月开始日期（自然月1日），默认值 NULL
+  - `last_month_total_mb` (DECIMAL): 上月结束时的总流量（MB），默认值 0
+
+#### Scenario: 字段用于跨月计算
+
+- **WHEN** Gateway 返回月总流量（自然月累计）
+- **THEN** 系统使用这 3 个字段计算本月增量流量，处理跨月重置逻辑
+
+#### Scenario: 兼容已有数据
+
+- **WHEN** 数据库迁移执行，已有卡记录
+- **THEN** 系统为已有卡初始化 current_month_usage_mb=0、current_month_start_date=NULL、last_month_total_mb=0
+
+### Requirement: 首次流量查询初始化
+
+系统 SHALL 在卡首次查询流量时初始化月流量追踪字段。
+
+#### Scenario: 首次查询初始化
+
+- **WHEN** 卡A首次查询流量，current_month_start_date 为 NULL，Gateway 返回 total_usage_mb=500
+- **THEN** 系统初始化 current_month_start_date=当前月1日（如 2024-01-01），current_month_usage_mb=500，last_month_total_mb=0
+
+#### Scenario: 非首次查询不重新初始化
+
+- **WHEN** 卡A再次查询流量，current_month_start_date 不为 NULL
+- **THEN** 系统使用已有的 current_month_start_date，不重新初始化
+
+### Requirement: 同月内流量增长
+
+系统 SHALL 在同月内正确计算流量增量。
+
+#### Scenario: 同月内流量增长
+
+- **WHEN** 卡A上次查询在本月（current_month_start_date=2024-01-01），Gateway 返回 total_usage_mb=500，数据库当前 current_month_usage_mb=400
+- **THEN** 系统计算增量 100 MB，更新 current_month_usage_mb=500
+
+#### Scenario: Gateway 返回值未变化
+
+- **WHEN** Gateway 返回 total_usage_mb=400，等于数据库当前值 current_month_usage_mb=400
+- **THEN** 系统判断无增量，不触发套餐检查
+
+#### Scenario: Gateway 返回值回退（异常）
+
+- **WHEN** Gateway 返回 total_usage_mb=300，小于数据库当前值 current_month_usage_mb=400
+- **THEN** 系统记录警告日志，但仍更新为 Gateway 值（信任 Gateway 数据源）
+
+### Requirement: 跨月流量重置
+
+系统 SHALL 在检测到跨月时正确重置月流量统计。
+
+#### Scenario: 跨月检测
+
+- **WHEN** 卡A上次查询在上月（current_month_start_date=2024-01-01），当前时间为 2024-02-05
+- **THEN** 系统检测到跨月（当前月1日 > current_month_start_date）
+
+#### Scenario: 跨月重置流程
+
+- **WHEN** 检测到跨月，当前 current_month_usage_mb=400，Gateway 返回 total_usage_mb=50
+- **THEN** 系统执行：
+  1. 保存 last_month_total_mb=400（上月结束值）
+  2. 更新 current_month_start_date=2024-02-01（新月1日）
+  3. 更新 current_month_usage_mb=50（新月流量）
+
+#### Scenario: 跨多月（异常长时间未检查）
+
+- **WHEN** 卡A上次查询在 2024-01-01，当前时间为 2024-04-05，跨越 3 个月
+- **THEN** 系统检测到跨月，重置到当前月（2024-04-01），记录警告日志（长时间未检查）
+
+### Requirement: 月流量历史记录
+
+系统 SHALL 在跨月时记录上月流量汇总到历史表。
+
+#### Scenario: 记录上月汇总
+
+- **WHEN** 检测到跨月，上月总流量为 400 MB
+- **THEN** 系统插入一条月度汇总记录到 data_usage_records 表（card_id、usage_mb=400、usage_type='monthly_summary'、recorded_at=上月最后一天）
+
+#### Scenario: 历史记录供报表使用
+
+- **WHEN** 管理员查询卡的月度流量报表
+- **THEN** 系统从 data_usage_records 表读取 usage_type='monthly_summary' 的记录
+
+### Requirement: API 响应包含月流量字段
+
+系统 SHALL 在卡详情和列表接口中返回月流量追踪字段。
+
+#### Scenario: 卡详情接口返回
+
+- **WHEN** 管理员请求查询卡详情
+- **THEN** 系统返回卡信息，包含 current_month_usage_mb、current_month_start_date、last_month_total_mb 字段
+
+#### Scenario: 卡列表接口返回
+
+- **WHEN** 管理员请求查询卡列表
+- **THEN** 系统返回卡列表，每张卡包含月流量追踪字段
+
+#### Scenario: 历史兼容
+
+- **WHEN** 客户端请求卡信息，旧版客户端不识别新字段
+- **THEN** 旧版客户端忽略新字段，不影响正常使用（向后兼容）
+
+### Requirement: 数据库迁移
+
+系统 SHALL 提供数据库迁移脚本增加月流量追踪字段。
+
+#### Scenario: 迁移脚本添加字段
+
+- **WHEN** 执行数据库迁移
+- **THEN** 系统执行 DDL：
+  ```sql
+  ALTER TABLE tb_iot_card
+  ADD COLUMN current_month_usage_mb DECIMAL(10,2) DEFAULT 0 COMMENT '本月已用流量(MB)',
+  ADD COLUMN current_month_start_date DATE DEFAULT NULL COMMENT '本月开始日期',
+  ADD COLUMN last_month_total_mb DECIMAL(10,2) DEFAULT 0 COMMENT '上月结束时总流量(MB)';
+  ```
+
+#### Scenario: 迁移回滚
+
+- **WHEN** 迁移失败需要回滚
+- **THEN** 系统执行回滚 DDL：
+  ```sql
+  ALTER TABLE tb_iot_card
+  DROP COLUMN current_month_usage_mb,
+  DROP COLUMN current_month_start_date,
+  DROP COLUMN last_month_total_mb;
+  ```
+
+#### Scenario: 迁移不影响已有数据
+
+- **WHEN** 迁移执行，表中有 1000 万条记录
+- **THEN** 系统添加字段使用默认值，不需要全表更新，迁移时间短（<5分钟）
+
+### Requirement: Redis 缓存同步
+
+系统 SHALL 在 Redis 缓存中同步月流量追踪字段。
+
+#### Scenario: 缓存包含月流量字段
+
+- **WHEN** 系统加载卡信息到 Redis 缓存（polling:card:{card_id}）
+- **THEN** 缓存包含 current_month_usage_mb、current_month_start_date、last_month_total_mb 字段
+
+#### Scenario: 更新缓存月流量字段
+
+- **WHEN** 流量检查任务更新数据库后
+- **THEN** 系统使用 HSET 同步更新 Redis 缓存的月流量字段
+
+#### Scenario: 缓存过期重新加载
+
+- **WHEN** Redis 缓存过期，重新从数据库加载
+- **THEN** 系统加载完整的卡信息，包含最新的月流量字段
+
+### Requirement: 数据一致性
+
+系统 SHALL 确保月流量追踪字段在数据库和缓存之间的一致性。
+
+#### Scenario: 更新事务保证一致性
+
+- **WHEN** 流量检查任务更新月流量字段
+- **THEN** 系统在数据库事务中更新，提交成功后再更新 Redis 缓存
+
+#### Scenario: 缓存更新失败不影响数据库
+
+- **WHEN** 数据库更新成功，但 Redis 更新失败
+- **THEN** 系统记录警告日志，数据库数据为准，下次缓存加载时恢复一致
+
+#### Scenario: 数据库更新失败回滚
+
+- **WHEN** 更新月流量字段时数据库失败
+- **THEN** 系统事务回滚，不更新 Redis 缓存，保持原有数据
+
+### Requirement: 监控和日志
+
+系统 SHALL 记录月流量追踪相关的关键操作日志。
+
+#### Scenario: 记录首次初始化日志
+
+- **WHEN** 卡首次查询流量，初始化月流量字段
+- **THEN** 系统记录 Info 日志，包含 card_id、initialized_month、initial_usage_mb
+
+#### Scenario: 记录跨月重置日志
+
+- **WHEN** 检测到跨月并重置月流量统计
+- **THEN** 系统记录 Info 日志，包含 card_id、old_month、new_month、last_month_total_mb
+
+#### Scenario: 记录异常日志
+
+- **WHEN** 检测到流量回退或跨多月未检查
+- **THEN** 系统记录 Warn 日志，包含详细上下文
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-alert/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-alert/spec.md
@@ -0,0 +1,350 @@
+## ADDED Requirements
+
+### Requirement: 告警规则配置
+
+系统 SHALL 允许管理员配置告警规则，指定监控指标、阈值、告警级别和通知渠道。
+
+#### Scenario: 创建队列积压告警规则
+
+- **WHEN** 管理员创建告警规则，指标类型为"队列积压"，队列类型为"实名检查"，阈值为 1000，告警级别为 warning
+- **THEN** 系统创建告警规则并返回规则ID
+
+#### Scenario: 创建成功率告警规则
+
+- **WHEN** 管理员创建告警规则，指标类型为"成功率"，队列类型为"流量检查"，阈值为 90%，告警级别为 error
+- **THEN** 系统创建告警规则
+
+#### Scenario: 创建平均耗时告警规则
+
+- **WHEN** 管理员创建告警规则，指标类型为"平均耗时"，队列类型为"套餐检查"，阈值为 500 毫秒，告警级别为 warning
+- **THEN** 系统创建告警规则
+
+#### Scenario: 创建正在处理任务数告警规则
+
+- **WHEN** 管理员创建告警规则，指标类型为"正在处理任务数"，任务类型为"实名检查"，阈值为 50（满载），告警级别为 info
+- **THEN** 系统创建告警规则
+
+#### Scenario: 配置多通知渠道
+
+- **WHEN** 管理员创建告警规则，通知渠道为 ["email", "webhook"]
+- **THEN** 系统保存规则，触发告警时向多个渠道发送通知
+
+#### Scenario: 规则名称重复
+
+- **WHEN** 管理员创建告警规则，规则名称与已有规则重复
+- **THEN** 系统返回错误，提示规则名称已存在
+
+#### Scenario: 阈值无效
+
+- **WHEN** 管理员创建告警规则，阈值为负数或超出合理范围
+- **THEN** 系统返回错误，提示阈值无效
+
+### Requirement: 告警规则查询
+
+系统 SHALL 提供接口查询告警规则列表和详情。
+
+#### Scenario: 查询所有告警规则
+
+- **WHEN** 管理员请求查询告警规则列表
+- **THEN** 系统返回所有规则，包含规则ID、名称、指标类型、阈值、告警级别、状态、通知渠道
+
+#### Scenario: 筛选启用的规则
+
+- **WHEN** 管理员请求查询启用的告警规则
+- **THEN** 系统只返回状态为启用的规则
+
+#### Scenario: 查询单个规则详情
+
+- **WHEN** 管理员请求查询规则ID为 1 的详情
+- **THEN** 系统返回规则的完整信息，包含历史触发次数、最后触发时间
+
+#### Scenario: 规则不存在
+
+- **WHEN** 管理员请求查询不存在的规则ID
+- **THEN** 系统返回错误，提示规则不存在
+
+### Requirement: 告警规则更新
+
+系统 SHALL 允许管理员更新告警规则。
+
+#### Scenario: 更新阈值
+
+- **WHEN** 管理员更新规则，将阈值从 1000 修改为 2000
+- **THEN** 系统更新规则，下次检查使用新阈值
+
+#### Scenario: 更新通知渠道
+
+- **WHEN** 管理员更新规则，添加短信通知渠道
+- **THEN** 系统更新规则，下次触发时向所有配置的渠道发送通知
+
+#### Scenario: 更新告警级别
+
+- **WHEN** 管理员更新规则，将告警级别从 warning 提升为 error
+- **THEN** 系统更新规则，影响告警通知的优先级和展示
+
+#### Scenario: 更新不存在的规则
+
+- **WHEN** 管理员尝试更新不存在的规则ID
+- **THEN** 系统返回错误，提示规则不存在
+
+### Requirement: 告警规则删除
+
+系统 SHALL 允许管理员删除告警规则（软删除）。
+
+#### Scenario: 删除未使用的规则
+
+- **WHEN** 管理员删除一个从未触发过的规则
+- **THEN** 系统软删除规则，标记 deleted_at 字段
+
+#### Scenario: 删除正在使用的规则
+
+- **WHEN** 管理员删除一个活跃的规则
+- **THEN** 系统软删除规则，停止检查该规则
+
+#### Scenario: 删除不存在的规则
+
+- **WHEN** 管理员尝试删除不存在的规则ID
+- **THEN** 系统返回错误，提示规则不存在
+
+### Requirement: 启用/禁用告警规则
+
+系统 SHALL 提供接口快捷启用或禁用告警规则。
+
+#### Scenario: 禁用规则
+
+- **WHEN** 管理员禁用规则ID为 1 的规则
+- **THEN** 系统更新规则状态为禁用，停止检查该规则
+
+#### Scenario: 启用规则
+
+- **WHEN** 管理员启用规则ID为 1 的规则
+- **THEN** 系统更新规则状态为启用，恢复检查该规则
+
+### Requirement: 告警检查循环
+
+系统 SHALL 每 1 分钟执行一次告警检查循环，检查所有启用的告警规则。
+
+#### Scenario: 定时触发检查
+
+- **WHEN** 告警检查器启动后
+- **THEN** 系统每 1 分钟执行一次检查循环（使用 time.Ticker）
+
+#### Scenario: 遍历所有启用规则
+
+- **WHEN** 检查循环执行
+- **THEN** 系统从数据库读取所有启用的告警规则，逐个检查
+
+#### Scenario: 跳过禁用规则
+
+- **WHEN** 检查到某规则状态为禁用
+- **THEN** 系统跳过该规则，继续检查下一个
+
+### Requirement: 队列积压检查
+
+系统 SHALL 检查队列积压情况，超过阈值时触发告警。
+
+#### Scenario: 队列积压超过阈值
+
+- **WHEN** 实名检查队列逾期任务数为 1200，规则阈值为 1000
+- **THEN** 系统触发告警，记录告警到数据库，发送通知
+
+#### Scenario: 队列积压正常
+
+- **WHEN** 实名检查队列逾期任务数为 800，规则阈值为 1000
+- **THEN** 系统不触发告警
+
+#### Scenario: 队列为空
+
+- **WHEN** 队列逾期任务数为 0
+- **THEN** 系统不触发告警
+
+### Requirement: 成功率检查
+
+系统 SHALL 检查任务执行成功率，低于阈值时触发告警。
+
+#### Scenario: 成功率低于阈值
+
+- **WHEN** 流量检查成功率为 85%，规则阈值为 90%
+- **THEN** 系统触发告警
+
+#### Scenario: 成功率正常
+
+- **WHEN** 流量检查成功率为 95%，规则阈值为 90%
+- **THEN** 系统不触发告警
+
+#### Scenario: 无数据时不告警
+
+- **WHEN** 查询成功率，Redis 中没有数据（首次启动）
+- **THEN** 系统不触发告警（避免误报）
+
+### Requirement: 平均耗时检查
+
+系统 SHALL 检查任务平均耗时，超过阈值时触发告警。
+
+#### Scenario: 平均耗时超过阈值
+
+- **WHEN** 套餐检查平均耗时为 600 毫秒，规则阈值为 500 毫秒
+- **THEN** 系统触发告警
+
+#### Scenario: 平均耗时正常
+
+- **WHEN** 套餐检查平均耗时为 400 毫秒，规则阈值为 500 毫秒
+- **THEN** 系统不触发告警
+
+### Requirement: 正在处理任务数检查
+
+系统 SHALL 检查正在处理的任务数（并发数），超过阈值时触发告警。
+
+#### Scenario: 并发数满载
+
+- **WHEN** 实名检查当前并发数为 50，最大并发数为 50，规则阈值为 50
+- **THEN** 系统触发告警，提示可能需要提高并发数
+
+#### Scenario: 并发数正常
+
+- **WHEN** 实名检查当前并发数为 30，规则阈值为 50
+- **THEN** 系统不触发告警
+
+### Requirement: 告警去重
+
+系统 SHALL 对同一规则的重复告警进行去重，避免短时间内多次发送。
+
+#### Scenario: 首次触发告警
+
+- **WHEN** 规则首次触发告警
+- **THEN** 系统记录告警到数据库，发送通知，记录最后触发时间
+
+#### Scenario: 短时间内重复触发
+
+- **WHEN** 规则在 5 分钟内再次触发，上次已发送通知
+- **THEN** 系统更新数据库记录，但不发送通知（避免轰炸）
+
+#### Scenario: 冷却期后再次触发
+
+- **WHEN** 规则在 5 分钟后再次触发
+- **THEN** 系统再次发送通知
+
+#### Scenario: 不同规则独立去重
+
+- **WHEN** 规则A和规则B同时触发
+- **THEN** 两个规则独立去重，各自发送通知
+
+### Requirement: 告警通知发送
+
+系统 SHALL 根据配置的通知渠道发送告警通知。
+
+#### Scenario: 发送邮件通知
+
+- **WHEN** 规则触发，通知渠道包含 email
+- **THEN** 系统调用邮件服务，发送告警邮件到配置的邮箱
+
+#### Scenario: 发送短信通知
+
+- **WHEN** 规则触发，通知渠道包含 sms
+- **THEN** 系统调用短信服务，发送告警短信到配置的手机号
+
+#### Scenario: 发送 Webhook 通知
+
+- **WHEN** 规则触发，通知渠道包含 webhook
+- **THEN** 系统调用配置的 Webhook URL，发送告警数据（JSON 格式）
+
+#### Scenario: 多渠道并行发送
+
+- **WHEN** 规则配置了多个通知渠道
+- **THEN** 系统并行发送通知到所有渠道（使用 Goroutine）
+
+#### Scenario: 单个渠道发送失败
+
+- **WHEN** 邮件发送失败，但短信发送成功
+- **THEN** 系统记录邮件失败日志，但告警仍视为成功（部分成功）
+
+#### Scenario: 所有渠道发送失败
+
+- **WHEN** 所有通知渠道发送失败
+- **THEN** 系统记录错误日志，告警记录标记为发送失败，等待下次重试
+
+### Requirement: 告警历史记录
+
+系统 SHALL 记录所有告警历史到数据库。
+
+#### Scenario: 记录告警触发
+
+- **WHEN** 规则触发告警
+- **THEN** 系统插入告警记录到 tb_polling_alert_history 表，包含规则ID、指标类型、当前值、阈值、告警级别、触发时间
+
+#### Scenario: 记录通知发送结果
+
+- **WHEN** 告警通知发送完成
+- **THEN** 系统更新告警记录，包含通知渠道、发送状态、发送时间
+
+#### Scenario: 记录告警恢复
+
+- **WHEN** 之前触发的告警现在恢复正常（如队列积压降低）
+- **THEN** 系统插入恢复记录，关联原告警记录
+
+#### Scenario: 历史记录查询
+
+- **WHEN** 管理员查询告警历史
+- **THEN** 系统返回历史记录，支持筛选（规则、时间范围、告警级别）
+
+### Requirement: 告警统计
+
+系统 SHALL 提供告警统计接口。
+
+#### Scenario: 查询告警次数统计
+
+- **WHEN** 管理员请求查询最近 24 小时的告警次数
+- **THEN** 系统从数据库聚合统计，返回各规则的触发次数
+
+#### Scenario: 查询告警分布
+
+- **WHEN** 管理员请求查询告警级别分布
+- **THEN** 系统返回各级别（info、warning、error、critical）的告警次数和占比
+
+#### Scenario: 查询最频繁告警规则
+
+- **WHEN** 管理员请求查询最频繁触发的规则
+- **THEN** 系统返回触发次数 TOP 10 的规则
+
+### Requirement: 告警静默
+
+系统 SHALL 支持临时静默某个告警规则。
+
+#### Scenario: 设置静默期
+
+- **WHEN** 管理员对规则ID为 1 的规则设置静默 1 小时
+- **THEN** 系统更新规则，在静默期内不检查该规则
+
+#### Scenario: 静默期结束自动恢复
+
+- **WHEN** 静默期结束
+- **THEN** 系统自动恢复检查该规则
+
+#### Scenario: 手动取消静默
+
+- **WHEN** 管理员提前取消静默
+- **THEN** 系统立即恢复检查该规则
+
+### Requirement: 日志记录
+
+系统 SHALL 记录告警检查和发送的详细日志。
+
+#### Scenario: 记录检查开始日志
+
+- **WHEN** 告警检查循环开始
+- **THEN** 系统记录 Info 日志，包含检查时间、规则数量
+
+#### Scenario: 记录触发日志
+
+- **WHEN** 规则触发告警
+- **THEN** 系统记录 Warn 日志，包含规则名称、指标类型、当前值、阈值
+
+#### Scenario: 记录通知发送日志
+
+- **WHEN** 告警通知发送
+- **THEN** 系统记录 Info 日志，包含通知渠道、发送状态
+
+#### Scenario: 记录失败日志
+
+- **WHEN** 告警检查或通知发送失败
+- **THEN** 系统记录 Error 日志，包含错误详情
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-carddata-check/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-carddata-check/spec.md
@@ -0,0 +1,196 @@
+## ADDED Requirements
+
+### Requirement: 卡流量查询
+
+系统 SHALL 调用 Gateway API 查询卡的流量使用情况，并处理跨月流量计算。
+
+#### Scenario: 查询卡流量
+
+- **WHEN** 流量检查任务执行，卡A的 ICCID 为 "89860123456789012345"
+- **THEN** 系统调用 Gateway.QueryFlow(ICCID)，获取流量响应（包含月总流量 MB）
+
+#### Scenario: Gateway 返回月总流量
+
+- **WHEN** Gateway 返回流量数据，total_usage_mb=500（本自然月累计）
+- **THEN** 系统获取到月总流量数据，准备计算增量
+
+#### Scenario: Gateway API 超时
+
+- **WHEN** 调用 Gateway API 超时（>30秒）
+- **THEN** 系统记录错误日志，任务失败，不重试，卡重新入队（按原计划下次检查）
+
+#### Scenario: Gateway API 返回错误
+
+- **WHEN** Gateway API 返回业务错误（如卡号不存在）
+- **THEN** 系统记录错误日志，不更新数据库，任务失败，卡重新入队
+
+### Requirement: 跨月流量计算
+
+系统 SHALL 正确处理跨月流量计算，识别月份切换并重置月度统计。
+
+#### Scenario: 首次查询流量（冷启动）
+
+- **WHEN** 卡A从未查询过流量，current_month_start_date 为 NULL
+- **THEN** 系统初始化 current_month_start_date=当前月1日，current_month_usage_mb=Gateway返回值，last_month_total_mb=0
+
+#### Scenario: 同月内流量增长
+
+- **WHEN** 卡A上次查询在本月（current_month_start_date=2024-01-01），Gateway 返回 total_usage_mb=500，数据库当前 current_month_usage_mb=400
+- **THEN** 系统计算增量 100 MB，更新 current_month_usage_mb=500
+
+#### Scenario: 跨月流量重置
+
+- **WHEN** 卡A上次查询在上月（current_month_start_date=2024-01-01），当前时间为 2024-02-05，Gateway 返回 total_usage_mb=50（新月重置后）
+- **THEN** 系统检测到跨月，保存 last_month_total_mb=400（上月结束值），重置 current_month_start_date=2024-02-01，current_month_usage_mb=50
+
+#### Scenario: Gateway 返回值回退（异常）
+
+- **WHEN** Gateway 返回 total_usage_mb=300，小于数据库当前值 current_month_usage_mb=400（同月内）
+- **THEN** 系统记录警告日志，怀疑数据异常，但仍更新为 Gateway 值（信任 Gateway 数据源）
+
+### Requirement: 数据库更新
+
+系统 SHALL 更新卡的流量字段到数据库。
+
+#### Scenario: 更新流量字段
+
+- **WHEN** 计算出增量流量 100 MB
+- **THEN** 系统执行 `UPDATE iot_cards SET current_month_usage_mb=500, current_month_start_date='2024-01-01', last_realname_check_at=NOW() WHERE id=?`
+
+#### Scenario: 数据库更新失败
+
+- **WHEN** 数据库更新失败（如连接断开）
+- **THEN** 系统记录错误日志，任务失败，卡重新入队
+
+### Requirement: Redis 缓存更新
+
+系统 SHALL 同步更新 Redis 缓存中的卡流量信息。
+
+#### Scenario: 更新缓存流量字段
+
+- **WHEN** 数据库更新成功
+- **THEN** 系统使用 HSET 更新 Redis 缓存（polling:card:{card_id}）的 current_month_usage_mb、current_month_start_date、last_month_total_mb 字段
+
+#### Scenario: 缓存更新失败不影响主流程
+
+- **WHEN** Redis 更新失败
+- **THEN** 系统记录警告日志，但任务仍视为成功（缓存可以通过定时同步或懒加载恢复）
+
+### Requirement: 流量历史记录
+
+系统 SHALL 记录流量变化历史到 data_usage_records 表。
+
+#### Scenario: 记录流量增量
+
+- **WHEN** 计算出增量流量 100 MB
+- **THEN** 系统插入记录到 data_usage_records 表（card_id、usage_mb=100、usage_type='data'、recorded_at=NOW()）
+
+#### Scenario: 跨月时记录上月总量
+
+- **WHEN** 检测到跨月，上月总流量为 400 MB
+- **THEN** 系统插入一条月度汇总记录（card_id、usage_mb=400、usage_type='monthly_summary'、recorded_at=上月最后一天）
+
+#### Scenario: 历史记录插入失败
+
+- **WHEN** 历史记录插入失败
+- **THEN** 系统记录警告日志，但任务仍视为成功（历史记录非关键路径）
+
+### Requirement: 触发套餐检查
+
+系统 SHALL 在流量更新后触发关联套餐的流量检查。
+
+#### Scenario: 卡有关联套餐
+
+- **WHEN** 卡A更新流量后，card_package_id 不为空
+- **THEN** 系统将该套餐加入 polling:manual:package 手动触发队列，优先检查套餐流量
+
+#### Scenario: 卡无关联套餐
+
+- **WHEN** 卡A更新流量后，card_package_id 为空
+- **THEN** 系统不触发套餐检查
+
+#### Scenario: 卡关联设备级套餐
+
+- **WHEN** 卡A属于设备D，设备D有套餐
+- **THEN** 系统将设备的套餐加入手动触发队列
+
+### Requirement: 并发控制
+
+系统 SHALL 使用 Redis 信号量控制流量检查的并发数。
+
+#### Scenario: 获取并发信号量成功
+
+- **WHEN** 流量检查任务开始执行，当前并发数为 30，配置的最大并发数为 50
+- **THEN** 系统使用 INCR 增加计数，获取信号量成功，执行任务
+
+#### Scenario: 并发已满
+
+- **WHEN** 流量检查任务开始执行，当前并发数为 50，配置的最大并发数为 50
+- **THEN** 系统 INCR 后发现超过限制，DECR 归还，任务返回 SkipRetry（不执行，等待下次调度）
+
+#### Scenario: 任务完成释放信号量
+
+- **WHEN** 流量检查任务完成（成功或失败）
+- **THEN** 系统使用 DECR 释放信号量
+
+### Requirement: 重新入队
+
+系统 SHALL 在检查完成后，将卡重新加入轮询队列。
+
+#### Scenario: 计算下次检查时间
+
+- **WHEN** 流量检查完成，当前配置的检查间隔为 1800 秒
+- **THEN** 系统计算 next_check_time = NOW() + 1800秒
+
+#### Scenario: 加回队列
+
+- **WHEN** 计算出下次检查时间
+- **THEN** 系统使用 ZADD 将卡ID和时间戳加入 polling:queue:carddata
+
+#### Scenario: 任务失败也重新入队
+
+- **WHEN** 任务因 Gateway 超时失败
+- **THEN** 系统仍然将卡重新入队（按原计划下次检查），不阻塞后续检查
+
+### Requirement: 监控统计
+
+系统 SHALL 记录流量检查的成功率和耗时。
+
+#### Scenario: 记录成功统计
+
+- **WHEN** 流量检查成功完成，耗时 234 毫秒
+- **THEN** 系统更新 Redis Hash（polling:stats:carddata），增加 success_count_1h，累加 total_duration_1h
+
+#### Scenario: 记录失败统计
+
+- **WHEN** 流量检查失败（Gateway 超时）
+- **THEN** 系统更新 Redis Hash，增加 failure_count_1h
+
+#### Scenario: 每小时重置计数器
+
+- **WHEN** 每小时整点（如 10:00:00）
+- **THEN** 系统重置计数器（success_count_1h、failure_count_1h、total_duration_1h），保持时间窗口滚动
+
+### Requirement: 日志记录
+
+系统 SHALL 记录详细的流量检查日志，便于排查问题。
+
+#### Scenario: 记录开始日志
+
+- **WHEN** 流量检查任务开始执行
+- **THEN** 系统记录 Info 日志，包含 card_id、iccid、config_id
+
+#### Scenario: 记录成功日志
+
+- **WHEN** 流量检查成功完成
+- **THEN** 系统记录 Info 日志，包含 card_id、iccid、old_usage_mb、new_usage_mb、increment_mb、duration_ms
+
+#### Scenario: 记录失败日志
+
+- **WHEN** 流量检查失败
+- **THEN** 系统记录 Error 日志，包含 card_id、iccid、error 详情
+
+#### Scenario: 记录跨月日志
+
+- **WHEN** 检测到跨月
+- **THEN** 系统记录 Info 日志，包含 card_id、old_month、new_month、last_month_total_mb
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-concurrency-control/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-concurrency-control/spec.md
@@ -0,0 +1,226 @@
+## ADDED Requirements
+
+### Requirement: 并发配置初始化
+
+系统 SHALL 在启动时从数据库加载并发配置到 Redis。
+
+#### Scenario: 首次启动加载配置
+
+- **WHEN** Worker 进程启动，Redis 中没有并发配置
+- **THEN** 系统从 tb_polling_concurrency_config 表读取所有配置，写入 Redis（polling:concurrency:config:{type}）
+
+#### Scenario: 配置已存在则跳过
+
+- **WHEN** Worker 进程启动，Redis 中已有并发配置
+- **THEN** 系统跳过初始化，使用 Redis 中的配置（避免覆盖运行时修改）
+
+#### Scenario: 数据库无配置则使用默认值
+
+- **WHEN** 数据库中没有并发配置记录
+- **THEN** 系统使用默认值（实名检查:50、流量检查:50、套餐检查:30、停复机:10），写入 Redis
+
+### Requirement: 并发信号量获取
+
+系统 SHALL 在任务执行前获取 Redis 信号量，控制并发数。
+
+#### Scenario: 获取信号量成功
+
+- **WHEN** 实名检查任务开始，当前并发数为 30，最大并发数为 50
+- **THEN** 系统执行 INCR polling:concurrency:current:realname，返回值 31，小于等于 50，获取成功
+
+#### Scenario: 并发已满拒绝执行
+
+- **WHEN** 实名检查任务开始，当前并发数为 50，最大并发数为 50
+- **THEN** 系统执行 INCR 返回值 51，大于 50，立即 DECR 归还，任务返回 SkipRetry
+
+#### Scenario: 信号量获取失败重试
+
+- **WHEN** 任务在并发已满时被拒绝
+- **THEN** 系统不重试，直接返回，等待下次调度周期（10秒后）再次尝试
+
+#### Scenario: Redis 连接失败
+
+- **WHEN** INCR 操作因 Redis 连接失败
+- **THEN** 系统记录错误日志，任务失败，不执行业务逻辑
+
+### Requirement: 并发信号量释放
+
+系统 SHALL 在任务完成后释放 Redis 信号量。
+
+#### Scenario: 任务成功完成释放
+
+- **WHEN** 实名检查任务成功完成
+- **THEN** 系统执行 DECR polling:concurrency:current:realname，释放信号量
+
+#### Scenario: 任务失败也释放
+
+- **WHEN** 实名检查任务因 Gateway 超时失败
+- **THEN** 系统在 defer 中执行 DECR，确保信号量释放
+
+#### Scenario: Panic 恢复后释放
+
+- **WHEN** 任务执行中发生 panic
+- **THEN** 系统在 recover 后执行 DECR，防止信号量泄漏
+
+#### Scenario: DECR 失败记录日志
+
+- **WHEN** DECR 操作失败
+- **THEN** 系统记录错误日志，包含 task_type、task_id，便于排查信号量计数异常
+
+### Requirement: 动态调整并发数
+
+系统 SHALL 支持通过管理接口实时调整最大并发数，无需重启 Worker。
+
+#### Scenario: 管理员提高并发数
+
+- **WHEN** 管理员调用接口，将实名检查最大并发数从 50 提高到 80
+- **THEN** 系统更新 Redis（SET polling:concurrency:config:realname 80），更新数据库配置表
+
+#### Scenario: 管理员降低并发数
+
+- **WHEN** 管理员调用接口，将流量检查最大并发数从 50 降低到 30
+- **THEN** 系统更新 Redis 和数据库，当前正在执行的任务继续，新任务受新限制
+
+#### Scenario: 调整后立即生效
+
+- **WHEN** 并发数调整完成
+- **THEN** 系统下次任务获取信号量时，使用新的最大并发数判断
+
+#### Scenario: 并发数无效值校验
+
+- **WHEN** 管理员尝试设置并发数为 0 或负数
+- **THEN** 系统返回错误，提示并发数必须大于 0
+
+#### Scenario: 并发数过大警告
+
+- **WHEN** 管理员尝试设置并发数大于 200
+- **THEN** 系统返回警告，提示过高并发可能打爆 Gateway，建议值范围 10-100
+
+### Requirement: 查询并发状态
+
+系统 SHALL 提供接口查询各类型任务的并发配置和实时并发数。
+
+#### Scenario: 查询所有类型并发状态
+
+- **WHEN** 管理员请求查询并发状态
+- **THEN** 系统返回所有类型（realname、carddata、package、stoprestart）的最大并发数和当前并发数
+
+#### Scenario: 查询单个类型并发状态
+
+- **WHEN** 管理员请求查询实名检查并发状态
+- **THEN** 系统返回 max_concurrency=50、current_concurrency=30、usage_rate=60%
+
+#### Scenario: 并发数异常检测
+
+- **WHEN** 查询并发状态，发现当前并发数大于最大并发数
+- **THEN** 系统返回警告标志，提示可能存在信号量泄漏
+
+#### Scenario: 长时间满载告警
+
+- **WHEN** 查询并发状态，某类型并发数连续 5 分钟保持满载（usage_rate=100%）
+- **THEN** 系统返回建议，提示可能需要提高并发数或优化任务性能
+
+### Requirement: 分类型并发控制
+
+系统 SHALL 为不同任务类型（实名检查、流量检查、套餐检查、停复机）独立控制并发数。
+
+#### Scenario: 实名检查独立控制
+
+- **WHEN** 实名检查任务获取信号量
+- **THEN** 系统使用 polling:concurrency:config:realname 和 polling:concurrency:current:realname
+
+#### Scenario: 流量检查独立控制
+
+- **WHEN** 流量检查任务获取信号量
+- **THEN** 系统使用 polling:concurrency:config:carddata 和 polling:concurrency:current:carddata
+
+#### Scenario: 套餐检查独立控制
+
+- **WHEN** 套餐检查任务获取信号量
+- **THEN** 系统使用 polling:concurrency:config:package 和 polling:concurrency:current:package
+
+#### Scenario: 停复机独立控制
+
+- **WHEN** 停复机任务获取信号量
+- **THEN** 系统使用 polling:concurrency:config:stoprestart 和 polling:concurrency:current:stoprestart
+
+#### Scenario: 互不影响
+
+- **WHEN** 实名检查并发满载（50/50），流量检查并发正常（30/50）
+- **THEN** 流量检查任务仍然可以正常获取信号量并执行，不受实名检查影响
+
+### Requirement: 并发配置持久化
+
+系统 SHALL 将并发配置变更持久化到数据库。
+
+#### Scenario: 更新配置同步数据库
+
+- **WHEN** 管理员调整并发数
+- **THEN** 系统先更新 Redis，再更新数据库（UPDATE tb_polling_concurrency_config SET max_concurrency=? WHERE task_type=?）
+
+#### Scenario: 数据库更新失败回滚
+
+- **WHEN** Redis 更新成功，但数据库更新失败
+- **THEN** 系统回滚 Redis 配置到原值，返回错误
+
+#### Scenario: 启动时以数据库为准
+
+- **WHEN** Worker 进程重启，Redis 和数据库配置不一致
+- **THEN** 系统以数据库配置为准，覆盖 Redis
+
+### Requirement: 并发监控统计
+
+系统 SHALL 记录并发使用情况的监控统计。
+
+#### Scenario: 记录峰值并发数
+
+- **WHEN** 每次任务获取信号量成功
+- **THEN** 系统更新 Redis Hash（polling:stats:concurrency:{type}），记录当前并发数，如果大于历史峰值则更新峰值
+
+#### Scenario: 记录并发拒绝次数
+
+- **WHEN** 任务因并发已满被拒绝
+- **THEN** 系统增加 Redis Hash 的 reject_count_1h 计数
+
+#### Scenario: 每小时重置统计
+
+- **WHEN** 每小时整点
+- **THEN** 系统重置 reject_count_1h，保留 peak_concurrency（持续统计）
+
+### Requirement: 信号量计数修复
+
+系统 SHALL 提供接口修复异常的信号量计数。
+
+#### Scenario: 手动重置计数器
+
+- **WHEN** 管理员发现并发计数异常（如泄漏导致一直为 50 无法下降）
+- **THEN** 管理员调用接口，系统将 polling:concurrency:current:{type} 重置为 0
+
+#### Scenario: 自动检测修复
+
+- **WHEN** 系统定期检查（每 5 分钟），发现当前并发数长时间不变且无任务执行
+- **THEN** 系统记录警告日志，建议管理员检查并手动修复
+
+#### Scenario: 修复操作记录日志
+
+- **WHEN** 执行信号量重置
+- **THEN** 系统记录操作日志，包含操作人、重置前值、重置后值、原因
+
+### Requirement: 日志记录
+
+系统 SHALL 记录并发控制的关键操作日志。
+
+#### Scenario: 记录并发满载日志
+
+- **WHEN** 任务因并发已满被拒绝
+- **THEN** 系统记录 Info 日志，包含 task_type、current_concurrency、max_concurrency
+
+#### Scenario: 记录配置变更日志
+
+- **WHEN** 管理员调整并发数
+- **THEN** 系统记录 Info 日志，包含 task_type、old_value、new_value、operator
+
+#### Scenario: 记录信号量异常日志
+
+- **WHEN** DECR 失败或检测到计数异常
+- **THEN** 系统记录 Error 日志，包含详细上下文
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-configuration/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-configuration/spec.md
@@ -0,0 +1,159 @@
+## ADDED Requirements
+
+### Requirement: 创建轮询配置
+
+系统 SHALL 允许管理员创建轮询配置，指定卡匹配条件（卡状态、卡类型、运营商）和检查间隔（实名检查、卡流量检查、套餐流量检查），以及优先级。
+
+#### Scenario: 创建基本轮询配置
+
+- **WHEN** 管理员提交创建轮询配置请求，包含配置名称、卡状态条件（not_real_name）、实名检查间隔（30秒）、优先级（10）
+- **THEN** 系统创建轮询配置并返回配置ID和详情
+
+#### Scenario: 创建带运营商筛选的配置
+
+- **WHEN** 管理员创建轮询配置，指定卡状态条件（not_real_name）、运营商ID（1-中国移动）、实名检查间隔（60秒）
+- **THEN** 系统创建配置，该配置只匹配中国移动的未实名卡
+
+#### Scenario: 创建带卡类型筛选的配置
+
+- **WHEN** 管理员创建轮询配置，指定卡业务类型（industry-行业卡）、卡流量检查间隔（1800秒）、禁用实名检查
+- **THEN** 系统创建配置，行业卡不参与实名检查，只参与流量检查
+
+#### Scenario: 配置名称重复
+
+- **WHEN** 管理员创建轮询配置，配置名称与已有配置重复
+- **THEN** 系统返回错误，提示配置名称已存在
+
+#### Scenario: 检查间隔无效
+
+- **WHEN** 管理员创建轮询配置，检查间隔小于 10 秒或大于 86400 秒（24小时）
+- **THEN** 系统返回错误，提示检查间隔超出有效范围（10-86400秒）
+
+### Requirement: 查询轮询配置列表
+
+系统 SHALL 提供轮询配置列表查询接口，支持分页和状态筛选。
+
+#### Scenario: 查询所有配置
+
+- **WHEN** 管理员请求查询轮询配置列表，不指定筛选条件
+- **THEN** 系统返回所有轮询配置列表，按优先级升序排序，包含配置ID、名称、卡匹配条件、检查间隔、优先级、状态
+
+#### Scenario: 查询启用的配置
+
+- **WHEN** 管理员请求查询轮询配置列表，筛选条件为状态=启用
+- **THEN** 系统只返回状态为启用的配置
+
+#### Scenario: 分页查询
+
+- **WHEN** 管理员请求查询轮询配置列表，指定分页参数（page=2, page_size=10）
+- **THEN** 系统返回第二页的配置列表，每页最多 10 条
+
+### Requirement: 查询单个轮询配置详情
+
+系统 SHALL 提供查询单个轮询配置详情的接口，包含完整的配置信息和匹配卡数量统计。
+
+#### Scenario: 查询配置详情
+
+- **WHEN** 管理员请求查询配置ID为 1 的详情
+- **THEN** 系统返回配置的完整信息，包括配置名称、描述、卡匹配条件、检查间隔、优先级、状态、创建时间、更新时间
+
+#### Scenario: 查询不存在的配置
+
+- **WHEN** 管理员请求查询不存在的配置ID
+- **THEN** 系统返回错误，提示配置不存在
+
+#### Scenario: 包含匹配卡数量
+
+- **WHEN** 管理员请求查询配置详情，请求参数包含 include_stats=true
+- **THEN** 系统返回配置信息，额外包含当前匹配该配置的卡数量
+
+### Requirement: 更新轮询配置
+
+系统 SHALL 允许管理员更新轮询配置，修改检查间隔、优先级、启用状态等参数，更新后自动影响匹配的卡。
+
+#### Scenario: 更新检查间隔
+
+- **WHEN** 管理员更新配置，将实名检查间隔从 30 秒修改为 60 秒
+- **THEN** 系统更新配置，所有匹配该配置的卡的下次实名检查时间重新计算
+
+#### Scenario: 更新优先级
+
+- **WHEN** 管理员更新配置优先级，从 10 修改为 5
+- **THEN** 系统更新配置，重新匹配所有卡（因为优先级影响匹配顺序）
+
+#### Scenario: 修改卡匹配条件
+
+- **WHEN** 管理员更新配置，将卡状态条件从 not_real_name 修改为 real_name
+- **THEN** 系统更新配置，重新匹配所有卡，原匹配该配置的卡不再匹配，原不匹配的卡可能匹配
+
+#### Scenario: 禁用某项检查
+
+- **WHEN** 管理员更新配置，禁用实名检查（real_name_check_enabled=false）
+- **THEN** 系统更新配置，所有匹配该配置的卡从实名检查队列移除
+
+#### Scenario: 更新不存在的配置
+
+- **WHEN** 管理员尝试更新不存在的配置ID
+- **THEN** 系统返回错误，提示配置不存在
+
+### Requirement: 删除轮询配置
+
+系统 SHALL 允许管理员删除轮询配置（软删除），删除后匹配该配置的卡将从轮询队列移除。
+
+#### Scenario: 删除未使用的配置
+
+- **WHEN** 管理员删除一个没有匹配卡的配置
+- **THEN** 系统软删除配置，标记 deleted_at 字段
+
+#### Scenario: 删除正在使用的配置
+
+- **WHEN** 管理员删除一个有 1000 张卡匹配的配置
+- **THEN** 系统软删除配置，所有匹配该配置的卡从轮询队列移除，卡缓存中的 matched_config_id 清空
+
+#### Scenario: 删除后卡重新匹配
+
+- **WHEN** 管理员删除配置后，卡失去匹配配置
+- **THEN** 系统自动为卡重新匹配其他可用配置（按优先级），如果没有匹配配置，卡不参与轮询
+
+#### Scenario: 删除不存在的配置
+
+- **WHEN** 管理员尝试删除不存在的配置ID
+- **THEN** 系统返回错误，提示配置不存在
+
+### Requirement: 启用/禁用轮询配置
+
+系统 SHALL 提供快捷接口启用或禁用轮询配置，禁用后匹配该配置的卡不再参与轮询。
+
+#### Scenario: 禁用配置
+
+- **WHEN** 管理员禁用配置ID为 1 的配置
+- **THEN** 系统更新配置状态为禁用（status=2），所有匹配该配置的卡从轮询队列移除
+
+#### Scenario: 启用配置
+
+- **WHEN** 管理员启用配置ID为 1 的配置
+- **THEN** 系统更新配置状态为启用（status=1），重新匹配卡并加入轮询队列
+
+#### Scenario: 禁用后卡重新匹配其他配置
+
+- **WHEN** 管理员禁用优先级为 10 的配置A，该配置有 1000 张卡匹配
+- **THEN** 系统为这 1000 张卡重新匹配其他配置（如优先级为 20 的配置B），卡使用新配置的检查间隔
+
+### Requirement: 配置匹配规则验证
+
+系统 SHALL 验证轮询配置的匹配规则，确保配置逻辑正确。
+
+#### Scenario: 实名检查不适用于行业卡
+
+- **WHEN** 管理员创建配置，卡类型为 industry（行业卡），启用实名检查
+- **THEN** 系统返回警告，提示行业卡无需实名检查，建议禁用实名检查
+
+#### Scenario: 至少启用一种检查
+
+- **WHEN** 管理员创建配置，禁用所有检查（实名、流量、套餐都为 false）
+- **THEN** 系统返回错误，提示至少启用一种检查类型
+
+#### Scenario: 优先级唯一性建议
+
+- **WHEN** 管理员创建配置，优先级与已有配置相同
+- **THEN** 系统返回警告，提示优先级重复可能导致匹配顺序不确定，建议使用唯一优先级
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-manual-trigger/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-manual-trigger/spec.md
@@ -0,0 +1,294 @@
+## ADDED Requirements
+
+### Requirement: 手动触发单卡检查
+
+系统 SHALL 允许管理员手动触发单张卡的立即检查。
+
+#### Scenario: 手动触发实名检查
+
+- **WHEN** 管理员请求手动触发卡ID为 12345 的实名检查
+- **THEN** 系统将卡ID加入 Redis List（polling:manual:realname），返回成功，提示将在 10 秒内执行
+
+#### Scenario: 手动触发流量检查
+
+- **WHEN** 管理员请求手动触发卡ID为 12345 的流量检查
+- **THEN** 系统将卡ID加入 Redis List（polling:manual:carddata），返回成功
+
+#### Scenario: 手动触发套餐检查
+
+- **WHEN** 管理员请求手动触发套餐ID为 678 的套餐检查
+- **THEN** 系统将套餐ID加入 Redis List（polling:manual:package），返回成功
+
+#### Scenario: 手动触发所有检查
+
+- **WHEN** 管理员请求手动触发卡ID为 12345 的所有检查（实名、流量、套餐）
+- **THEN** 系统将卡ID加入所有手动触发队列，返回成功
+
+#### Scenario: 卡不存在
+
+- **WHEN** 管理员请求手动触发不存在的卡ID
+- **THEN** 系统返回错误，提示卡不存在
+
+#### Scenario: 卡未启用轮询
+
+- **WHEN** 管理员请求手动触发卡ID为 12345，但该卡 enable_polling=false
+- **THEN** 系统返回警告，提示卡未启用轮询，但仍允许手动触发
+
+### Requirement: 手动触发批量卡检查
+
+系统 SHALL 允许管理员手动触发批量卡的立即检查。
+
+#### Scenario: 批量触发实名检查
+
+- **WHEN** 管理员请求批量触发 100 张卡的实名检查，提供卡ID列表
+- **THEN** 系统将所有卡ID批量加入 Redis List（使用 RPUSH），返回成功，提示将在 10 秒内执行
+
+#### Scenario: 批量触发流量检查
+
+- **WHEN** 管理员请求批量触发 50 张卡的流量检查
+- **THEN** 系统将所有卡ID批量加入手动触发队列
+
+#### Scenario: 批量数量限制
+
+- **WHEN** 管理员请求批量触发超过 1000 张卡
+- **THEN** 系统返回错误，提示批量数量超过限制（最多 1000 张）
+
+#### Scenario: 部分卡不存在
+
+- **WHEN** 管理员请求批量触发，100 张卡中有 5 张不存在
+- **THEN** 系统返回警告，列出不存在的卡ID，其余 95 张卡加入队列
+
+#### Scenario: 异步处理批量请求
+
+- **WHEN** 管理员请求批量触发 1000 张卡
+- **THEN** 系统异步处理请求（Goroutine），立即返回任务ID，管理员可查询进度
+
+### Requirement: 手动触发条件筛选
+
+系统 SHALL 支持按条件筛选卡进行批量手动触发。
+
+#### Scenario: 按卡状态筛选
+
+- **WHEN** 管理员请求触发所有未实名卡的实名检查
+- **THEN** 系统查询符合条件的卡（real_name_status=0），将卡ID批量加入队列
+
+#### Scenario: 按运营商筛选
+
+- **WHEN** 管理员请求触发所有中国移动卡的流量检查
+- **THEN** 系统查询符合条件的卡（carrier_id=1），批量触发
+
+#### Scenario: 按卡类型筛选
+
+- **WHEN** 管理员请求触发所有行业卡的流量检查
+- **THEN** 系统查询符合条件的卡（card_category='industry'），批量触发
+
+#### Scenario: 组合条件筛选
+
+- **WHEN** 管理员请求触发所有"未实名+中国移动"的卡
+- **THEN** 系统查询符合多个条件的卡，批量触发
+
+#### Scenario: 预览筛选结果
+
+- **WHEN** 管理员请求预览筛选条件将触发多少张卡
+- **THEN** 系统返回符合条件的卡数量，不实际触发
+
+#### Scenario: 筛选结果过多
+
+- **WHEN** 筛选条件匹配超过 10000 张卡
+- **THEN** 系统返回警告，建议缩小筛选范围或分批触发
+
+### Requirement: 手动触发优先级
+
+系统 SHALL 确保手动触发的任务优先于定时任务执行。
+
+#### Scenario: 调度器先处理手动队列
+
+- **WHEN** 调度循环执行，手动触发队列有 10 张卡，定时队列有 1000 张卡到期
+- **THEN** 系统先从手动触发队列取出所有卡，生成高优先级任务（ProcessIn(0)），再处理定时队列
+
+#### Scenario: 手动触发立即生成任务
+
+- **WHEN** 手动触发请求完成，卡加入手动队列
+- **THEN** 系统在下个调度周期（最多 10 秒）生成 Asynq 任务并执行
+
+#### Scenario: 清空手动队列
+
+- **WHEN** 调度器处理完手动触发队列
+- **THEN** 系统清空手动触发队列（LTRIM 或 DEL）
+
+### Requirement: 手动触发去重
+
+系统 SHALL 对手动触发进行去重，避免重复执行。
+
+#### Scenario: 同卡重复触发
+
+- **WHEN** 管理员对同一张卡连续触发两次实名检查
+- **THEN** 系统检查手动队列，如果卡ID已存在则不重复加入
+
+#### Scenario: 使用 Redis Set 去重
+
+- **WHEN** 批量触发 100 张卡，其中有 10 张重复
+- **THEN** 系统使用 Redis Set 临时存储卡ID，去重后再加入队列
+
+#### Scenario: 手动触发与定时任务去重
+
+- **WHEN** 卡A在手动队列中，同时定时队列也到期
+- **THEN** 系统优先执行手动触发，定时队列检测到卡已在执行则跳过
+
+### Requirement: 手动触发状态查询
+
+系统 SHALL 提供接口查询手动触发的状态和进度。
+
+#### Scenario: 查询手动队列长度
+
+- **WHEN** 管理员查询手动触发队列状态
+- **THEN** 系统返回各类型手动队列的长度（LLEN polling:manual:realname 等）
+
+#### Scenario: 查询批量任务进度
+
+- **WHEN** 管理员查询批量触发任务的进度
+- **THEN** 系统返回任务ID、总卡数、已处理数、进度百分比、预计完成时间
+
+#### Scenario: 查询任务详情
+
+- **WHEN** 管理员查询批量触发任务的详情
+- **THEN** 系统返回已成功的卡、已失败的卡、正在处理的卡列表
+
+#### Scenario: 任务已完成
+
+- **WHEN** 管理员查询已完成的批量触发任务
+- **THEN** 系统返回总结信息，包含成功数、失败数、总耗时
+
+### Requirement: 手动触发历史记录
+
+系统 SHALL 记录手动触发的历史。
+
+#### Scenario: 记录触发请求
+
+- **WHEN** 管理员手动触发检查
+- **THEN** 系统插入记录到 tb_polling_manual_trigger_log 表，包含操作人、卡ID列表、触发类型、请求时间
+
+#### Scenario: 记录触发结果
+
+- **WHEN** 手动触发任务完成
+- **THEN** 系统更新记录，包含成功数、失败数、完成时间
+
+#### Scenario: 查询触发历史
+
+- **WHEN** 管理员查询手动触发历史
+- **THEN** 系统返回历史记录，支持筛选（时间范围、操作人、触发类型）
+
+#### Scenario: 历史记录保留 30 天
+
+- **WHEN** 数据清理任务执行
+- **THEN** 系统清理 30 天前的手动触发历史记录
+
+### Requirement: 手动触发权限控制
+
+系统 SHALL 控制手动触发的权限。
+
+#### Scenario: 普通管理员触发自己管理的卡
+
+- **WHEN** 代理账号请求手动触发卡ID为 12345，该卡属于代理管理的店铺
+- **THEN** 系统验证权限通过，允许触发
+
+#### Scenario: 普通管理员触发其他卡
+
+- **WHEN** 代理账号请求手动触发卡ID为 99999，该卡不属于代理管理的店铺
+- **THEN** 系统返回错误，提示无权限操作该卡
+
+#### Scenario: 超级管理员触发任意卡
+
+- **WHEN** 超级管理员请求手动触发任意卡
+- **THEN** 系统允许触发，无权限限制
+
+#### Scenario: 企业账号触发企业卡
+
+- **WHEN** 企业账号请求手动触发卡ID为 12345，该卡属于企业
+- **THEN** 系统验证权限通过，允许触发
+
+### Requirement: 手动触发限流
+
+系统 SHALL 对手动触发进行限流，防止滥用。
+
+#### Scenario: 单次批量限制
+
+- **WHEN** 管理员单次批量触发超过 1000 张卡
+- **THEN** 系统拒绝请求，提示超过单次限制
+
+#### Scenario: 频率限制
+
+- **WHEN** 管理员在 1 分钟内触发超过 10 次
+- **THEN** 系统拒绝请求，提示操作过于频繁，建议稍后再试
+
+#### Scenario: 每日限制
+
+- **WHEN** 管理员当日累计触发超过 10000 张卡
+- **THEN** 系统拒绝请求，提示已达每日限制
+
+#### Scenario: 超级管理员无限制
+
+- **WHEN** 超级管理员手动触发
+- **THEN** 系统不应用限流规则
+
+### Requirement: 手动触发取消
+
+系统 SHALL 支持取消未执行的手动触发任务。
+
+#### Scenario: 取消手动队列中的卡
+
+- **WHEN** 管理员请求取消卡ID为 12345 的手动触发
+- **THEN** 系统从手动触发队列中移除该卡ID（LREM）
+
+#### Scenario: 取消批量任务
+
+- **WHEN** 管理员请求取消批量触发任务
+- **THEN** 系统停止添加新卡到队列，已加入队列的卡继续执行
+
+#### Scenario: 无法取消正在执行的任务
+
+- **WHEN** 管理员请求取消已在执行的任务
+- **THEN** 系统返回提示，无法取消正在执行的任务
+
+### Requirement: 手动触发通知
+
+系统 SHALL 在手动触发完成后通知管理员。
+
+#### Scenario: 批量触发完成通知
+
+- **WHEN** 批量触发任务完成
+- **THEN** 系统发送通知（邮件、站内消息），包含成功数、失败数、总耗时
+
+#### Scenario: 失败率高时告警
+
+- **WHEN** 批量触发任务完成，失败率超过 20%
+- **THEN** 系统发送告警通知，建议检查失败原因
+
+#### Scenario: 单卡触发不通知
+
+- **WHEN** 单张卡手动触发完成
+- **THEN** 系统不发送通知，管理员可主动查询结果
+
+### Requirement: 日志记录
+
+系统 SHALL 记录手动触发的详细日志。
+
+#### Scenario: 记录触发请求日志
+
+- **WHEN** 管理员手动触发检查
+- **THEN** 系统记录 Info 日志，包含操作人、卡ID、触发类型
+
+#### Scenario: 记录批量触发进度日志
+
+- **WHEN** 批量触发任务处理中
+- **THEN** 系统每处理 100 张卡记录一次 Debug 日志，包含进度
+
+#### Scenario: 记录触发完成日志
+
+- **WHEN** 手动触发任务完成
+- **THEN** 系统记录 Info 日志，包含成功数、失败数、耗时
+
+#### Scenario: 记录权限拒绝日志
+
+- **WHEN** 管理员因权限不足被拒绝
+- **THEN** 系统记录 Warn 日志，包含操作人、被拒绝原因
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-monitoring/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-monitoring/spec.md
@@ -0,0 +1,266 @@
+## ADDED Requirements
+
+### Requirement: 总览统计查询
+
+系统 SHALL 提供轮询系统总览统计接口，展示所有队列的汇总信息。
+
+#### Scenario: 查询总览统计
+
+- **WHEN** 管理员请求查询总览统计
+- **THEN** 系统返回所有轮询队列（实名、流量、套餐）的汇总信息，包含总队列长度、总逾期任务数、总成功率、总平均耗时
+
+#### Scenario: 总览包含各队列概览
+
+- **WHEN** 查询总览统计
+- **THEN** 系统返回各队列的简要信息，包含队列名称、队列长度、成功率、状态（正常/告警）
+
+#### Scenario: 总览包含系统健康度
+
+- **WHEN** 查询总览统计
+- **THEN** 系统计算健康度评分（0-100），基于成功率、队列积压、平均耗时等指标
+
+#### Scenario: 总览包含最后调度时间
+
+- **WHEN** 查询总览统计
+- **THEN** 系统返回各队列的最后调度时间，如果超过 30 秒未调度则标记异常
+
+### Requirement: 队列状态查询
+
+系统 SHALL 提供接口查询各轮询队列的详细状态。
+
+#### Scenario: 查询实名检查队列状态
+
+- **WHEN** 管理员请求查询实名检查队列状态
+- **THEN** 系统返回队列长度（ZCARD polling:queue:realname）、逾期任务数（score < NOW()）、下个待处理任务的时间
+
+#### Scenario: 查询流量检查队列状态
+
+- **WHEN** 管理员请求查询流量检查队列状态
+- **THEN** 系统返回队列长度、逾期任务数、下个待处理任务的时间
+
+#### Scenario: 查询套餐检查队列状态
+
+- **WHEN** 管理员请求查询套餐检查队列状态
+- **THEN** 系统返回队列长度、逾期任务数、下个待处理任务的时间
+
+#### Scenario: 查询手动触发队列
+
+- **WHEN** 管理员请求查询手动触发队列
+- **THEN** 系统返回各类型手动触发队列的长度（LLEN polling:manual:realname 等）
+
+#### Scenario: 队列为空
+
+- **WHEN** 查询队列状态，队列中没有任务
+- **THEN** 系统返回队列长度为 0，逾期任务数为 0，下个待处理任务为 NULL
+
+#### Scenario: 队列积压告警
+
+- **WHEN** 查询队列状态，逾期任务数超过 1000
+- **THEN** 系统返回告警标志，提示队列积压严重
+
+### Requirement: 任务执行统计
+
+系统 SHALL 提供接口查询各类型任务的执行统计。
+
+#### Scenario: 查询实名检查统计
+
+- **WHEN** 管理员请求查询实名检查统计（最近 1 小时）
+- **THEN** 系统从 Redis Hash（polling:stats:realname）读取 success_count_1h、failure_count_1h、total_duration_1h，计算成功率和平均耗时
+
+#### Scenario: 查询流量检查统计
+
+- **WHEN** 管理员请求查询流量检查统计
+- **THEN** 系统返回成功数、失败数、成功率、平均耗时
+
+#### Scenario: 查询套餐检查统计
+
+- **WHEN** 管理员请求查询套餐检查统计
+- **THEN** 系统返回成功数、失败数、成功率、平均耗时
+
+#### Scenario: 成功率计算
+
+- **WHEN** 成功数为 950，失败数为 50
+- **THEN** 系统计算成功率为 95%
+
+#### Scenario: 平均耗时计算
+
+- **WHEN** 总耗时为 120000 毫秒，成功数为 1000
+- **THEN** 系统计算平均耗时为 120 毫秒
+
+#### Scenario: 无数据时返回默认值
+
+- **WHEN** 查询统计，Redis 中没有数据（首次启动）
+- **THEN** 系统返回成功数 0、失败数 0、成功率 100%、平均耗时 0
+
+#### Scenario: 成功率低于阈值告警
+
+- **WHEN** 查询统计，成功率低于 90%
+- **THEN** 系统返回告警标志，提示成功率过低
+
+### Requirement: 实时并发数查询
+
+系统 SHALL 提供接口查询各类型任务的实时并发数。
+
+#### Scenario: 查询实名检查并发数
+
+- **WHEN** 管理员请求查询实名检查并发数
+- **THEN** 系统从 Redis 读取 polling:concurrency:current:realname 和 polling:concurrency:config:realname，返回当前并发数和最大并发数
+
+#### Scenario: 查询所有类型并发数
+
+- **WHEN** 管理员请求查询所有类型并发数
+- **THEN** 系统返回实名、流量、套餐、停复机四种类型的并发情况
+
+#### Scenario: 计算并发使用率
+
+- **WHEN** 当前并发数为 30，最大并发数为 50
+- **THEN** 系统计算使用率为 60%
+
+#### Scenario: 并发满载标记
+
+- **WHEN** 当前并发数等于最大并发数
+- **THEN** 系统返回满载标志，提示可能需要提高并发数
+
+### Requirement: 历史趋势查询
+
+系统 SHALL 提供接口查询任务执行的历史趋势。
+
+#### Scenario: 查询最近 24 小时趋势
+
+- **WHEN** 管理员请求查询最近 24 小时的执行趋势
+- **THEN** 系统从 Redis 或数据库读取每小时的成功数、失败数、平均耗时，返回 24 个数据点
+
+#### Scenario: 查询最近 7 天趋势
+
+- **WHEN** 管理员请求查询最近 7 天的执行趋势
+- **THEN** 系统从数据库聚合每日的统计数据，返回 7 个数据点
+
+#### Scenario: 趋势数据格式
+
+- **WHEN** 返回趋势数据
+- **THEN** 系统返回数组，每个元素包含时间戳、成功数、失败数、成功率、平均耗时
+
+#### Scenario: 趋势数据缺失补零
+
+- **WHEN** 某个时间点没有数据
+- **THEN** 系统补充该时间点，成功数和失败数为 0
+
+### Requirement: 配置匹配统计
+
+系统 SHALL 提供接口查询轮询配置的匹配统计。
+
+#### Scenario: 查询配置匹配卡数
+
+- **WHEN** 管理员请求查询配置ID为 1 的匹配卡数
+- **THEN** 系统从 Redis Set（polling:config:cards:1）读取卡数量（SCARD），或从数据库实时计算
+
+#### Scenario: 查询所有配置匹配统计
+
+- **WHEN** 管理员请求查询所有配置的匹配统计
+- **THEN** 系统返回每个配置的匹配卡数、占比、启用状态
+
+#### Scenario: 未匹配卡统计
+
+- **WHEN** 查询配置匹配统计
+- **THEN** 系统额外返回未匹配任何配置的卡数量
+
+#### Scenario: 配置匹配卡数为 0
+
+- **WHEN** 某配置没有匹配的卡
+- **THEN** 系统返回匹配卡数为 0，建议禁用或删除该配置
+
+### Requirement: 最近任务详情
+
+系统 SHALL 提供接口查询最近执行的任务详情。
+
+#### Scenario: 查询最近 100 个任务
+
+- **WHEN** 管理员请求查询最近执行的任务
+- **THEN** 系统从 Asynq 或数据库读取最近 100 个任务的详情，包含任务ID、类型、状态、开始时间、结束时间、耗时、错误信息
+
+#### Scenario: 筛选失败任务
+
+- **WHEN** 管理员请求查询最近失败的任务
+- **THEN** 系统只返回状态为失败的任务
+
+#### Scenario: 筛选特定类型任务
+
+- **WHEN** 管理员请求查询实名检查的最近任务
+- **THEN** 系统只返回任务类型为 iot:realname:check 的任务
+
+#### Scenario: 任务详情包含卡信息
+
+- **WHEN** 返回任务详情
+- **THEN** 每个任务包含关联的卡ID、ICCID、卡状态等上下文信息
+
+#### Scenario: 任务详情包含错误堆栈
+
+- **WHEN** 任务失败，返回任务详情
+- **THEN** 任务详情包含完整的错误信息和堆栈
+
+### Requirement: 初始化进度查询
+
+系统 SHALL 提供接口查询轮询系统的初始化进度。
+
+#### Scenario: 查询初始化状态
+
+- **WHEN** 管理员请求查询初始化进度
+- **THEN** 系统从 Redis（polling:init:progress）读取初始化状态，包含已处理卡数、总卡数、百分比、预计完成时间
+
+#### Scenario: 初始化未开始
+
+- **WHEN** Worker 刚启动，初始化未开始
+- **THEN** 系统返回状态为"未开始"，进度为 0%
+
+#### Scenario: 初始化进行中
+
+- **WHEN** 初始化任务正在后台运行，已处理 300 万张卡，总数 1000 万
+- **THEN** 系统返回状态为"进行中"，进度为 30%，预计剩余时间约 14 分钟
+
+#### Scenario: 初始化已完成
+
+- **WHEN** 初始化任务完成
+- **THEN** 系统返回状态为"已完成"，进度为 100%，完成时间
+
+#### Scenario: 初始化失败
+
+- **WHEN** 初始化任务因错误中断
+- **THEN** 系统返回状态为"失败"，包含错误信息
+
+### Requirement: 监控数据实时性
+
+系统 SHALL 确保监控数据的实时性和准确性。
+
+#### Scenario: 队列长度实时查询
+
+- **WHEN** 查询队列状态
+- **THEN** 系统实时执行 Redis 命令（ZCARD）获取最新数据，不使用缓存
+
+#### Scenario: 统计数据允许延迟
+
+- **WHEN** 查询任务执行统计
+- **THEN** 系统从 Redis Hash 读取数据，允许 1-2 秒延迟（更新由任务处理器异步写入）
+
+#### Scenario: 并发数实时查询
+
+- **WHEN** 查询实时并发数
+- **THEN** 系统实时读取 Redis 计数器，不使用缓存
+
+#### Scenario: 趋势数据可缓存
+
+- **WHEN** 查询历史趋势
+- **THEN** 系统可缓存结果 5 分钟，减少数据库查询
+
+### Requirement: 日志记录
+
+系统 SHALL 记录监控接口的访问日志。
+
+#### Scenario: 记录查询操作
+
+- **WHEN** 管理员调用监控接口
+- **THEN** 系统记录 Info 日志，包含接口名称、查询参数、响应时间
+
+#### Scenario: 记录异常查询
+
+- **WHEN** 监控接口查询失败（如 Redis 连接断开）
+- **THEN** 系统记录 Error 日志，包含错误详情
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-package-check/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-package-check/spec.md
@@ -0,0 +1,254 @@
+## ADDED Requirements
+
+### Requirement: 套餐流量汇总
+
+系统 SHALL 根据套餐类型（单卡套餐、设备级套餐）汇总流量使用情况。
+
+#### Scenario: 单卡套餐流量读取
+
+- **WHEN** 检查套餐A，套餐类型为单卡套餐（单张卡绑定）
+- **THEN** 系统直接读取该卡的 current_month_usage_mb，作为套餐已用流量
+
+#### Scenario: 设备级套餐流量汇总
+
+- **WHEN** 检查套餐B，套餐类型为设备级套餐，设备D下有 3 张卡
+- **THEN** 系统查询设备下所有卡的 current_month_usage_mb，求和得到套餐已用流量
+
+#### Scenario: 设备级套餐部分卡无流量数据
+
+- **WHEN** 设备级套餐，部分卡从未查询过流量（current_month_usage_mb 为 NULL 或 0）
+- **THEN** 系统将 NULL 视为 0，继续汇总其他卡的流量
+
+#### Scenario: 套餐无关联卡
+
+- **WHEN** 检查套餐C，套餐下没有关联的卡
+- **THEN** 系统记录警告日志，套餐已用流量为 0
+
+### Requirement: 虚流量对比
+
+系统 SHALL 对比套餐的实际流量使用与虚流量，判断是否超额。
+
+#### Scenario: 未超额
+
+- **WHEN** 套餐A的实际流量为 800 MB，虚流量为 1000 MB
+- **THEN** 系统判断未超额，更新 package_usage 状态为正常（status=1）
+
+#### Scenario: 已超额
+
+- **WHEN** 套餐A的实际流量为 1200 MB，虚流量为 1000 MB
+- **THEN** 系统判断已超额，更新 package_usage 状态为超额（status=2），触发停机流程
+
+#### Scenario: 临近超额（预警）
+
+- **WHEN** 套餐A的实际流量为 950 MB，虚流量为 1000 MB，超过 95% 阈值
+- **THEN** 系统更新 package_usage 状态为预警（status=3），发送告警通知，但不停机
+
+#### Scenario: 虚流量为 0 或 NULL
+
+- **WHEN** 套餐的虚流量字段为 0 或 NULL
+- **THEN** 系统记录警告日志，跳过超额检查（视为无限流量套餐）
+
+### Requirement: 自动停机
+
+系统 SHALL 在套餐超额时自动调用 Gateway 停机。
+
+#### Scenario: 单卡套餐停机
+
+- **WHEN** 套餐A超额，套餐类型为单卡套餐
+- **THEN** 系统调用 Gateway.StopCard(ICCID)，停机该卡
+
+#### Scenario: 设备级套餐批量停机
+
+- **WHEN** 套餐B超额，套餐类型为设备级套餐，设备下有 3 张卡
+- **THEN** 系统调用 Gateway.StopCard() 停机所有 3 张卡（串行或并行）
+
+#### Scenario: Gateway 停机成功
+
+- **WHEN** Gateway.StopCard() 返回成功
+- **THEN** 系统更新卡的 network_status=2（已停机），记录操作日志
+
+#### Scenario: Gateway 停机失败
+
+- **WHEN** Gateway.StopCard() 返回失败（如卡已停机、网络超时）
+- **THEN** 系统记录错误日志，任务失败，卡重新入队（下次继续尝试停机）
+
+#### Scenario: 部分卡停机失败
+
+- **WHEN** 设备级套餐停机，3 张卡中 2 张成功、1 张失败
+- **THEN** 系统记录成功的卡，对失败的卡单独重试或记录错误
+
+### Requirement: 数据库更新
+
+系统 SHALL 更新套餐使用状态和卡的网络状态到数据库。
+
+#### Scenario: 更新套餐使用状态
+
+- **WHEN** 套餐超额，执行停机后
+- **THEN** 系统执行 `UPDATE package_usage SET status=2, used_mb=1200, last_check_at=NOW() WHERE id=?`
+
+#### Scenario: 更新卡网络状态
+
+- **WHEN** 卡A被停机
+- **THEN** 系统执行 `UPDATE iot_cards SET network_status=2, last_status_change_at=NOW() WHERE id=?`
+
+#### Scenario: 数据库更新失败
+
+- **WHEN** 数据库更新失败（如连接断开）
+- **THEN** 系统记录错误日志，任务失败，套餐重新入队
+
+### Requirement: Redis 缓存更新
+
+系统 SHALL 同步更新 Redis 缓存中的套餐和卡状态。
+
+#### Scenario: 更新套餐缓存
+
+- **WHEN** 数据库更新成功
+- **THEN** 系统使用 HSET 更新 Redis 缓存（polling:package:{package_id}）的 status、used_mb、last_check_at 字段
+
+#### Scenario: 更新卡缓存
+
+- **WHEN** 卡状态更新成功
+- **THEN** 系统使用 HSET 更新 Redis 缓存（polling:card:{card_id}）的 network_status 字段
+
+#### Scenario: 缓存更新失败不影响主流程
+
+- **WHEN** Redis 更新失败
+- **THEN** 系统记录警告日志，但任务仍视为成功（缓存可以通过定时同步或懒加载恢复）
+
+### Requirement: 操作日志记录
+
+系统 SHALL 记录停机操作到操作日志表。
+
+#### Scenario: 记录停机操作
+
+- **WHEN** 卡A被停机
+- **THEN** 系统插入操作日志（card_id、operation_type='stop'、reason='套餐超额'、operator='系统自动'、created_at=NOW()）
+
+#### Scenario: 操作日志包含套餐信息
+
+- **WHEN** 记录停机操作
+- **THEN** 操作日志包含 package_id、used_mb、virtual_flow 等上下文信息
+
+#### Scenario: 操作日志插入失败
+
+- **WHEN** 操作日志插入失败
+- **THEN** 系统记录警告日志，但任务仍视为成功（操作日志非关键路径）
+
+### Requirement: 手动触发队列
+
+系统 SHALL 支持从手动触发队列获取套餐并优先处理。
+
+#### Scenario: 卡流量更新后触发
+
+- **WHEN** 卡A的流量检查完成，卡A有关联套餐
+- **THEN** 系统将套餐ID加入 polling:manual:package 手动触发队列
+
+#### Scenario: 手动触发队列优先处理
+
+- **WHEN** 调度循环执行，手动触发队列有 10 个套餐
+- **THEN** 系统先从手动触发队列取出所有套餐，生成高优先级任务（ProcessIn(0)），清空手动触发队列
+
+#### Scenario: 再处理定时队列
+
+- **WHEN** 手动触发队列处理完成后
+- **THEN** 系统继续处理定时队列中到期的套餐
+
+### Requirement: 定时队列扫描
+
+系统 SHALL 定期扫描所有套餐的流量使用情况，防止遗漏。
+
+#### Scenario: 周期性扫描套餐
+
+- **WHEN** 调度循环执行，当前时间为 T
+- **THEN** 系统从 Redis Sorted Set（polling:queue:package）获取 score <= T 的套餐（最多 1000 个）
+
+#### Scenario: 生成 Asynq 任务
+
+- **WHEN** 获取到 100 个到期的套餐
+- **THEN** 系统为每个套餐生成 Asynq 任务（TaskTypeIotPackageCheck），入队到 iot_polling_package 队列
+
+#### Scenario: 从队列移除已调度的套餐
+
+- **WHEN** 任务生成完成
+- **THEN** 系统使用 ZREM 从 Redis 队列移除这些套餐（检查完成后会重新加入）
+
+### Requirement: 并发控制
+
+系统 SHALL 使用 Redis 信号量控制套餐检查的并发数。
+
+#### Scenario: 获取并发信号量成功
+
+- **WHEN** 套餐检查任务开始执行，当前并发数为 20，配置的最大并发数为 30
+- **THEN** 系统使用 INCR 增加计数，获取信号量成功，执行任务
+
+#### Scenario: 并发已满
+
+- **WHEN** 套餐检查任务开始执行，当前并发数为 30，配置的最大并发数为 30
+- **THEN** 系统 INCR 后发现超过限制，DECR 归还，任务返回 SkipRetry（不执行，等待下次调度）
+
+#### Scenario: 任务完成释放信号量
+
+- **WHEN** 套餐检查任务完成（成功或失败）
+- **THEN** 系统使用 DECR 释放信号量
+
+### Requirement: 重新入队
+
+系统 SHALL 在检查完成后，将套餐重新加入轮询队列。
+
+#### Scenario: 计算下次检查时间
+
+- **WHEN** 套餐检查完成，当前配置的检查间隔为 3600 秒
+- **THEN** 系统计算 next_check_time = NOW() + 3600秒
+
+#### Scenario: 加回队列
+
+- **WHEN** 计算出下次检查时间
+- **THEN** 系统使用 ZADD 将套餐ID和时间戳加入 polling:queue:package
+
+#### Scenario: 任务失败也重新入队
+
+- **WHEN** 任务因 Gateway 超时失败
+- **THEN** 系统仍然将套餐重新入队（按原计划下次检查），不阻塞后续检查
+
+### Requirement: 监控统计
+
+系统 SHALL 记录套餐检查的成功率和耗时。
+
+#### Scenario: 记录成功统计
+
+- **WHEN** 套餐检查成功完成，耗时 345 毫秒
+- **THEN** 系统更新 Redis Hash（polling:stats:package），增加 success_count_1h，累加 total_duration_1h
+
+#### Scenario: 记录失败统计
+
+- **WHEN** 套餐检查失败（Gateway 超时）
+- **THEN** 系统更新 Redis Hash，增加 failure_count_1h
+
+#### Scenario: 每小时重置计数器
+
+- **WHEN** 每小时整点（如 10:00:00）
+- **THEN** 系统重置计数器（success_count_1h、failure_count_1h、total_duration_1h），保持时间窗口滚动
+
+### Requirement: 日志记录
+
+系统 SHALL 记录详细的套餐检查日志，便于排查问题。
+
+#### Scenario: 记录开始日志
+
+- **WHEN** 套餐检查任务开始执行
+- **THEN** 系统记录 Info 日志，包含 package_id、package_type、virtual_flow
+
+#### Scenario: 记录成功日志
+
+- **WHEN** 套餐检查成功完成
+- **THEN** 系统记录 Info 日志，包含 package_id、used_mb、virtual_flow、is_exceeded、duration_ms
+
+#### Scenario: 记录停机日志
+
+- **WHEN** 执行停机操作
+- **THEN** 系统记录 Warn 日志，包含 package_id、card_ids、reason='套餐超额'
+
+#### Scenario: 记录失败日志
+
+- **WHEN** 套餐检查失败
+- **THEN** 系统记录 Error 日志，包含 package_id、error 详情
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-realname-check/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-realname-check/spec.md
@@ -0,0 +1,172 @@
+## ADDED Requirements
+
+### Requirement: 实名状态查询
+
+系统 SHALL 调用 Gateway API 查询卡的实名状态，并更新数据库和缓存。
+
+#### Scenario: 查询未实名卡
+
+- **WHEN** 实名检查任务执行，卡A的 ICCID 为 "89860123456789012345"，real_name_status=0
+- **THEN** 系统调用 Gateway.QueryRealnameStatus(ICCID)，获取实名状态响应
+
+#### Scenario: 实名状态未变化
+
+- **WHEN** Gateway 返回实名状态为"未实名"（status=0），与数据库当前值相同
+- **THEN** 系统更新 last_realname_check_at 字段，不触发配置重新匹配
+
+#### Scenario: 实名状态变化为已实名
+
+- **WHEN** Gateway 返回实名状态为"已实名"（status=1），数据库当前值为 0
+- **THEN** 系统更新 real_name_status=1 和 last_realname_check_at，触发 OnCardStatusChanged() 重新匹配配置
+
+#### Scenario: Gateway API 超时
+
+- **WHEN** 调用 Gateway API 超时（>30秒）
+- **THEN** 系统记录错误日志，任务失败，不重试，卡重新入队（按原计划下次检查）
+
+#### Scenario: Gateway API 返回错误
+
+- **WHEN** Gateway API 返回业务错误（如卡号不存在）
+- **THEN** 系统记录错误日志，不更新数据库，任务失败，卡重新入队
+
+### Requirement: 并发控制
+
+系统 SHALL 使用 Redis 信号量控制实名检查的并发数，避免打爆 Gateway。
+
+#### Scenario: 获取并发信号量成功
+
+- **WHEN** 实名检查任务开始执行，当前并发数为 30，配置的最大并发数为 50
+- **THEN** 系统使用 INCR 增加计数，获取信号量成功，执行任务
+
+#### Scenario: 并发已满
+
+- **WHEN** 实名检查任务开始执行，当前并发数为 50，配置的最大并发数为 50
+- **THEN** 系统 INCR 后发现超过限制，DECR 归还，任务返回 SkipRetry（不执行，等待下次调度）
+
+#### Scenario: 任务完成释放信号量
+
+- **WHEN** 实名检查任务完成（成功或失败）
+- **THEN** 系统使用 DECR 释放信号量
+
+### Requirement: 数据库更新
+
+系统 SHALL 更新卡的实名状态和最后检查时间到数据库。
+
+#### Scenario: 更新实名状态
+
+- **WHEN** Gateway 返回实名状态为 1
+- **THEN** 系统执行 `UPDATE iot_cards SET real_name_status=1, last_realname_check_at=NOW() WHERE id=?`
+
+#### Scenario: 数据库更新失败
+
+- **WHEN** 数据库更新失败（如连接断开）
+- **THEN** 系统记录错误日志，任务失败，卡重新入队
+
+### Requirement: Redis 缓存更新
+
+系统 SHALL 同步更新 Redis 缓存中的卡信息。
+
+#### Scenario: 更新缓存实名状态
+
+- **WHEN** 数据库更新成功
+- **THEN** 系统使用 HSET 更新 Redis 缓存（polling:card:{card_id}）的 real_name_status 和 last_realname_check_at 字段
+
+#### Scenario: 缓存更新失败不影响主流程
+
+- **WHEN** Redis 更新失败
+- **THEN** 系统记录警告日志，但任务仍视为成功（缓存可以通过定时同步或懒加载恢复）
+
+### Requirement: 配置重新匹配
+
+系统 SHALL 在实名状态变化时重新匹配轮询配置。
+
+#### Scenario: 从未实名变为已实名
+
+- **WHEN** 卡A从 real_name_status=0 变为 1
+- **THEN** 系统调用 OnCardStatusChanged()，重新匹配配置（从"未实名卡配置"切换到"已实名卡配置"）
+
+#### Scenario: 切换到低频检查
+
+- **WHEN** 卡A匹配的配置从"未实名-30秒"切换到"已实名-3600秒"
+- **THEN** 系统更新 Redis 缓存的 matched_config_id，更新队列中的 next_check_time（下次检查时间推迟）
+
+#### Scenario: 不再匹配任何配置
+
+- **WHEN** 卡A状态变化后，不再匹配任何启用的配置
+- **THEN** 系统从所有队列移除该卡
+
+### Requirement: 重新入队
+
+系统 SHALL 在检查完成后，将卡重新加入轮询队列。
+
+#### Scenario: 计算下次检查时间
+
+- **WHEN** 实名检查完成，当前配置的检查间隔为 60 秒
+- **THEN** 系统计算 next_check_time = NOW() + 60秒
+
+#### Scenario: 加回队列
+
+- **WHEN** 计算出下次检查时间
+- **THEN** 系统使用 ZADD 将卡ID和时间戳加入 polling:queue:realname
+
+#### Scenario: 任务失败也重新入队
+
+- **WHEN** 任务因 Gateway 超时失败
+- **THEN** 系统仍然将卡重新入队（按原计划下次检查），不阻塞后续检查
+
+### Requirement: 行业卡特殊处理
+
+系统 SHALL 识别行业卡，行业卡无需实名检查。
+
+#### Scenario: 行业卡不参与实名检查
+
+- **WHEN** 轮询配置匹配卡时，卡A的 card_category="industry"
+- **THEN** 如果配置启用实名检查，系统跳过该卡或使用不启用实名检查的配置
+
+#### Scenario: 行业卡配置示例
+
+- **WHEN** 管理员创建配置，card_category="industry"，real_name_check_enabled=false，card_data_check_enabled=true
+- **THEN** 行业卡只参与流量检查，不参与实名检查
+
+### Requirement: 监控统计
+
+系统 SHALL 记录实名检查的成功率和耗时。
+
+#### Scenario: 记录成功统计
+
+- **WHEN** 实名检查成功完成，耗时 123 毫秒
+- **THEN** 系统更新 Redis Hash（polling:stats:realname），增加 success_count_1h，累加 total_duration_1h
+
+#### Scenario: 记录失败统计
+
+- **WHEN** 实名检查失败（Gateway 超时）
+- **THEN** 系统更新 Redis Hash，增加 failure_count_1h
+
+#### Scenario: 每小时重置计数器
+
+- **WHEN** 每小时整点（如 10:00:00）
+- **THEN** 系统重置计数器（success_count_1h、failure_count_1h、total_duration_1h），保持时间窗口滚动
+
+### Requirement: 日志记录
+
+系统 SHALL 记录详细的实名检查日志，便于排查问题。
+
+#### Scenario: 记录开始日志
+
+- **WHEN** 实名检查任务开始执行
+- **THEN** 系统记录 Info 日志，包含 card_id、iccid、config_id
+
+#### Scenario: 记录成功日志
+
+- **WHEN** 实名检查成功完成
+- **THEN** 系统记录 Info 日志，包含 card_id、iccid、old_status、new_status、duration_ms
+
+#### Scenario: 记录失败日志
+
+- **WHEN** 实名检查失败
+- **THEN** 系统记录 Error 日志，包含 card_id、iccid、error 详情
+
+#### Scenario: 记录状态变化日志
+
+- **WHEN** 实名状态发生变化
+- **THEN** 系统记录 Info 日志，包含 card_id、old_status、new_status、old_config、new_config
--- a/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-scheduler/spec.md
+++ b/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-scheduler/spec.md
@@ -0,0 +1,187 @@
+## ADDED Requirements
+
+### Requirement: Worker 启动时快速初始化
+
+系统 SHALL 在 Worker 进程启动时快速完成初始化（<10秒），不阻塞服务启动。
+
+#### Scenario: 启动时只加载配置
+
+- **WHEN** Worker 进程启动
+- **THEN** 系统在 10 秒内完成配置加载（轮询配置、并发控制配置），启动调度器 Goroutine，Worker 进程可用
+
+#### Scenario: 后台异步加载卡数据
+
+- **WHEN** Worker 快速启动完成后
+- **THEN** 系统在后台启动异步任务，分批加载卡数据到 Redis（每批 10万张，处理后 sleep 1秒）
+
+#### Scenario: 记录初始化进度
+
+- **WHEN** 后台初始化任务运行中
+- **THEN** 系统在 Redis 存储初始化进度（已处理数量、总数量、百分比、预计完成时间），管理员可查询进度
+
+### Requirement: 渐进式卡数据加载
+
+系统 SHALL 使用渐进式策略加载百万级卡数据到 Redis，避免打爆数据库。
+
+#### Scenario: 分批读取卡数据
+
+- **WHEN** 初始化任务从数据库读取卡数据
+- **THEN** 系统使用游标（主键范围）分批读取，每批 10万张，使用 `WHERE id > last_id ORDER BY id LIMIT 100000`
+
+#### Scenario: 批量写入 Redis
+
+- **WHEN** 读取到一批卡数据后
+- **THEN** 系统使用 Redis Pipeline 批量写入（HSET 卡信息、ZADD 队列、SADD 配置匹配关系），减少网络往返
+
+#### Scenario: 限流保护数据库
+
+- **WHEN** 每批卡数据处理完成后
+- **THEN** 系统 sleep 1秒，避免连续高频查询打爆数据库
+
+#### Scenario: 断点续传
+
+- **WHEN** Worker 重启，初始化未完成
+- **THEN** 系统从 Redis 读取上次进度，从上次最大ID继续加载，不重新开始
+
+### Requirement: 懒加载机制
+
+系统 SHALL 支持懒加载机制，当卡未初始化但被访问时，实时加载到 Redis。
+
+#### Scenario: 卡缓存未命中时加载
+
+- **WHEN** 手动触发检查，卡ID为 123456，但 Redis 中没有该卡缓存
+- **THEN** 系统从数据库读取卡信息，匹配配置，写入 Redis 缓存，加入轮询队列，继续执行检查
+
+#### Scenario: 新卡创建时自动加载
+
+- **WHEN** 用户创建新卡或批量导入卡
+- **THEN** 系统在 Service 层调用 PollingService.OnCardCreated()，自动加载到 Redis
+
+#### Scenario: 热点卡优先
+
+- **WHEN** 初始化未完成，用户频繁访问某些卡
+- **THEN** 这些卡通过懒加载机制优先初始化到 Redis
+
+### Requirement: 调度循环执行
+
+系统 SHALL 每 10 秒执行一次调度循环，从 Redis 队列获取到期的卡并生成任务。
+
+#### Scenario: 定时触发调度
+
+- **WHEN** 调度器启动后
+- **THEN** 系统每 10 秒执行一次调度循环（使用 time.Ticker）
+
+#### Scenario: 获取到期的卡
+
+- **WHEN** 调度循环执行，当前时间为 T
+- **THEN** 系统从 Redis Sorted Set 使用 ZRANGEBYSCORE 获取 score <= T 的卡（最多 1000 张）
+
+#### Scenario: 生成 Asynq 任务
+
+- **WHEN** 获取到 500 张到期的卡
+- **THEN** 系统为每张卡生成 Asynq 任务（TaskTypeIotRealNameCheck），入队到 iot_polling_realname 队列
+
+#### Scenario: 从队列移除已调度的卡
+
+- **WHEN** 任务生成完成
+- **THEN** 系统使用 ZREM 从 Redis 队列移除这些卡（检查完成后会重新加入）
+
+### Requirement: 手动触发优先处理
+
+系统 SHALL 优先处理手动触发队列中的卡，确保手动触发立即执行。
+
+#### Scenario: 先处理手动触发队列
+
+- **WHEN** 调度循环执行，手动触发队列（polling:manual:realname）有 10 张卡
+- **THEN** 系统先从手动触发队列取出所有卡，生成高优先级任务（ProcessIn(0)），清空手动触发队列
+
+#### Scenario: 再处理定时队列
+
+- **WHEN** 手动触发队列处理完成后
+- **THEN** 系统继续处理定时队列中到期的卡
+
+### Requirement: 配置匹配引擎
+
+系统 SHALL 为每张卡匹配最合适的轮询配置，基于优先级选择。
+
+#### Scenario: 按优先级匹配配置
+
+- **WHEN** 卡A的状态为未实名（not_real_name）、运营商为移动（carrier_id=1）
+- **THEN** 系统读取所有启用配置，按 priority ASC 排序，依次检查匹配条件，返回第一个匹配的配置
+
+#### Scenario: 精确匹配优先
+
+- **WHEN** 配置1（优先级10）匹配"未实名+移动"，配置2（优先级20）匹配"未实名"，卡A为"未实名+移动"
+- **THEN** 系统匹配配置1（优先级更高）
+
+#### Scenario: 无匹配配置
+
+- **WHEN** 卡A的状态无法匹配任何启用的配置
+- **THEN** 系统返回 nil，卡A不参与轮询
+
+#### Scenario: 卡状态变化重新匹配
+
+- **WHEN** 卡A从未实名变为已实名
+- **THEN** 系统调用 OnCardStatusChanged()，重新匹配配置，更新 Redis 缓存和队列
+
+### Requirement: 下次检查时间计算
+
+系统 SHALL 根据配置的检查间隔计算卡的下次检查时间。
+
+#### Scenario: 首次加入队列
+
+- **WHEN** 卡A首次加入轮询队列，配置的实名检查间隔为 60 秒
+- **THEN** 系统计算 next_check_time = NOW() + 60秒，使用 ZADD 加入队列
+
+#### Scenario: 检查完成后重新入队
+
+- **WHEN** 卡A的实名检查完成，配置的检查间隔为 60 秒
+- **THEN** 系统计算 next_check_time = NOW() + 60秒，使用 ZADD 重新加入队列
+
+#### Scenario: 配置更新后重新计算
+
+- **WHEN** 管理员将配置的检查间隔从 60 秒修改为 120 秒
+- **THEN** 系统为所有匹配该配置的卡重新计算 next_check_time，更新队列
+
+### Requirement: 卡生命周期回调
+
+系统 SHALL 在卡的生命周期事件发生时，自动同步到轮询系统。
+
+#### Scenario: 新卡创建时加入轮询
+
+- **WHEN** IotCardService.Create() 创建新卡，enable_polling=true
+- **THEN** Service 调用 PollingService.OnCardCreated()，卡自动加入轮询系统
+
+#### Scenario: 批量导入时加入轮询
+
+- **WHEN** IotCardImportHandler 批量导入 10000 张卡
+- **THEN** Handler 调用 PollingService.OnBatchCardsCreated()，使用 Pipeline 批量加入轮询系统
+
+#### Scenario: 卡删除时移除轮询
+
+- **WHEN** IotCardService.Delete() 软删除卡
+- **THEN** Service 调用 PollingService.OnCardDeleted()，从所有队列移除，删除缓存
+
+#### Scenario: 禁用轮询时移除队列
+
+- **WHEN** IotCardService.Update() 更新卡，enable_polling=false
+- **THEN** Service 调用 PollingService.OnCardDisabled()，从队列移除但保留缓存
+
+#### Scenario: 启用轮询时加入队列
+
+- **WHEN** IotCardService.Update() 更新卡，enable_polling=true
+- **THEN** Service 调用 PollingService.OnCardEnabled()，重新匹配配置并加入队列
+
+### Requirement: 监控统计更新
+
+系统 SHALL 在每次调度后更新监控统计数据。
+
+#### Scenario: 记录调度信息
+
+- **WHEN** 调度循环完成，处理了 500 张卡
+- **THEN** 系统更新 Redis Hash（polling:stats:realname），记录 last_schedule_at 和 last_schedule_count
+
+#### Scenario: 更新队列长度
+
+- **WHEN** 任何时候查询队列状态
+- **THEN** 系统使用 ZCARD 实时读取队列长度