Files
junhong_cmp_fiber/internal/infrastructure/audit/persist_policy.go
邹进 b7a7430cc3
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s
feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
- 审计注册表为可由系统任务、定时任务发起的动作声明落库策略(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>
2026-11-05 18:27:24 +09:00

251 lines
8.6 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 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
}