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

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 日志，包含操作人、被拒绝原因