收口审计治理与套餐任务进展

Constraint: 在线热修前必须保存当前迭代分支全部有效代码进展 Confidence: medium Scope-risk: broad Directive: 后续修改需保持审计事件与业务事务边界一致 Tested: git diff --cached --check Not-tested: 未运行全量测试，提交用于切换分支前保存既有工作
2026-08-05 14:30:54 +08:00
parent b3499adfca
commit 5e552d99bc
178 changed files with 16797 additions and 5674 deletions
--- a/internal/application/cardobservation/apply.go
+++ b/internal/application/cardobservation/apply.go
@@ -10,6 +10,7 @@ import (

 	domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
 	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/auditcontext"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"gorm.io/gorm"
@@ -42,11 +43,28 @@ type CacheInvalidator interface {
 	Invalidate(ctx context.Context, cardID uint)
 }

+// StateAudit 描述一次需要与卡事实关联保存的状态操作。
+type StateAudit struct {
+	ActionCode    string
+	Summary       string
+	Card          *model.IotCard
+	IntegrationID string
+	BeforeData    map[string]any
+	AfterData     map[string]any
+}
+
+// StateAuditWriter 在卡状态事务中追加统一 Audit Event。
+type StateAuditWriter interface {
+	WriteCardStateAudit(ctx context.Context, tx *gorm.DB, input StateAudit) error
+	WriteCardStateFailure(ctx context.Context, input StateAudit, businessErr error)
+}
+
 // Service 负责卡实名观测的锁定、规则应用和可靠事件写入。
 type Service struct {
 	db          *gorm.DB
 	eventWriter EventWriter
 	cache       CacheInvalidator
+	auditWriter StateAuditWriter
 }

 // NewService 创建卡实名观测应用服务。
@@ -54,6 +72,22 @@ func NewService(db *gorm.DB, eventWriter EventWriter, cache CacheInvalidator) *S
 	return &Service{db: db, eventWriter: eventWriter, cache: cache}
 }

+// SetStateAuditWriter 注入卡状态统一审计 Writer。
+func (s *Service) SetStateAuditWriter(writer StateAuditWriter) {
+	s.auditWriter = writer
+}
+
+// RecordCarrierCallbackFailure 在已解析卡资源后记录运营商回调处理失败。
+func (s *Service) RecordCarrierCallbackFailure(ctx context.Context, card *model.IotCard, integrationID string, businessErr error) {
+	if s == nil || s.auditWriter == nil || card == nil || card.ID == 0 {
+		return
+	}
+	s.auditWriter.WriteCardStateFailure(ctx, StateAudit{
+		ActionCode: constants.AuditActionIotCardRealnameCallbackSynced,
+		Summary: "运营商回调同步 IoT 卡实名状态失败", Card: card, IntegrationID: integrationID,
+	}, businessErr)
+}
+
 // ApplyCardObservation 在同一事务中应用实名状态、逆转窗口和状态变更事件。
 func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.RealnameObservation) (domain.RealnameDecision, error) {
 	if s == nil || s.db == nil || s.eventWriter == nil {
@@ -111,6 +145,58 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
 				return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名 Outbox 事件失败")
 			}
 		}
+		if observation.Metadata.Source == constants.CardObservationSourceManualOverride {
+			if s.auditWriter == nil {
+				return errors.New(errors.CodeInternalError, "卡状态统一审计能力未配置")
+			}
+			summary := "人工更新 IoT 卡实名状态"
+			if !decision.StatusChanged {
+				summary = "人工确认 IoT 卡实名状态无需变化"
+			}
+			if err := s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
+				ActionCode: constants.AuditActionIotCardRealnameStatusUpdated,
+				Summary:    summary,
+				Card:       &card,
+				BeforeData: map[string]any{"real_name_status": card.RealNameStatus, "first_realname_at": card.FirstRealnameAt},
+				AfterData: map[string]any{
+					"real_name_status": decision.AfterStatus, "first_realname_at": firstRealnameAfter(card.FirstRealnameAt, observation.Metadata.ObservedAt, decision.FirstVerified),
+					"status_changed": decision.StatusChanged,
+				},
+			}); err != nil {
+				return err
+			}
+		} else if actionCode, audited := manualRefreshAuditAction(ctx); observation.Metadata.Source == constants.CardObservationSourceManualSync && decision.StatusChanged && audited {
+			if s.auditWriter == nil {
+				return errors.New(errors.CodeInternalError, "卡状态统一审计能力未配置")
+			}
+			if err := s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
+				ActionCode: actionCode,
+				Summary:    "人工刷新 IoT 卡实名状态",
+				Card:       &card,
+				BeforeData: map[string]any{"real_name_status": card.RealNameStatus, "first_realname_at": card.FirstRealnameAt},
+				AfterData: map[string]any{
+					"real_name_status": decision.AfterStatus, "first_realname_at": firstRealnameAfter(card.FirstRealnameAt, observation.Metadata.ObservedAt, decision.FirstVerified),
+				},
+			}); err != nil {
+				return err
+			}
+		} else if observation.Metadata.Source == constants.CardObservationSourceCarrierCallback && decision.StatusChanged {
+			if s.auditWriter == nil {
+				return errors.New(errors.CodeInternalError, "卡状态统一审计能力未配置")
+			}
+			if err := s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
+				ActionCode: constants.AuditActionIotCardRealnameCallbackSynced,
+				Summary:    "运营商回调同步 IoT 卡实名状态",
+				Card:       &card,
+				IntegrationID: observation.Metadata.ObservationID,
+				BeforeData: map[string]any{"real_name_status": card.RealNameStatus, "first_realname_at": card.FirstRealnameAt},
+				AfterData: map[string]any{
+					"real_name_status": decision.AfterStatus, "first_realname_at": firstRealnameAfter(card.FirstRealnameAt, observation.Metadata.ObservedAt, decision.FirstVerified),
+				},
+			}); err != nil {
+				return err
+			}
+		}
 		return nil
 	})
 	if err != nil {
@@ -122,6 +208,24 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
 	return decision, nil
 }

+func firstRealnameAfter(before *time.Time, observedAt time.Time, firstVerified bool) *time.Time {
+	if firstVerified {
+		return &observedAt
+	}
+	return before
+}
+
+func manualRefreshAuditAction(ctx context.Context) (string, bool) {
+	switch auditcontext.From(ctx).ActorKind {
+	case constants.AuditActorAccount:
+		return constants.AuditActionIotCardManualRefreshed, true
+	case constants.AuditActorPersonalCustomer:
+		return constants.AuditActionIotCardPersonalRefreshed, true
+	default:
+		return "", false
+	}
+}
+
 func realnameChangedEventID(cardID uint, observationID string) string {
 	prefix := "card-realname:"
 	digest := sha256.Sum256([]byte(strconv.FormatUint(uint64(cardID), 10) + ":" + observationID + ":changed"))
--- a/internal/application/cardobservation/network.go
+++ b/internal/application/cardobservation/network.go
@@ -7,6 +7,7 @@ import (

 	domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
 	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
@@ -74,17 +75,48 @@ func (s *Service) ApplyNetworkObservation(ctx context.Context, observation domai
 		if result.RowsAffected != 1 {
 			return errors.New(errors.CodeConflict, "卡网络事实已被其他请求更新")
 		}
-		if !decision.StatusChanged {
-			return nil
+		if decision.StatusChanged {
+			eventID := "card-network:" + strconv.FormatUint(uint64(card.ID), 10) + ":" + observation.Metadata.ObservationID + ":changed"
+			if err := s.eventWriter.AppendNetwork(ctx, tx, NetworkChangedEvent{
+				EventID: eventID, CardID: card.ID, BeforeStatus: card.NetworkStatus, AfterStatus: decision.AfterStatus,
+				GatewayExtend: decision.GatewayExtend, ObservedAt: observation.Metadata.ObservedAt,
+				Source: observation.Metadata.Source, Scene: observation.Metadata.Scene,
+				RequestID: observation.Metadata.RequestID, CorrelationID: observation.Metadata.CorrelationID,
+			}); err != nil {
+				return errors.Wrap(errors.CodeDatabaseError, err, "写入卡网络 Outbox 事件失败")
+			}
 		}
-		eventID := "card-network:" + strconv.FormatUint(uint64(card.ID), 10) + ":" + observation.Metadata.ObservationID + ":changed"
-		if err := s.eventWriter.AppendNetwork(ctx, tx, NetworkChangedEvent{
-			EventID: eventID, CardID: card.ID, BeforeStatus: card.NetworkStatus, AfterStatus: decision.AfterStatus,
-			GatewayExtend: decision.GatewayExtend, ObservedAt: observation.Metadata.ObservedAt,
-			Source: observation.Metadata.Source, Scene: observation.Metadata.Scene,
-			RequestID: observation.Metadata.RequestID, CorrelationID: observation.Metadata.CorrelationID,
-		}); err != nil {
-			return errors.Wrap(errors.CodeDatabaseError, err, "写入卡网络 Outbox 事件失败")
+		stateChanged := decision.StatusChanged || decision.StopReasonChanged || decision.StopPolling ||
+			decision.GatewayExtend != card.GatewayExtend || decision.UpdateIMEI && decision.GatewayIMEI != card.GatewayCardIMEI
+		if actionCode, audited := manualRefreshAuditAction(ctx); observation.Metadata.Source == constants.CardObservationSourceManualSync && stateChanged && audited {
+			if s.auditWriter == nil {
+				return errors.New(errors.CodeInternalError, "卡状态统一审计能力未配置")
+			}
+			enablePolling := card.EnablePolling
+			if decision.StopPolling {
+				enablePolling = false
+			}
+			gatewayIMEI := card.GatewayCardIMEI
+			if decision.UpdateIMEI {
+				gatewayIMEI = decision.GatewayIMEI
+			}
+			if err := s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
+				ActionCode: actionCode,
+				Summary:    "人工刷新 IoT 卡网络状态",
+				Card:       &card,
+				BeforeData: map[string]any{
+					"network_status": card.NetworkStatus, "stop_reason": card.StopReason,
+					"gateway_extend": card.GatewayExtend, "gateway_card_imei": card.GatewayCardIMEI,
+					"enable_polling": card.EnablePolling,
+				},
+				AfterData: map[string]any{
+					"network_status": decision.AfterStatus, "stop_reason": decision.StopReason,
+					"gateway_extend": decision.GatewayExtend, "gateway_card_imei": gatewayIMEI,
+					"enable_polling": enablePolling,
+				},
+			}); err != nil {
+				return err
+			}
 		}
 		return nil
 	})
--- a/internal/application/cardobservation/traffic.go
+++ b/internal/application/cardobservation/traffic.go
@@ -10,6 +10,7 @@ import (

 	domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
 	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 )

@@ -65,16 +66,41 @@ func (s *Service) ApplyTrafficObservation(ctx context.Context, observation domai
 		if result.RowsAffected != 1 {
 			return errors.New(errors.CodeConflict, "卡流量基线已被其他请求更新")
 		}
-		if decision.IncrementMB <= 0 {
-			return nil
+		if decision.IncrementMB > 0 {
+			eventID := "card-traffic:" + strconv.FormatUint(uint64(card.ID), 10) + ":" + observation.Metadata.ObservationID + ":incremented"
+			if err := s.eventWriter.AppendTraffic(ctx, tx, TrafficIncrementedEvent{
+				EventID: eventID, CardID: card.ID, IncrementMB: decision.IncrementMB,
+				ObservedAt: observation.Metadata.ObservedAt, Source: observation.Metadata.Source,
+				Scene: observation.Metadata.Scene, RequestID: observation.Metadata.RequestID,
+				CorrelationID: observation.Metadata.CorrelationID,
+			}); err != nil {
+				return err
+			}
 		}
-		eventID := "card-traffic:" + strconv.FormatUint(uint64(card.ID), 10) + ":" + observation.Metadata.ObservationID + ":incremented"
-		return s.eventWriter.AppendTraffic(ctx, tx, TrafficIncrementedEvent{
-			EventID: eventID, CardID: card.ID, IncrementMB: decision.IncrementMB,
-			ObservedAt: observation.Metadata.ObservedAt, Source: observation.Metadata.Source,
-			Scene: observation.Metadata.Scene, RequestID: observation.Metadata.RequestID,
-			CorrelationID: observation.Metadata.CorrelationID,
-		})
+		stateChanged := decision.IncrementMB != 0 || decision.CrossMonth || decision.LastGatewayReadingMB != card.LastGatewayReadingMB
+		if actionCode, audited := manualRefreshAuditAction(ctx); observation.Metadata.Source == constants.CardObservationSourceManualSync && stateChanged && audited {
+			if s.auditWriter == nil {
+				return errors.New(errors.CodeInternalError, "卡状态统一审计能力未配置")
+			}
+			if err := s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
+				ActionCode: actionCode,
+				Summary:    "人工刷新 IoT 卡流量",
+				Card:       &card,
+				BeforeData: map[string]any{
+					"data_usage_mb": card.DataUsageMB, "current_month_usage_mb": card.CurrentMonthUsageMB,
+					"current_month_start_date": card.CurrentMonthStartDate, "last_month_total_mb": card.LastMonthTotalMB,
+					"last_gateway_reading_mb": card.LastGatewayReadingMB,
+				},
+				AfterData: map[string]any{
+					"data_usage_mb": decision.DataUsageMB, "current_month_usage_mb": decision.CurrentMonthUsageMB,
+					"current_month_start_date": decision.CurrentMonthStartDate, "last_month_total_mb": decision.LastMonthTotalMB,
+					"last_gateway_reading_mb": decision.LastGatewayReadingMB, "increment_mb": decision.IncrementMB,
+				},
+			}); err != nil {
+				return err
+			}
+		}
+		return nil
 	})
 	if err != nil {
 		return domain.TrafficDecision{}, err