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

@@ -88,6 +88,19 @@ func (s *CardFlowDayStore) AddSettled(ctx context.Context, cardID uint, flowDate
).Error
}
// AddSettledToLatest 把增量计入本月截至 flowDate 最近一天快照的已结算;本月没有快照时不做任何事。
func (s *CardFlowDayStore) AddSettledToLatest(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 id = (SELECT id FROM tb_card_flow_day WHERE iot_card_id = ? AND flow_date >= ?::date AND flow_date <= ?::date
ORDER BY flow_date DESC LIMIT 1)`,
deltaMB, cardID, cardflow.MonthStart(flowDate).Format(cardFlowDateLayout), 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)

View File

@@ -1,43 +0,0 @@
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

@@ -0,0 +1,97 @@
package postgres
import (
"context"
"fmt"
"strings"
"time"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/model"
)
// collectionPartitionPrefix 是采集记录月分区表名前缀,后接 YYYYMM。
const collectionPartitionPrefix = "tb_card_traffic_collection_"
// CardTrafficCollectionStore 卡流量采集记录存储。
type CardTrafficCollectionStore struct {
db *gorm.DB
}
// NewCardTrafficCollectionStore 创建采集记录存储。
func NewCardTrafficCollectionStore(db *gorm.DB) *CardTrafficCollectionStore {
return &CardTrafficCollectionStore{db: db}
}
// Create 写入一条采集记录。
func (s *CardTrafficCollectionStore) Create(ctx context.Context, record *model.CardTrafficCollection) error {
return s.db.WithContext(ctx).Create(record).Error
}
// CardTrafficCollectionQuery 是采集记录查询条件。
type CardTrafficCollectionQuery struct {
CardID uint
From, To time.Time
Page int
PageSize int
}
// List 按卡与采集时间范围分页查询采集记录,按采集时间倒序。
func (s *CardTrafficCollectionStore) List(ctx context.Context, query CardTrafficCollectionQuery) ([]model.CardTrafficCollection, int64, error) {
db := s.db.WithContext(ctx).Model(&model.CardTrafficCollection{}).
Where("iot_card_id = ? AND observed_at >= ? AND observed_at < ?", query.CardID, query.From, query.To)
var total int64
if err := db.Count(&total).Error; err != nil {
return nil, 0, err
}
var rows []model.CardTrafficCollection
err := db.Order("observed_at DESC, id DESC").Offset((query.Page - 1) * query.PageSize).Limit(query.PageSize).Find(&rows).Error
return rows, total, err
}
// FindByObservationID 按采集 ID 查询采集记录。
func (s *CardTrafficCollectionStore) FindByObservationID(ctx context.Context, observationID string) ([]model.CardTrafficCollection, error) {
var rows []model.CardTrafficCollection
err := s.db.WithContext(ctx).Where("observation_id = ?", observationID).Order("observed_at DESC").Find(&rows).Error
return rows, err
}
// MaintainPartitions 预建本月起 aheadMonths 个月的分区,并删除整月都早于保留期的分区。
func (s *CardTrafficCollectionStore) MaintainPartitions(ctx context.Context, now time.Time, aheadMonths int, retentionDays int) error {
monthStart := cardflow.MonthStart(now)
for i := 0; i <= aheadMonths; i++ {
from := monthStart.AddDate(0, i, 0)
to := from.AddDate(0, 1, 0)
sql := fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s%s PARTITION OF tb_card_traffic_collection FOR VALUES FROM ('%s') TO ('%s')`,
collectionPartitionPrefix, from.Format("200601"), from.Format(time.RFC3339), to.Format(time.RFC3339))
if err := s.db.WithContext(ctx).Exec(sql).Error; err != nil {
return err
}
}
cutoff := cardflow.ShanghaiDate(now).AddDate(0, 0, -retentionDays)
var partitions []string
if err := s.db.WithContext(ctx).Raw(`
SELECT c.relname FROM pg_inherits i
JOIN pg_class c ON c.oid = i.inhrelid
JOIN pg_class p ON p.oid = i.inhparent
WHERE p.relname = 'tb_card_traffic_collection'`).Scan(&partitions).Error; err != nil {
return err
}
for _, name := range partitions {
if len(name) != len(collectionPartitionPrefix)+6 || !strings.HasPrefix(name, collectionPartitionPrefix) {
continue
}
start, err := time.ParseInLocation("200601", name[len(collectionPartitionPrefix):], cutoff.Location())
if err != nil {
continue
}
if !start.AddDate(0, 1, 0).After(cutoff) {
if err := s.db.WithContext(ctx).Exec(fmt.Sprintf("DROP TABLE IF EXISTS %s", name)).Error; err != nil {
return err
}
}
}
return nil
}

View File

@@ -0,0 +1,94 @@
package postgres
import (
"context"
"time"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// effectivePackageStatuses 是"采集时刻有效套餐"认可的套餐状态:状态可能在采集之后才变为已用完或已过期,
// 是否在采集时刻有效由激活时间与到期时间判断。
var effectivePackageStatuses = []int{
constants.PackageUsageStatusActive, constants.PackageUsageStatusDepleted, constants.PackageUsageStatusExpired,
}
// EffectivePackages 是一次"采集时刻有效套餐"查询的结果。
type EffectivePackages struct {
// CarrierType 与 CarrierID 是实际扣减载体:卡自身没有有效套餐时回退到卡当前绑定的设备。
CarrierType string
CarrierID uint
// Packages 按扣减优先级排序:加油包优先,再按 priority、id。
Packages []*model.PackageUsage
}
// FindEffectivePackagesAt 按"有套餐"共用口径查询卡在采集时刻的有效套餐:状态为生效中、已用完或已过期,
// 激活时间不晚于采集时间(为空按已生效),到期时间为空或晚于采集时间,未退款;
// 卡自身一个都没有时看卡当前绑定设备的套餐。lock 为 true 时对查到的套餐行加 FOR UPDATE。
// 采集侧(写入范围、是否发事件、采集记录、日用量 0 行)与扣费侧共用本函数,避免两边口径不一致。
func FindEffectivePackagesAt(ctx context.Context, db *gorm.DB, cardID uint, observedAt time.Time, lock bool) (EffectivePackages, error) {
own, err := queryEffectivePackages(ctx, db, "iot_card_id = ?", cardID, observedAt, lock)
if err != nil || len(own) > 0 {
return EffectivePackages{CarrierType: constants.AssetTypeIotCard, CarrierID: cardID, Packages: own}, err
}
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 EffectivePackages{}, err
}
if len(deviceIDs) == 0 {
return EffectivePackages{CarrierType: constants.AssetTypeIotCard, CarrierID: cardID}, nil
}
devicePackages, err := queryEffectivePackages(ctx, db, "device_id = ?", deviceIDs[0], observedAt, lock)
if err != nil {
return EffectivePackages{}, err
}
if len(devicePackages) == 0 {
return EffectivePackages{CarrierType: constants.AssetTypeIotCard, CarrierID: cardID}, nil
}
return EffectivePackages{CarrierType: constants.AssetTypeDevice, CarrierID: deviceIDs[0], Packages: devicePackages}, nil
}
func queryEffectivePackages(ctx context.Context, db *gorm.DB, carrierCondition string, carrierID uint, observedAt time.Time, lock bool) ([]*model.PackageUsage, error) {
query := db.WithContext(ctx).Model(&model.PackageUsage{}).
Where(carrierCondition, carrierID).
Where("status IN ?", effectivePackageStatuses).
Where("activated_at IS NULL OR activated_at <= ?", observedAt).
Where("expires_at IS NULL OR expires_at > ?", observedAt).
Where("refund_id IS NULL")
if lock {
query = query.Clauses(clause.Locking{Strength: "UPDATE"})
}
var packages []*model.PackageUsage
err := query.Order("CASE WHEN master_usage_id IS NOT NULL THEN 0 ELSE 1 END, priority ASC, id ASC").Find(&packages).Error
return packages, err
}
// EnsureDailyUsageRows 为每个套餐确保 date 当天一行套餐日用量(没有则写 0,已有不动)。
func EnsureDailyUsageRows(ctx context.Context, db *gorm.DB, packageUsageIDs []uint, date time.Time, cumulative map[uint]int64) error {
for _, id := range packageUsageIDs {
if err := db.WithContext(ctx).Exec(`
INSERT INTO tb_package_usage_daily_record (package_usage_id, date, daily_usage_mb, cumulative_usage_mb, created_at, updated_at)
VALUES (?, ?::date, 0, ?, NOW(), NOW())
ON CONFLICT (package_usage_id, date) DO NOTHING`, id, date.Format(cardFlowDateLayout), cumulative[id]).Error; err != nil {
return err
}
}
return nil
}
// AddDailyUsage 原子累加套餐 date 当天用量并覆盖累计用量;当天没有行时新建。
func AddDailyUsage(ctx context.Context, db *gorm.DB, packageUsageID uint, date time.Time, dailyMB int64, cumulativeMB int64) error {
return db.WithContext(ctx).Exec(`
INSERT INTO tb_package_usage_daily_record (package_usage_id, date, daily_usage_mb, cumulative_usage_mb, created_at, updated_at)
VALUES (?, ?::date, ?, ?, NOW(), NOW())
ON CONFLICT (package_usage_id, date) DO UPDATE SET
daily_usage_mb = tb_package_usage_daily_record.daily_usage_mb + EXCLUDED.daily_usage_mb,
cumulative_usage_mb = EXCLUDED.cumulative_usage_mb,
updated_at = NOW()`, packageUsageID, date.Format(cardFlowDateLayout), dailyMB, cumulativeMB).Error
}

View File

@@ -8,6 +8,7 @@ import (
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/redis/go-redis/v9"
"gorm.io/gorm"
"gorm.io/gorm/clause"
)
type PackageUsageStore struct {
@@ -53,6 +54,17 @@ func (s *PackageUsageStore) GetByIDForCarrier(ctx context.Context, id uint, carr
return &usage, nil
}
// LockByIDForCarrier 在当前事务内按载体锁定套餐使用记录(FOR UPDATE),与流量扣减同一把行锁。
func (s *PackageUsageStore) LockByIDForCarrier(ctx context.Context, id uint, carrierType string, carrierID uint) (*model.PackageUsage, error) {
var usage model.PackageUsage
query := s.db.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", id)
query = applyPackageUsageCarrierFilter(query, carrierType, carrierID)
if err := query.First(&usage).Error; err != nil {
return nil, err
}
return &usage, nil
}
// Update 更新套餐使用记录
func (s *PackageUsageStore) Update(ctx context.Context, usage *model.PackageUsage) error {
return s.db.WithContext(ctx).Save(usage).Error