feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
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:
邹进
2026-11-05 18:27:24 +09:00
parent 96ff9c1e35
commit b7a7430cc3
21 changed files with 1720 additions and 4 deletions

View 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 "", ""
}

View 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
}

View File

@@ -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
}

View File

@@ -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

View File

@@ -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
}