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