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

@@ -30,6 +30,7 @@ import (
// IotCardRefresher 用于调用 RefreshCardDataFromGateway,避免循环依赖
type IotCardRefresher interface {
RefreshCardDataFromGateway(ctx context.Context, iccid string) error
RefreshCardDataWithTraffic(ctx context.Context, iccid string) (*dto.CardTrafficRefreshResult, error)
}
// PackageExpiryResolver 查询资产的套餐最终到期推算结果。
@@ -60,7 +61,9 @@ type Service struct {
packageExpiryQuery PackageExpiryResolver
pollingRestorer PollingRestorer
resumeEvaluator AssetResumeEvaluator
logger *zap.Logger
// trafficAdjustmentEvaluator 在冲正提交后评估停复机;未注入时冲正后不评估。
trafficAdjustmentEvaluator TrafficAdjustmentEvaluator
logger *zap.Logger
}
// SetPackageExpiryQuery 注入套餐最终到期查询,供资产详情统一投影使用。
@@ -681,10 +684,16 @@ func (s *Service) Refresh(ctx context.Context, assetType string, id uint) (*dto.
if err != nil {
return nil, errors.Wrap(errors.CodeNotFound, err, "卡不存在")
}
if err := s.iotCardService.RefreshCardDataFromGateway(ctx, card.ICCID); err != nil {
trafficResult, err := s.iotCardService.RefreshCardDataWithTraffic(ctx, card.ICCID)
if err != nil {
return nil, errors.Wrap(errors.CodeInternalError, err, "刷新卡数据失败")
}
return s.GetRealtimeStatus(ctx, "card", id)
status, err := s.GetRealtimeStatus(ctx, "card", id)
if err != nil {
return nil, err
}
status.TrafficRefresh = trafficResult
return status, nil
case "device":
totalStart := time.Now()
@@ -1017,44 +1026,23 @@ func (s *Service) UpdatePackageExpiresAt(ctx context.Context, assetType string,
return s.buildAssetPackageResponse(ctx, updated, constants.OwnerTypePlatform), nil
}
// UpdatePackageUsage 修改资产套餐已用量。
// UpdatePackageUsage 修改资产套餐已用量:改为经冲正流水进行,调整量 = 新已用量 − 锁定后的当前已用量。
func (s *Service) UpdatePackageUsage(ctx context.Context, assetType string, assetID uint, assetIdentifier string, packageUsageID uint, dataUsageMB int64) (*dto.AssetPackageResponse, error) {
if dataUsageMB < 0 {
return nil, errors.New(errors.CodeInvalidParam)
}
carrierType, err := normalizeAssetCarrierType(assetType)
if err != nil {
return nil, err
}
before, err := s.packageUsageStore.GetByIDForCarrier(ctx, packageUsageID, carrierType, assetID)
if _, err := s.adjustPackageTraffic(ctx, assetType, assetID, assetIdentifier,
trafficAdjustment{PackageUsageID: packageUsageID, Reason: legacyUsageEditReason}, &dataUsageMB); err != nil {
return nil, err
}
updated, err := s.packageUsageStore.GetByIDForCarrier(ctx, packageUsageID, carrierType, assetID)
if err != nil {
return nil, wrapPackageUsageNotFound(err)
}
beforeData := packageUsageTrafficAuditData(before)
nextStatus := statusForManualDataUsage(before, dataUsageMB)
var updated *model.PackageUsage
err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
store := postgres.NewPackageUsageStore(tx, nil)
rows, updateErr := store.UpdateDataUsageForCarrier(ctx, packageUsageID, carrierType, assetID, dataUsageMB, nextStatus)
if updateErr != nil {
return errors.Wrap(errors.CodeDatabaseError, updateErr, "修改套餐已用量失败")
}
if rows == 0 {
return errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
}
updated, updateErr = store.GetByIDForCarrier(ctx, packageUsageID, carrierType, assetID)
if updateErr != nil {
return errors.Wrap(errors.CodeDatabaseError, updateErr, "查询套餐使用记录失败")
}
return s.appendPackageAdjustmentAudit(ctx, tx, constants.AuditActionPackageUsageTrafficAdjusted, "修改资产套餐已用量", constants.AuditResultSuccess, updated, assetType, assetID, assetIdentifier, beforeData, packageUsageTrafficAuditData(updated), nil)
})
if err != nil {
s.recordPackageAdjustmentFailure(ctx, constants.AuditActionPackageUsageTrafficAdjusted, "修改资产套餐已用量失败", before, assetType, assetID, assetIdentifier, beforeData, map[string]any{"package_usage_id": packageUsageID, "data_usage_mb": dataUsageMB}, err)
return nil, err
}
return s.buildAssetPackageResponse(ctx, updated, constants.OwnerTypePlatform), nil
}

View File

@@ -0,0 +1,201 @@
package asset
import (
"context"
"strings"
"go.uber.org/zap"
"gorm.io/gorm"
stopresumedomain "github.com/break/junhong_cmp_fiber/internal/domain/stopresume"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
)
// legacyUsageEditReason 是旧"修改资产套餐已用量"接口改走冲正流水时记录的原因。
const legacyUsageEditReason = "后台修改资产套餐已用量"
// TrafficAdjustmentEvaluator 在冲正提交后按最新套餐、流量、实名事实评估卡的停复机。
type TrafficAdjustmentEvaluator interface {
EvaluateAndAct(ctx context.Context, card *model.IotCard) error
}
// SetTrafficAdjustmentEvaluator 注入冲正提交后的停复机判断。
func (s *Service) SetTrafficAdjustmentEvaluator(evaluator TrafficAdjustmentEvaluator) {
s.trafficAdjustmentEvaluator = evaluator
}
// trafficAdjustment 是一次冲正的输入。
type trafficAdjustment struct {
PackageUsageID uint
DeltaMB int64
Reason string
RefObservationID string
RefEventID string
}
// AdjustPackageTraffic 人工冲正套餐流量:锁套餐行、按锁定后的当前已用量加减、退回后不得小于 0,
// 同事务写冲正流水、更新已用量并按阈值重算状态(已过期、已失效只改已用量)、写审计;提交后走停复机判断。
// 冲正不修改卡日快照与已结算。
func (s *Service) AdjustPackageTraffic(ctx context.Context, assetType string, assetID uint, assetIdentifier string, req *dto.AdjustAssetPackageTrafficRequest) (*dto.PackageTrafficAdjustmentItem, error) {
if req == nil || req.DeltaMB == 0 || strings.TrimSpace(req.Reason) == "" {
return nil, errors.New(errors.CodeInvalidParam, "冲正调整量不能为 0,原因必填")
}
return s.adjustPackageTraffic(ctx, assetType, assetID, assetIdentifier, trafficAdjustment{
PackageUsageID: req.PackageUsageID, DeltaMB: req.DeltaMB, Reason: strings.TrimSpace(req.Reason),
RefObservationID: strings.TrimSpace(req.RefObservationID), RefEventID: strings.TrimSpace(req.RefEventID),
}, nil)
}
// adjustPackageTraffic 执行冲正;targetUsageMB 非空时按"改成该已用量"计算调整量(旧接口兼容)。
func (s *Service) adjustPackageTraffic(ctx context.Context, assetType string, assetID uint, assetIdentifier string, input trafficAdjustment, targetUsageMB *int64) (*dto.PackageTrafficAdjustmentItem, error) {
operatorID := middleware.GetUserIDFromContext(ctx)
if operatorID == 0 {
return nil, errors.New(errors.CodeUnauthorized, "未授权访问")
}
carrierType, err := normalizeAssetCarrierType(assetType)
if err != nil {
return nil, err
}
var record model.PackageUsageAdjustment
var before, updated *model.PackageUsage
err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
store := postgres.NewPackageUsageStore(tx, nil)
locked, lockErr := store.LockByIDForCarrier(ctx, input.PackageUsageID, carrierType, assetID)
if lockErr != nil {
return wrapPackageUsageNotFound(lockErr)
}
before = locked
delta := input.DeltaMB
if targetUsageMB != nil {
delta = *targetUsageMB - locked.DataUsageMB
}
if delta == 0 {
if targetUsageMB != nil {
// 旧接口改成与当前相同的已用量:不产生冲正流水。
return nil
}
return errors.New(errors.CodeInvalidParam, "冲正调整量不能为 0")
}
after := locked.DataUsageMB + delta
if after < 0 {
return errors.New(errors.CodeInvalidParam, "退回后套餐已用量不能小于 0")
}
nextStatus := statusForManualDataUsage(locked, after)
if _, updateErr := store.UpdateDataUsageForCarrier(ctx, locked.ID, carrierType, assetID, after, nextStatus); updateErr != nil {
return errors.Wrap(errors.CodeDatabaseError, updateErr, "冲正套餐已用量失败")
}
afterStatus := locked.Status
if nextStatus != nil {
afterStatus = *nextStatus
}
record = model.PackageUsageAdjustment{
PackageUsageID: locked.ID, IotCardID: locked.IotCardID, DeviceID: locked.DeviceID,
DeltaMB: delta, BeforeUsageMB: locked.DataUsageMB, AfterUsageMB: after,
BeforeStatus: locked.Status, AfterStatus: afterStatus, Reason: input.Reason,
RefObservationID: input.RefObservationID, RefEventID: input.RefEventID, OperatorID: operatorID,
}
if createErr := tx.WithContext(ctx).Create(&record).Error; createErr != nil {
return errors.Wrap(errors.CodeDatabaseError, createErr, "写入冲正流水失败")
}
var loadErr error
if updated, loadErr = store.GetByIDForCarrier(ctx, locked.ID, carrierType, assetID); loadErr != nil {
return errors.Wrap(errors.CodeDatabaseError, loadErr, "查询套餐使用记录失败")
}
afterData := packageUsageTrafficAuditData(updated)
afterData["adjustment_id"], afterData["delta_mb"], afterData["reason"] = record.ID, delta, input.Reason
return s.appendPackageAdjustmentAudit(ctx, tx, constants.AuditActionPackageUsageTrafficAdjusted, "人工冲正套餐流量", constants.AuditResultSuccess,
updated, assetType, assetID, assetIdentifier, packageUsageTrafficAuditData(locked), afterData, nil)
})
if err != nil {
if before != nil {
s.recordPackageAdjustmentFailure(ctx, constants.AuditActionPackageUsageTrafficAdjusted, "人工冲正套餐流量失败", before, assetType, assetID, assetIdentifier,
packageUsageTrafficAuditData(before), map[string]any{"package_usage_id": input.PackageUsageID, "delta_mb": input.DeltaMB, "reason": input.Reason}, err)
}
return nil, err
}
if record.ID == 0 {
return nil, nil
}
s.evaluateAfterAdjustment(ctx, carrierType, assetID)
item := toTrafficAdjustmentItem(record)
return &item, nil
}
// evaluateAfterAdjustment 冲正提交后对载体下的卡调用停复机判断,不直接复机或停机。
func (s *Service) evaluateAfterAdjustment(ctx context.Context, carrierType string, carrierID uint) {
if s.trafficAdjustmentEvaluator == nil {
return
}
evalCtx := stopresumedomain.WithScene(context.WithoutCancel(ctx), constants.StopResumeSceneUsage)
var cards []*model.IotCard
query := s.db.WithContext(evalCtx).Model(&model.IotCard{})
if carrierType == constants.AssetTypeDevice {
query = query.Where("id IN (?)", s.db.Model(&model.DeviceSimBinding{}).Select("iot_card_id").
Where("device_id = ? AND bind_status = ?", carrierID, constants.BindStatusBound))
} else {
query = query.Where("id = ?", carrierID)
}
if err := query.Find(&cards).Error; err != nil {
s.adjustmentLogger().Warn("冲正后查询载体下的卡失败,未做停复机判断", zap.String("carrier_type", carrierType), zap.Uint("carrier_id", carrierID), zap.Error(err))
return
}
for _, card := range cards {
if err := s.trafficAdjustmentEvaluator.EvaluateAndAct(evalCtx, card); err != nil {
s.adjustmentLogger().Warn("冲正后停复机判断失败", zap.Uint("card_id", card.ID), zap.Error(err))
}
}
}
func (s *Service) adjustmentLogger() *zap.Logger {
if s.logger == nil {
return zap.NewNop()
}
return s.logger
}
// ListPackageTrafficAdjustments 分页查询套餐的冲正流水,按时间倒序。
func (s *Service) ListPackageTrafficAdjustments(ctx context.Context, assetType string, assetID uint, req *dto.PackageTrafficAdjustmentListRequest) (*dto.PackageTrafficAdjustmentListResponse, error) {
carrierType, err := normalizeAssetCarrierType(assetType)
if err != nil {
return nil, err
}
if _, err := s.packageUsageStore.GetByIDForCarrier(ctx, req.PackageUsageID, carrierType, assetID); err != nil {
return nil, wrapPackageUsageNotFound(err)
}
page, size := req.Page, req.PageSize
if page <= 0 {
page = 1
}
if size <= 0 {
size = 20
}
query := s.db.WithContext(ctx).Model(&model.PackageUsageAdjustment{}).Where("package_usage_id = ?", req.PackageUsageID)
var total int64
if err := query.Count(&total).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询冲正流水失败")
}
var rows []model.PackageUsageAdjustment
if err := query.Order("created_at DESC, id DESC").Offset((page - 1) * size).Limit(size).Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询冲正流水失败")
}
items := make([]dto.PackageTrafficAdjustmentItem, 0, len(rows))
for _, row := range rows {
items = append(items, toTrafficAdjustmentItem(row))
}
return &dto.PackageTrafficAdjustmentListResponse{Items: items, Total: total}, nil
}
func toTrafficAdjustmentItem(row model.PackageUsageAdjustment) dto.PackageTrafficAdjustmentItem {
return dto.PackageTrafficAdjustmentItem{
ID: row.ID, PackageUsageID: row.PackageUsageID, DeltaMB: row.DeltaMB,
BeforeUsageMB: row.BeforeUsageMB, AfterUsageMB: row.AfterUsageMB,
BeforeStatus: row.BeforeStatus, AfterStatus: row.AfterStatus, Reason: row.Reason,
RefObservationID: row.RefObservationID, RefEventID: row.RefEventID,
OperatorID: row.OperatorID, CreatedAt: row.CreatedAt,
}
}

View File

@@ -0,0 +1,66 @@
package asset
import (
"context"
"encoding/json"
"time"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// maxCollectionQuerySpan 是采集记录单次查询的最长时间跨度。
const maxCollectionQuerySpan = 31 * 24 * time.Hour
// collectionTimeLayouts 是采集记录查询时间参数接受的格式(无时区时按上海时间解析)。
var collectionTimeLayouts = []string{time.RFC3339, "2006-01-02 15:04:05", "2006-01-02"}
// ListCardTrafficCollections 按卡与采集时间范围分页查询卡流量采集记录,按采集时间倒序。
func (s *Service) ListCardTrafficCollections(ctx context.Context, cardID uint, req *dto.CardTrafficCollectionListRequest) (*dto.CardTrafficCollectionListResponse, error) {
from, err := parseCollectionTime(req.StartTime)
if err != nil {
return nil, err
}
to, err := parseCollectionTime(req.EndTime)
if err != nil {
return nil, err
}
if !to.After(from) || to.Sub(from) > maxCollectionQuerySpan {
return nil, errors.New(errors.CodeInvalidParam, "结束时间必须晚于开始时间,且跨度不超过 31 天")
}
page, size := req.Page, req.PageSize
if page <= 0 {
page = 1
}
if size <= 0 {
size = 50
}
rows, total, err := postgres.NewCardTrafficCollectionStore(s.db).List(ctx, postgres.CardTrafficCollectionQuery{
CardID: cardID, From: from, To: to, Page: page, PageSize: size,
})
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量采集记录失败")
}
items := make([]dto.CardTrafficCollectionItem, 0, len(rows))
for _, row := range rows {
items = append(items, dto.CardTrafficCollectionItem{
ID: row.ID, ObservedAt: row.ObservedAt, ObservationID: row.ObservationID, Source: row.Source,
Scene: row.Scene, Result: row.Result, VendorUsedMB: row.VendorUsedMB, QueuePoints: json.RawMessage(row.QueuePoints),
Decision: row.Decision, MonthUsedMB: row.MonthUsedMB, StaleGuarded: row.StaleGuarded,
DeltaMB: row.DeltaMB, EventID: row.EventID,
})
}
return &dto.CardTrafficCollectionListResponse{Items: items, Total: total}, nil
}
func parseCollectionTime(value string) (time.Time, error) {
location := cardflow.ShanghaiDate(time.Now()).Location()
for _, layout := range collectionTimeLayouts {
if t, err := time.ParseInLocation(layout, value, location); err == nil {
return t, nil
}
}
return time.Time{}, errors.New(errors.CodeInvalidParam, "时间格式无效")
}

View File

@@ -32,6 +32,9 @@ func (s *Service) executeMigrationWithTx(ctx context.Context, tx *gorm.DB, order
if err = s.copyResourceTagsWithTx(ctx, tx, oldAsset, newAsset); err != nil {
return nil, errors.Wrap(errors.CodeExchangeMigrationFailed, err, "复制资产标签失败")
}
if err = markTrafficBaselinePendingWithTx(ctx, tx, newAsset); err != nil {
return nil, errors.Wrap(errors.CodeExchangeMigrationFailed, err, "标记新资产流量待建起点失败")
}
return &exchangeMigrationResult{Balance: migrationBalance, PackageUsageIDs: usageIDs}, nil
}
@@ -136,6 +139,19 @@ func (s *Service) migratePackageUsageWithTx(ctx context.Context, tx *gorm.DB, ol
return usageIDs, nil
}
// markTrafficBaselinePendingWithTx 给换货新卡(设备换货时为新设备当前绑定的每张卡)打"待建起点"标记:
// 新卡第一次通过采集队列写入时只建起点不扣费,出库前已有的读数不算给迁过来的套餐。不调用运营商接口。
func markTrafficBaselinePendingWithTx(ctx context.Context, tx *gorm.DB, newAsset *resolvedExchangeAsset) error {
query := tx.WithContext(ctx).Model(&model.IotCard{})
if newAsset.AssetType == constants.ExchangeAssetTypeIotCard {
query = query.Where("id = ?", newAsset.AssetID)
} else {
query = query.Where("id IN (?)", tx.Model(&model.DeviceSimBinding{}).Select("iot_card_id").
Where("device_id = ? AND bind_status = ?", newAsset.AssetID, constants.BindStatusBound))
}
return query.Update("traffic_baseline_pending", true).Error
}
func (s *Service) copyAccumulatedFieldsWithTx(tx *gorm.DB, oldAsset, newAsset *resolvedExchangeAsset) error {
if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
if oldAsset.Card == nil {

View File

@@ -1408,6 +1408,18 @@ func (s *Service) RefreshCardDataByID(ctx context.Context, cardID uint) error {
// 调用网关查询网络状态、实名状态、本月流量,并写回数据库
// 流量采用增量计算(与轮询逻辑一致):increment = 当前网关读数 - 上次网关读数
func (s *Service) RefreshCardDataFromGateway(ctx context.Context, iccid string) error {
_, err := s.RefreshCardDataWithTraffic(ctx, iccid)
return err
}
// RefreshCardDataWithTraffic 同 RefreshCardDataFromGateway,并返回本次流量读数、是否写入与原因。
func (s *Service) RefreshCardDataWithTraffic(ctx context.Context, iccid string) (*dto.CardTrafficRefreshResult, error) {
var trafficResult *dto.CardTrafficRefreshResult
err := s.refreshCardDataFromGateway(ctx, iccid, &trafficResult)
return trafficResult, err
}
func (s *Service) refreshCardDataFromGateway(ctx context.Context, iccid string, trafficResult **dto.CardTrafficRefreshResult) error {
card, err := s.iotCardStore.GetByICCID(ctx, iccid)
if err != nil {
if err == gorm.ErrRecordNotFound {
@@ -1644,6 +1656,7 @@ func (s *Service) RefreshCardDataFromGateway(ctx context.Context, iccid string)
resetDay := postgres.NewCarrierStore(s.db).GetDataResetDay(ctx, card.CarrierID)
decision, applyErr := s.cardObservation.ApplyTrafficObservation(ctx, carddomain.TrafficObservation{
CardID: card.ID, GatewayReadingMB: float64(flowResp.Used), ResetDay: resetDay,
ReadingResult: refreshReadingResult(flowResp),
Metadata: carddomain.ObservationMetadata{
ObservationID: uuid.NewString(), Source: constants.CardObservationSourceManualSync,
Scene: constants.CardObservationSceneManualRefresh, ObservedAt: syncTime,
@@ -1663,6 +1676,10 @@ func (s *Service) RefreshCardDataFromGateway(ctx context.Context, iccid string)
}
refreshSuccess++
flowIncrementMB = decision.IncrementMB
*trafficResult = &dto.CardTrafficRefreshResult{
ReadingMB: decision.ReadingMB, Result: decision.Result, Written: decision.ReadingAccepted,
Decision: decision.Decision, DeltaMB: decision.IncrementMB,
}
}
}
}
@@ -2096,3 +2113,11 @@ func applyFirstPurchaseFilters(filters map[string]any, start, end string) error
}
return nil
}
// refreshReadingResult 把运营商流量响应映射为读数结果:没给出可解析读数时为无读数。
func refreshReadingResult(response *gateway.FlowUsageResp) string {
if !response.HasReading() {
return constants.TrafficCollectionResultNoReading
}
return constants.TrafficCollectionResultOK
}

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
}

View File

@@ -28,6 +28,8 @@ type ConfigService struct {
logger *zap.Logger
configMgr *pollingcore.PollingConfigManager
queueClient TaskEnqueuer
// trafficQueueLimits 返回当前采集队列配置,用于校验启用中配置的流量采集间隔上限。
trafficQueueLimits func(ctx context.Context) TrafficQueueLimits
}
// SetAudit 注入轮询配置事务与统一审计 Writer。
@@ -92,6 +94,9 @@ func (s *ConfigService) Create(ctx context.Context, req *dto.CreatePollingConfig
if err := validatePollingConfig(config); err != nil {
return nil, err
}
if err := s.validateTrafficInterval(ctx, config); err != nil {
return nil, err
}
err := runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := s.configStore.WithTx(tx).Create(ctx, config); err != nil {
@@ -211,6 +216,9 @@ func (s *ConfigService) Update(ctx context.Context, id uint, req *dto.UpdatePoll
if err := validatePollingConfig(config); err != nil {
return nil, err
}
if err := s.validateTrafficInterval(ctx, config); err != nil {
return nil, err
}
config.UpdatedBy = &currentUserID
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
@@ -343,6 +351,13 @@ func (s *ConfigService) UpdateStatus(ctx context.Context, id uint, status int16)
}
before := pollingConfigState(config)
if status == 1 {
enabled := *config
enabled.Status = status
if err := s.validateTrafficInterval(ctx, &enabled); err != nil {
return err
}
}
err = runPollingTransaction(ctx, s.db, s.auditWriter, func(tx *gorm.DB) error {
if err := s.configStore.WithTx(tx).UpdateStatus(ctx, id, status, currentUserID); err != nil {
return err

View File

@@ -0,0 +1,64 @@
package polling
import (
"context"
"fmt"
"time"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// TrafficQueueLimits 是校验流量采集间隔需要的采集队列配置。
type TrafficQueueLimits struct {
Size int
ClearOnNewDay bool
MaxPointAgeHours int
}
// SetTrafficQueueLimits 注入当前采集队列配置;未注入时不校验流量采集间隔。
func (s *ConfigService) SetTrafficQueueLimits(limits func(ctx context.Context) TrafficQueueLimits) {
s.trafficQueueLimits = limits
}
// validateTrafficInterval 只对启用中的轮询配置校验流量采集间隔:不超过 24h ÷ (N+2)(跨天清空开启)
// 或最长点龄 ÷ (N+2)(关闭);停用的配置不校验。
func (s *ConfigService) validateTrafficInterval(ctx context.Context, config *model.PollingConfig) error {
if s.trafficQueueLimits == nil || config.Status != 1 {
return nil
}
return checkTrafficInterval(config, s.trafficQueueLimits(ctx))
}
func checkTrafficInterval(config *model.PollingConfig, limits TrafficQueueLimits) error {
limit := cardflow.MaxCollectionInterval(limits.Size, limits.ClearOnNewDay, limits.MaxPointAgeHours, constants.TrafficQueueIntervalSpare)
if limit <= 0 || config.CarddataCheckInterval == nil || *config.CarddataCheckInterval <= 0 {
return nil
}
interval := time.Duration(*config.CarddataCheckInterval) * time.Second
if interval <= limit {
return nil
}
return errors.New(errors.CodeInvalidParam, fmt.Sprintf(
"轮询配置「%s」流量检查间隔 %d 秒超过上限 %d 秒(采集队列长度 %d,留 %d 次冗余),请调小间隔",
config.ConfigName, *config.CarddataCheckInterval, int64(limit/time.Second), limits.Size, constants.TrafficQueueIntervalSpare))
}
// CheckEnabledTrafficIntervals 校验全部启用中的轮询配置在给定队列配置下是否都满足流量采集间隔上限,
// 用于修改队列长度、跨天清空、最长点龄前的拦截。
func CheckEnabledTrafficIntervals(ctx context.Context, db *gorm.DB, limits TrafficQueueLimits) error {
var configs []*model.PollingConfig
if err := db.WithContext(ctx).Where("status = ? AND carddata_check_interval > 0", 1).Find(&configs).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "查询启用中的轮询配置失败")
}
for _, config := range configs {
if err := checkTrafficInterval(config, limits); err != nil {
return err
}
}
return nil
}