junhong_cmp_fiber/openspec/specs/polling-queue-manager/spec.md

Requirement: 统一 Redis 队列操作封装（PollingQueueManager）

新建 internal/polling/queue_manager.go，提供 PollingQueueManager 类型，封装所有轮询相关的 Redis 队列操作。

文件目标：< 200 行，只依赖 redis.Client，无 DB 依赖，两个进程（API 进程和 Worker 进程）共享同一实现。

以下代码的 Redis 操作均须通过 PollingQueueManager：

• internal/polling/callbacks.go（删除后由此替代）
• internal/polling/api_callback.go（删除后由此替代）
• internal/polling/scheduler.go 中的所有队列出队/入队操作
• internal/task/polling_handler.go 中的 requeueCard

接口定义（方法签名）：

// PollingQueueManager 轮询队列统一管理器
type PollingQueueManager struct {
    redis      *redis.Client
    shardCount int // 默认16
}

  // DequeueReady 从指定分片出队到期卡（Lua 脚本：ZRANGEBYSCORE + ZREM 原子执行）
  // 只取 score ≤ now 的到期卡，不触碰未来项
  // 返回 []CardEntry，包含 CardID（从 ZRANGEBYSCORE 结果解析）
  func (m *PollingQueueManager) DequeueReady(ctx context.Context, shardID int, taskType string, batchSize int) ([]CardEntry, error)

// Requeue 将卡重新入队（ZADD，score=nextCheckAt Unix时间戳）
func (m *PollingQueueManager) Requeue(ctx context.Context, cardID uint, taskType string, nextCheckAt time.Time) error

// RemoveFromAllQueues 从所有分片的4个队列（含protect）移除该卡
func (m *PollingQueueManager) RemoveFromAllQueues(ctx context.Context, cardID uint) error

// EnqueueManual 手动触发入队（List RPUSH，调度器优先消费）
func (m *PollingQueueManager) EnqueueManual(ctx context.Context, cardID uint, taskType string) error

// OnCardDeleted 卡删除事件：移除所有队列 + 清理缓存
func (m *PollingQueueManager) OnCardDeleted(ctx context.Context, cardID uint) error

  // GetQueueDepth 获取分片队列深度（用于背压检测）
  func (m *PollingQueueManager) GetQueueDepth(ctx context.Context, shardID int, taskType string) (int64, error)

  // GetTotalQueueDepth 获取指定任务类型的总队列深度（聚合所有分片 ZCard 之和）
  // 供 MonitoringService 使用，替代直接读取旧的非分片 Redis Key
  func (m *PollingQueueManager) GetTotalQueueDepth(ctx context.Context, taskType string) (int64, error)

Scenario: Lua 脚本原子出队替换竞态操作

• GIVEN 调度器从分片队列出队
• WHEN Scheduler 调用 DequeueReady(ctx, shardID=3, taskType="carddata", batchSize=1000)
• THEN Lua 脚本在 Redis 服务端原子执行 ZRANGEBYSCORE + ZREM，只取 score ≤ now 的到期卡；不存在原来 ZRANGEBYSCORE + ZREMRANGEBYSCORE 分步操作的竞态窗口和卡丢失风险；返回卡ID列表，每张卡保证只被取出一次

Scenario: 高并发下不重复出队

• GIVEN 2个 Scheduler Worker 同时消费同一分片
• WHEN 两个 Worker 同时调用 DequeueReady(ctx, shardID=0, taskType="realname", batchSize=500)
• THEN 两次调用返回的 CardID 集合不相交（Lua 脚本在 Redis 单线程中串行执行，保证原子性），不存在同一张卡被两个 Worker 同时处理的情况

Scenario: 未到期卡不被提前取出

• GIVEN 分片队列中有 100 张到期卡（score ≤ now）和 50 张未到期卡（score > now）
• WHEN Scheduler 调用 DequeueReady(ctx, shardID=0, taskType="carddata", batchSize=200)
• THEN 只返回 100 张到期卡；50 张未到期卡保持在队列中不受影响；这是 Lua 脚本方案相比 ZPOPMIN 的关键优势（ZPOPMIN 会错误取出未到期卡）

---

Requirement: 分片 Sorted Set 支持千万级规模

PollingQueueManager 的存储结构使用分片 Sorted Set，Key 格式为 polling:shard:{shardID}:queue:{taskType}。

分片路由：卡入队时按 cardID % shardCount 分桶，确保同一张卡的同一任务类型始终在固定分片。

Key 命名：通过 pkg/constants/redis.go 的 RedisPollingShardQueueKey(shardID int, taskType string) string 生成。

Scenario: 分片路由一致性

• GIVEN 默认 16 个分片
• WHEN cardID=1000 的卡执行 Requeue(ctx, 1000, "carddata", nextTime)
• THEN 写入 polling:shard:8:queue:carddata（1000 % 16 = 8），每次入队该卡都写同一个分片

Scenario: 背压跳过深度超限的分片

• GIVEN 分片 5 的 carddata 队列深度达到 600,000（超过阈值 500,000）
• WHEN Scheduler 调用 GetQueueDepth(ctx, 5, "carddata")
• THEN 返回 600000；Scheduler 跳过该分片本轮出队，等待 Asynq 消化积压后恢复

---

Requirement: 从所有队列移除（修复 protect 队列遗漏 Bug）

RemoveFromAllQueues 须覆盖 4 个任务类型（realname、carddata、package、protect）× N 个分片 = 4N 次 Redis ZREM 操作。

Scenario: 删除卡后 protect 队列不残留

• GIVEN cardID=500 的卡在 realname/carddata/package/protect 4个队列均有条目
• WHEN 调用 RemoveFromAllQueues(ctx, 500)
• THEN 4 类任务类型 × 16 分片共 64 个 Key 均执行 ZREM；Redis CLI 验证 ZRANK polling:shard:*:queue:protect 500 均不存在

Scenario: 不存在的卡调用无副作用

• GIVEN cardID=999 的卡从未入队
• WHEN 调用 RemoveFromAllQueues(ctx, 999)
• THEN 无报错返回，各队列 ZREM 操作幂等（不存在成员 ZREM 返回 0，不视为错误）

---

Requirement: 手动触发入队

EnqueueManual 使用 List 的 RPUSH 将卡 ID 推入手动触发队列，Scheduler 在每轮调度中优先消费该队列（LPOP）。

Scenario: 手动触发优先于定时队列

• GIVEN 某卡定时轮询间隔为 30 分钟，距下次定时触发还有 25 分钟
• WHEN 管理员调用手动触发接口 → EnqueueManual(ctx, cardID, "carddata")
• THEN 卡被推入 polling:manual:carddata 列表；下一个调度周期（1秒内）即被 Scheduler 取出推入 Asynq，无需等待 25 分钟

Scenario: 手动队列不影响分片定时队列

• GIVEN cardID=200 的卡在手动队列和定时分片队列均有条目
• WHEN Scheduler 先消费手动队列取出 cardID=200，推入 Asynq
• THEN 分片队列中的条目不受影响（仍按原定时间等待）；Task Handler 执行完后通过 Requeue 更新分片队列的 score

---

Requirement: 合并两个 Callback 实现

删除 internal/polling/callbacks.go 和 internal/polling/api_callback.go，统一通过 PollingQueueManager 处理所有卡生命周期事件。

两个进程（API 进程和 Worker 进程）共享同一个 PollingQueueManager 实例，均只需要 Redis Client，无需 Scheduler 实例。

Scenario: API 进程处理卡删除不依赖 Scheduler

• GIVEN API 进程没有启动 Scheduler（只有 Worker 进程有）
• WHEN API 进程处理卡删除请求，调用 pollingQueueMgr.OnCardDeleted(ctx, cardID)
• THEN 卡从所有 4 类任务 × 16 分片队列中移除，卡信息 Redis 缓存清理；操作不依赖 Scheduler 对象，API 进程独立完成

Scenario: Worker 进程卡状态变化重新入队

• GIVEN Worker 进程检测到卡状态变化（如卡由停机变为在线）
• WHEN 调用 pollingQueueMgr.Requeue(ctx, cardID, taskType, time.Now())
• THEN 卡按 cardID % shardCount 路由到对应分片，score=当前时间戳，Scheduler 下一轮即可出队处理

Scenario: 两个进程不产生重复清理

• GIVEN API 进程和 Worker 进程同时响应同一卡的删除事件（极端情况）
• WHEN 两者同时调用 OnCardDeleted(ctx, cardID)
• THEN Redis ZREM 操作幂等，不产生副作用；缓存 DEL 操作幂等，不报错

---

Requirement: LifecycleService 入队前检查 enable_polling（M3）

PollingLifecycleService 在 OnCardCreated、OnCardEnabled、OnCardStatusChanged 触发重新入队前，必须检查资产的 enable_polling 状态，防止禁用轮询的设置因生命周期事件被意外绕过。

Scenario: 设备禁用轮询后状态变更不重新入队

• GIVEN deviceID=10 已被设置 enable_polling=false，设备下 card-A（cardID=100）因状态变化触发 OnCardStatusChanged
• WHEN PollingLifecycleService.OnCardStatusChanged(ctx, 100) 执行
• THEN 先调 RemoveFromAllQueues(ctx, 100) 清理队列；再检查 card.DeviceID → 查 device.EnablePolling=false → 跳过 Requeue；记录 Debug 日志「设备轮询已禁用，跳过重新入队: deviceID=10, cardID=100」

Scenario: 卡自身禁用轮询后不重新入队

• GIVEN cardID=200 的 enable_polling=false（无绑定设备），触发 OnCardEnabled
• WHEN PollingLifecycleService.OnCardEnabled(ctx, 200) 执行
• THEN 检查 card.EnablePolling=false → 跳过 Requeue；记录 Debug 日志「卡轮询已禁用，跳过入队: cardID=200」

Scenario: 删除和禁用事件无需检查 enable_polling

• GIVEN OnCardDeleted、OnCardDisabled 被调用
• WHEN 执行队列清理操作
• THEN 直接执行 RemoveFromAllQueues，不需要检查 enable_polling（清理操作本身是正确行为）

---

Requirement: 监控服务适配分片队列

PollingQueueManager 新增 GetTotalQueueDepth(ctx, taskType) 方法，聚合所有分片的 ZCard 之和，供 MonitoringService 替代直接读取旧的非分片 Redis Key。

Scenario: MonitoringService 读取分片后的队列深度

• GIVEN 16 个分片中 carddata 队列分别有 100、200、300...1600 条数据
• WHEN MonitoringService 调用 queueMgr.GetTotalQueueDepth(ctx, "carddata")
• THEN 返回 13600（所有分片 ZCard 之和）；与重构前直接读 polling:queue:carddata 的语义等价

Scenario: 部分分片 ZCard 失败不影响总体

• GIVEN 16 个分片中 1 个分片 Redis 读取超时
• WHEN GetTotalQueueDepth 执行
• THEN 跳过超时分片，返回其余 15 个分片之和；记录 Warn 日志「分片 X 队列深度查询失败」