package iot_card import ( "time" "context" "go.uber.org/zap" "github.com/google/uuid" carddomain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation" carrierthresholddomain "github.com/break/junhong_cmp_fiber/internal/domain/carrierthreshold" "github.com/break/junhong_cmp_fiber/internal/gateway" "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/pkg/constants" "github.com/break/junhong_cmp_fiber/pkg/errors" ) // ChannelThresholdLockGuard 判断卡在当前计费周期是否持有运营商通道流量阈值停机锁。 // 由通道阈值能力实现并注入,停复机服务只做前置拒绝判定,不复制周期与锁的规则。 type ChannelThresholdLockGuard interface { ChannelThresholdLocked(ctx context.Context, cardID uint) (bool, error) } // ChannelThresholdResumeDeniedMessage 是持通道阈值锁复机被拒的统一可读文案。 const ChannelThresholdResumeDeniedMessage = "该卡当前计费周期已达到运营商通道流量阈值并被锁定,禁止复机" // ChannelThresholdDenialSnapshotKey 是拒绝审计中标记「持通道阈值锁」的快照键。 const ChannelThresholdDenialSnapshotKey = "channel_threshold_lock" // SetChannelThresholdLockGuard 注入通道阈值持锁判定能力。 func (s *StopResumeService) SetChannelThresholdLockGuard(guard ChannelThresholdLockGuard) { if s == nil { return } s.channelThresholdGuard = guard } // StopCardForChannelThreshold 执行通道阈值达量停机。 // // 复用既有停机重试、Integration Log 与统一审计:成功后同一事务写回 network_status=offline、 // stop_reason=channel_threshold、stopped_at。返回的 outcome 始终携带可回填的结果分类 // (成功/失败/未知);error 只表示执行过程本身的基础设施故障(读卡、写审计或写卡失败), // 此时调用方不得据此判定终态,应保留 submitted 等待恢复扫描确认。 func (s *StopResumeService) StopCardForChannelThreshold(ctx context.Context, cardID uint) (carrierthresholddomain.CommandOutcome, error) { card, err := s.iotCardStore.GetByID(ctx, cardID) if err != nil { return carrierthresholddomain.CommandOutcome{}, errors.Wrap(errors.CodeDatabaseError, err, "读取通道阈值停机卡事实失败") } return s.stopCardWithRetry(ctx, card, constants.StopReasonChannelThreshold) } // ResumeCardForChannelThreshold 执行通道阈值新周期复机。 // // 复用既有复机重试、Integration Log 与统一审计;成功时在同一事务写回 network_status=online、 // resumed_at,并且只在该卡停因正是通道阈值时清除停因,绝不覆盖其他停因。 func (s *StopResumeService) ResumeCardForChannelThreshold(ctx context.Context, cardID uint) (carrierthresholddomain.CommandOutcome, error) { card, err := s.iotCardStore.GetByID(ctx, cardID) if err != nil { return carrierthresholddomain.CommandOutcome{}, errors.Wrap(errors.CodeDatabaseError, err, "读取通道阈值复机卡事实失败") } actionCode, summary := constants.AuditActionIotCardAutoStarted, "自动恢复 IoT 卡网络" attempt, integrationID, err := s.resumeCardWithRetry(ctx, card, actionCode, summary) if err != nil { return carrierthresholddomain.CommandOutcome{ IntegrationID: integrationID, Result: cardCommandAuditResult(err), }, err } fields := map[string]any{ "network_status": constants.NetworkStatusOnline, "resumed_at": time.Now(), } if card.StopReason == constants.StopReasonChannelThreshold { fields["stop_reason"] = "" } if err := s.updateCardAndAppendNetworkSeries(ctx, card, fields, constants.CardObservationSceneBusinessResume, "online", uuid.NewString(), actionCode, summary, attempt.log.IntegrationID); err != nil { if logErr := s.completeCardCommandAttempt(ctx, attempt, nil, false); logErr != nil { s.logger.Error("终结通道阈值复机 Integration Log 失败", zap.String("integration_id", attempt.log.IntegrationID), zap.Error(logErr)) } s.recordCardCommandAudit(ctx, card, actionCode, summary+"结果待核对", constants.AuditResultUnknown, attempt.log.IntegrationID, cardSnapshot(card), map[string]any{"requested_network_status": constants.NetworkStatusOnline}, err) // 运营商已成功但本地回写失败:按结果未知交恢复扫描查询确认。 return carrierthresholddomain.CommandOutcome{ IntegrationID: attempt.log.IntegrationID, Result: constants.AuditResultUnknown, }, err } s.reschedulePolling(ctx, card.ID) if logErr := s.completeCardCommandAttempt(ctx, attempt, nil, true); logErr != nil { return carrierthresholddomain.CommandOutcome{ IntegrationID: attempt.log.IntegrationID, Result: constants.AuditResultSuccess, }, errors.Wrap(errors.CodeDatabaseError, logErr, "终结通道阈值复机 Integration Log 失败") } s.logger.Info("通道阈值新周期复机成功", zap.Uint("card_id", card.ID), zap.String("iccid", card.ICCID)) return carrierthresholddomain.CommandOutcome{ IntegrationID: attempt.log.IntegrationID, Result: constants.AuditResultSuccess, }, nil } // ChannelThresholdResumeReady 判断通道阈值跨期解锁后的卡是否满足自动复机条件。 // // 条件全部复用既有单一事实源:有效主套餐、流量未耗尽、实名满足、非风险网关扩展,且不存在其他停机锁 // (停因为空或正是通道阈值本身)。返回的 reason 是不满足原因(可安全记录),满足时为空。 func (s *StopResumeService) ChannelThresholdResumeReady(ctx context.Context, cardID uint) (bool, string, error) { card, err := s.iotCardStore.GetByID(ctx, cardID) if err != nil { return false, "", errors.Wrap(errors.CodeDatabaseError, err, "读取通道阈值复机判定卡事实失败") } // 其他停机锁:风险网关扩展(风险停机/销户)或非通道阈值的停因。 if isRiskGatewayExtend(card.GatewayExtend) { return false, "网关扩展状态为风险停机或已销户,不自动复机", nil } if card.StopReason != "" && card.StopReason != constants.StopReasonChannelThreshold { return false, "存在其他停机原因,不自动复机", nil } hasPackage, err := s.hasValidPackage(ctx, card) if err != nil { return false, "", err } if !hasPackage { return false, "无有效主套餐,不自动复机", nil } exhausted, err := s.isTrafficExhausted(ctx, card) if err != nil { return false, "", err } if exhausted { return false, "套餐流量已耗尽,不自动复机", nil } realnameOK, err := s.isRealnameOK(ctx, card) if err != nil { return false, "", err } if !realnameOK { return false, "实名要求未满足,不自动复机", nil } return true, "", nil } // QueryChannelThresholdCardStatus 只查询运营商卡状态并映射为本地网络状态,供恢复扫描回填。 // // 不发起任何停复机调用:只做状态查询,并按既有网关状态映射规则给出本地网络状态。 // 查询失败把 known 置 false 并返回错误,调用方必须按「仍未确认」处理,不得判为失败终态。 func (s *StopResumeService) QueryChannelThresholdCardStatus(ctx context.Context, cardID uint) (int, bool, string, error) { card, err := s.iotCardStore.GetByID(ctx, cardID) if err != nil { return 0, false, "", errors.Wrap(errors.CodeDatabaseError, err, "读取通道阈值状态查询卡事实失败") } if s.gatewayClient == nil { return 0, false, "", errors.New(errors.CodeInternalError, "Gateway 未配置,无法查询卡状态") } attempt, err := s.startCardCommandAttempt(ctx, card, constants.IntegrationOperationGatewayNetwork, constants.CardObservationSceneCarrierThresholdRecovery, cardCommandSeriesKey(ctx), 1) if err != nil { return 0, false, "", err } response, callErr := s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{CardNo: card.ICCID}) if callErr != nil { if completeErr := s.completeCardCommandAttempt(ctx, attempt, callErr, false); completeErr != nil { s.logger.Error("终结通道阈值状态查询 Integration Log 失败", zap.String("integration_id", attempt.log.IntegrationID), zap.Error(completeErr)) } return 0, false, attempt.log.IntegrationID, callErr } if completeErr := s.completeCardCommandAttempt(ctx, attempt, nil, false); completeErr != nil { s.logger.Error("终结通道阈值状态查询 Integration Log 失败", zap.String("integration_id", attempt.log.IntegrationID), zap.Error(completeErr)) return 0, false, attempt.log.IntegrationID, completeErr } status, known := carddomain.MapGatewayNetworkStatus(response.CardStatus, response.Extend) return status, known, attempt.log.IntegrationID, nil } // ConfirmChannelThresholdCardState 按已确认的运营商结果补写卡状态,覆盖运营商调用成功但本地回写失败的场景。 // // offline=true 写回停机事实(停因为通道阈值);offline=false 写回在线事实,并且只在该卡停因 // 正是通道阈值时清除停因,绝不覆盖其他停因。卡状态与统一审计、观测序列在同一事务写入。 func (s *StopResumeService) ConfirmChannelThresholdCardState(ctx context.Context, cardID uint, offline bool) error { card, err := s.iotCardStore.GetByID(ctx, cardID) if err != nil { return errors.Wrap(errors.CodeDatabaseError, err, "读取通道阈值确认卡事实失败") } actionCode, summary := constants.AuditActionIotCardAutoStarted, "自动恢复 IoT 卡网络" scene, expected := constants.CardObservationSceneBusinessResume, "online" fields := map[string]any{ "network_status": constants.NetworkStatusOnline, "resumed_at": time.Now(), } if offline { actionCode, summary = constants.AuditActionIotCardAutoStopped, "自动停用 IoT 卡网络" scene, expected = constants.CardObservationSceneBusinessStop, "offline" fields = map[string]any{ "network_status": constants.NetworkStatusOffline, "stopped_at": time.Now(), "stop_reason": constants.StopReasonChannelThreshold, } } else if card.StopReason == constants.StopReasonChannelThreshold { fields["stop_reason"] = "" } return s.updateCardAndAppendNetworkSeries(ctx, card, fields, scene, expected, uuid.NewString(), actionCode, summary, "") } // channelThresholdBlocked 判断复机入口是否必须拒绝:卡在当前周期持有通道阈值停机锁。 // 判定失败直接返回错误,绝不在事实不可读时放开复机。 func (s *StopResumeService) channelThresholdBlocked(ctx context.Context, card *model.IotCard) (bool, error) { if s == nil || s.channelThresholdGuard == nil || card == nil || card.ID == 0 { return false, nil } return s.channelThresholdGuard.ChannelThresholdLocked(ctx, card.ID) } // recordChannelThresholdDenial 记录持锁复机被拒的事实:不改卡状态、不解除锁、不调用运营商。 func (s *StopResumeService) recordChannelThresholdDenial(ctx context.Context, card *model.IotCard, actionCode, summary string) { s.recordCardCommandAudit(ctx, card, actionCode, summary+"被拒绝", constants.AuditResultDenied, "", cardSnapshot(card), map[string]any{ChannelThresholdDenialSnapshotKey: true}, channelThresholdDenyError()) } // channelThresholdDenyError 返回持锁复机被拒的稳定业务错误(中文可读)。 func channelThresholdDenyError() error { return errors.New(errors.CodeForbidden, ChannelThresholdResumeDeniedMessage) }