feat: 实现 IoT 卡轮询系统(支持千万级卡规模)
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 6m35s

实现功能:
- 实名状态检查轮询(可配置间隔)
- 卡流量检查轮询(支持跨月流量追踪)
- 套餐检查与超额自动停机
- 分布式并发控制(Redis 信号量)
- 手动触发轮询(单卡/批量/条件筛选)
- 数据清理配置与执行
- 告警规则与历史记录
- 实时监控统计(队列/性能/并发)

性能优化:
- Redis 缓存卡信息,减少 DB 查询
- Pipeline 批量写入 Redis
- 异步流量记录写入
- 渐进式初始化(10万卡/批)

压测工具(scripts/benchmark/):
- Mock Gateway 模拟上游服务
- 测试卡生成器
- 配置初始化脚本
- 实时监控脚本

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-02-05 17:32:44 +08:00
parent b11edde720
commit 931e140e8e
104 changed files with 16883 additions and 87 deletions

View File

@@ -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 Hashpolling: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 Setpolling: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** 系统从 Redispolling: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 日志,包含错误详情