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