csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
931e140e8e2c7c4c9350cadecbaa79944e5cd1cb
junhong_cmp_fiber/openspec/changes/polling-system-implementation/specs/polling-manual-trigger/spec.md
huang 931e140e8e
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m35s
Details
feat: 实现 IoT 卡轮询系统（支持千万级卡规模） 
实现功能：
- 实名状态检查轮询（可配置间隔）
- 卡流量检查轮询（支持跨月流量追踪）
- 套餐检查与超额自动停机
- 分布式并发控制（Redis 信号量）
- 手动触发轮询（单卡/批量/条件筛选）
- 数据清理配置与执行
- 告警规则与历史记录
- 实时监控统计（队列/性能/并发）

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

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-05 17:32:44 +08:00

9.7 KiB
Raw Blame History

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 日志，包含操作人、被拒绝原因
Reference in New Issue View Git Blame Copy Permalink