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

Constraint: 在线热修前必须保存当前迭代分支全部有效代码进展
Confidence: medium
Scope-risk: broad
Directive: 后续修改需保持审计事件与业务事务边界一致
Tested: git diff --cached --check
Not-tested: 未运行全量测试，提交用于切换分支前保存既有工作

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"))