junhong_cmp_fiber/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/polling-alert/spec.md

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