### 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` **接口定义(方法签名)**: ```go // 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 队列深度查询失败」