feat: 卡实名时间以上游 archiveTime 为准并记录实名时间历史,新增二次实名批次
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled

This commit is contained in:
邹进
2026-11-08 19:12:46 +09:00
parent 94f86ab217
commit 4967f4df43
32 changed files with 1885 additions and 47 deletions

View File

@@ -20,10 +20,11 @@ import (
// RealnameChangedEvent 是卡实名状态变化的可靠领域事实。
type RealnameChangedEvent struct {
EventID string `json:"event_id"`
CardID uint `json:"card_id"`
BeforeStatus int `json:"before_status"`
AfterStatus int `json:"after_status"`
EventID string `json:"event_id"`
CardID uint `json:"card_id"`
BeforeStatus int `json:"before_status"`
AfterStatus int `json:"after_status"`
// FirstVerified 表示需要触发实名激活:首次实名,或二次实名完成(此时 first_realname_at 不变)。
FirstVerified bool `json:"first_verified"`
ObservedAt time.Time `json:"observed_at"`
Source string `json:"source"`
@@ -175,6 +176,27 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
stale = true
return nil
}
realnameRecord, realnameSnapshot, loadErr := loadRealnameTime(ctx, tx, card.ID)
if loadErr != nil {
return loadErr
}
resetGate := domain.EvaluateRealnameResetGate(realnameSnapshot, observation)
if resetGate == domain.RealnameResetGateBlocked {
// 等待二次实名期间读到的仍是旧实名(上游实名时间不晚于清除前时间,或没有上游时间):不改实名状态,只记检查时间。
decision = domain.RealnameDecision{BeforeStatus: card.RealNameStatus, AfterStatus: card.RealNameStatus,
ReversalCount: card.RealnameReversalCount, ReversalStartedAt: card.RealnameReversalStartedAt}
checked := map[string]any{"last_real_name_check_at": observation.Metadata.ObservedAt}
if observation.Metadata.Source != constants.CardObservationSourceManualOverride {
checked["last_sync_time"] = observation.Metadata.ObservedAt
}
if err := tx.Model(&model.IotCard{}).Where("id = ?", card.ID).Updates(checked).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新卡实名检查时间失败")
}
s.warnLogger().Info("等待二次实名的卡读到旧实名,不覆盖",
zap.Uint("card_id", card.ID), zap.String("observation_id", observation.Metadata.ObservationID),
zap.Timep("upstream_realname_at", observation.UpstreamRealnameAt), zap.Timep("baseline_at", realnameSnapshot.ResetBaselineAt))
return nil
}
nextDecision, decisionErr := domain.ApplyRealname(domain.CardRealnameSnapshot{
CardID: card.ID, Status: card.RealNameStatus, FirstRealnameAt: card.FirstRealnameAt,
ReversalCount: card.RealnameReversalCount, ReversalStartedAt: card.RealnameReversalStartedAt,
@@ -207,11 +229,16 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
if result.RowsAffected != 1 {
return errors.New(errors.CodeConflict, "卡实名状态已被其他请求更新")
}
if observation.Verified && decision.AfterStatus == constants.RealNameStatusVerified {
if err := applyRealnameTime(ctx, tx, &card, realnameRecord, observation, resetGate); err != nil {
return err
}
}
if decision.StatusChanged {
eventID := realnameChangedEventID(card.ID, observation.Metadata.ObservationID)
if err := s.eventWriter.AppendRealname(ctx, tx, RealnameChangedEvent{
EventID: eventID, CardID: card.ID, BeforeStatus: card.RealNameStatus, AfterStatus: decision.AfterStatus,
FirstVerified: decision.FirstVerified, ObservedAt: observation.Metadata.ObservedAt,
FirstVerified: decision.FirstVerified || resetGate == domain.RealnameResetGateCompleted, ObservedAt: observation.Metadata.ObservedAt,
Source: observation.Metadata.Source, Scene: observation.Metadata.Scene,
RequestID: observation.Metadata.RequestID, CorrelationID: observation.Metadata.CorrelationID,
}); err != nil {

View File

@@ -0,0 +1,177 @@
package cardobservation
import (
"context"
"strconv"
"time"
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"
"github.com/break/junhong_cmp_fiber/pkg/outboxid"
"gorm.io/gorm"
"gorm.io/gorm/clause"
)
// RealnameResetCommand 描述对一张卡的二次实名清除或撤销。
type RealnameResetCommand struct {
CardID uint
BatchID uint
OperatorID uint
}
// 二次实名不可执行的原因(业务可预期,按行记录,不当作系统错误)。
var (
ErrRealnameResetNotVerified = errors.New(errors.CodeInvalidStatus, "卡未实名,无需二次实名")
ErrRealnameResetNoUpstream = errors.New(errors.CodeInvalidStatus, "上游未返回实名时间,不支持二次实名")
ErrRealnameResetAlreadyReset = errors.New(errors.CodeInvalidStatus, "卡已在等待二次实名")
ErrRealnameResetNotPending = errors.New(errors.CodeInvalidStatus, "卡不在等待二次实名,不能撤销")
)
// ResetRealname 二次实名清除:卡置为未实名、当前实名时间置空,记下清除前的上游实名时间作为新旧判定基准。
// 只支持上游返回过 archiveTime 的卡;已激活套餐不回退,first_realname_at 不修改。
// 状态变化按现有流程写实名变化事件与审计,下游停复机评估与普通未实名卡一致。
func (s *Service) ResetRealname(ctx context.Context, command RealnameResetCommand) error {
return s.changeRealnameForReset(ctx, command, false)
}
// RevertRealnameReset 撤销等待中的二次实名:卡恢复已实名,当前实名时间恢复为清除前时间。
func (s *Service) RevertRealnameReset(ctx context.Context, command RealnameResetCommand) error {
return s.changeRealnameForReset(ctx, command, true)
}
func (s *Service) changeRealnameForReset(ctx context.Context, command RealnameResetCommand, revert bool) error {
if s == nil || s.db == nil || s.eventWriter == nil || s.auditWriter == nil {
return errors.New(errors.CodeInternalError, "卡实名观测能力未完整配置")
}
if command.CardID == 0 {
return errors.New(errors.CodeInvalidParam, "卡 ID 无效")
}
now := time.Now()
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
var card model.IotCard
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", command.CardID).First(&card).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return errors.New(errors.CodeNotFound, "IoT卡不存在")
}
return errors.Wrap(errors.CodeDatabaseError, err, "锁定IoT卡失败")
}
record, snapshot, err := loadRealnameTime(ctx, tx, card.ID)
if err != nil {
return err
}
if revert {
return s.revertResetInTx(ctx, tx, &card, record, snapshot, command, now)
}
return s.resetInTx(ctx, tx, &card, record, snapshot, command, now)
})
if err != nil {
return err
}
if s.cache != nil {
s.cache.Invalidate(ctx, command.CardID)
}
return nil
}
func (s *Service) resetInTx(ctx context.Context, tx *gorm.DB, card *model.IotCard, record *model.IotCardRealname,
snapshot domain.RealnameTimeSnapshot, command RealnameResetCommand, now time.Time) error {
if card.RealNameStatus != constants.RealNameStatusVerified {
return ErrRealnameResetNotVerified
}
if record == nil || record.UpstreamRealnameAt == nil {
return ErrRealnameResetNoUpstream
}
if snapshot.ResetStatus == constants.RealnameResetStatusPending {
return ErrRealnameResetAlreadyReset
}
if err := s.updateCardRealnameStatusInTx(ctx, tx, card, constants.RealNameStatusNotVerified, now, "reset", command.BatchID); err != nil {
return err
}
batchID := command.BatchID
if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ?", record.ID).Updates(map[string]any{
"realname_at": nil, "reset_status": constants.RealnameResetStatusPending, "reset_at": now,
"reset_baseline_at": *record.UpstreamRealnameAt, "reset_batch_id": batchID, "updated_at": now,
}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入二次实名等待状态失败")
}
return writeResetHistory(ctx, tx, card, record.RealnameAt, nil, "", constants.RealnameChangeReset, command, now)
}
func (s *Service) revertResetInTx(ctx context.Context, tx *gorm.DB, card *model.IotCard, record *model.IotCardRealname,
snapshot domain.RealnameTimeSnapshot, command RealnameResetCommand, now time.Time) error {
if record == nil || snapshot.ResetStatus != constants.RealnameResetStatusPending {
return ErrRealnameResetNotPending
}
if command.BatchID != 0 && (record.ResetBatchID == nil || *record.ResetBatchID != command.BatchID) {
return ErrRealnameResetNotPending
}
if card.RealNameStatus != constants.RealNameStatusVerified {
if err := s.updateCardRealnameStatusInTx(ctx, tx, card, constants.RealNameStatusVerified, now, "revert", command.BatchID); err != nil {
return err
}
}
restored := record.ResetBaselineAt
if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ?", record.ID).Updates(map[string]any{
"realname_at": restored, "realname_at_source": constants.RealnameAtSourceUpstream,
"reset_status": constants.RealnameResetStatusNone, "reset_at": nil, "reset_baseline_at": nil, "reset_batch_id": nil,
"updated_at": now,
}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "撤销二次实名等待状态失败")
}
return writeResetHistory(ctx, tx, card, nil, restored, constants.RealnameAtSourceUpstream, constants.RealnameChangeResetReverted, command, now)
}
// updateCardRealnameStatusInTx 按实名观测的同一口径更新卡实名状态,并写实名变化事件与人工审计。
func (s *Service) updateCardRealnameStatusInTx(ctx context.Context, tx *gorm.DB, card *model.IotCard, after int, now time.Time, kind string, batchID uint) error {
verified := after == constants.RealNameStatusVerified
result := tx.WithContext(ctx).Model(&model.IotCard{}).Where("id = ? AND real_name_status = ?", card.ID, card.RealNameStatus).Updates(map[string]any{
"real_name_status": after,
"realname_reversal_count": 0,
"realname_reversal_started_at": nil,
"activation_status": gorm.Expr(`CASE WHEN network_status = ? AND (card_category = ? OR ?) THEN 1 ELSE 0 END`, constants.NetworkStatusOnline, constants.CardCategoryIndustry, verified),
})
if result.Error != nil {
return errors.Wrap(errors.CodeDatabaseError, result.Error, "更新卡实名状态失败")
}
if result.RowsAffected != 1 {
return errors.New(errors.CodeConflict, "卡实名状态已被其他请求更新")
}
observationID := "realname-" + kind + ":" + strconv.FormatUint(uint64(batchID), 10) + ":" + strconv.FormatInt(now.UnixNano(), 10)
eventID := outboxid.Stable("card-realname:", strconv.FormatUint(uint64(card.ID), 10)+":"+observationID+":changed")
if err := s.eventWriter.AppendRealname(ctx, tx, RealnameChangedEvent{
EventID: eventID, CardID: card.ID, BeforeStatus: card.RealNameStatus, AfterStatus: after,
ObservedAt: now, Source: constants.CardObservationSourceManualOverride, Scene: "realname_" + kind,
CorrelationID: observationID,
}); err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名 Outbox 事件失败")
}
summary := "二次实名清除:卡实名状态置为未实名"
if verified {
summary = "二次实名撤销:卡恢复已实名"
}
return s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
ActionCode: constants.AuditActionIotCardRealnameStatusUpdated, Summary: summary, Card: card,
BeforeData: map[string]any{"real_name_status": card.RealNameStatus},
AfterData: map[string]any{"real_name_status": after, "realname_reset_batch_id": batchID},
})
}
func writeResetHistory(ctx context.Context, tx *gorm.DB, card *model.IotCard, before, after *time.Time, afterSource, changeType string,
command RealnameResetCommand, now time.Time) error {
var batchID *uint
if command.BatchID != 0 {
value := command.BatchID
batchID = &value
}
history := model.IotCardRealnameHistory{
CardID: card.ID, ICCID: card.ICCID, BeforeAt: before, AfterAt: after, AfterSource: afterSource,
ChangeType: changeType, ObservationSource: constants.CardObservationSourceManualOverride,
ResetBatchID: batchID, OperatorID: command.OperatorID, ObservedAt: now, CreatedAt: now,
}
if err := tx.WithContext(ctx).Create(&history).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名时间历史失败")
}
return nil
}

View File

@@ -0,0 +1,96 @@
package cardobservation
import (
"context"
"time"
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"
)
// loadRealnameTime 在调用方事务中读取卡当前实名记录;调用方已锁定卡行,同一张卡的写入因此串行。
func loadRealnameTime(ctx context.Context, tx *gorm.DB, cardID uint) (*model.IotCardRealname, domain.RealnameTimeSnapshot, error) {
var record model.IotCardRealname
err := tx.WithContext(ctx).Where("card_id = ?", cardID).Take(&record).Error
if err == gorm.ErrRecordNotFound {
return nil, domain.RealnameTimeSnapshot{}, nil
}
if err != nil {
return nil, domain.RealnameTimeSnapshot{}, errors.Wrap(errors.CodeDatabaseError, err, "查询卡当前实名记录失败")
}
return &record, realnameTimeSnapshot(&record), nil
}
func realnameTimeSnapshot(record *model.IotCardRealname) domain.RealnameTimeSnapshot {
if record == nil {
return domain.RealnameTimeSnapshot{}
}
return domain.RealnameTimeSnapshot{
Exists: true, RealnameAt: record.RealnameAt, RealnameAtSource: record.RealnameAtSource,
UpstreamRealnameAt: record.UpstreamRealnameAt, FirstObservedAt: record.FirstObservedAt,
ResetStatus: record.ResetStatus, ResetBaselineAt: record.ResetBaselineAt,
}
}
// applyRealnameTime 在卡已被采纳为已实名后更新当前实名记录;只有实名时间变化才写历史。
func applyRealnameTime(ctx context.Context, tx *gorm.DB, card *model.IotCard, record *model.IotCardRealname,
observation domain.RealnameObservation, gate domain.RealnameResetGate) error {
decision := domain.DecideRealnameTime(realnameTimeSnapshot(record), observation, gate)
if !decision.Changed {
return nil
}
now := time.Now()
var resetBatchID *uint
if record != nil {
resetBatchID = record.ResetBatchID
}
if record == nil {
created := model.IotCardRealname{
CardID: card.ID, RealnameAt: decision.RealnameAt, RealnameAtSource: decision.Source,
UpstreamRealnameAt: decision.UpstreamRealnameAt, FirstObservedAt: decision.FirstObservedAt,
ResetStatus: constants.RealnameResetStatusNone, CreatedAt: now, UpdatedAt: now,
}
if err := tx.WithContext(ctx).Create(&created).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "创建卡当前实名记录失败")
}
} else {
updates := map[string]any{
"realname_at": decision.RealnameAt, "realname_at_source": decision.Source,
"upstream_realname_at": decision.UpstreamRealnameAt, "first_observed_at": decision.FirstObservedAt,
"updated_at": now,
}
if decision.ClearReset {
updates["reset_status"] = constants.RealnameResetStatusNone
updates["reset_at"] = nil
updates["reset_baseline_at"] = nil
updates["reset_batch_id"] = nil
}
if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ?", record.ID).Updates(updates).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新卡当前实名记录失败")
}
}
if decision.ClearReset && resetBatchID != nil {
if err := tx.WithContext(ctx).Model(&model.IotCardRealnameResetBatch{}).Where("id = ?", *resetBatchID).
Updates(map[string]any{"completed_count": gorm.Expr("completed_count + 1"), "updated_at": now}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新二次实名批次完成数失败")
}
}
if !decision.WriteHistory {
return nil
}
history := model.IotCardRealnameHistory{
CardID: card.ID, ICCID: card.ICCID, BeforeAt: decision.BeforeAt, AfterAt: decision.RealnameAt,
AfterSource: decision.Source, ChangeType: decision.ChangeType, ObservationSource: observation.Metadata.Source,
ObservedAt: observation.Metadata.ObservedAt, CreatedAt: now,
}
if decision.ClearReset {
history.ResetBatchID = resetBatchID
}
if err := tx.WithContext(ctx).Create(&history).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名时间历史失败")
}
return nil
}