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

@@ -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
}