feat: 卡流量改为日快照计量并统一停复机规则
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled

卡流量计量(按名单灰度,默认 off):
- 新增卡日快照与切换水位表(000241),按通道上游流量重置日换算自然月、重置日防旧值
- 已切换的卡按月对账产生增量,无生效中套餐只结算不发事件;第一次切换写水位
- 已切换卡读数有效即判定通道阈值,卡表本月用量用快照覆盖,日流量读快照
- 配置 JUNHONG_TRAFFIC_CALC_MODE/CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED

停复机规则(总开关 JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED,默认关闭):
- 复机不看停机原因,持通道阈值锁仍拒绝;暂停轮询的卡不自动停复机
- 通道新增实名管控 realname_control_enabled(000242,默认 0),开启后不区分行业卡与实名策略
- 实名管控从 0 改 1 需确认,修改并入通道更新审计

OpenSpec Change: rebuild-card-traffic-metering-and-stop-resume
This commit is contained in:
邹进
2026-10-20 17:49:26 +09:00
parent 44a05cf687
commit 96771a204f
37 changed files with 1859 additions and 98 deletions

View File

@@ -13,6 +13,7 @@ import (
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/outboxid"
"go.uber.org/zap"
"gorm.io/gorm"
"gorm.io/gorm/clause"
)
@@ -73,6 +74,24 @@ type Service struct {
auditWriter StateAuditWriter
// channelThreshold 为可选的通道阈值判定能力;未注入时流量观测不做阈值判定。
channelThreshold ChannelThresholdEvaluator
// trafficCalc 判定卡是否走日快照计量算法;未注入时全部卡走卡表基线算法且不写快照。
trafficCalc *TrafficCalcPolicy
// logger 记录快照写入失败等不影响观测结果的告警;未注入时不输出。
logger *zap.Logger
}
// SetTrafficCalcPolicy 注入卡流量计量切换策略与告警日志。
func (s *Service) SetTrafficCalcPolicy(policy *TrafficCalcPolicy, logger *zap.Logger) {
s.trafficCalc = policy
s.logger = logger
}
// warnLogger 返回可用的告警日志器。
func (s *Service) warnLogger() *zap.Logger {
if s.logger == nil {
return zap.NewNop()
}
return s.logger
}
// NewService 创建卡实名观测应用服务。

View File

@@ -8,6 +8,7 @@ import (
"gorm.io/gorm"
"gorm.io/gorm/clause"
cardflow "github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
domain "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/model"
@@ -53,6 +54,23 @@ func (s *Service) ApplyTrafficObservation(ctx context.Context, observation domai
return decisionErr
}
decision = nextDecision
// 已切换日快照算法的卡:增量、通道阈值与本月用量改由快照决定;读数为 0 或无效时不写快照、不产生增量。
switched := s.trafficCalc.Switched(card.ID)
var flow *switchedFlowOutcome
if switched && cardflow.ValidReading(observation.GatewayReadingMB) {
outcome, flowErr := s.applySwitchedFlow(ctx, tx, &card, observation, decision)
if flowErr != nil {
return flowErr
}
flow = outcome
}
if switched {
decision.IncrementMB = 0
if flow != nil {
decision.IncrementMB = flow.EmitMB
decision.CurrentMonthUsageMB = flow.MonthMaxMB
}
}
updates := map[string]any{
"last_data_check_at": observation.Metadata.ObservedAt, "last_sync_time": observation.Metadata.ObservedAt,
"current_month_start_date": decision.CurrentMonthStartDate, "last_month_total_mb": decision.LastMonthTotalMB,
@@ -71,6 +89,7 @@ func (s *Service) ApplyTrafficObservation(ctx context.Context, observation domai
return errors.New(errors.CodeConflict, "卡流量基线已被其他请求更新")
}
if decision.IncrementMB > 0 {
// 未切换卡沿用卡表基线算法的增量;已切换卡的增量已替换为按月对账结果,每次观测最多一条 V1 事件。
eventID := outboxid.Stable("card-traffic:", strconv.FormatUint(uint64(card.ID), 10)+":"+observation.Metadata.ObservationID+":incremented")
if err := s.eventWriter.AppendTraffic(ctx, tx, TrafficIncrementedEvent{
EventID: eventID, CardID: card.ID, IncrementMB: decision.IncrementMB,
@@ -81,12 +100,17 @@ func (s *Service) ApplyTrafficObservation(ctx context.Context, observation domai
return err
}
}
if decision.ReadingAccepted && s.channelThreshold != nil {
// 达量判定只使用本次已接受的网关累计读数,异常下降保护命中的观测不参与判定;
evaluateThreshold := decision.ReadingAccepted
if switched {
evaluateThreshold = switchedThresholdEvaluable(flow, decision.ReadingAccepted)
}
if evaluateThreshold && s.channelThreshold != nil {
// 未切换卡只使用本次已接受的网关累计读数,异常下降保护命中的观测不参与判定;
// 已切换卡读数有效且未被重置日防旧值处理即判定,不再受卡表基线影响。
// 判定失败必须回滚整个流量事务,与既有流量事实保持同事务语义。
if err := s.channelThreshold.EvaluateInTx(ctx, tx, carrierthresholddomain.Evaluation{
CardID: card.ID, CarrierID: card.CarrierID,
ReadingMB: decision.LastGatewayReadingMB, ObservedAt: observation.Metadata.ObservedAt,
ReadingMB: thresholdReading(switched, flow, observation, decision), ObservedAt: observation.Metadata.ObservedAt,
// 观测来源是判定端获取触发来源的唯一位置:命中留痕据此区分自动判定、人工同步与回调。
Source: observation.Metadata.Source,
}); err != nil {
@@ -152,5 +176,28 @@ func (s *Service) ApplyTrafficObservation(ctx context.Context, observation domai
if s.cache != nil {
s.cache.Invalidate(ctx, observation.CardID)
}
if auditedCard != nil && !s.trafficCalc.Switched(auditedCard.ID) {
s.writeUnswitchedSnapshot(ctx, auditedCard, observation)
}
return decision, nil
}
// switchedThresholdEvaluable 判定已切换卡本次是否做通道阈值判定:读数有效且本次未被防旧值按 0 处理;
// 第一次切换观测仍按卡表基线算法是否接受读数判定。
func switchedThresholdEvaluable(flow *switchedFlowOutcome, oldAccepted bool) bool {
if flow == nil {
return false
}
if flow.FirstSwitch {
return oldAccepted
}
return !flow.StaleGuarded
}
// thresholdReading 返回通道阈值判定使用的网关累计读数:已切换卡(非第一次切换观测)用本次读数。
func thresholdReading(switched bool, flow *switchedFlowOutcome, observation domain.TrafficObservation, decision domain.TrafficDecision) float64 {
if switched && flow != nil && !flow.FirstSwitch {
return observation.GatewayReadingMB
}
return decision.LastGatewayReadingMB
}

View File

@@ -0,0 +1,164 @@
package cardobservation
import (
"context"
"strconv"
"strings"
"go.uber.org/zap"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/config"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// 灰度名单中扣减载体的前缀。
const (
trafficCalcCarrierDevice = "device"
trafficCalcCarrierIotCard = "iot_card"
)
// TrafficCalcPolicy 判定卡是否走日快照计量算法,以及未切换卡是否写快照。
//
// 名单在进程启动时展开为内存卡集合,观测事务内只查内存、不查库;API 与全部 Worker 必须使用一致的配置。
// 零值策略等同于 off 模式且不写快照。
type TrafficCalcPolicy struct {
mode string
cards map[uint]struct{}
snapshotEnabled bool
}
// Switched 判定卡是否走日快照算法。
func (p *TrafficCalcPolicy) Switched(cardID uint) bool {
if p == nil {
return false
}
switch p.mode {
case config.TrafficCalcModeFull:
return true
case config.TrafficCalcModeGray:
_, ok := p.cards[cardID]
return ok
default:
return false
}
}
// SnapshotEnabled 判定未切换卡是否写日快照。
func (p *TrafficCalcPolicy) SnapshotEnabled() bool {
return p != nil && p.snapshotEnabled
}
// BuildTrafficCalcPolicy 按配置展开灰度名单:device 展开为当前绑定的全部卡;iot_card 实际使用设备套餐时
// 记录错误并跳过该项(不阻止启动)。展开查询失败时整体退回 off 模式,保证判定出错一律走卡表基线算法。
func BuildTrafficCalcPolicy(ctx context.Context, db *gorm.DB, cfg config.TrafficCalcConfig, logger *zap.Logger) *TrafficCalcPolicy {
if logger == nil {
logger = zap.NewNop()
}
policy := &TrafficCalcPolicy{mode: cfg.Mode, cards: map[uint]struct{}{}, snapshotEnabled: cfg.FlowSnapshotEnabled}
if cfg.Mode != config.TrafficCalcModeGray {
logger.Info("卡流量计量模式", zap.String("mode", cfg.Mode), zap.Bool("flow_snapshot_enabled", cfg.FlowSnapshotEnabled))
return policy
}
for _, item := range strings.Split(cfg.Cards, ",") {
item = strings.TrimSpace(item)
if item == "" {
continue
}
if err := policy.expandItem(ctx, db, item, logger); err != nil {
logger.Error("展开卡流量计量灰度名单失败,本进程全部卡走卡表基线算法", zap.String("item", item), zap.Error(err))
return &TrafficCalcPolicy{mode: config.TrafficCalcModeOff, snapshotEnabled: cfg.FlowSnapshotEnabled}
}
}
logger.Info("卡流量计量灰度名单已展开", zap.String("cards", cfg.Cards), zap.Int("card_count", len(policy.cards)))
return policy
}
// expandItem 展开一项扣减载体;格式非法或单卡实际用设备套餐时只记录错误并跳过,查询失败时返回错误。
func (p *TrafficCalcPolicy) expandItem(ctx context.Context, db *gorm.DB, item string, logger *zap.Logger) error {
kind, rawID, found := strings.Cut(item, ":")
id, parseErr := strconv.ParseUint(strings.TrimSpace(rawID), 10, 64)
if !found || parseErr != nil || id == 0 {
logger.Error("卡流量计量灰度名单项格式非法,已跳过", zap.String("item", item))
return nil
}
switch strings.TrimSpace(kind) {
case trafficCalcCarrierDevice:
var cardIDs []uint
if err := db.WithContext(ctx).Model(&model.DeviceSimBinding{}).
Where("device_id = ? AND bind_status = ?", id, constants.BindStatusBound).
Pluck("iot_card_id", &cardIDs).Error; err != nil {
return err
}
for _, cardID := range cardIDs {
p.cards[cardID] = struct{}{}
}
return nil
case trafficCalcCarrierIotCard:
usesDevice, err := cardUsesDevicePackage(ctx, db, uint(id))
if err != nil {
return err
}
if usesDevice {
logger.Error("灰度名单中的单卡实际从设备套餐扣减,已跳过;请改为按设备整台切换", zap.String("item", item))
return nil
}
p.cards[uint(id)] = struct{}{}
return nil
default:
logger.Error("卡流量计量灰度名单项载体类型非法,已跳过", zap.String("item", item))
return nil
}
}
// cardUsesDevicePackage 与套餐扣减的载体解析同口径:卡自身没有生效中套餐、且当前绑定设备有生效中套餐时,
// 卡的流量扣到设备套餐上。
func cardUsesDevicePackage(ctx context.Context, db *gorm.DB, cardID uint) (bool, error) {
ownActive, err := countActivePackages(ctx, db, "iot_card_id = ?", cardID)
if err != nil || ownActive > 0 {
return false, err
}
deviceID, bound, err := activeBoundDeviceID(ctx, db, cardID)
if err != nil || !bound {
return false, err
}
deviceActive, err := countActivePackages(ctx, db, "device_id = ?", deviceID)
return deviceActive > 0, err
}
// hasActivePackageForCard 判定卡本次增量是否有可扣的生效中套餐:卡自身或当前绑定设备存在生效中套餐。
func hasActivePackageForCard(ctx context.Context, db *gorm.DB, cardID uint) (bool, error) {
ownActive, err := countActivePackages(ctx, db, "iot_card_id = ?", cardID)
if err != nil || ownActive > 0 {
return ownActive > 0, err
}
deviceID, bound, err := activeBoundDeviceID(ctx, db, cardID)
if err != nil || !bound {
return false, err
}
deviceActive, err := countActivePackages(ctx, db, "device_id = ?", deviceID)
return deviceActive > 0, err
}
func countActivePackages(ctx context.Context, db *gorm.DB, carrierCondition string, carrierID uint) (int64, error) {
var count int64
err := db.WithContext(ctx).Model(&model.PackageUsage{}).
Where(carrierCondition, carrierID).
Where("status = ?", constants.PackageUsageStatusActive).
Count(&count).Error
return count, err
}
func activeBoundDeviceID(ctx context.Context, db *gorm.DB, cardID uint) (uint, bool, error) {
var deviceIDs []uint
if err := db.WithContext(ctx).Model(&model.DeviceSimBinding{}).
Where("iot_card_id = ? AND bind_status = ?", cardID, constants.BindStatusBound).
Limit(1).Pluck("device_id", &deviceIDs).Error; err != nil {
return 0, false, err
}
if len(deviceIDs) == 0 {
return 0, false, nil
}
return deviceIDs[0], true, nil
}

View File

@@ -0,0 +1,150 @@
package cardobservation
import (
"context"
"time"
"go.uber.org/zap"
"gorm.io/gorm"
cardflow "github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// unswitchedSnapshotTimeout 是未切换卡在观测事务提交后写快照的超时,超时只告警。
const unswitchedSnapshotTimeout = 3 * time.Second
// switchedFlowOutcome 是已切换卡一次观测的日快照计量结果。
type switchedFlowOutcome struct {
// EmitMB 是本次应写入 V1 流量事件的增量,0 表示不写事件。
EmitMB float64
// MonthMaxMB 是写入本次快照后的本月最大快照,用于覆盖卡表本月用量。
MonthMaxMB float64
// StaleGuarded 为 true 表示本次读数在重置日触发防旧值、按 0 计。
StaleGuarded bool
// FirstSwitch 为 true 表示这是卡的第一次切换观测(本次写入了切换水位)。
FirstSwitch bool
}
// snapshotResult 是一次快照换算与写入的结果。
type snapshotResult struct {
flowDate time.Time
conversion cardflow.Conversion
}
// writeSnapshot 按卡所属通道的重置日换算并原子写入当天快照;读数必须已通过 cardflow.ValidReading。
func (s *Service) writeSnapshot(ctx context.Context, db *gorm.DB, card *model.IotCard, readingMB float64, observedAt time.Time) (snapshotResult, error) {
resetDay := s.strictResetDay(ctx, db, card)
flowDate := cardflow.ShanghaiDate(observedAt)
days := postgres.NewCardFlowDayStore(db)
monthCtx, err := days.MonthContext(ctx, card.ID, flowDate, resetDay)
if err != nil {
return snapshotResult{}, errors.Wrap(errors.CodeDatabaseError, err, "查询卡日流量快照失败")
}
conversion := cardflow.Convert(readingMB, flowDate.Day(), resetDay, monthCtx)
if err := days.Upsert(ctx, postgres.CardFlowSnapshotWrite{
CardID: card.ID, FlowDate: flowDate, MonthUsedMB: conversion.MonthUsedMB,
VendorUsedMB: readingMB, StaleGuarded: conversion.StaleGuarded,
}); err != nil {
return snapshotResult{}, errors.Wrap(errors.CodeDatabaseError, err, "写入卡日流量快照失败")
}
return snapshotResult{flowDate: flowDate, conversion: conversion}, nil
}
// strictResetDay 在当前连接内按卡的 carrier_id 读取上游流量重置日,不使用调用方预先计算的值;
// 查询失败、为空或非法时按卡的运营商类型兜底(联通 27,其余 1)并记录日志。
func (s *Service) strictResetDay(ctx context.Context, db *gorm.DB, card *model.IotCard) int {
var days []int
queryErr := db.WithContext(ctx).Model(&model.Carrier{}).
Where("id = ?", card.CarrierID).Limit(1).Pluck("data_reset_day", &days).Error
queried := 0
if len(days) > 0 {
queried = days[0]
}
resetDay, fallback := cardflow.ResolveResetDay(queried, queryErr == nil && len(days) > 0, card.CarrierType)
if fallback {
s.warnLogger().Warn("通道上游流量重置日不可用,按运营商类型兜底",
zap.Uint("card_id", card.ID), zap.Uint("carrier_id", card.CarrierID),
zap.String("carrier_type", card.CarrierType), zap.Int("queried", queried),
zap.Int("reset_day", resetDay), zap.Error(queryErr))
}
return resetDay
}
// applySwitchedFlow 在观测事务内为已切换卡写快照、按月对账结算增量,并在第一次切换观测时写切换水位。
//
// oldDecision 是卡表基线算法对本次观测的结果:只在第一次切换观测时沿用其增量,此后不再使用。
func (s *Service) applySwitchedFlow(ctx context.Context, tx *gorm.DB, card *model.IotCard, observation domain.TrafficObservation, oldDecision domain.TrafficDecision) (*switchedFlowOutcome, error) {
readingMB := observation.GatewayReadingMB
snapshot, err := s.writeSnapshot(ctx, tx, card, readingMB, observation.Metadata.ObservedAt)
if err != nil {
return nil, err
}
days := postgres.NewCardFlowDayStore(tx)
monthMax, settled, err := days.MonthTotals(ctx, card.ID, snapshot.flowDate)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡本月流量结算失败")
}
hasPackage, pkgErr := hasActivePackageForCard(ctx, tx, card.ID)
if pkgErr != nil {
// 判断出错按有套餐处理,保持不丢量。
s.warnLogger().Warn("判断卡是否有生效中套餐失败,按有套餐处理", zap.Uint("card_id", card.ID), zap.Error(pkgErr))
hasPackage = true
}
outcome := &switchedFlowOutcome{MonthMaxMB: monthMax, StaleGuarded: snapshot.conversion.StaleGuarded}
switches := postgres.NewCardFlowSwitchStore(tx)
watermark, err := switches.Get(ctx, card.ID)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量切换水位失败")
}
if watermark == nil {
return outcome, s.firstSwitch(ctx, tx, card, observation, oldDecision, snapshot.flowDate, monthMax, settled, hasPackage, outcome)
}
delta := cardflow.MonthlyDelta(monthMax, settled)
if delta <= 0 {
return outcome, nil
}
if err := days.AddSettled(ctx, card.ID, snapshot.flowDate, delta); err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "结算卡流量增量失败")
}
if hasPackage {
outcome.EmitMB = delta
}
return outcome, nil
}
// firstSwitch 处理第一次切换观测:本次沿用卡表基线算法的增量,此前部分记为已结算,并写入切换水位。
func (s *Service) firstSwitch(ctx context.Context, tx *gorm.DB, card *model.IotCard, observation domain.TrafficObservation,
oldDecision domain.TrafficDecision, flowDate time.Time, monthMax, settled float64, hasPackage bool, outcome *switchedFlowOutcome) error {
outcome.FirstSwitch = true
if oldDecision.IncrementMB > 0 && hasPackage {
outcome.EmitMB = oldDecision.IncrementMB
}
if err := postgres.NewCardFlowDayStore(tx).AddSettled(ctx, card.ID, flowDate, cardflow.MonthlyDelta(monthMax, settled)); err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "结算卡流量切换前用量失败")
}
if err := postgres.NewCardFlowSwitchStore(tx).Create(ctx, &model.CardFlowSwitch{
IotCardID: card.ID, SwitchedAt: observation.Metadata.ObservedAt, MonthUsedMB: monthMax,
VendorUsedMB: observation.GatewayReadingMB, OldBaselineMB: card.LastGatewayReadingMB,
OldMonthUsageMB: card.CurrentMonthUsageMB, OldReadingAccepted: oldDecision.ReadingAccepted,
OldIncrementMB: oldDecision.IncrementMB,
}); err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡流量切换水位失败")
}
return nil
}
// writeUnswitchedSnapshot 在观测事务提交后为未切换卡写快照;失败只告警,不影响本次观测结果。
func (s *Service) writeUnswitchedSnapshot(ctx context.Context, card *model.IotCard, observation domain.TrafficObservation) {
if card == nil || !s.trafficCalc.SnapshotEnabled() || !cardflow.ValidReading(observation.GatewayReadingMB) {
return
}
writeCtx, cancel := context.WithTimeout(ctx, unswitchedSnapshotTimeout)
defer cancel()
if _, err := s.writeSnapshot(writeCtx, s.db, card, observation.GatewayReadingMB, observation.Metadata.ObservedAt); err != nil {
s.warnLogger().Warn("未切换卡写日流量快照失败,不影响本次观测", zap.Uint("card_id", card.ID), zap.Error(err))
}
}

View File

@@ -14,8 +14,8 @@ import (
// EvaluateInTx 在流量观测事务内判定通道阈值,达量时写周期锁并同事务写停机事件。
//
// 判定前提由调用方保证:只有「读数被接受」(ReadingAccepted)的观测才进入本方法,
// 异常下降保护命中的观测不参与判定。重复达量观测由部分唯一索引的 23505 识别为
// 判定前提由调用方保证:未切换日快照算法的卡只有「读数被接受」(ReadingAccepted)的观测才进入本方法,
// 异常下降保护命中的观测不参与判定;已切换的卡读数有效且未被重置日防旧值处理即进入本方法。重复达量观测由部分唯一索引的 23505 识别为
// 「该周期已处理」并幂等跳过:不重复建锁、不重复写停机事件,该冲突与流量基线 CAS 的
// CodeConflict 语义不同,绝不能混流。返回错误表示必须整体回滚(与既有流量事实同事务)。
func (s *Service) EvaluateInTx(ctx context.Context, tx *gorm.DB, evaluation domain.Evaluation) error {

View File

@@ -201,6 +201,12 @@ func initServices(s *stores, deps *Dependencies) *services {
cardObservationService.SetStateAuditWriter(iotCard)
// 运营商通道流量阈值达量判定嵌入流量观测事务:与卡流量事实同事务写周期锁与停机事件。
cardObservationService.SetChannelThresholdEvaluator(carrierThresholdService)
// 卡流量计量切换策略:启动时展开灰度名单为内存卡集合,API 与全部 Worker 必须使用一致配置。
var trafficCalcPolicy *cardObservationApp.TrafficCalcPolicy
if cfg := config.Get(); cfg != nil {
trafficCalcPolicy = cardObservationApp.BuildTrafficCalcPolicy(context.Background(), deps.DB, cfg.TrafficCalc, deps.Logger)
}
cardObservationService.SetTrafficCalcPolicy(trafficCalcPolicy, deps.Logger)
iotCard.SetCardObservationService(cardObservationService)
iotCard.SetSpeedTierIntegrationLog(integrationlog.NewRepository(deps.DB))
seriesCoordinator := cardObservationInfra.NewSeriesCoordinator(deps.Redis)
@@ -550,7 +556,7 @@ func initServices(s *stores, deps *Dependencies) *services {
AgentRechargePaymentConfirm: agentRechargePaymentConfirm,
AgentRechargeVoucherOCR: agentRechargeVoucherOCR,
PackageActivation: packageActivation,
TrafficQuery: trafficSvc.NewQueryService(deps.Redis, s.CardDailyUsage),
TrafficQuery: trafficSvc.NewQueryService(deps.Redis, s.CardDailyUsage).WithFlowSnapshots(trafficCalcPolicy.Switched, postgres.NewCardFlowDayStore(deps.DB)),
OperationPassword: operationPassword,
AgentOpenAPI: agentOpenAPI,
Refund: refundService,

View File

@@ -1,6 +1,10 @@
package bootstrap
import (
"context"
"github.com/break/junhong_cmp_fiber/pkg/config"
assetAutoRenewalApp "github.com/break/junhong_cmp_fiber/internal/application/assetautorenewal"
cardObservationApp "github.com/break/junhong_cmp_fiber/internal/application/cardobservation"
carrierThresholdApp "github.com/break/junhong_cmp_fiber/internal/application/carrierthreshold"
@@ -120,6 +124,11 @@ func initWorkerServices(stores *queue.WorkerStores, deps *WorkerDependencies) *q
cardObservationService.SetStateAuditWriter(iotCardAuditService)
// 运营商通道流量阈值达量判定嵌入流量观测事务:与卡流量事实同事务写周期锁与停机事件。
cardObservationService.SetChannelThresholdEvaluator(carrierThresholdService)
// 卡流量计量切换策略:启动时展开灰度名单为内存卡集合,API 与全部 Worker 必须使用一致配置。
if cfg := config.Get(); cfg != nil {
cardObservationService.SetTrafficCalcPolicy(
cardObservationApp.BuildTrafficCalcPolicy(context.Background(), deps.DB, cfg.TrafficCalc, deps.Logger), deps.Logger)
}
cardObservationIntegration := integrationlog.NewRepository(deps.DB)
cardObservationSeriesCoordinator := cardObservationInfra.NewSeriesCoordinator(deps.Redis)
cardObservationSeriesService := cardObservationApp.NewSeriesAttemptService(

View File

@@ -0,0 +1,5 @@
// Package cardflow 提供卡日流量快照计量的纯领域规则:自然月换算、重置日防旧值、按月对账增量与每天用量。
//
// 规则照搬老卡管:每卡每天一条「本月自然月累计」快照,任意区间用量 = 区间内最大快照 − 区间开始前最大快照。
// 本包不依赖数据库、Redis 或外部 SDK,取值由调用方从快照存储查询后传入。
package cardflow

View File

@@ -0,0 +1,126 @@
package cardflow
import (
"math"
"strings"
"time"
)
// 计量规则常量。
const (
// StaleGuardRatio 是重置日防旧值阈值:重置日读数超过比较基准的该倍数时按 0 计。
StaleGuardRatio = 0.9
// MinResetDay 与 MaxResetDay 是通道上游流量重置日的合法范围。
MinResetDay = 1
MaxResetDay = 28
// FallbackResetDayCUCC 是联通卡重置日查询失败时的兜底值。
FallbackResetDayCUCC = 27
// FallbackResetDayDefault 是非联通卡重置日查询失败时的兜底值。
FallbackResetDayDefault = 1
// carrierTypeCUCC 是联通运营商类型编码。
carrierTypeCUCC = "CUCC"
)
// shanghaiLocation 是快照日期与周期边界的固定时区。
var shanghaiLocation = time.FixedZone("Asia/Shanghai", 8*60*60)
// ShanghaiDate 返回观测时刻对应的上海日期(当天 0 点)。
func ShanghaiDate(t time.Time) time.Time {
local := t.In(shanghaiLocation)
return time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, shanghaiLocation)
}
// MonthStart 返回日期所在自然月 1 号(上海时区)。
func MonthStart(date time.Time) time.Time {
local := date.In(shanghaiLocation)
return time.Date(local.Year(), local.Month(), 1, 0, 0, 0, 0, shanghaiLocation)
}
// ResolveResetDay 返回可用的重置日;查询失败或取值非法时按运营商类型兜底,fallback 为 true 表示使用了兜底值。
func ResolveResetDay(queried int, queryOK bool, carrierType string) (resetDay int, fallback bool) {
if queryOK && queried >= MinResetDay && queried <= MaxResetDay {
return queried, false
}
if strings.EqualFold(strings.TrimSpace(carrierType), carrierTypeCUCC) {
return FallbackResetDayCUCC, true
}
return FallbackResetDayDefault, true
}
// MonthContext 是换算与防旧值需要的已有快照取值,均为自然月累计(MB)。
type MonthContext struct {
// ThisMonthBeforeResetMax 是本月 1 号~重置日前一天的最大快照。
ThisMonthBeforeResetMax float64
// PrevMonthMax 是上月最大快照。
PrevMonthMax float64
// PrevMonthBeforeResetMax 是上月 1 号~重置日前一天的最大快照。
PrevMonthBeforeResetMax float64
}
// Conversion 是一次读数换算为自然月累计的结果。
type Conversion struct {
// MonthUsedMB 是换算后的本月自然月累计。
MonthUsedMB float64
// StaleGuarded 为 true 表示本次读数在重置日触发了防旧值、按 0 参与换算。
StaleGuarded bool
}
// Convert 把运营商周期读数换算为自然月累计,并在重置日当天应用防旧值。
//
// 重置日为 1 时运营商周期即自然月;重置日大于 1 时:日号 ≥ 重置日累加本月重置日前的最大快照,
// 日号 < 重置日扣除上月重置日及以后的用量(上月最大 − 上月重置日前最大),结果小于 0 按 0。
func Convert(readingMB float64, day int, resetDay int, ctx MonthContext) Conversion {
reading := readingMB
guarded := isStale(readingMB, day, resetDay, ctx)
if guarded {
reading = 0
}
var month float64
switch {
case resetDay <= 1:
month = reading
case day >= resetDay:
month = reading + ctx.ThisMonthBeforeResetMax
default:
month = reading - (ctx.PrevMonthMax - ctx.PrevMonthBeforeResetMax)
}
return Conversion{MonthUsedMB: nonNegative(round3(month)), StaleGuarded: guarded}
}
// isStale 判断重置日当天的读数是否仍接近上周期总量。
func isStale(readingMB float64, day int, resetDay int, ctx MonthContext) bool {
if day != resetDay || readingMB <= 0 {
return false
}
if resetDay <= 1 {
return readingMB > ctx.PrevMonthMax*StaleGuardRatio
}
return ctx.ThisMonthBeforeResetMax > 0 && readingMB > ctx.ThisMonthBeforeResetMax*StaleGuardRatio
}
// MonthlyDelta 返回按月对账的待结算增量:本月最大快照 − 本月已结算合计,不大于 0 时返回 0。
func MonthlyDelta(monthMaxMB float64, settledSumMB float64) float64 {
return nonNegative(round3(monthMaxMB - settledSumMB))
}
// DailyUsage 返回某天用量:当天最大快照 − 本月此前最大快照,小于 0 按 0;本月第一条快照时 priorMax 传 0。
func DailyUsage(dayMaxMB float64, priorMaxMB float64) float64 {
return nonNegative(round3(dayMaxMB - priorMaxMB))
}
// ValidReading 判断运营商读数能否写入快照:必须为有限正数。
func ValidReading(readingMB float64) bool {
return !math.IsNaN(readingMB) && !math.IsInf(readingMB, 0) && readingMB > 0
}
func nonNegative(v float64) float64 {
if v < 0 {
return 0
}
return v
}
// round3 按快照列精度(三位小数)取整,避免浮点误差产生极小的虚假增量。
func round3(v float64) float64 {
return math.Round(v*1000) / 1000
}

View File

@@ -0,0 +1,44 @@
package model
import "time"
// CardFlowDay 卡日流量快照:每卡每天一条本月自然月累计。
//
// MonthUsedMB 按通道上游流量重置日换算为自然月累计,同一天只增不减;SettledMB 是当天已结算的增量合计
// (发出的增量、无生效套餐时丢弃的增量、切换时视为老算法已结算的部分)。由观测链路原子写入,永久保留。
type CardFlowDay struct {
ID uint `gorm:"column:id;primaryKey" json:"id"`
IotCardID uint `gorm:"column:iot_card_id;type:bigint;not null;uniqueIndex:uk_card_flow_day_card_date" json:"iot_card_id"`
FlowDate time.Time `gorm:"column:flow_date;type:date;not null;uniqueIndex:uk_card_flow_day_card_date" json:"flow_date"`
MonthUsedMB float64 `gorm:"column:month_used_mb;type:numeric(14,3);not null;default:0" json:"month_used_mb"`
VendorUsedMB float64 `gorm:"column:vendor_used_mb;type:numeric(14,3);not null;default:0" json:"vendor_used_mb"`
SettledMB float64 `gorm:"column:settled_mb;type:numeric(14,3);not null;default:0" json:"settled_mb"`
StaleGuarded bool `gorm:"column:stale_guarded;not null;default:false" json:"stale_guarded"`
ObsCount int `gorm:"column:obs_count;not null;default:0" json:"obs_count"`
CreatedAt time.Time `gorm:"column:created_at;autoCreateTime" json:"created_at"`
UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime" json:"updated_at"`
}
// TableName 指定表名
func (CardFlowDay) TableName() string {
return "tb_card_flow_day"
}
// CardFlowSwitch 卡流量计量切换水位:卡第一次走新算法时写入,退回老算法时由维护者删除。
type CardFlowSwitch struct {
ID uint `gorm:"column:id;primaryKey" json:"id"`
IotCardID uint `gorm:"column:iot_card_id;type:bigint;not null;uniqueIndex:uk_card_flow_switch_card" json:"iot_card_id"`
SwitchedAt time.Time `gorm:"column:switched_at;type:timestamptz;not null" json:"switched_at"`
MonthUsedMB float64 `gorm:"column:month_used_mb;type:numeric(14,3);not null;default:0" json:"month_used_mb"`
VendorUsedMB float64 `gorm:"column:vendor_used_mb;type:numeric(14,3);not null;default:0" json:"vendor_used_mb"`
OldBaselineMB float64 `gorm:"column:old_baseline_mb;type:numeric(14,3);not null;default:0" json:"old_baseline_mb"`
OldMonthUsageMB float64 `gorm:"column:old_month_usage_mb;type:numeric(14,3);not null;default:0" json:"old_month_usage_mb"`
OldReadingAccepted bool `gorm:"column:old_reading_accepted;not null;default:false" json:"old_reading_accepted"`
OldIncrementMB float64 `gorm:"column:old_increment_mb;type:numeric(14,3);not null;default:0" json:"old_increment_mb"`
CreatedAt time.Time `gorm:"column:created_at;autoCreateTime" json:"created_at"`
}
// TableName 指定表名
func (CardFlowSwitch) TableName() string {
return "tb_card_flow_switch"
}

View File

@@ -22,6 +22,9 @@ type Carrier struct {
TrafficThresholdValue *float64 `gorm:"column:traffic_threshold_value;type:numeric(18,2);comment:通道流量阈值数值,单位由 traffic_threshold_unit 决定" json:"traffic_threshold_value"`
// TrafficThresholdUnit 是阈值单位,取值 MB/GB(1 GB = 1024 MB),换算后与网关累计读数同单位比较;空字符串表示未配置。
TrafficThresholdUnit string `gorm:"column:traffic_threshold_unit;type:varchar(8);not null;default:'';comment:通道流量阈值单位 MB/GB,空字符串-未配置" json:"traffic_threshold_unit"`
// RealnameControlEnabled 是通道实名管控开关,取值 0-不管控(默认)1-管控;只用于停复机,
// 且只在停复机新规则总开关开启后参与判断,不复用 RealnameLinkType 等现有实名字段。
RealnameControlEnabled int `gorm:"column:realname_control_enabled;type:smallint;not null;default:0;comment:通道实名管控 0-不管控 1-管控" json:"realname_control_enabled"`
}
// TableName 指定表名

View File

@@ -13,15 +13,17 @@ type CreateCarrierRequest struct {
TrafficThresholdEnabled *int `json:"traffic_threshold_enabled" validate:"omitempty,oneof=0 1" description:"通道流量阈值是否启用 (0:禁用, 1:启用),仅超级管理员与平台账号可配置"`
TrafficThresholdValue *float64 `json:"traffic_threshold_value" validate:"omitempty,gt=0" description:"通道流量阈值数值,必须为正数,单位由 traffic_threshold_unit 决定,仅超级管理员与平台账号可配置"`
TrafficThresholdUnit *string `json:"traffic_threshold_unit" validate:"omitempty,oneof=MB GB" description:"通道流量阈值单位 (MB:兆字节, GB:吉字节,1 GB = 1024 MB),仅超级管理员与平台账号可配置"`
RealnameControlEnabled *int `json:"realname_control_enabled" validate:"omitempty,oneof=0 1" description:"通道实名管控 (0:不管控, 1:管控),默认0;只在停复机新规则开启后影响停复机:管控时未实名卡停机、实名后才复机。仅超级管理员与平台账号可配置"`
}
// HasTrafficThresholdFields 判断请求是否携带通道流量阈值字段。
// 非超管、非平台账号提交携带阈值字段的请求必须被整体拒绝。
// HasTrafficThresholdFields 判断请求是否携带仅平台账号可配置的通道字段(通道流量阈值、通道实名管控)。
// 非超管、非平台账号提交携带这些字段的请求必须被整体拒绝。
func (r *CreateCarrierRequest) HasTrafficThresholdFields() bool {
if r == nil {
return false
}
return r.TrafficThresholdEnabled != nil || r.TrafficThresholdValue != nil || r.TrafficThresholdUnit != nil
return r.TrafficThresholdEnabled != nil || r.TrafficThresholdValue != nil || r.TrafficThresholdUnit != nil ||
r.RealnameControlEnabled != nil
}
type UpdateCarrierRequest struct {
@@ -33,15 +35,18 @@ type UpdateCarrierRequest struct {
TrafficThresholdEnabled *int `json:"traffic_threshold_enabled" validate:"omitempty,oneof=0 1" description:"通道流量阈值是否启用 (0:禁用, 1:启用),仅超级管理员与平台账号可配置"`
TrafficThresholdValue *float64 `json:"traffic_threshold_value" validate:"omitempty,gt=0" description:"通道流量阈值数值,必须为正数,单位由 traffic_threshold_unit 决定,仅超级管理员与平台账号可配置"`
TrafficThresholdUnit *string `json:"traffic_threshold_unit" validate:"omitempty,oneof=MB GB" description:"通道流量阈值单位 (MB:兆字节, GB:吉字节,1 GB = 1024 MB),仅超级管理员与平台账号可配置"`
RealnameControlEnabled *int `json:"realname_control_enabled" validate:"omitempty,oneof=0 1" description:"通道实名管控 (0:不管控, 1:管控),默认0;只在停复机新规则开启后影响停复机:管控时未实名卡停机、实名后才复机。仅超级管理员与平台账号可配置"`
RealnameControlConfirm *bool `json:"realname_control_confirm" description:"把实名管控从 0 改为 1 时必须传 true,确认该通道未实名的开机卡会在下一次评估时被停机"`
}
// HasTrafficThresholdFields 判断请求是否携带通道流量阈值字段。
// 非超管、非平台账号提交携带阈值字段的请求必须被整体拒绝。
// HasTrafficThresholdFields 判断请求是否携带仅平台账号可配置的通道字段(通道流量阈值、通道实名管控)。
// 非超管、非平台账号提交携带这些字段的请求必须被整体拒绝。
func (r *UpdateCarrierRequest) HasTrafficThresholdFields() bool {
if r == nil {
return false
}
return r.TrafficThresholdEnabled != nil || r.TrafficThresholdValue != nil || r.TrafficThresholdUnit != nil
return r.TrafficThresholdEnabled != nil || r.TrafficThresholdValue != nil || r.TrafficThresholdUnit != nil ||
r.RealnameControlEnabled != nil
}
type CarrierListRequest struct {
@@ -70,6 +75,7 @@ type CarrierResponse struct {
TrafficThresholdEnabled *int `json:"traffic_threshold_enabled,omitempty" description:"通道流量阈值是否启用 (0:禁用, 1:启用),仅超级管理员与平台账号可见"`
TrafficThresholdValue *float64 `json:"traffic_threshold_value,omitempty" description:"通道流量阈值数值,单位由 traffic_threshold_unit 决定,未配置时不返回,仅超级管理员与平台账号可见"`
TrafficThresholdUnit *string `json:"traffic_threshold_unit,omitempty" description:"通道流量阈值单位 (MB:兆字节, GB:吉字节,1 GB = 1024 MB),未配置时不返回,仅超级管理员与平台账号可见"`
RealnameControlEnabled *int `json:"realname_control_enabled,omitempty" description:"通道实名管控 (0:不管控, 1:管控),仅超级管理员与平台账号可见"`
CreatedAt string `json:"created_at" description:"创建时间"`
UpdatedAt string `json:"updated_at" description:"更新时间"`
}

View File

@@ -70,10 +70,13 @@ func registerCarrierRoutes(router fiber.Router, handler *admin.CarrierHandler, d
Register(carriers, doc, groupPath, "PUT", "/:id", handler.Update, RouteSpec{
Summary: "更新运营商",
Tags: []string{"运营商管理"},
Input: new(dto.UpdateCarrierParams),
Output: new(dto.CarrierResponse),
Auth: true,
Description: "通道流量阈值与通道实名管控(realname_control_enabled)仅超级管理员与平台账号可修改,非平台账号携带即整体拒绝;" +
"实名管控从 0 改为 1 时必须携带 realname_control_confirm=true,未确认时返回该通道未实名开机卡数且不保存;" +
"修改并入运营商更新审计",
Tags: []string{"运营商管理"},
Input: new(dto.UpdateCarrierParams),
Output: new(dto.CarrierResponse),
Auth: true,
})
Register(carriers, doc, groupPath, "DELETE", "/:id", handler.Delete, RouteSpec{

View File

@@ -2,6 +2,7 @@ package carrier
import (
"context"
"fmt"
"strconv"
"time"
@@ -54,7 +55,7 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateCarrierRequest) (*d
// 阈值字段只由超级管理员与平台账号配置:非平台账号提交即整体拒绝,不落任何配置。
if req.HasTrafficThresholdFields() && !canManageThreshold(ctx) {
s.recordDenied(ctx, constants.AuditOperationCarrierCreate, "拒绝非平台账号配置运营商通道流量阈值",
s.recordDenied(ctx, constants.AuditOperationCarrierCreate, "拒绝非平台账号配置运营商通道流量阈值或实名管控",
thresholdCreateProbe(req), errors.CodeForbidden)
return nil, errors.New(errors.CodeForbidden, constants.PlatformManagementForbiddenMessage)
}
@@ -92,6 +93,9 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateCarrierRequest) (*d
TrafficThresholdValue: thresholdValue,
TrafficThresholdUnit: thresholdUnit,
}
if req.RealnameControlEnabled != nil {
carrier.RealnameControlEnabled = *req.RealnameControlEnabled
}
if req.DataResetDay != nil {
carrier.DataResetDay = *req.DataResetDay
}
@@ -145,7 +149,7 @@ func (s *Service) Update(ctx context.Context, id uint, req *dto.UpdateCarrierReq
// 阈值字段只由超级管理员与平台账号修改:非平台账号提交即整体拒绝。
if req.HasTrafficThresholdFields() && !canManageThreshold(ctx) {
s.recordDenied(ctx, constants.AuditOperationCarrierUpdate, "拒绝非平台账号配置运营商通道流量阈值",
s.recordDenied(ctx, constants.AuditOperationCarrierUpdate, "拒绝非平台账号配置运营商通道流量阈值或实名管控",
&before, errors.CodeForbidden)
return nil, errors.New(errors.CodeForbidden, constants.PlatformManagementForbiddenMessage)
}
@@ -168,6 +172,12 @@ func (s *Service) Update(ctx context.Context, id uint, req *dto.UpdateCarrierReq
carrier.TrafficThresholdEnabled = thresholdEnabled
carrier.TrafficThresholdValue = thresholdValue
carrier.TrafficThresholdUnit = thresholdUnit
if req.RealnameControlEnabled != nil {
if err := s.confirmRealnameControl(ctx, &before, *req.RealnameControlEnabled, req.RealnameControlConfirm); err != nil {
return nil, err
}
carrier.RealnameControlEnabled = *req.RealnameControlEnabled
}
if req.CarrierName != nil {
carrier.CarrierName = *req.CarrierName
@@ -375,9 +385,31 @@ func carrierAuditSnapshot(carrier *model.Carrier) map[string]any {
"traffic_threshold_enabled": carrier.TrafficThresholdEnabled,
"traffic_threshold_value": carrier.TrafficThresholdValue,
"traffic_threshold_unit": carrier.TrafficThresholdUnit,
// 通道实名管控的修改同样并入运营商更新审计。
"realname_control_enabled": carrier.RealnameControlEnabled,
}
}
// confirmRealnameControl 在把通道实名管控从 0 改为 1 时要求显式确认:
// 未确认时返回该通道未实名开机卡数,提示这些卡会在下一次评估时被停机,本次不保存。
func (s *Service) confirmRealnameControl(ctx context.Context, before *model.Carrier, next int, confirm *bool) error {
if before.RealnameControlEnabled == next || next != constants.StatusEnabled {
return nil
}
if confirm != nil && *confirm {
return nil
}
var count int64
if err := s.carrierStore.DB().WithContext(ctx).Model(&model.IotCard{}).
Where("carrier_id = ? AND real_name_status <> ? AND network_status = ?",
before.ID, constants.RealNameStatusVerified, constants.NetworkStatusOnline).
Count(&count).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "统计通道未实名开机卡数失败")
}
return errors.New(errors.CodeInvalidParam, fmt.Sprintf(
"开启实名管控后,该通道 %d 张未实名的开机卡会在下一次评估时被停机;确认后请携带 realname_control_confirm=true 重新提交", count))
}
// canManageThreshold 判断当前账号是否具备通道流量阈值字段的读写权限。
// 只有超级管理员与平台账号可见可写,与 requirePlatformManagement 的判定一致(引用同一用户类型枚举)。
func canManageThreshold(ctx context.Context) bool {
@@ -438,6 +470,8 @@ func (s *Service) toResponse(ctx context.Context, c *model.Carrier) *dto.Carrier
}
enabled := c.TrafficThresholdEnabled
result.TrafficThresholdEnabled = &enabled
realnameControl := c.RealnameControlEnabled
result.RealnameControlEnabled = &realnameControl
result.TrafficThresholdValue = c.TrafficThresholdValue
if c.TrafficThresholdUnit != "" {
unit := c.TrafficThresholdUnit

View File

@@ -107,12 +107,23 @@ func (s *StopResumeService) ChannelThresholdResumeReady(ctx context.Context, car
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
if unifiedStopResumeEnabled() {
// 总开关开启时不看其他停因与网关扩展状态,卡或所在设备暂停轮询时只解锁不复机。
suspended, suspendErr := s.autoControlSuspended(ctx, card)
if suspendErr != nil {
return false, "", suspendErr
}
if suspended {
return false, "卡或所在设备已暂停轮询,不自动复机", nil
}
} else {
// 其他停机锁:风险网关扩展(风险停机/销户)或非通道阈值的停因。
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 {

View File

@@ -34,6 +34,8 @@ type StopResumeServiceInterface interface {
ForceStopCard(ctx context.Context, card *model.IotCard, stopReason string) error
// ForceStartCard 强制复机单张卡,不执行正常复机条件判断。
ForceStartCard(ctx context.Context, card *model.IotCard) error
// ProtectCheckSkipsForRealname 判定保护期一致性检查是否因实名跳过该卡。
ProtectCheckSkipsForRealname(ctx context.Context, card *model.IotCard) (bool, error)
}
// 编译时验证 StopResumeService 实现了 StopResumeServiceInterface
@@ -109,6 +111,14 @@ func (s *StopResumeService) SetPollingCallback(callback PollingCallback) {
// 根据卡的当前网络状态,自动判断并执行停机或复机操作
// 设备/单卡维度通过 card.IsStandalone 推导(false 则为设备维度,停/复机覆盖设备下所有卡)
func (s *StopResumeService) EvaluateAndAct(ctx context.Context, card *model.IotCard) error {
// 总开关开启时,卡或所在设备暂停轮询的不自动停复机。
suspended, err := s.autoControlSuspended(ctx, card)
if err != nil {
return err
}
if suspended {
return nil
}
switch card.NetworkStatus {
case constants.NetworkStatusOnline:
// 卡在线,检查是否需要停机
@@ -142,8 +152,8 @@ func (s *StopResumeService) EvaluateAndAct(ctx context.Context, card *model.IotC
case constants.NetworkStatusOffline:
// 卡停机,检查是否可以复机
// 只处理轮询系统引起的停机原因(手动停机等不自动复机)
if !isPollingStopReason(card.StopReason) {
// 总开关关闭时只处理轮询系统引起的停机原因(手动停机等不自动复机);开启时不看停机原因
if !autoResumableStopReason(card.StopReason) {
return nil
}
shouldResume, err := s.shouldResume(ctx, card)
@@ -318,6 +328,10 @@ func (s *StopResumeService) isTrafficExhausted(ctx context.Context, card *model.
// isRealnameOK 检查卡是否满足实名要求
// 行业卡、已实名卡直接放行;其他卡按有效设备或自身的无需实名策略判断。
func (s *StopResumeService) isRealnameOK(ctx context.Context, card *model.IotCard) (bool, error) {
// 总开关开启时实名只按卡所属通道的实名管控判断,不区分行业卡、不看卡或设备实名策略。
if unifiedStopResumeEnabled() {
return s.unifiedRealnameOK(ctx, card)
}
if card.CardCategory == constants.CardCategoryIndustry || card.RealNameStatus == constants.RealNameStatusVerified {
return true, nil
}
@@ -420,6 +434,13 @@ func (s *StopResumeService) stopDeviceCards(ctx context.Context, deviceID uint,
var cardErrors []error
for _, card := range cards {
// 总开关开启时,暂停轮询的卡不随设备自动停机。
if suspended, suspendErr := s.autoControlSuspended(ctx, card); suspendErr != nil {
cardErrors = append(cardErrors, suspendErr)
continue
} else if suspended {
continue
}
if _, stopErr := s.stopCardWithRetry(ctx, card, stopReason); stopErr != nil {
cardErrors = append(cardErrors, stopErr)
s.logger.Warn("设备卡停机失败,继续处理其他卡",
@@ -450,8 +471,14 @@ func (s *StopResumeService) resumeDeviceCards(ctx context.Context, deviceID uint
}
defer s.redis.Del(ctx, lockKey)
// 查询设备下因轮询原因停机的卡
cards, err := s.iotCardStore.ListByDeviceIDAndPollingStopReasons(ctx, deviceID)
// 查询设备下待复机的卡:总开关关闭时只取因轮询原因停机的卡,开启时取全部停机卡(不看停机原因)
var cards []*model.IotCard
var err error
if unifiedStopResumeEnabled() {
cards, err = s.iotCardStore.ListByDeviceIDAndNetworkStatus(ctx, deviceID, constants.NetworkStatusOffline)
} else {
cards, err = s.iotCardStore.ListByDeviceIDAndPollingStopReasons(ctx, deviceID)
}
if err != nil {
s.logger.Error("查询设备停机卡失败",
zap.Uint("device_id", deviceID), zap.Error(err))
@@ -569,6 +596,15 @@ func (s *StopResumeService) resumeSingleCard(ctx context.Context, cardID uint) e
actionCode, summary := constants.AuditActionIotCardAutoStarted, "自动恢复 IoT 卡网络"
// 总开关开启时,卡或所在设备暂停轮询的不自动复机(含套餐激活、重置、充值等非轮询触发)。
suspended, suspendErr := s.autoControlSuspended(ctx, card)
if suspendErr != nil {
return suspendErr
}
if suspended {
return nil
}
// 持通道阈值锁:周期内拒绝一切复机,记录拒绝事实并保留锁。
// 该入口被轮询评估、套餐激活/重置与设备维度复机复用,返回 nil 表示本次不动作,
// 避免让自动链路按失败重试;用户可见入口由 ManualStartCard/ForceStartCard 返回拒绝错误。
@@ -587,8 +623,8 @@ func (s *StopResumeService) resumeSingleCard(ctx context.Context, cardID uint) e
return nil
}
// 只处理轮询系统引起的停机
if !isPollingStopReason(card.StopReason) {
// 总开关关闭时只处理轮询系统引起的停机;开启时不看停机原因
if !autoResumableStopReason(card.StopReason) {
s.logger.Debug("卡非轮询停机原因,不自动复机",
zap.Uint("card_id", cardID),
zap.String("stop_reason", card.StopReason))

View File

@@ -0,0 +1,98 @@
package iot_card
import (
"context"
stderrors "errors"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/config"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// realnameControlEnabled 是通道实名管控开启时的取值。
const realnameControlEnabled = 1
// unifiedStopResumeEnabled 判定停复机新规则总开关是否开启。
//
// 开启后:复机不看停机原因;实名按卡所属通道的实名管控判断(不区分行业卡、不看卡/设备实名策略);
// 卡或所在设备暂停轮询时不自动停复机。关闭时全部停复机路径与原有行为一致。
func unifiedStopResumeEnabled() bool {
cfg := config.Get()
return cfg != nil && cfg.StopResume.UnifiedRuleEnabled
}
// autoResumableStopReason 判定该停因的停机卡能否进入自动复机判断:总开关开启时不看停因,
// 关闭时只处理轮询系统引起的停机。
func autoResumableStopReason(reason string) bool {
return unifiedStopResumeEnabled() || isPollingStopReason(reason)
}
// autoControlSuspended 判定总开关开启时该卡是否因暂停轮询而不自动停复机:卡自身或其有效绑定设备暂停轮询。
// 总开关关闭时恒为 false。
func (s *StopResumeService) autoControlSuspended(ctx context.Context, card *model.IotCard) (bool, error) {
if !unifiedStopResumeEnabled() || card == nil {
return false, nil
}
if !card.EnablePolling {
return true, nil
}
deviceID, bound, err := s.getCardDeviceID(ctx, card)
if err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询卡绑定设备失败")
}
if !bound {
return false, nil
}
var device model.Device
if err := s.db.WithContext(ctx).Select("id", "enable_polling").First(&device, deviceID).Error; err != nil {
if stderrors.Is(err, gorm.ErrRecordNotFound) {
return false, nil
}
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询设备轮询状态失败")
}
return !device.EnablePolling, nil
}
// channelRealnameControlled 查询卡所属通道是否开启实名管控。
func (s *StopResumeService) channelRealnameControlled(ctx context.Context, card *model.IotCard) (bool, error) {
var values []int
if err := s.db.WithContext(ctx).Model(&model.Carrier{}).
Where("id = ?", card.CarrierID).Limit(1).Pluck("realname_control_enabled", &values).Error; err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询通道实名管控失败")
}
if len(values) == 0 {
return false, errors.New(errors.CodeNotFound, "卡所属运营商通道不存在,无法判断实名管控")
}
return values[0] == realnameControlEnabled, nil
}
// unifiedRealnameOK 是总开关开启后的实名门槛:通道未开启实名管控即满足;开启时只看卡是否已实名。
func (s *StopResumeService) unifiedRealnameOK(ctx context.Context, card *model.IotCard) (bool, error) {
controlled, err := s.channelRealnameControlled(ctx, card)
if err != nil {
return false, err
}
if !controlled {
return true, nil
}
return card.RealNameStatus == constants.RealNameStatusVerified, nil
}
// ProtectCheckSkipsForRealname 判定保护期一致性检查是否因实名跳过该卡。
// 总开关关闭时与原有行为一致(未实名即跳过);开启时只在通道开启实名管控且卡未实名时跳过。
func (s *StopResumeService) ProtectCheckSkipsForRealname(ctx context.Context, card *model.IotCard) (bool, error) {
if card.RealNameStatus == constants.RealNameStatusVerified {
return false, nil
}
if !unifiedStopResumeEnabled() {
return true, nil
}
controlled, err := s.channelRealnameControlled(ctx, card)
if err != nil {
return false, err
}
return controlled, nil
}

View File

@@ -8,6 +8,7 @@ import (
"strconv"
"time"
cardflow "github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/redis/go-redis/v9"
@@ -20,10 +21,46 @@ type DailyUsageItem struct {
}
// QueryService 流量查询服务
// 合并 Redis(当天实时)和 DB(历史落盘)两段数据源
// 未切换日快照算法的卡合并 Redis(当天实时)和 DB(历史落盘)两段数据源;已切换的卡读日流量快照。
type QueryService struct {
redis *redis.Client
cardDailyUsageStore *postgres.CardDailyUsageStore
switched func(cardID uint) bool
flowDays *postgres.CardFlowDayStore
}
// WithFlowSnapshots 注入日快照数据源:switched 判定卡是否已切换日快照算法,已切换的卡改读快照。
func (s *QueryService) WithFlowSnapshots(switched func(cardID uint) bool, flowDays *postgres.CardFlowDayStore) *QueryService {
s.switched = switched
s.flowDays = flowDays
return s
}
// dailyUsageFromSnapshots 按快照计算每天用量:当天最大快照 − 本月此前最大快照,小于 0 按 0,跨月重新累计。
func (s *QueryService) dailyUsageFromSnapshots(ctx context.Context, cardID uint, startDate, endDate time.Time) ([]*DailyUsageItem, error) {
start := cardflow.ShanghaiDate(startDate)
end := cardflow.ShanghaiDate(endDate)
rows, err := s.flowDays.ListBetween(ctx, cardID, cardflow.MonthStart(start), end)
if err != nil {
return nil, err
}
items := make([]*DailyUsageItem, 0, len(rows))
var month string
var priorMax float64
for _, row := range rows {
date := row.FlowDate.Format("2006-01-02")
if rowMonth := date[:7]; rowMonth != month {
month, priorMax = rowMonth, 0
}
usage := cardflow.DailyUsage(row.MonthUsedMB, priorMax)
if row.MonthUsedMB > priorMax {
priorMax = row.MonthUsedMB
}
if date >= start.Format("2006-01-02") {
items = append(items, &DailyUsageItem{Date: date, UsageMB: usage})
}
}
return items, nil
}
// NewQueryService 创建流量查询服务实例
@@ -37,6 +74,9 @@ func NewQueryService(redisClient *redis.Client, cardDailyUsageStore *postgres.Ca
// GetDailyUsage 查询卡在指定日期范围内的日粒度流量
// 今天的数据从 Redis 缓冲读取(可能尚未落盘),历史数据从 DB 读取,合并后按日期 ASC 排序返回
func (s *QueryService) GetDailyUsage(ctx context.Context, cardID uint, startDate, endDate time.Time) ([]*DailyUsageItem, error) {
if s.switched != nil && s.flowDays != nil && s.switched(cardID) {
return s.dailyUsageFromSnapshots(ctx, cardID, startDate, endDate)
}
now := time.Now()
todayStr := now.Format("2006-01-02")

View File

@@ -0,0 +1,130 @@
package postgres
import (
"context"
"time"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/model"
)
// cardFlowDateLayout 是快照日期参数格式,按上海日期字符串传给数据库,避免时区换算。
const cardFlowDateLayout = "2006-01-02"
// CardFlowDayStore 卡日流量快照存储。
type CardFlowDayStore struct {
db *gorm.DB
}
// NewCardFlowDayStore 创建卡日流量快照存储。
func NewCardFlowDayStore(db *gorm.DB) *CardFlowDayStore {
return &CardFlowDayStore{db: db}
}
// WithTx 返回复用当前事务的快照存储。
func (s *CardFlowDayStore) WithTx(tx *gorm.DB) *CardFlowDayStore {
return &CardFlowDayStore{db: tx}
}
// CardFlowSnapshotWrite 是一次快照写入的取值。
type CardFlowSnapshotWrite struct {
CardID uint
FlowDate time.Time
MonthUsedMB float64
VendorUsedMB float64
StaleGuarded bool
}
// Upsert 原子写入当天快照:本月累计取已有值与本次值中的较大者,防旧值标记只要当天触发过就保留。
func (s *CardFlowDayStore) Upsert(ctx context.Context, write CardFlowSnapshotWrite) error {
return s.db.WithContext(ctx).Exec(`
INSERT INTO tb_card_flow_day (iot_card_id, flow_date, month_used_mb, vendor_used_mb, stale_guarded, obs_count, created_at, updated_at)
VALUES (?, ?::date, ?, ?, ?, 1, NOW(), NOW())
ON CONFLICT (iot_card_id, flow_date) DO UPDATE SET
month_used_mb = GREATEST(tb_card_flow_day.month_used_mb, EXCLUDED.month_used_mb),
vendor_used_mb = EXCLUDED.vendor_used_mb,
stale_guarded = tb_card_flow_day.stale_guarded OR EXCLUDED.stale_guarded,
obs_count = tb_card_flow_day.obs_count + 1,
updated_at = NOW()`,
write.CardID, write.FlowDate.Format(cardFlowDateLayout), write.MonthUsedMB, write.VendorUsedMB, write.StaleGuarded,
).Error
}
// MaxBetween 返回 [from, to] 日期闭区间内的最大本月累计,没有快照时返回 0。
func (s *CardFlowDayStore) MaxBetween(ctx context.Context, cardID uint, from, to time.Time) (float64, error) {
if to.Before(from) {
return 0, nil
}
var max float64
err := s.db.WithContext(ctx).Model(&model.CardFlowDay{}).
Select("COALESCE(MAX(month_used_mb), 0)").
Where("iot_card_id = ? AND flow_date >= ?::date AND flow_date <= ?::date",
cardID, from.Format(cardFlowDateLayout), to.Format(cardFlowDateLayout)).
Scan(&max).Error
return max, err
}
// SettledBetween 返回 [from, to] 日期闭区间内的已结算合计。
func (s *CardFlowDayStore) SettledBetween(ctx context.Context, cardID uint, from, to time.Time) (float64, error) {
var sum float64
err := s.db.WithContext(ctx).Model(&model.CardFlowDay{}).
Select("COALESCE(SUM(settled_mb), 0)").
Where("iot_card_id = ? AND flow_date >= ?::date AND flow_date <= ?::date",
cardID, from.Format(cardFlowDateLayout), to.Format(cardFlowDateLayout)).
Scan(&sum).Error
return sum, err
}
// AddSettled 把增量计入当天已结算;当天快照行必须已由 Upsert 写入。
func (s *CardFlowDayStore) AddSettled(ctx context.Context, cardID uint, flowDate time.Time, deltaMB float64) error {
if deltaMB <= 0 {
return nil
}
return s.db.WithContext(ctx).Exec(
"UPDATE tb_card_flow_day SET settled_mb = settled_mb + ?, updated_at = NOW() WHERE iot_card_id = ? AND flow_date = ?::date",
deltaMB, cardID, flowDate.Format(cardFlowDateLayout),
).Error
}
// MonthContext 查询换算与防旧值需要的已有快照取值:本月重置日前最大、上月最大与上月重置日前最大。
func (s *CardFlowDayStore) MonthContext(ctx context.Context, cardID uint, flowDate time.Time, resetDay int) (cardflow.MonthContext, error) {
monthStart := cardflow.MonthStart(flowDate)
prevStart := monthStart.AddDate(0, -1, 0)
prevEnd := monthStart.AddDate(0, 0, -1)
var result cardflow.MonthContext
var err error
if result.PrevMonthMax, err = s.MaxBetween(ctx, cardID, prevStart, prevEnd); err != nil {
return result, err
}
if resetDay <= 1 {
return result, nil
}
if result.ThisMonthBeforeResetMax, err = s.MaxBetween(ctx, cardID, monthStart, monthStart.AddDate(0, 0, resetDay-2)); err != nil {
return result, err
}
result.PrevMonthBeforeResetMax, err = s.MaxBetween(ctx, cardID, prevStart, prevStart.AddDate(0, 0, resetDay-2))
return result, err
}
// MonthTotals 返回截至 flowDate 的本月最大快照与本月已结算合计,用于按月对账。
func (s *CardFlowDayStore) MonthTotals(ctx context.Context, cardID uint, flowDate time.Time) (monthMax float64, settled float64, err error) {
monthStart := cardflow.MonthStart(flowDate)
monthEnd := monthStart.AddDate(0, 1, -1)
if monthMax, err = s.MaxBetween(ctx, cardID, monthStart, monthEnd); err != nil {
return 0, 0, err
}
settled, err = s.SettledBetween(ctx, cardID, monthStart, monthEnd)
return monthMax, settled, err
}
// ListBetween 返回 [from, to] 日期闭区间内的快照,按日期升序。
func (s *CardFlowDayStore) ListBetween(ctx context.Context, cardID uint, from, to time.Time) ([]model.CardFlowDay, error) {
var rows []model.CardFlowDay
err := s.db.WithContext(ctx).
Where("iot_card_id = ? AND flow_date >= ?::date AND flow_date <= ?::date",
cardID, from.Format(cardFlowDateLayout), to.Format(cardFlowDateLayout)).
Order("flow_date ASC").Find(&rows).Error
return rows, err
}

View File

@@ -0,0 +1,43 @@
package postgres
import (
"context"
stderrors "errors"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/model"
)
// CardFlowSwitchStore 卡流量计量切换水位存储。
type CardFlowSwitchStore struct {
db *gorm.DB
}
// NewCardFlowSwitchStore 创建切换水位存储。
func NewCardFlowSwitchStore(db *gorm.DB) *CardFlowSwitchStore {
return &CardFlowSwitchStore{db: db}
}
// WithTx 返回复用当前事务的切换水位存储。
func (s *CardFlowSwitchStore) WithTx(tx *gorm.DB) *CardFlowSwitchStore {
return &CardFlowSwitchStore{db: tx}
}
// Get 返回卡的切换水位;不存在时返回 nil、nil。
func (s *CardFlowSwitchStore) Get(ctx context.Context, cardID uint) (*model.CardFlowSwitch, error) {
var row model.CardFlowSwitch
err := s.db.WithContext(ctx).Where("iot_card_id = ?", cardID).First(&row).Error
if stderrors.Is(err, gorm.ErrRecordNotFound) {
return nil, nil
}
if err != nil {
return nil, err
}
return &row, nil
}
// Create 写入切换水位;同卡已存在时由唯一索引拒绝,调用方随事务回滚后重试。
func (s *CardFlowSwitchStore) Create(ctx context.Context, row *model.CardFlowSwitch) error {
return s.db.WithContext(ctx).Create(row).Error
}

View File

@@ -74,8 +74,17 @@ func (h *PollingProtectHandler) Handle(ctx context.Context, t *asynq.Task) error
return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingProtect)
}
// 未实名卡跳过保护期检查
if card.RealNameStatus != constants.RealNameStatusVerified {
// 实名不满足的卡跳过保护期检查:停复机新规则总开关关闭时未实名即跳过,开启时只在通道开启实名管控且未实名时跳过
if h.stopResumeSvc != nil {
skip, skipErr := h.stopResumeSvc.ProtectCheckSkipsForRealname(ctx, card)
if skipErr != nil {
h.base.logger.Warn("保护期检查判断实名管控失败,本次跳过", zap.Uint("card_id", cardID), zap.Error(skipErr))
return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingProtect)
}
if skip {
return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingProtect)
}
} else if card.RealNameStatus != constants.RealNameStatusVerified {
return h.base.requeueCard(ctx, cardID, constants.TaskTypePollingProtect)
}