feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s
- 审计注册表为可由系统任务、定时任务发起的动作声明落库策略(always/on_success/outcome/log_only/none),未声明按 log_only - 人工、开放接口、个人客户、外部系统发起的动作始终写审计表 - log_only 写所在服务 app.log(logger=audit),不含快照 - 对接日志不再补写 integration.attempt_started,无上游审计时 audit_event_id 为空 - 新增 audit.persist_overrides 按动作覆盖策略 - 审计覆盖扫描要求机器动作必须声明策略 - 新增 OpenSpec 提案 refactor-audit-log-persistence 与技术方案文档 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
130
internal/infrastructure/audit/persist_decision.go
Normal file
130
internal/infrastructure/audit/persist_decision.go
Normal file
@@ -0,0 +1,130 @@
|
||||
package audit
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"sync/atomic"
|
||||
|
||||
"go.uber.org/zap"
|
||||
|
||||
"github.com/break/junhong_cmp_fiber/pkg/constants"
|
||||
"github.com/break/junhong_cmp_fiber/pkg/logger"
|
||||
"github.com/break/junhong_cmp_fiber/pkg/sanitizer"
|
||||
)
|
||||
|
||||
// persistDecision 是一次审计写入的去向。
|
||||
type persistDecision int
|
||||
|
||||
const (
|
||||
decisionWrite persistDecision = iota
|
||||
decisionLog
|
||||
decisionSkip
|
||||
)
|
||||
|
||||
// auditLoggerName 是应用日志中审计行的固定 logger 名,日志同步端按它过滤。
|
||||
const auditLoggerName = "audit"
|
||||
|
||||
// persistOverrides 是运行时按动作覆盖的落库策略(只作用于系统任务、定时任务操作者)。
|
||||
var persistOverrides atomic.Pointer[map[string]PersistPolicy]
|
||||
|
||||
// SetPersistOverrides 解析并设置运行时覆盖,格式为 "动作编码=策略,动作编码=策略";返回被忽略的非法项。
|
||||
func SetPersistOverrides(raw string) []string {
|
||||
overrides := map[string]PersistPolicy{}
|
||||
var invalid []string
|
||||
for _, item := range strings.Split(raw, ",") {
|
||||
item = strings.TrimSpace(item)
|
||||
if item == "" {
|
||||
continue
|
||||
}
|
||||
code, policy, ok := strings.Cut(item, "=")
|
||||
code, policy = strings.TrimSpace(code), strings.TrimSpace(policy)
|
||||
if !ok || code == "" || !validPersistPolicy(PersistPolicy(policy)) {
|
||||
invalid = append(invalid, item)
|
||||
continue
|
||||
}
|
||||
overrides[code] = PersistPolicy(policy)
|
||||
}
|
||||
persistOverrides.Store(&overrides)
|
||||
return invalid
|
||||
}
|
||||
|
||||
// effectivePolicy 返回机器操作者下动作实际采用的策略:运行时覆盖 > 注册表声明 > 默认只写应用日志。
|
||||
func effectivePolicy(action ActionDefinition) PersistPolicy {
|
||||
if overrides := persistOverrides.Load(); overrides != nil {
|
||||
if policy, ok := (*overrides)[action.Code]; ok {
|
||||
return policy
|
||||
}
|
||||
}
|
||||
if action.Persist != "" {
|
||||
return action.Persist
|
||||
}
|
||||
return PersistLogOnly
|
||||
}
|
||||
|
||||
// decidePersist 按"动作 × 操作者"决定写表、写应用日志还是跳过;人工与外部操作者始终写表。
|
||||
func decidePersist(action ActionDefinition, input AppendInput) persistDecision {
|
||||
if !isMachineActor(input.Actor.Kind) {
|
||||
return decisionWrite
|
||||
}
|
||||
switch effectivePolicy(action) {
|
||||
case PersistAlways:
|
||||
return decisionWrite
|
||||
case PersistOnSuccess:
|
||||
if input.Result == constants.AuditResultSuccess {
|
||||
return decisionWrite
|
||||
}
|
||||
return decisionLog
|
||||
case PersistOutcome:
|
||||
if input.Final {
|
||||
return decisionWrite
|
||||
}
|
||||
return decisionLog
|
||||
case PersistNone:
|
||||
return decisionSkip
|
||||
default:
|
||||
return decisionLog
|
||||
}
|
||||
}
|
||||
|
||||
// writeAuditLog 把未落表的审计写成一行应用日志;只含标识类字段,不含快照与主体数据。
|
||||
func writeAuditLog(ctx context.Context, action ActionDefinition, input AppendInput) {
|
||||
resourceType, resourceKey := primaryResource(input)
|
||||
fields := []zap.Field{
|
||||
zap.String("action_code", action.Code),
|
||||
zap.String("actor_kind", input.Actor.Kind),
|
||||
zap.String("actor_id", input.Actor.ID),
|
||||
zap.String("source", input.Source),
|
||||
zap.String("result", input.Result),
|
||||
zap.String("resource_type", resourceType),
|
||||
zap.String("resource_key", resourceKey),
|
||||
zap.String("correlation_id", input.CorrelationID),
|
||||
zap.String("request_id", input.RequestID),
|
||||
zap.String("error_code", input.ErrorCode),
|
||||
zap.String("summary", sanitizer.SanitizeText(input.Summary)),
|
||||
}
|
||||
if input.Attempt > 0 {
|
||||
fields = append(fields, zap.Int("attempt", input.Attempt))
|
||||
}
|
||||
if input.AttemptRecordID != "" {
|
||||
fields = append(fields, zap.String("attempt_record_id", input.AttemptRecordID))
|
||||
}
|
||||
auditLogger := logger.GetAppLogger().Named(auditLoggerName)
|
||||
if input.Result == constants.AuditResultSuccess {
|
||||
auditLogger.Info("audit_event", fields...)
|
||||
return
|
||||
}
|
||||
auditLogger.Warn("audit_event", fields...)
|
||||
}
|
||||
|
||||
// primaryResource 返回主资源的类型与键,没有主资源时取第一条资源。
|
||||
func primaryResource(input AppendInput) (string, string) {
|
||||
for _, resource := range input.Resources {
|
||||
if resource.Relation == constants.AuditResourceRelationPrimary {
|
||||
return resource.Type, resource.Key
|
||||
}
|
||||
}
|
||||
if len(input.Resources) > 0 {
|
||||
return input.Resources[0].Type, input.Resources[0].Key
|
||||
}
|
||||
return "", ""
|
||||
}
|
||||
250
internal/infrastructure/audit/persist_policy.go
Normal file
250
internal/infrastructure/audit/persist_policy.go
Normal file
@@ -0,0 +1,250 @@
|
||||
package audit
|
||||
|
||||
import (
|
||||
"sort"
|
||||
|
||||
"github.com/break/junhong_cmp_fiber/pkg/constants"
|
||||
)
|
||||
|
||||
// PersistPolicy 决定系统任务、定时任务发起的审计动作是否写入审计表。
|
||||
// 后台账号、个人客户、开放接口、外部系统发起的动作始终写表,不受该策略约束。
|
||||
type PersistPolicy string
|
||||
|
||||
const (
|
||||
// PersistAlways 成功、失败都写审计表。
|
||||
PersistAlways PersistPolicy = "always"
|
||||
// PersistOnSuccess 只写成功;失败写应用日志。
|
||||
PersistOnSuccess PersistPolicy = "on_success"
|
||||
// PersistOutcome 只写最终结论(AppendInput.Final=true);中间失败写应用日志,逐次细节由业务尝试记录保存。
|
||||
PersistOutcome PersistPolicy = "outcome"
|
||||
// PersistLogOnly 不写审计表,只写所在服务的应用日志。
|
||||
PersistLogOnly PersistPolicy = "log_only"
|
||||
// PersistNone 不写审计表,也不写应用日志。
|
||||
PersistNone PersistPolicy = "none"
|
||||
)
|
||||
|
||||
// validPersistPolicy 判断策略取值是否合法。
|
||||
func validPersistPolicy(policy PersistPolicy) bool {
|
||||
switch policy {
|
||||
case PersistAlways, PersistOnSuccess, PersistOutcome, PersistLogOnly, PersistNone:
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// machinePersistPolicies 是可由系统任务或定时任务发起的动作的落库策略。
|
||||
// 只登记资金、套餐生命周期与业务状态变化等需要留在审计表的动作,以及明确不写的动作;
|
||||
// 未登记的机器动作按 PersistLogOnly 写应用日志(见 docs/2026-11-05-审计日志写入改造技术方案.md 4.1、4.2)。
|
||||
var machinePersistPolicies = func() map[string]PersistPolicy {
|
||||
policies := map[string]PersistPolicy{
|
||||
// 对接调用开始:与 tb_integration_log 完全重复,不写。
|
||||
constants.AuditActionIntegrationAttemptStarted: PersistNone,
|
||||
// 退款资产后处理:只写最终结论(成功或转人工),逐次尝试见 tb_refund_post_process_attempt。
|
||||
"refund.process_asset": PersistOutcome,
|
||||
}
|
||||
// 资金、审批、订单、套餐生命周期、导入与资产归属等业务状态变化:留在审计表。
|
||||
for _, code := range []string{
|
||||
"agent_distribution.registration_approve",
|
||||
"agent_distribution.registration_reject",
|
||||
"agent_recharge.close",
|
||||
"agent_recharge.create",
|
||||
"agent_recharge.credit",
|
||||
"agent_wallet.order_complete",
|
||||
"agent_wallet.order_debit",
|
||||
"agent_wallet.order_release",
|
||||
"agent_wallet.order_reserve",
|
||||
"approval.recover_submission",
|
||||
"approval.sync_decision",
|
||||
"approval.sync_submission",
|
||||
"asset.first_purchase_ended",
|
||||
"asset.first_purchase_recorded",
|
||||
"asset_auto_renewal.failed",
|
||||
"asset_auto_renewal.renewed",
|
||||
"asset_package_batch_order_task.complete",
|
||||
"asset_recharge.auto_purchase",
|
||||
"audit.retention_cleanup",
|
||||
"commission.calculate",
|
||||
"commission.credit",
|
||||
"commission_withdrawal.anomaly_flag",
|
||||
"commission_withdrawal.approve",
|
||||
"commission_withdrawal.attempt_approve",
|
||||
"commission_withdrawal.attempt_close",
|
||||
"commission_withdrawal.attempt_reject",
|
||||
"commission_withdrawal.attempt_submit",
|
||||
"commission_withdrawal.reject",
|
||||
"commission_withdrawal.request",
|
||||
"device.allocate",
|
||||
"device.allocate_batch",
|
||||
"device.create",
|
||||
"device.recall",
|
||||
"device.recall_batch",
|
||||
"device.series_binding",
|
||||
"device.series_binding_batch",
|
||||
"device.update_polling_status",
|
||||
"device_import_task.complete",
|
||||
"employee_collection.application.approve",
|
||||
"employee_collection.application.reject",
|
||||
"employee_collection.application.revoke",
|
||||
"employee_collection.application.submit",
|
||||
"employee_collection.bill.close",
|
||||
"employee_collection.bill.create",
|
||||
"employee_collection.bill.refund_offset",
|
||||
"integration.inbound_received",
|
||||
// 自动停复机:系统自动发起的已由 StopResumeService.commandAuditRequired 改写停复机记录,
|
||||
// 仍写审计的只剩通道阈值、自动续费等豁免链路(gateway-call-observability 要求保留)。
|
||||
"iot_card.auto_start",
|
||||
"iot_card.auto_stop",
|
||||
"iot_card.batch_update_polling_status",
|
||||
"iot_card.create",
|
||||
"iot_card.terminal_disable_polling",
|
||||
"iot_card.update_polling_status",
|
||||
"iot_card_import_task.complete",
|
||||
"order.cancel",
|
||||
"order.create",
|
||||
"order.expire_close",
|
||||
"order.online_pay",
|
||||
"order.wallet_pay",
|
||||
"order_package_invalidate_task.complete",
|
||||
"order_package_invalidate_task.item",
|
||||
"package.silence_default_changed",
|
||||
"package.silence_switch_changed",
|
||||
"package_silence_policy.created",
|
||||
"package_silence_policy.status_changed",
|
||||
"package_silence_policy.updated",
|
||||
"package_traffic_alert.trigger",
|
||||
"package_usage.activate",
|
||||
"package_usage.adjust_traffic",
|
||||
"package_usage.expire",
|
||||
"package_usage.invalidate_asset",
|
||||
"package_usage.invalidate_refund",
|
||||
"package_usage.silence_adjust_approved",
|
||||
"package_usage.silence_adjust_rejected",
|
||||
"package_usage.silence_adjust_requested",
|
||||
"package_usage.silence_backfilled",
|
||||
"package_usage.silence_ended",
|
||||
"package_usage.silence_expired",
|
||||
"package_usage.silence_extension_applied",
|
||||
"package_usage.silence_extension_approved",
|
||||
"package_usage.silence_extension_exception",
|
||||
"package_usage.silence_extension_order_changed",
|
||||
"package_usage.silence_extension_rejected",
|
||||
"package_usage.silence_extension_requested",
|
||||
"package_usage.silence_migrated_on_exchange",
|
||||
"package_usage.silence_set",
|
||||
"package_usage.update_expires_at",
|
||||
"payment.confirm",
|
||||
"payment.create",
|
||||
"payment.fail",
|
||||
"phone_asset_association.import_unbind",
|
||||
"phone_asset_unbind_import_task.complete",
|
||||
"refund.anomaly_flag",
|
||||
"refund.approve",
|
||||
"refund.attempt_approve",
|
||||
"refund.attempt_close",
|
||||
"refund.channel_call",
|
||||
"refund.channel_recover",
|
||||
"refund.clawback_commission",
|
||||
"refund.clawback_not_required",
|
||||
"refund.invalidate_commission",
|
||||
"refund.reject",
|
||||
"shop.import_business_owner",
|
||||
"shop_business_owner_import_task.complete",
|
||||
"withdrawal_qualification.approve",
|
||||
"withdrawal_qualification.invalidate",
|
||||
"withdrawal_qualification.reject",
|
||||
"withdrawal_qualification.submit",
|
||||
"withdrawal_qualification.submit_reject",
|
||||
"withdrawal_qualification.void",
|
||||
} {
|
||||
policies[code] = PersistAlways
|
||||
}
|
||||
// 过程类动作:写应用日志。采集与扣减见采集记录与日流量,流量重置见套餐重置时间与日流量。
|
||||
for _, code := range []string{
|
||||
"device.worker_observation_sync",
|
||||
"iot_card.auto_stop_reason_update",
|
||||
"iot_card.worker_network_sync",
|
||||
"iot_card.worker_realname_sync",
|
||||
"iot_card.worker_traffic_sync",
|
||||
"notification.cleanup",
|
||||
"notification.cleanup_item",
|
||||
"notification.deliver",
|
||||
"package_usage.deduct_traffic",
|
||||
"package_usage.reset_traffic",
|
||||
"polling_priority.claim",
|
||||
"polling_priority.complete",
|
||||
"polling_priority.dequeue",
|
||||
"polling_priority.enqueue",
|
||||
"polling_priority.expire",
|
||||
"polling_priority.fail",
|
||||
"polling_priority.retry",
|
||||
} {
|
||||
policies[code] = PersistLogOnly
|
||||
}
|
||||
return policies
|
||||
}()
|
||||
|
||||
// applyPersistPolicies 把机器动作落库策略写入已注册的动作定义。
|
||||
func applyPersistPolicies(registry *Registry, policies map[string]PersistPolicy) {
|
||||
for code, policy := range policies {
|
||||
action, ok := registry.actionsByCode[code]
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
action.Persist = policy
|
||||
registry.actionsByCode[code] = action
|
||||
for operation, byOperation := range registry.actionsByOperation {
|
||||
if byOperation.Code == code {
|
||||
byOperation.Persist = policy
|
||||
registry.actionsByOperation[operation] = byOperation
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// isMachineActor 判断操作者是否为系统任务或定时任务。
|
||||
func isMachineActor(actorKind string) bool {
|
||||
return actorKind == constants.AuditActorSystemTask || actorKind == constants.AuditActorScheduledJob
|
||||
}
|
||||
|
||||
// allowsMachineOrigin 判断动作是否允许由系统任务或定时任务发起。
|
||||
func allowsMachineOrigin(action ActionDefinition) bool {
|
||||
if isMachineActor(action.AllowedActor) {
|
||||
return true
|
||||
}
|
||||
for _, origin := range action.AllowedOrigins {
|
||||
if isMachineActor(origin.Actor) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// MachineActionsWithoutPolicy 返回可由系统任务或定时任务发起、但未声明落库策略的动作编码(审计覆盖扫描使用)。
|
||||
func (r *Registry) MachineActionsWithoutPolicy() []string {
|
||||
if r == nil {
|
||||
return nil
|
||||
}
|
||||
var codes []string
|
||||
for code, action := range r.actionsByCode {
|
||||
if allowsMachineOrigin(action) && action.Persist == "" {
|
||||
codes = append(codes, code)
|
||||
}
|
||||
}
|
||||
sort.Strings(codes)
|
||||
return codes
|
||||
}
|
||||
|
||||
// MachineActions 返回可由系统任务或定时任务发起的全部动作及其声明的策略(空表示未声明)。
|
||||
func (r *Registry) MachineActions() map[string]PersistPolicy {
|
||||
if r == nil {
|
||||
return nil
|
||||
}
|
||||
actions := map[string]PersistPolicy{}
|
||||
for code, action := range r.actionsByCode {
|
||||
if allowsMachineOrigin(action) {
|
||||
actions[code] = action.Persist
|
||||
}
|
||||
}
|
||||
return actions
|
||||
}
|
||||
@@ -18,6 +18,8 @@ type ActionDefinition struct {
|
||||
SubjectFields []string
|
||||
SensitiveRead bool
|
||||
AllowedOrigins []ActionOrigin
|
||||
// Persist 是系统任务、定时任务发起时的落库策略,空表示未声明(按 PersistLogOnly 处理)。
|
||||
Persist PersistPolicy
|
||||
}
|
||||
|
||||
// ActionOrigin 定义动作允许的操作者与入口组合。
|
||||
@@ -1185,6 +1187,7 @@ func NewRegistry() *Registry {
|
||||
},
|
||||
}
|
||||
registerPackageSilenceAudit(registry)
|
||||
applyPersistPolicies(registry, machinePersistPolicies)
|
||||
return registry
|
||||
}
|
||||
|
||||
|
||||
@@ -812,6 +812,11 @@ type AppendInput struct {
|
||||
FailCount int
|
||||
Metadata map[string]any
|
||||
Resources []ResourceInput
|
||||
// Final 只对"只写结论"策略生效:true 表示本次是最终结论(成功或重试用尽转人工),写审计表;false 只写应用日志。
|
||||
Final bool
|
||||
// Attempt 与 AttemptRecordID 是自动重试类动作的尝试序号与业务尝试记录标识,只写入应用日志。
|
||||
Attempt int
|
||||
AttemptRecordID string
|
||||
}
|
||||
|
||||
// Writer 只提供不可变 Audit Event 追加能力。
|
||||
@@ -956,6 +961,13 @@ func (w *Writer) AppendAndGet(ctx context.Context, tx *gorm.DB, input AppendInpu
|
||||
if !validResult(input.Result) || len(input.Resources) == 0 {
|
||||
return nil, pkgerrors.New(pkgerrors.CodeInvalidParam, "审计结果非法或缺少资源")
|
||||
}
|
||||
switch decidePersist(action, input) {
|
||||
case decisionSkip:
|
||||
return nil, nil
|
||||
case decisionLog:
|
||||
writeAuditLog(ctx, action, input)
|
||||
return nil, nil
|
||||
}
|
||||
resources, err := w.buildResources(input.Resources, action)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
|
||||
@@ -115,9 +115,7 @@ func (r *Repository) Start(ctx context.Context, input Attempt) (*model.Integrati
|
||||
if input.AuditEventID == nil && input.TriggerSeries != nil {
|
||||
input.AuditEventID = r.auditEventIDForSeries(ctx, *input.TriggerSeries)
|
||||
}
|
||||
if input.AuditEventID == nil {
|
||||
input.AuditEventID = r.recordAuditEvent(ctx, constants.AuditActionIntegrationAttemptStarted, input.IntegrationID, input.Provider, input.Direction, input.Operation, input.ResourceType, input.ResourceID, input.ResourceKey, input.CorrelationID)
|
||||
}
|
||||
// 没有上游审计事件时 audit_event_id 留空,不再补写 integration.attempt_started(与本表内容重复)。
|
||||
autoAttempt := input.Attempt <= 0 && input.TriggerSeries != nil
|
||||
if input.Attempt <= 0 {
|
||||
input.Attempt = 1
|
||||
@@ -321,6 +319,10 @@ func (r *Repository) recordAuditEvent(ctx context.Context, actionCode, integrati
|
||||
zap.L().Warn("Integration Log 缺少审计关联", zap.String("integration_id", integrationID), zap.Error(err))
|
||||
return nil
|
||||
}
|
||||
if event == nil {
|
||||
// 落库策略决定不写审计表(只写应用日志或不写)时没有事件可关联。
|
||||
return nil
|
||||
}
|
||||
return &event.ID
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user