feat: 轮询系统重构（分片队列 + 停复机统一 + Handler 拆分）

【核心变更】

1. 停复机逻辑统一（StopResumeService）
   - 新增 EvaluateAndAct 统一入口，封装三条件停复机判断
   - 停机条件：无套餐(no_package) / 流量耗尽(traffic_exhausted) / 未实名(not_realname)
   - 复机条件：stop_reason 合规 + 有套餐且未耗尽 + 已实名或行业卡
   - 修复设备套餐 Bug：hasValidPackage 按 device_id 查套餐，而非仅 iot_card_id
   - 设备维度停复机加幂等锁（Redis SetNX，TTL 30s），防止多卡并发重复调 Gateway

2. Redis 分片队列（PollingQueueManager）
   - 新建 queue_manager.go，封装所有轮询 Redis 操作
   - 16 分片 Sorted Set，Key 格式：polling:shard:{shardID}:queue:{taskType}
   - Lua 脚本原子出队（ZRANGEBYSCORE + 分批 ZREM），消除竞态窗口
   - 新增背压检测：队列深度超 50 万时 Scheduler 跳过该分片
   - RemoveFromAllQueues 覆盖 4 种任务类型（含 protect）

3. Handler 拆分（polling_handler.go 1360行 → 5个专注文件）
   - polling_base.go：共享基类（并发控制/卡缓存/重入队）
   - polling_realname_handler.go：实名采集，实名 0→1 时立即触发复机
   - polling_carddata_handler.go：流量采集，保留跨月边界检测逻辑
   - polling_package_handler.go：套餐采集，委托 EvaluateAndAct 决策
   - polling_protect_handler.go：保护期一致性检查，保护期内强制修正

4. 配置管理（PollingConfigManager）
   - 新建 config_manager.go，从 scheduler.go 提取配置职责
   - 内存缓存 + 5 分钟定时刷新，刷新失败保留原缓存
   - 修复 getCardCondition：停机卡返回 suspended，不再错配 activated 配置

5. 渐进式初始化（CardInitializer）
   - 新建 initializer.go，分批加载（每批 10 万），批次间 sleep 500ms
   - 过滤 enable_polling=false 的卡，初始化完成前 Scheduler 不出队

6. 卡生命周期服务（PollingLifecycleService）
   - 新建 lifecycle_service.go，替代已删除的 callbacks.go 和 api_callback.go
   - OnCardCreated/OnCardEnabled/OnCardStatusChanged 入队前检查 enable_polling

7. Scheduler 精简（1000+行 → 227行）
   - 保留纯调度循环：scheduleLoop + processShardSchedule + enqueueBatch
   - 保留每 10 秒触发套餐过期检测和流量重置
   - 移除所有 DB 操作、配置加载、卡初始化逻辑

8. 轮询管控 API（enable_polling）
   - 新增 PUT /api/admin/assets/:id/polling-status 接口
   - 支持对设备/卡维度开关轮询，关闭后从所有分片队列移除

9. 数据库迁移
   - 000103：tb_device 新增 enable_polling 字段（boolean, NOT NULL, DEFAULT true）
   - 000104：新增 suspended 轮询配置，为 activated 配置补全 protect_check_interval

【文件统计】
- 新增：19 个文件（handler × 5、polling 组件 × 4、迁移 × 3 等）
- 修改：20 个文件（bootstrap 注入、store 接口、monitoring 适配分片等）
- 删除：3 个文件（polling_handler.go、callbacks.go、api_callback.go）

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

internal/task/polling_carddata_handler.go

@@ -0,0 +1,188 @@
+package task
+
+import (
+	"context"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/break/junhong_cmp_fiber/internal/gateway"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	iot_card_svc "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
+	packagepkg "github.com/break/junhong_cmp_fiber/internal/service/package"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+// PollingCarddataHandler 流量检查任务处理器
+// 职责：调 Gateway 查流量 → 写 DB → 扣减套餐流量 → 调 EvaluateAndAct 判断停复机
+// 不做：直接停复机决策，委托给 StopResumeService.EvaluateAndAct
+type PollingCarddataHandler struct {
+	base          *PollingBase
+	gateway       *gateway.Client
+	iotCardStore  *postgres.IotCardStore
+	carrierStore  *postgres.CarrierStore
+	usageService  *packagepkg.UsageService
+	stopResumeSvc iot_card_svc.StopResumeServiceInterface
+}
+
+// NewPollingCarddataHandler 创建流量检查任务处理器
+func NewPollingCarddataHandler(
+	base *PollingBase,
+	gw *gateway.Client,
+	iotCardStore *postgres.IotCardStore,
+	carrierStore *postgres.CarrierStore,
+	usageService *packagepkg.UsageService,
+	stopResumeSvc iot_card_svc.StopResumeServiceInterface,
+) *PollingCarddataHandler {
+	return &PollingCarddataHandler{
+		base:          base,
+		gateway:       gw,
+		iotCardStore:  iotCardStore,
+		carrierStore:  carrierStore,
+		usageService:  usageService,
+		stopResumeSvc: stopResumeSvc,
+	}
+}
+
+// Handle 处理流量检查任务
+func (h *PollingCarddataHandler) Handle(ctx context.Context, t *asynq.Task) error {
+	startTime := time.Now()
+
+	cardID, ok := parseTaskPayload(t.Payload(), h.base.logger)
+	if !ok {
+		return nil
+	}
+
+	if !h.base.acquireConcurrency(ctx, constants.TaskTypePollingCarddata) {
+		h.base.logger.Debug("并发已满，重新入队", zap.Uint("card_id", cardID))
+		return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingCarddata)
+	}
+	defer h.base.releaseConcurrency(ctx, constants.TaskTypePollingCarddata)
+
+	card, err := h.base.getCardWithCache(ctx, cardID)
+	if err != nil {
+		if isNotFound(err) {
+			return nil
+		}
+		h.base.logger.Error("获取卡信息失败", zap.Uint("card_id", cardID), zap.Error(err))
+		h.base.updateStats(ctx, constants.TaskTypePollingCarddata, false, time.Since(startTime))
+		return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingCarddata)
+	}
+
+	var gatewayFlowMB float64
+	if h.gateway != nil {
+		result, gwErr := h.gateway.QueryFlow(ctx, &gateway.FlowQueryReq{CardNo: card.ICCID})
+		if gwErr != nil {
+			h.base.logger.Warn("查询流量失败",
+				zap.Uint("card_id", cardID), zap.String("iccid", card.ICCID), zap.Error(gwErr))
+			h.base.updateStats(ctx, constants.TaskTypePollingCarddata, false, time.Since(startTime))
+			return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingCarddata)
+		}
+		gatewayFlowMB = result.Used
+	} else {
+		gatewayFlowMB = card.CurrentMonthUsageMB
+	}
+
+	now := time.Now()
+	resetDay := h.carrierStore.GetDataResetDay(ctx, card.CarrierID)
+	updates, flowIncrementMB, isCrossMonth := h.calculateFlowUpdates(card, gatewayFlowMB, now, resetDay)
+	updates["last_data_check_at"] = now
+
+	if updateErr := h.iotCardStore.UpdateFields(ctx, cardID, updates); updateErr != nil {
+		h.base.logger.Error("更新卡流量信息失败", zap.Uint("card_id", cardID), zap.Error(updateErr))
+	}
+
+	go h.base.insertDataUsageRecord(context.Background(), cardID, flowIncrementMB, now)
+
+	cacheUpdates := map[string]any{"last_gateway_reading_mb": gatewayFlowMB}
+	if isCrossMonth {
+		// 跨月时同步更新缓存中的本月开始日期和本月用量，避免下次从缓存读取时再次误判跨月
+		currentMonthStart := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, now.Location())
+		cacheUpdates["current_month_start_date"] = currentMonthStart.Unix()
+		if flowIncrementMB > 0 {
+			cacheUpdates["current_month_usage_mb"] = flowIncrementMB
+		} else {
+			cacheUpdates["current_month_usage_mb"] = float64(0)
+		}
+	}
+	h.base.updateCardCache(ctx, cardID, cacheUpdates)
+
+	if flowIncrementMB > 0 && h.usageService != nil {
+		if deductErr := h.usageService.DeductDataUsage(ctx, "iot_card", cardID, int64(flowIncrementMB)); deductErr != nil {
+			h.base.logger.Warn("套餐流量扣减失败",
+				zap.Uint("card_id", cardID), zap.Float64("increment_mb", flowIncrementMB), zap.Error(deductErr))
+		}
+	}
+
+	if h.stopResumeSvc != nil {
+		freshCard, loadErr := h.iotCardStore.GetByID(ctx, cardID)
+		if loadErr == nil {
+			if evalErr := h.stopResumeSvc.EvaluateAndAct(ctx, freshCard); evalErr != nil {
+				h.base.logger.Warn("流量检查后停复机评估失败",
+					zap.Uint("card_id", cardID), zap.Error(evalErr))
+			}
+		}
+	}
+
+	h.base.updateStats(ctx, constants.TaskTypePollingCarddata, true, time.Since(startTime))
+	return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingCarddata)
+}
+
+// calculateFlowUpdates 计算流量更新字段、增量和是否跨月
+// 决策13：完整迁移跨月流量边界检测逻辑（月份切换检测、上月总量保存、当月计数器重置）
+// 第三个返回值 isCrossMonth 供调用方同步更新 Redis 缓存，避免下次误判跨月
+func (h *PollingCarddataHandler) calculateFlowUpdates(card *model.IotCard, gatewayFlowMB float64, now time.Time, resetDay int) (map[string]any, float64, bool) {
+	updates := make(map[string]any)
+
+	increment := gatewayFlowMB - card.LastGatewayReadingMB
+	if increment < 0 {
+		if isResetWindow(now, resetDay) {
+			increment = gatewayFlowMB
+			h.base.logger.Info("检测到上游运营商重置",
+				zap.Uint("card_id", card.ID),
+				zap.Float64("gateway_flow", gatewayFlowMB),
+				zap.Float64("last_reading", card.LastGatewayReadingMB),
+				zap.Int("reset_day", resetDay))
+		} else {
+			h.base.logger.Warn("流量异常：非重置日出现值下降",
+				zap.Uint("card_id", card.ID),
+				zap.Float64("gateway_flow", gatewayFlowMB),
+				zap.Float64("last_reading", card.LastGatewayReadingMB))
+			increment = 0
+		}
+	}
+
+	updates["last_gateway_reading_mb"] = gatewayFlowMB
+
+	currentMonthStart := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, now.Location())
+	isCrossMonth := card.CurrentMonthStartDate == nil ||
+		card.CurrentMonthStartDate.Before(currentMonthStart)
+
+	if isCrossMonth {
+		h.base.logger.Info("检测到跨月，重置流量计数",
+			zap.Uint("card_id", card.ID),
+			zap.Float64("last_month_total", card.CurrentMonthUsageMB))
+		updates["last_month_total_mb"] = card.CurrentMonthUsageMB
+		updates["current_month_start_date"] = currentMonthStart
+		if increment > 0 {
+			updates["current_month_usage_mb"] = increment
+		} else {
+			updates["current_month_usage_mb"] = float64(0)
+		}
+	} else if increment > 0 {
+		updates["current_month_usage_mb"] = gorm.Expr("current_month_usage_mb + ?", increment)
+	}
+
+	if increment > 0 {
+		updates["data_usage_mb"] = gorm.Expr("data_usage_mb + ?", int64(increment))
+	}
+
+	if card.CurrentMonthStartDate == nil {
+		updates["current_month_start_date"] = currentMonthStart
+	}
+
+	return updates, increment, isCrossMonth
+}