feat: 卡流量读数先过采集队列再入账,扣减按采集时刻确定套餐
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m27s

- 每卡 Redis 采集队列(默认 N=3、跨天清空、回退容差 1 MB),攒满且不下降才写最后一个点
- 测试环境全量切换日快照计量,下线灰度名单、切换水位与卡表基线扣费;全部卡置待建起点
- 读数区分没给值与 0;有套餐的卡读数 0 也写快照与日用量 0 行;重置日比较基准为 0 照常防旧值
- 新增采集记录(按月分区保留 90 天)、人工冲正流水与后台接口、采集告警
- 扣减按采集时刻有效套餐查找,只对生效中套餐做状态迁移,查不到套餐按成功跳过
- 换货新卡(新设备下的卡)打待建起点;采集间隔上限只校验启用中的轮询配置

Change: add-card-traffic-queue-and-observed-deduction

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
邹进
2026-10-29 12:18:47 +09:00
parent c33cc6f6c3
commit 9c3c258f16
55 changed files with 3142 additions and 881 deletions

View File

@@ -7,6 +7,7 @@ import (
"strconv"
"time"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
@@ -15,7 +16,6 @@ import (
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
"gorm.io/gorm"
"gorm.io/gorm/clause"
)
const (
@@ -72,16 +72,19 @@ func (s *UsageService) SetStopResumeCallback(callback StopResumeCallback) {
s.stopResumeCallback = callback
}
// DeductDataUsage 任务 10.2-10.6: 按优先级扣减流量
// 扣减顺序:加油包(按 priority ASC) → 主套餐
// 真实用量允许超过套餐阈值,超额部分记入最后一个生效套餐,用于后续虚流量阈值评估。
// 流量用完时自动标记 status=2,所有套餐用完时触发停机。
func (s *UsageService) DeductDataUsage(ctx context.Context, carrierType string, carrierID uint, usageMB float64) error {
// DeductDataUsage 按采集时刻扣减卡的流量增量。
// 扣减套餐按"有套餐"共用口径(postgres.FindEffectivePackagesAt)在采集时刻查找:采集时刻有效、扣费时已用完或已到期的套餐照扣;
// 扣减顺序:加油包(按 priority ASC) → 主套餐,超额部分记入最后一个套餐,用于后续虚流量阈值评估。
// 只对当前"生效中"的套餐做"扣到阈值改为已用完";一个套餐都查不到时记跳过审计并按成功返回;全部用完时触发停机。
func (s *UsageService) DeductDataUsage(ctx context.Context, cardID uint, usageMB float64, observedAt time.Time, observationID string) error {
if usageMB <= 0 {
return errors.New(errors.CodeInvalidParam, "扣减流量必须大于0")
}
if observedAt.IsZero() {
observedAt = time.Now()
}
deductUsageMB := s.convertToDeductMB(ctx, carrierType, carrierID, usageMB)
deductUsageMB := s.convertToDeductMB(ctx, constants.AssetTypeIotCard, cardID, usageMB)
if deductUsageMB <= 0 {
return nil
}
@@ -92,78 +95,60 @@ func (s *UsageService) DeductDataUsage(ctx context.Context, carrierType string,
var auditChanges []packageUsageAuditChange
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
targetCarrierType, targetCarrierID, packages, err := s.resolveActivePackages(ctx, tx, carrierType, carrierID)
effective, err := postgres.FindEffectivePackagesAt(ctx, tx, cardID, observedAt, true)
if err != nil {
return err
return errors.Wrap(errors.CodeDatabaseError, err, "查询采集时刻有效套餐失败")
}
today := time.Now().Format("2006-01-02")
packages := effective.Packages
if len(packages) == 0 {
// 无生效套餐:尝试找 Depleted 套餐记录溢出流量详单,避免详单断档
if recordErr := s.recordOverflowToDepletedPackage(ctx, tx, targetCarrierType, targetCarrierID, deductUsageMB, today); recordErr != nil {
s.logger.Warn("记录溢出流量到已耗尽套餐失败",
zap.String("carrier_type", targetCarrierType),
zap.Uint("carrier_id", targetCarrierID),
zap.Int64("usage_mb", deductUsageMB),
zap.Error(recordErr))
}
return errors.New(errors.CodeNoAvailablePackage, "没有可用套餐")
// 采集时刻有套餐、扣费前被退款或作废:记告警并按成功处理,不重试;需要时人工冲正。
s.logger.Warn("扣减卡流量时查不到采集时刻有效套餐,按成功跳过",
zap.Uint("card_id", cardID), zap.Int64("usage_mb", deductUsageMB),
zap.Time("observed_at", observedAt), zap.String("observation_id", observationID),
zap.String("metric", "package.traffic_deduct.skipped_no_package"))
return nil
}
flowDate := cardflow.ShanghaiDate(observedAt)
// 按优先级扣减流量
remainingUsage := deductUsageMB
for index, pkg := range packages {
if remainingUsage <= 0 {
break
}
// 计算当前套餐剩余额度
effectiveThresholdMB := pkg.EffectiveThresholdMB()
remainingQuota := pkg.RemainingQuotaMB()
isLastPackage := index == len(packages)-1
if remainingQuota <= 0 && !isLastPackage {
// 套餐已用完,标记为已用完
beforeData := packageUsageStateData(pkg)
if err := tx.Model(pkg).Update("status", constants.PackageUsageStatusDepleted).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新套餐状态失败")
}
pkg.Status = constants.PackageUsageStatusDepleted
auditChanges = append(auditChanges, packageUsageAuditChange{Usage: pkg, BeforeData: beforeData, AfterData: packageUsageStateData(pkg)})
continue
}
// 本次从该套餐扣减的流量
var deductFromPkg int64
if isLastPackage {
switch {
case isLastPackage:
deductFromPkg = remainingUsage
} else if remainingUsage <= remainingQuota {
case remainingQuota <= 0:
deductFromPkg = 0
case remainingUsage <= remainingQuota:
deductFromPkg = remainingUsage
} else {
default:
deductFromPkg = remainingQuota
}
if deductFromPkg <= 0 {
beforeData := packageUsageStateData(pkg)
if err := tx.Model(pkg).Update("status", constants.PackageUsageStatusDepleted).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新套餐状态失败")
// 余量已用完且不是最后一个套餐:跳过;只有当前生效中的套餐顺带改为已用完。
if pkg.Status == constants.PackageUsageStatusActive {
beforeData := packageUsageStateData(pkg)
if err := tx.Model(pkg).Update("status", constants.PackageUsageStatusDepleted).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新套餐状态失败")
}
pkg.Status = constants.PackageUsageStatusDepleted
auditChanges = append(auditChanges, packageUsageAuditChange{Usage: pkg, BeforeData: beforeData, AfterData: packageUsageStateData(pkg)})
}
pkg.Status = constants.PackageUsageStatusDepleted
auditChanges = append(auditChanges, packageUsageAuditChange{Usage: pkg, BeforeData: beforeData, AfterData: packageUsageStateData(pkg)})
continue
}
// 更新套餐使用量
newUsage := pkg.DataUsageMB + deductFromPkg
updates := map[string]interface{}{
"data_usage_mb": newUsage,
}
// 检查是否用完
if effectiveThresholdMB > 0 && newUsage >= effectiveThresholdMB {
updates := map[string]interface{}{"data_usage_mb": newUsage}
if pkg.Status == constants.PackageUsageStatusActive && effectiveThresholdMB > 0 && newUsage >= effectiveThresholdMB {
updates["status"] = constants.PackageUsageStatusDepleted
}
beforeData := packageUsageStateData(pkg)
if err := tx.Model(pkg).Updates(updates).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新套餐使用量失败")
@@ -172,42 +157,42 @@ func (s *UsageService) DeductDataUsage(ctx context.Context, carrierType string,
if status, ok := updates["status"].(int); ok {
pkg.Status = status
}
// 任务 10.6: 写入日记录
if err := s.updateDailyRecord(ctx, tx, pkg.ID, today, deductFromPkg, newUsage); err != nil {
return err
if err := postgres.AddDailyUsage(ctx, tx, pkg.ID, flowDate, deductFromPkg, newUsage); err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入套餐日用量失败")
}
auditChanges = append(auditChanges, packageUsageAuditChange{Usage: pkg, BeforeData: beforeData, AfterData: packageUsageStateData(pkg)})
remainingUsage -= deductFromPkg
s.logger.Info("扣减套餐流量",
zap.Uint("usage_id", pkg.ID),
zap.Int("status", pkg.Status),
zap.Int64("deduct_mb", deductFromPkg),
zap.Int64("new_usage_mb", newUsage),
zap.Int64("effective_threshold_mb", effectiveThresholdMB),
zap.Int64("data_limit_mb", pkg.DataLimitMB),
zap.Int64("remaining_quota_mb", remainingQuota),
zap.Bool("crossed_reset", crossedReset(pkg, observedAt)),
zap.Bool("over_threshold", effectiveThresholdMB > 0 && newUsage > effectiveThresholdMB))
}
// 任务 10.5: 检查是否所有套餐都用完(触发停机)
shouldSuspendCurrent, suspensionChanges, err := s.checkAndTriggerSuspension(ctx, tx, targetCarrierType, targetCarrierID)
// 检查是否所有套餐都用完(触发停机),按套餐当前状态判断
shouldSuspendCurrent, suspensionChanges, err := s.checkAndTriggerSuspension(ctx, tx, effective.CarrierType, effective.CarrierID)
if err != nil {
return err
}
auditChanges = append(auditChanges, suspensionChanges...)
shouldSuspend = shouldSuspendCurrent
suspendCarrierType = targetCarrierType
suspendCarrierID = targetCarrierID
suspendCarrierType = effective.CarrierType
suspendCarrierID = effective.CarrierID
if len(auditChanges) > 0 {
if err := appendPackageUsageAudit(ctx, tx, s.auditWriter, constants.AuditActionPackageUsageTrafficDeducted, "扣减套餐权益流量", normalizePackageUsageAuditChanges(auditChanges), nil, map[string]any{
"carrier_type": targetCarrierType, "carrier_id": targetCarrierID, "usage_mb": deductUsageMB,
"carrier_type": effective.CarrierType, "carrier_id": effective.CarrierID, "usage_mb": deductUsageMB,
"card_id": cardID, "observed_at": observedAt, "observation_id": observationID,
"crossed_reset_usage_ids": crossedResetUsageIDs(packages, observedAt),
}); err != nil {
return err
}
}
return nil
})
if err != nil {
@@ -224,6 +209,22 @@ func (s *UsageService) DeductDataUsage(ctx context.Context, carrierType string,
return nil
}
// crossedReset 判断采集时间是否早于套餐最近一次流量重置:这笔用量会扣在重置后的周期。
func crossedReset(pkg *model.PackageUsage, observedAt time.Time) bool {
return pkg.LastResetAt != nil && observedAt.Before(*pkg.LastResetAt)
}
// crossedResetUsageIDs 返回采集时间早于最近一次流量重置的套餐,写入扣费审计便于排查跨重置扣费。
func crossedResetUsageIDs(packages []*model.PackageUsage, observedAt time.Time) []uint {
var ids []uint
for _, pkg := range packages {
if crossedReset(pkg, observedAt) {
ids = append(ids, pkg.ID)
}
}
return ids
}
// convertToDeductMB 将浮点增量转换为可扣减的整数 MB
// 规则:先合并 Redis 中的小数余量,再按整数 MB 扣减;余数回写 Redis
func (s *UsageService) convertToDeductMB(ctx context.Context, carrierType string, carrierID uint, usageMB float64) int64 {
@@ -290,107 +291,6 @@ func (s *UsageService) persistUsageRemainder(ctx context.Context, key string, re
return s.redis.Set(ctx, key, value, usageRemainderTTL).Err()
}
// resolveActivePackages 统一解析可扣减载体
// 优先按请求载体查找;当 iot_card 无生效套餐且存在设备绑定时,回退到 device 载体
func (s *UsageService) resolveActivePackages(ctx context.Context, tx *gorm.DB, carrierType string, carrierID uint) (string, uint, []*model.PackageUsage, error) {
packages, err := s.queryActivePackages(tx, carrierType, carrierID)
if err != nil {
return "", 0, nil, err
}
if len(packages) > 0 {
return carrierType, carrierID, packages, nil
}
if carrierType != constants.AssetTypeIotCard {
return carrierType, carrierID, packages, nil
}
binding, err := s.deviceSimBindingStore.GetActiveBindingByCardID(ctx, carrierID)
if err == gorm.ErrRecordNotFound {
return carrierType, carrierID, packages, nil
}
if err != nil {
return "", 0, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡绑定设备失败")
}
devicePackages, queryErr := s.queryActivePackages(tx, constants.AssetTypeDevice, binding.DeviceID)
if queryErr != nil {
return "", 0, nil, queryErr
}
if len(devicePackages) == 0 {
return carrierType, carrierID, packages, nil
}
s.logger.Info("卡载体无生效套餐,回退设备载体扣减流量",
zap.Uint("card_id", carrierID),
zap.Uint("device_id", binding.DeviceID))
return constants.AssetTypeDevice, binding.DeviceID, devicePackages, nil
}
// queryActivePackages 查询指定载体下的生效套餐(按扣减优先级排序)
func (s *UsageService) queryActivePackages(tx *gorm.DB, carrierType string, carrierID uint) ([]*model.PackageUsage, error) {
query := tx.Where("status = ?", constants.PackageUsageStatusActive)
switch carrierType {
case constants.AssetTypeIotCard:
query = query.Where("iot_card_id = ?", carrierID)
case constants.AssetTypeDevice:
query = query.Where("device_id = ?", carrierID)
default:
return nil, errors.New(errors.CodeInvalidParam, "无效的载体类型")
}
var packages []*model.PackageUsage
if err := query.
Clauses(clause.Locking{Strength: "UPDATE"}).
Order("CASE WHEN master_usage_id IS NOT NULL THEN 0 ELSE 1 END, priority ASC, id ASC").
Find(&packages).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询生效套餐失败")
}
return packages, nil
}
// updateDailyRecord 任务 10.6: 更新日流量记录
func (s *UsageService) updateDailyRecord(ctx context.Context, tx *gorm.DB, packageUsageID uint, dateStr string, dailyUsageMB, cumulativeUsageMB int64) error {
// 解析日期字符串
date, err := time.Parse("2006-01-02", dateStr)
if err != nil {
return errors.Wrap(errors.CodeInvalidParam, err, "日期格式错误")
}
// 查询是否已有今日记录
var record model.PackageUsageDailyRecord
err = tx.Where("package_usage_id = ? AND date = ?", packageUsageID, date).
First(&record).Error
if err == gorm.ErrRecordNotFound {
// 创建新记录
record = model.PackageUsageDailyRecord{
PackageUsageID: packageUsageID,
Date: date,
DailyUsageMB: int(dailyUsageMB),
CumulativeUsageMB: cumulativeUsageMB,
}
if err := tx.Create(&record).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "创建日流量记录失败")
}
} else if err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "查询日流量记录失败")
} else {
// 更新现有记录
updates := map[string]interface{}{
"daily_usage_mb": record.DailyUsageMB + int(dailyUsageMB),
"cumulative_usage_mb": cumulativeUsageMB,
}
if err := tx.Model(&record).Updates(updates).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新日流量记录失败")
}
}
return nil
}
// checkAndTriggerSuspension 任务 10.5: 检查停机条件
func (s *UsageService) checkAndTriggerSuspension(ctx context.Context, tx *gorm.DB, carrierType string, carrierID uint) (bool, []packageUsageAuditChange, error) {
query := tx.Model(&model.PackageUsage{}).
@@ -490,45 +390,3 @@ func (s *UsageService) triggerSuspensionAfterCommit(ctx context.Context, carrier
})
}
}
// recordOverflowToDepletedPackage 在所有套餐已耗尽时,将溢出流量写入最近的 Depleted 套餐日记录。
// 目的:保持流量详单连续性,即便套餐用完期间上游仍有流量使用,详单不会断档。
// 只写日记录和累加 data_usage_mb,不改变套餐 status,不触发停机。
func (s *UsageService) recordOverflowToDepletedPackage(ctx context.Context, tx *gorm.DB, carrierType string, carrierID uint, overflowMB int64, today string) error {
query := tx.Where("status = ?", constants.PackageUsageStatusDepleted)
switch carrierType {
case constants.AssetTypeIotCard:
query = query.Where("iot_card_id = ?", carrierID)
case constants.AssetTypeDevice:
query = query.Where("device_id = ?", carrierID)
default:
return nil
}
// 优先选主套餐(master_usage_id IS NULL),主套餐不存在时再退而求其次取加油包
var pkg model.PackageUsage
err := query.Where("master_usage_id IS NULL").Order("id DESC").First(&pkg).Error
if err == gorm.ErrRecordNotFound {
err = query.Order("id DESC").First(&pkg).Error
}
if err != nil {
// 找不到任何 Depleted 套餐,静默忽略
return nil
}
newUsage := pkg.DataUsageMB + overflowMB
if err := tx.Model(&pkg).Update("data_usage_mb", newUsage).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新溢出流量失败")
}
if err := s.updateDailyRecord(ctx, tx, pkg.ID, today, overflowMB, newUsage); err != nil {
return err
}
s.logger.Info("记录溢出流量到已耗尽套餐",
zap.Uint("package_usage_id", pkg.ID),
zap.Int64("overflow_mb", overflowMB),
zap.Int64("new_usage_mb", newUsage))
return nil
}