junhong_cmp_fiber/openspec/changes/fix-polling-stop-logic/design.md

Context

轮询停复机系统（stop_resume_service.go + 三个轮询 Handler）存在三个已在生产环境触发的缺陷，均已通过日志 + DB 分析定位到根因：

1. 连坐停机（已复现）：设备 862639076038233 下 card_id=5（未实名）触发 checkStopReasons → not_realname → stopDeviceCards，将同设备已实名的 card_id=2、card_id=4 一并停机。
2. 无防抖误停（潜在风险）：polling_realname_handler 单次检测到实名逆转即触发停机，上游运营商同步延迟时单次 false 可导致误停。
3. carrier 停机状态不完整（已复现）：polling_cardstatus_handler 检测到网关侧停机时仅更新 network_status=0，stop_reason 留空，导致卡进入无法被自动复机的死锁状态。

涉及文件：

• internal/service/iot_card/stop_resume_service.go（EvaluateAndAct）
• internal/task/polling_realname_handler.go
• internal/task/polling_cardstatus_handler.go
• pkg/constants/iot.go
• pkg/constants/redis.go

Goals / Non-Goals

Goals:

• not_realname 停机仅影响被评估的单卡，不扩散至设备维度
• 实名逆转需连续 3 次才触发停机，消除上游单次误报
• 网关侧停机事件写入明确的 stop_reason，确保卡状态完整可追踪

Non-Goals:

• 不修改 no_package / traffic_exhausted 的设备维度停机逻辑（仍保持连带停机）
• 不引入数据库 schema 变更
• 不回填存量 stop_reason='' 的历史数据
• carrier_stopped 不纳入 isPollingStopReason（不自动复机，运营商停机需人工确认）

Decisions

决策 1：isDeviceScopeReason——停机范围判断

背景：not_realname 是单卡属性（每张卡独立实名），no_package / traffic_exhausted 是设备共享资源，两者停机范围语义完全不同。

方案：新增 isDeviceScopeReason(reason string) bool，仅 no_package / traffic_exhausted 返回 true。EvaluateAndAct 中，只有当 isDeviceScopeReason(primaryReason) 为 true 时才调用 stopDeviceCards；否则走 stopCardWithRetry（单卡）。

// 停机范围为设备维度的原因（套餐/流量是设备共享资源）
func isDeviceScopeReason(reason string) bool {
    return reason == constants.StopReasonNoPackage ||
        reason == constants.StopReasonTrafficExhausted
}

// EvaluateAndAct 修改后的在线分支
primaryReason := reasons[0]
if !card.IsStandalone && isDeviceScopeReason(primaryReason) {
    deviceID, bound, lookupErr := s.getCardDeviceID(ctx, card)
    if lookupErr == nil && bound {
        s.stopDeviceCards(ctx, deviceID, primaryReason)
        return nil
    }
}
return s.stopCardWithRetry(ctx, card, primaryReason)

边界确认：若卡同时满足 no_package + not_realname，primaryReason = "no_package"（优先级更高），走设备维度——符合预期（设备整体无套餐）。

---

决策 2：实名逆转防抖——Redis 滑动计数器

背景：运营商实名接口存在同步延迟，单次返回 false 不足以确认实名已失效。

方案：在 polling_realname_handler 检测到 1→0 逆转时，写入 Redis 计数器（INCR + 独立 TTL），仅当计数 >= 3 时才触发 EvaluateAndAct；检测到 true 时清除计数器。不修改 DB 写入逻辑（real_name_status 仍实时同步，只延迟停机决策）。

Redis Key:  polling:card:realname:reversal:{card_id}
TTL:        10 分钟（若 10 分钟内未连续触发，计数归零）
阈值:       3 次（常量 PollingRealnameReversalThreshold = 3）

流程：

gateway 返回 false（已更新 DB real_name_status=0）
  ↓
INCR polling:card:realname:reversal:{card_id}（TTL=10min）
  ├─ count < 3：仅记录，不触发停机，返回
  └─ count >= 3：DEL key → EvaluateAndAct（触发停机）

gateway 返回 true（已更新 DB real_name_status=1 或无变化）
  ↓
DEL polling:card:realname:reversal:{card_id}
若 DB 为 0→1：触发 EvaluateAndAct（复机评估，逻辑不变）

注意：INCR 仅在当前 newStatus == RealNameStatusNotVerified 时执行，不影响 true 的处理路径。

---

决策 3：carrier_stopped——网关侧停机原因

背景：polling_cardstatus_handler 通过轮询 Gateway 卡状态（非主动停机操作）检测到在线→停机变化，当前未写入 stop_reason，导致 isPollingStopReason('')=false，卡永久无法自动复机。

方案：

• 新增常量 StopReasonCarrierStopped = "carrier_stopped"
• polling_cardstatus_handler 在检测到在线→停机变化时，在 fields 中补写 stop_reason = carrier_stopped
• carrier_stopped 不加入 isPollingStopReason（运营商停机原因不明，不自动复机）
• carrier_stopped 作为合法状态存储，管理员可在后台查看并手动决策

// polling_cardstatus_handler.go 修改处
if statusChanged {
    fields["network_status"] = newNetworkStatus
    if newNetworkStatus == constants.NetworkStatusOffline {
        fields["stop_reason"] = constants.StopReasonCarrierStopped
    }
}

关于存量数据：已处于 stop_reason='' 的停机卡不回填，需运维人工处理（可通过 SQL 批量检查后决策）。

---

关于 resumeDeviceCards 的兼容性

现有 resumeDeviceCards 在遍历停机卡时已对 isRealnameOK 做过滤：

for _, card := range cards {
    if !s.isRealnameOK(card) {
        s.iotCardStore.UpdateStopReason(ctx, card.ID, constants.StopReasonNotRealname)
        continue
    }
    s.resumeSingleCard(ctx, card.ID)
}

修复后，not_realname 只停单卡，触发 resumeDeviceCards 的场景（no_package / traffic_exhausted 复机）不会遇到 not_realname 卡，此处逻辑仍保留作为防御性检查，无需修改。

Risks / Trade-offs

风险	评估	缓解
防抖计数 3 次意味着最多 ~3 分钟延迟停机	低风险，实名验证丢失通常是持续状态	阈值做成常量，可快速调整
carrier_stopped 卡无法自动复机，需人工处理	已接受（运营商停机原因不明，保守处理）	后台日志/状态可见，管理员可手动触发复机
不回填存量 stop_reason='' 数据	存量问题继续存在	运维可执行一次性 SQL 修复，超出本次 change 范围