csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

chore: 归档轮询系统实现变更 (polling-system-implementation)
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 44s
Details

Browse Source 
已完成千万级卡规模轮询系统的完整实现和集成测试验证，将变更归档到 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>
This commit is contained in:
huang
2026-02-10 10:28:47 +08:00
parent 931e140e8e
commit 804145332b
15 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-alert/spec.md Normal file
View File

@@ -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 日志，包含错误详情