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, "时间格式无效")
}