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>

pkg/constants/iot.go

@@ -54,12 +54,14 @@ const (
 	NetworkStatusOnline  = 1 // 开机
 )
 
-// 任务 24.1: IoT 卡停机原因
+// IoT 卡停机原因
 const (
 	StopReasonTrafficExhausted = "traffic_exhausted" // 流量耗尽
 	StopReasonManual           = "manual"            // 手动停机
 	StopReasonArrears          = "arrears"           // 欠费
 	StopReasonProtectPeriod    = "protect_period"    // 保护期一致性检查自动停机
+	StopReasonNoPackage        = "no_package"        // 停机原因：无有效套餐
+	StopReasonNotRealname      = "not_realname"      // 停机原因：非行业卡且未完成实名认证
 )
 
 // 套餐流量类型

pkg/constants/polling.go

@@ -0,0 +1,23 @@
+package constants
+
+// PollingShardCount 轮询队列默认分片数
+// 千万级规模下，16 分片可将单队列深度控制在 ~60 万以内
+const PollingShardCount = 16
+
+// PollingBackpressureThreshold 单分片队列背压阈值
+// 超过此深度时，Scheduler 跳过该分片本轮出队，防止 Asynq 积压过载
+// 默认 50 万，可根据 Asynq Worker 处理速度调整
+const PollingBackpressureThreshold = 500_000
+
+// PollingDequeueMaxBatchSize Lua 脚本单次出队上限
+// 受 Lua unpack() 的 LUAI_MAXCSTACK 约 8000 限制，保守取 7000
+const PollingDequeueMaxBatchSize = 7000
+
+// PollingDefaultMaxConcurrency 并发信号量默认上限
+// 读取 Redis 配置 key 失败时使用，作为安全兜底值
+// 300：支撑 10M 卡、2小时 carddata 间隔（Gateway 200ms → 300并发 = 1500任务/秒/类型）
+const PollingDefaultMaxConcurrency = 300
+
+// PollingConcurrencyKeyTTL 并发计数 key 的过期时间（秒）
+// 保证 Worker 意外崩溃（defer Decr 未执行）时计数器在此时间内自动归零
+const PollingConcurrencyKeyTTL = 600 // 10 分钟

pkg/constants/redis.go

@@ -407,3 +407,23 @@ func RedisWechatConfigActiveKey() string {
 func RedisCardDailyTrafficKey(cardID uint, date string) string {
 	return fmt.Sprintf("traffic:daily:%d:%s", cardID, date)
 }
+
+// ========================================
+// 轮询分片队列相关 Redis Key
+// ========================================
+
+// RedisPollingShardQueueKey 轮询分片队列 Key
+// shardID: 分片编号（0 到 N-1）
+// taskType: 任务类型（realname/carddata/package/protect）
+// 格式：polling:shard:{shardID}:queue:{taskType}
+func RedisPollingShardQueueKey(shardID int, taskType string) string {
+	return fmt.Sprintf("polling:shard:%d:queue:%s", shardID, taskType)
+}
+
+// RedisPollingDeviceOpLockKey 设备维度停复机操作锁 Key
+// 防止设备下多张卡并发触发 EvaluateAndAct 导致重复 Gateway 调用
+// TTL 建议 30 秒（覆盖 stopDeviceCards/resumeDeviceCards 最长执行时间）
+// 格式：polling:device:op_lock:{deviceID}
+func RedisPollingDeviceOpLockKey(deviceID uint) string {
+	return fmt.Sprintf("polling:device:op_lock:%d", deviceID)
+}

pkg/openapi/handlers.go

@@ -54,7 +54,7 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		PollingAlert:                admin.NewPollingAlertHandler(nil),
 		PollingCleanup:              admin.NewPollingCleanupHandler(nil),
 		PollingManualTrigger:        admin.NewPollingManualTriggerHandler(nil),
-		Asset:                       admin.NewAssetHandler(nil, nil, nil),
+		Asset:                       admin.NewAssetHandler(nil, nil, nil, nil),
 		AssetWallet:                 admin.NewAssetWalletHandler(nil),
 		WechatConfig:                admin.NewWechatConfigHandler(nil),
 		AgentRecharge:               admin.NewAgentRechargeHandler(nil, nil),

pkg/queue/handler.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/break/junhong_cmp_fiber/internal/gateway"
 	"github.com/break/junhong_cmp_fiber/internal/polling"
+	iot_card_svc "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/internal/task"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -15,15 +16,17 @@ import (
 )
 
 type Handler struct {
-	mux             *asynq.ServeMux
-	logger          *zap.Logger
-	db              *gorm.DB
-	redis           *redis.Client
-	storage         *storage.Service
-	gatewayClient   *gateway.Client
-	pollingCallback task.PollingCallback
-	workerResult    *WorkerBootstrapResult
-	asynqClient     *asynq.Client
+	mux                  *asynq.ServeMux
+	logger               *zap.Logger
+	db                   *gorm.DB
+	redis                *redis.Client
+	storage              *storage.Service
+	gatewayClient        *gateway.Client
+	pollingCallback      task.PollingCallback
+	workerResult         *WorkerBootstrapResult
+	asynqClient          *asynq.Client
+	pollingBase          *task.PollingBase
+	pollingStopResumeSvc iot_card_svc.StopResumeServiceInterface
 }
 
 func NewHandler(
@@ -35,17 +38,21 @@ func NewHandler(
 	workerResult *WorkerBootstrapResult,
 	asynqClient *asynq.Client,
 	logger *zap.Logger,
+	pollingBase *task.PollingBase,
+	pollingStopResumeSvc iot_card_svc.StopResumeServiceInterface,
 ) *Handler {
 	return &Handler{
-		mux:             asynq.NewServeMux(),
-		logger:          logger,
-		db:              db,
-		redis:           redis,
-		storage:         storageSvc,
-		gatewayClient:   gatewayClient,
-		pollingCallback: pollingCallback,
-		workerResult:    workerResult,
-		asynqClient:     asynqClient,
+		mux:                  asynq.NewServeMux(),
+		logger:               logger,
+		db:                   db,
+		redis:                redis,
+		storage:              storageSvc,
+		gatewayClient:        gatewayClient,
+		pollingCallback:      pollingCallback,
+		workerResult:         workerResult,
+		asynqClient:          asynqClient,
+		pollingBase:          pollingBase,
+		pollingStopResumeSvc: pollingStopResumeSvc,
 	}
 }
 
@@ -149,26 +156,25 @@ func (h *Handler) registerCommissionCalculationHandler() {
 }
 
 func (h *Handler) registerPollingHandlers() {
-	pollingHandler := task.NewPollingHandler(
-		h.db,
-		h.redis,
-		h.asynqClient,
-		h.gatewayClient,
-		h.workerResult.Services.UsageService,
-		h.logger,
-	)
+	realnameHandler := task.NewPollingRealnameHandler(
+		h.pollingBase, h.gatewayClient, h.workerResult.Stores.IotCard,
+		h.asynqClient, h.pollingStopResumeSvc)
+	carrierStore := postgres.NewCarrierStore(h.db)
+	carddataHandler := task.NewPollingCarddataHandler(
+		h.pollingBase, h.gatewayClient, h.workerResult.Stores.IotCard,
+		carrierStore, h.workerResult.Services.UsageService, h.pollingStopResumeSvc)
+	packageHandler := task.NewPollingPackageHandler(
+		h.pollingBase, h.workerResult.Stores.IotCard,
+		h.pollingStopResumeSvc)
+	protectHandler := task.NewPollingProtectHandler(
+		h.pollingBase, h.gatewayClient, h.workerResult.Stores.IotCard,
+		h.workerResult.Stores.DeviceSimBinding, h.pollingStopResumeSvc)
 
-	h.mux.HandleFunc(constants.TaskTypePollingRealname, pollingHandler.HandleRealnameCheck)
-	h.logger.Info("注册实名检查任务处理器", zap.String("task_type", constants.TaskTypePollingRealname))
-
-	h.mux.HandleFunc(constants.TaskTypePollingCarddata, pollingHandler.HandleCarddataCheck)
-	h.logger.Info("注册流量检查任务处理器", zap.String("task_type", constants.TaskTypePollingCarddata))
-
-	h.mux.HandleFunc(constants.TaskTypePollingPackage, pollingHandler.HandlePackageCheck)
-	h.logger.Info("注册套餐检查任务处理器", zap.String("task_type", constants.TaskTypePollingPackage))
-
-	h.mux.HandleFunc(constants.TaskTypePollingProtect, pollingHandler.HandleProtectConsistencyCheck)
-	h.logger.Info("注册保护期一致性检查任务处理器", zap.String("task_type", constants.TaskTypePollingProtect))
+	h.mux.HandleFunc(constants.TaskTypePollingRealname, realnameHandler.Handle)
+	h.mux.HandleFunc(constants.TaskTypePollingCarddata, carddataHandler.Handle)
+	h.mux.HandleFunc(constants.TaskTypePollingPackage, packageHandler.Handle)
+	h.mux.HandleFunc(constants.TaskTypePollingProtect, protectHandler.Handle)
+	h.logger.Info("已注册轮询任务处理器（realname/carddata/package/protect）")
 }
 
 func (h *Handler) registerPackageActivationHandlers() {