Files
junhong_cmp_fiber/internal/service/iot_card/stop_resume_audit.go
邹进 42e881576d
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
feat: 卡网关按运营商账户限流并记录停复机调用
- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
2026-10-24 15:06:41 +09:00

318 lines
12 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package iot_card
import (
"context"
"strconv"
"time"
"github.com/google/uuid"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/gateway"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/gatewaylimit"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/integrationlog"
"github.com/break/junhong_cmp_fiber/internal/model"
assetAuditSvc "github.com/break/junhong_cmp_fiber/internal/service/asset_audit"
"github.com/break/junhong_cmp_fiber/pkg/auditcontext"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
func (s *StopResumeService) appendCardCommandAudit(
ctx context.Context,
tx *gorm.DB,
card *model.IotCard,
actionCode, summary, result, integrationID string,
beforeData, afterData map[string]any,
businessErr error,
) error {
if !commandAuditRequired(ctx, actionCode, result) {
return nil
}
if s.auditWriter == nil || card == nil || card.ID == 0 {
return errors.New(errors.CodeInvalidStatus, "IoT 卡停复机统一审计接缝未配置或资源不完整")
}
resourcesByCard, err := loadCardDeviceAuditReferences(ctx, tx, []*model.IotCard{card})
if err != nil {
return err
}
cardID := strconv.FormatUint(uint64(card.ID), 10)
resources := []audit.ResourceInput{{
Type: constants.AuditResourceIotCard, ID: &cardID,
Key: audit.IotCardResourceKey(card), DisplayName: card.ICCID,
Relation: constants.AuditResourceRelationPrimary, Role: constants.AuditResourceRoleIotCardTarget,
IdentitySnapshot: audit.IotCardIdentitySnapshot(card), BeforeData: beforeData, AfterData: afterData,
SubjectVisibility: constants.AuditSubjectResult, SubjectSummary: summary,
}}
resources = append(resources, resourcesByCard[card.ID]...)
errorCode, errorSummary := assetAuditSvc.BuildErrorInfo(businessErr)
input := audit.AppendInput{
ActionCode: actionCode, Summary: summary, ScopeType: constants.AuditScopePlatform,
Result: result, ErrorCode: errorCode, ErrorSummary: errorSummary,
Metadata: map[string]any{"integration_id": integrationID}, Resources: resources,
}
if actionCode == constants.AuditActionIotCardAutoStopped || actionCode == constants.AuditActionIotCardAutoStarted ||
actionCode == constants.AuditActionIotCardAutoStopReasonUpdated {
input.Actor = audit.ActorInput{Kind: constants.AuditActorSystemTask, ID: "iot-card-stop-resume", Name: "IoT 卡停复机服务"}
input.Source = constants.AuditSourceWorker
}
return s.auditWriter.Append(ctx, tx, input)
}
func (s *StopResumeService) recordCardCommandAudit(
ctx context.Context,
card *model.IotCard,
actionCode, summary, result, integrationID string,
beforeData, afterData map[string]any,
businessErr error,
) {
if !commandAuditRequired(ctx, actionCode, result) {
return
}
if s.db == nil || s.auditWriter == nil || card == nil || card.ID == 0 {
recordCardAuditSecondaryFailure(ctx, actionCode, cardID(card), businessErr,
errors.New(errors.CodeInvalidStatus, "IoT 卡停复机统一审计接缝未配置"))
return
}
if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
return s.appendCardCommandAudit(ctx, tx, card, actionCode, summary, result, integrationID, beforeData, afterData, businessErr)
}); err != nil {
recordCardAuditSecondaryFailure(ctx, actionCode, card.ID, businessErr, err)
}
}
// legacyCommandLogging 判断本次停复机是否沿用统一审计与集成日志:
// 带限流豁免标记的入口(后台人工点击、通道阈值、自动续费)与账户、个人客户、OpenAPI 发起的操作沿用;
// 系统自动停复机(轮询、Outbox、激活、重置、退款等系统任务)只写停复机记录(add-carrier-gateway-rate-limit)。
// 通道阈值与自动续费的恢复扫描依赖集成日志标识,因此必须沿用。
func legacyCommandLogging(ctx context.Context) bool {
if gateway.RateLimitExemptSource(ctx) != "" {
return true
}
switch auditcontext.From(ctx).ActorKind {
case constants.AuditActorAccount, constants.AuditActorPersonalCustomer, constants.AuditActorOpenAPI:
return true
default:
return false
}
}
// commandAuditRequired 判断停复机命令结果是否写统一审计:系统自动停复机的成功、失败与结果未知改由停复机记录承载;
// 被拒绝(未调用上游)与非停复机命令的审计保持不变。
func commandAuditRequired(ctx context.Context, actionCode, result string) bool {
if legacyCommandLogging(ctx) || result == constants.AuditResultDenied {
return true
}
switch actionCode {
case constants.AuditActionIotCardAutoStopped, constants.AuditActionIotCardAutoStarted,
constants.AuditActionIotCardManualStopped, constants.AuditActionIotCardManualStarted,
constants.AuditActionIotCardOpenAPIStarted:
return false
default:
return true
}
}
// commandSource 返回停复机记录的来源:豁免来源优先,其次审计来源。
func commandSource(ctx context.Context) string {
if source := gateway.RateLimitExemptSource(ctx); source != "" {
return source
}
if source := auditcontext.From(ctx).Source; source != "" {
return source
}
return constants.AuditSourceWorker
}
func cardID(card *model.IotCard) uint {
if card == nil {
return 0
}
return card.ID
}
func stopAuditAction(ctx context.Context, stopReason string) (string, string) {
if stopReason == constants.StopReasonManual && auditcontext.From(ctx).ActorKind == constants.AuditActorAccount {
return constants.AuditActionIotCardManualStopped, "人工停用 IoT 卡网络"
}
return constants.AuditActionIotCardAutoStopped, "自动停用 IoT 卡网络"
}
func cardCommandSeriesKey(ctx context.Context) string {
linkage := auditcontext.From(ctx)
if linkage.CorrelationID != "" {
return linkage.CorrelationID
}
if linkage.RequestID != "" {
return linkage.RequestID
}
return uuid.NewString()
}
func cardCommandAuditResult(err error) string {
if err == nil {
return constants.AuditResultSuccess
}
if isGatewayTimeout(err) {
return constants.AuditResultUnknown
}
return constants.AuditResultFailed
}
func (s *StopResumeService) updateCardStopReasonWithAudit(ctx context.Context, card *model.IotCard, stopReason string) error {
return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := tx.Model(&model.IotCard{}).Where("id = ?", card.ID).Update("stop_reason", stopReason).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新卡停机原因失败")
}
return s.appendCardCommandAudit(ctx, tx, card, constants.AuditActionIotCardAutoStopReasonUpdated,
"自动更新 IoT 卡停机原因", constants.AuditResultSuccess, "",
map[string]any{"stop_reason": card.StopReason}, map[string]any{"stop_reason": stopReason}, nil)
})
}
func (s *StopResumeService) startCardCommandAttempt(
ctx context.Context,
card *model.IotCard,
operation, scene, seriesKey string,
attempt int,
) (*gatewayAttempt, error) {
if s.integration == nil {
return nil, errors.New(errors.CodeInvalidStatus, "停复机 Integration Log 接缝未配置")
}
resourceID := strconv.FormatUint(uint64(card.ID), 10)
triggerSource := auditcontext.From(ctx).Source
if triggerSource == "" {
triggerSource = constants.AuditSourceWorker
}
triggerScene := scene
triggerSeries := uuid.NewSHA1(uuid.NameSpaceOID, []byte("gateway-card-command:"+seriesKey+":"+operation)).String()
requestID := requestIDFromContext(ctx)
correlationID := auditcontext.From(ctx).CorrelationID
if correlationID == "" {
correlationID = requestID
}
var requestIDPtr, correlationIDPtr *string
if requestID != "" {
requestIDPtr = &requestID
}
if correlationID != "" {
correlationIDPtr = &correlationID
}
log, err := s.integration.Start(ctx, integrationlog.Attempt{
Provider: constants.IntegrationProviderGateway, Direction: constants.IntegrationDirectionOutbound,
Operation: operation, ExternalID: &card.ICCID,
ResourceType: constants.AssetTypeIotCard, ResourceID: &resourceID, ResourceKey: &card.ICCID,
TriggerSource: &triggerSource, TriggerScene: &triggerScene, TriggerSeries: &triggerSeries,
Attempt: attempt, RequestID: requestIDPtr, CorrelationID: correlationIDPtr,
RequestSummary: map[string]any{"iot_card_id": card.ID, "iccid": card.ICCID},
})
if err != nil {
return nil, err
}
return &gatewayAttempt{log: log, startedAt: time.Now()}, nil
}
func (s *StopResumeService) completeCardCommandAttempt(ctx context.Context, attempt *gatewayAttempt, callErr error, stateChanged bool) error {
if attempt == nil || attempt.log == nil {
return nil
}
completion := integrationlog.Completion{
Result: constants.IntegrationResultSuccess, DurationMS: time.Since(attempt.startedAt).Milliseconds(),
StateChanged: stateChanged, ResponseSummary: map[string]any{"result": "success"},
}
if callErr != nil {
completion.Result = constants.IntegrationResultFailed
completion.SafeProviderMessage = "Gateway 停复机请求失败"
completion.ResponseSummary = map[string]any{"result": "failed"}
if isGatewayTimeout(callErr) {
completion.Result = constants.IntegrationResultUnknown
completion.SafeProviderMessage = "Gateway 停复机请求结果未知"
completion.ResponseSummary = map[string]any{"result": "unknown"}
completion.RecoveryStrategy = constants.GatewayCardCommandUnknownRecoveryStrategy
}
}
_, err := s.integration.Complete(ctx, attempt.log.IntegrationID, completion)
return err
}
type cardCommandAttemptObserver struct {
service *StopResumeService
card *model.IotCard
operation string
scene string
seriesKey string
action string // constants.StopResumeActionStop / StopResumeActionStart
reason string // 停机原因(复机为空)
legacy bool // 是否沿用集成日志(见 legacyCommandLogging)
startedAt time.Time
nextAttempt int
current *gatewayAttempt
successful *gatewayAttempt
lastIntegrationID string
lastCallErr error
recordingErr error
unknown bool
}
func (o *cardCommandAttemptObserver) BeforeAttempt(ctx context.Context, _ int) error {
o.nextAttempt++
o.lastCallErr = nil
o.startedAt = time.Now()
if !o.legacy {
// 系统自动停复机不再写集成日志,只在尝试结束后写停复机记录。
o.current = nil
o.lastIntegrationID = ""
return nil
}
attempt, err := o.service.startCardCommandAttempt(ctx, o.card, o.operation, o.scene, o.seriesKey, o.nextAttempt)
if err != nil {
o.recordingErr = err
return err
}
o.current = attempt
o.lastIntegrationID = attempt.log.IntegrationID
return nil
}
func (o *cardCommandAttemptObserver) AfterAttempt(ctx context.Context, _ int, callErr error) error {
o.lastCallErr = callErr
if isGatewayTimeout(callErr) {
o.unknown = true
}
o.service.recordStopResumeAttempt(ctx, o, callErr)
if !o.legacy {
return nil
}
if callErr == nil {
o.successful = o.current
o.current = nil
return nil
}
err := o.service.completeCardCommandAttempt(ctx, o.current, callErr, false)
o.current = nil
if err != nil {
o.recordingErr = err
}
return err
}
func (o *cardCommandAttemptObserver) auditResult(lastErr error) string {
if o.unknown {
return constants.AuditResultUnknown
}
return cardCommandAuditResult(lastErr)
}
// recordStopResumeAttempt 每次实际调用上游停机或复机后写一条停复机记录,写入失败不影响业务回写。
func (s *StopResumeService) recordStopResumeAttempt(ctx context.Context, o *cardCommandAttemptObserver, callErr error) {
if s.stopResumeRecorder == nil || o == nil || o.card == nil {
return
}
s.stopResumeRecorder.Record(ctx, gatewaylimit.StopResumeRecordInput{
CardID: o.card.ID, ICCID: o.card.ICCID, CarrierID: o.card.CarrierID, Action: o.action,
Source: commandSource(ctx), Scene: o.scene, Reason: o.reason, CommandID: o.seriesKey,
Attempt: o.nextAttempt, CallErr: callErr, Duration: time.Since(o.startedAt),
})
}