@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/audit/middleware_test.go

@@ -0,0 +1,268 @@
+package audit
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	commonmw "{{module}}/internal/common/middleware"
+	"{{module}}/pkg/apierror"
+)
+
+type recordingAuditService struct {
+	accessEntries   []AccessEntry
+	auditEntries    []AuditEntry
+	loginEntries    []LoginEntry
+	beginEntries    []BeginOperationEntry
+	completeEntries []CompleteOperationEntry
+}
+
+func (s *recordingAuditService) LogAccess(_ context.Context, entry AccessEntry) {
+	s.accessEntries = append(s.accessEntries, entry)
+}
+
+func (s *recordingAuditService) LogAudit(_ context.Context, entry AuditEntry) {
+	s.auditEntries = append(s.auditEntries, entry)
+}
+
+func (s *recordingAuditService) LogLogin(_ context.Context, entry LoginEntry) {
+	s.loginEntries = append(s.loginEntries, entry)
+}
+
+func (s *recordingAuditService) LogSync(_ context.Context, entry AuditEntry) error {
+	s.auditEntries = append(s.auditEntries, entry)
+	return nil
+}
+
+func (s *recordingAuditService) ProjectEventSync(_ context.Context, _, _ string, entry AuditEntry) error {
+	s.auditEntries = append(s.auditEntries, entry)
+	return nil
+}
+
+func (s *recordingAuditService) BeginOperation(_ context.Context, entry BeginOperationEntry) (int64, error) {
+	s.beginEntries = append(s.beginEntries, entry)
+	return int64(len(s.beginEntries)), nil
+}
+
+func (s *recordingAuditService) CompleteOperation(_ context.Context, _ int64, entry CompleteOperationEntry) error {
+	s.completeEntries = append(s.completeEntries, entry)
+	return nil
+}
+
+func (s *recordingAuditService) Flush(context.Context) error {
+	return nil
+}
+
+func (s *recordingAuditService) Stop() {}
+
+func TestAuditMiddlewareFinalizesOperationOnPanic(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := &recordingAuditService{}
+	router := gin.New()
+	router.Use(
+		commonmw.RequestID(),
+		NewAuditMiddleware(svc, zap.NewNop()).Handle(),
+	)
+	router.POST("/api/v1/admin/panic", func(*gin.Context) {
+		panic("boom")
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/panic", nil)
+	recorder := httptest.NewRecorder()
+
+	require.Panics(t, func() {
+		router.ServeHTTP(recorder, req)
+	})
+	require.Len(t, svc.accessEntries, 1)
+	require.Len(t, svc.completeEntries, 1)
+	require.False(t, svc.accessEntries[0].IsSuccess)
+	require.Equal(t, int16(http.StatusInternalServerError), svc.accessEntries[0].HTTPStatus)
+	require.Equal(t, operationPanicErrorMessage, svc.accessEntries[0].ErrorMessage)
+	require.False(t, svc.completeEntries[0].IsSuccess)
+	require.Equal(t, int16(http.StatusInternalServerError), svc.completeEntries[0].HTTPStatus)
+	require.Equal(t, operationPanicErrorMessage, svc.completeEntries[0].ErrorMessage)
+}
+
+func TestAuditMiddlewareUsesUnmatchedRouteForRawTokenPath(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := &recordingAuditService{}
+	router := gin.New()
+	router.Use(NewAuditMiddleware(svc, zap.NewNop()).Handle())
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/payment-results/secret-result-token", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusNotFound, recorder.Code)
+	require.Len(t, svc.accessEntries, 1)
+	require.Equal(t, "/unmatched", svc.accessEntries[0].HTTPPath)
+	require.NotContains(t, svc.accessEntries[0].HTTPPath, "secret-result-token")
+	require.Empty(t, svc.beginEntries)
+}
+
+func TestAuditMiddlewarePersistsRouteParamNamesWithoutValues(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := &recordingAuditService{}
+	router := gin.New()
+	router.Use(NewAuditMiddleware(svc, zap.NewNop()).Handle())
+	router.POST("/api/v1/admin/devices/:deviceKey", func(c *gin.Context) {
+		c.Status(http.StatusNoContent)
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/devices/route-param-secret", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusNoContent, recorder.Code)
+	require.Len(t, svc.accessEntries, 1)
+	require.Len(t, svc.beginEntries, 1)
+	require.Equal(t, "/api/v1/admin/devices/:deviceKey", svc.accessEntries[0].HTTPPath)
+	require.Empty(t, svc.accessEntries[0].ResourceID)
+	encoded := string(svc.beginEntries[0].RequestContext)
+	require.NotContains(t, encoded, "route-param-secret")
+	require.NotContains(t, string(svc.beginEntries[0].OperationMetadata), "route-param-secret")
+	var envelope map[string]any
+	require.NoError(t, json.Unmarshal(svc.beginEntries[0].RequestContext, &envelope))
+	require.Equal(t, []any{"deviceKey"}, envelope["route_param_names"])
+	require.NotContains(t, envelope, "route_params")
+}
+
+func TestAuditMiddlewarePersistsStableEvidenceForRawDatabaseError(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := &recordingAuditService{}
+	router := gin.New()
+	router.Use(NewAuditMiddleware(svc, zap.NewNop()).Handle())
+	router.POST("/api/v1/admin/users", func(c *gin.Context) {
+		_ = c.Error(fmt.Errorf("pq: duplicate key users_email_key email=user@example.com token=token-secret"))
+		c.Status(http.StatusInternalServerError)
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/admin/users", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+
+	require.Equal(t, http.StatusInternalServerError, recorder.Code)
+	require.Len(t, svc.accessEntries, 1)
+	require.Len(t, svc.completeEntries, 1)
+	require.Equal(t, apierror.CodeInternalError, svc.accessEntries[0].ErrorMessage)
+	require.Equal(t, apierror.CodeInternalError, svc.completeEntries[0].ErrorMessage)
+	encoded := string(svc.completeEntries[0].ResponseContext)
+	for _, secret := range []string{"duplicate key", "users_email_key", "user@example.com", "token-secret"} {
+		require.NotContains(t, encoded, secret)
+	}
+	var envelope map[string]any
+	require.NoError(t, json.Unmarshal(svc.completeEntries[0].ResponseContext, &envelope))
+	require.Equal(t, apierror.CodeInternalError, envelope["error_code"])
+	require.Equal(t, apierror.TypeAPI, envelope["error_type"])
+	require.EqualValues(t, 1, envelope["error_count"])
+}
+
+func TestCompleteOperationEntryFromContextUsesResourceDecisionEvidence(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(recorder)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/admin/orders", nil)
+	commonmw.SetResourcePermissionDecision(c, commonmw.ResourcePermissionDecision{
+		Action:                 "commerce:order:list",
+		Resource:               "onex:global:-:commerce:order/*",
+		Allowed:                true,
+		ReasonCode:             "allow",
+		ReasonKind:             "allow",
+		PrincipalID:            88,
+		ScopeConstraintSummary: "allow_groups=1;deny_groups=0;dimensions=product",
+	})
+
+	entry := CompleteOperationEntryFromContext(c, AccessEntry{RequestID: "req_1"}, http.StatusOK, 12)
+
+	require.Equal(t, int64(88), entry.IAMPrincipalID)
+	require.Equal(t, "commerce:order:list", entry.IAMAction)
+	require.Equal(t, "onex:global:-:commerce:order/*", entry.IAMResource)
+
+	var envelope map[string]any
+	require.NoError(t, json.Unmarshal(entry.PolicyViolation, &envelope))
+	require.Equal(t, "allow_groups=1;deny_groups=0;dimensions=product", envelope["scope_constraint_summary"])
+}
+
+func TestAuditExcludedPathMatchesDocsBoundary(t *testing.T) {
+	require.True(t, isAuditExcludedPath("/docs"))
+	require.True(t, isAuditExcludedPath("/docs/openapi.json"))
+	require.False(t, isAuditExcludedPath("/docs-archive"))
+	require.False(t, isAuditExcludedPath("/api/v1/docs"))
+}
+
+func TestMatchRouteRuleForDeliveryCapacityTemplateActions(t *testing.T) {
+	cases := []struct {
+		name      string
+		path      string
+		action    AuditAction
+		riskLevel RiskLevel
+	}{
+		{
+			name:      "publish",
+			path:      "/admin/delivery/capacity/templates/:templateNo/publish",
+			action:    ActionPublish,
+			riskLevel: RiskLevelHigh,
+		},
+		{
+			name:      "publish api v1 route",
+			path:      "/api/v1/admin/delivery/capacity/templates/:templateNo/publish",
+			action:    ActionPublish,
+			riskLevel: RiskLevelHigh,
+		},
+		{
+			name:      "archive",
+			path:      "/admin/delivery/capacity/templates/:templateNo/archive",
+			action:    ActionArchive,
+			riskLevel: RiskLevelHigh,
+		},
+		{
+			name:      "validate",
+			path:      "/admin/delivery/capacity/templates/:templateNo/validate",
+			action:    ActionVerify,
+			riskLevel: RiskLevelMedium,
+		},
+		{
+			name:      "generation preview",
+			path:      "/admin/delivery/capacity/templates/:templateNo/generation-preview",
+			action:    ActionGenerate,
+			riskLevel: RiskLevelMedium,
+		},
+		{
+			name:      "generate",
+			path:      "/admin/delivery/capacity/templates/:templateNo/generate",
+			action:    ActionGenerate,
+			riskLevel: RiskLevelHigh,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			rule := matchRouteRule(http.MethodPost, tc.path)
+
+			require.Equal(t, tc.action, rule.Action)
+			require.Equal(t, CategoryCommerce, rule.Category)
+			require.Equal(t, tc.riskLevel, rule.RiskLevel)
+		})
+	}
+}
+
+func TestOperationPolicyViolationKeepsScopeSummaryBounded(t *testing.T) {
+	payload := BuildOperationPolicyViolation(OperationPolicyEnvelopeInput{
+		IAMAction:              "ops:operation-log:list",
+		IAMResource:            "onex:global:-:ops:operation-log/*",
+		Allowed:                true,
+		ReasonCode:             "allow",
+		ReasonKind:             "allow",
+		ScopeConstraintSummary: strings.Repeat("x", operationEnvelopeMaxBytes+100),
+	})
+
+	require.LessOrEqual(t, len(payload), operationEnvelopeMaxBytes)
+}

package/dist/resources/templates/go-backend/internal/core/audit/model.go

@@ -0,0 +1,306 @@
+package audit
+
+import (
+	"strconv"
+	"time"
+
+	"gorm.io/datatypes"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/database"
+)
+
+// AccessLog 访问日志记录（L1 中间件自动采集的 HTTP 请求级记录）
+// 轻量化 schema，不含 changes/metadata 等审计专用字段
+type AccessLog struct {
+	// 主键 ID（分区表中与 created_at 组成联合主键）
+	ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:主键 ID" json:"id"`
+	// 分布式追踪 ID
+	TraceID string `gorm:"column:trace_id;type:varchar(64);not null;default:'';comment:分布式追踪 ID" json:"trace_id"`
+	// HTTP 请求唯一 ID
+	RequestID string `gorm:"column:request_id;type:varchar(64);not null;default:'';comment:HTTP 请求唯一 ID" json:"request_id"`
+	// 操作者类型
+	ActorType ActorType `gorm:"column:actor_type;type:varchar(20);not null;comment:操作者类型" json:"actor_type"`
+	// 操作者业务用户 ID（来自认证上下文，对应 p_user_users.id）
+	ActorID types.UserID `gorm:"column:actor_id;type:bigint;not null;default:0;comment:操作者业务 ID" json:"actor_id"`
+	// 认证主体类型
+	AuthSubjectType string `gorm:"column:auth_subject_type;type:varchar(32);not null;default:'';comment:认证主体类型" json:"auth_subject_type"`
+	// IAM 主体 ID
+	IAMPrincipalID int64 `gorm:"column:iam_principal_id;type:bigint;not null;default:0;comment:IAM 主体 ID" json:"iam_principal_id"`
+	// 凭证公开 ID
+	CredentialPublicID string `gorm:"column:credential_public_id;type:varchar(80);not null;default:'';comment:凭证公开 ID" json:"credential_public_id"`
+	// Token 指纹
+	TokenFingerprint string `gorm:"column:token_fingerprint;type:char(64);not null;default:'';comment:Token 指纹" json:"token_fingerprint"`
+	// 认证机制
+	AuthMechanism string `gorm:"column:auth_mechanism;type:varchar(32);not null;default:'';comment:认证机制" json:"auth_mechanism"`
+	// 客户端 IP 地址
+	ActorIP string `gorm:"column:actor_ip;type:varchar(45);not null;default:'';comment:客户端 IP 地址" json:"actor_ip"`
+	// 客户端 User-Agent
+	ActorUserAgent string `gorm:"column:actor_user_agent;type:text;not null;default:'';comment:客户端 User-Agent" json:"actor_user_agent"`
+	// HTTP 方法
+	HTTPMethod string `gorm:"column:http_method;type:varchar(10);not null;default:'';comment:HTTP 方法" json:"http_method"`
+	// 请求路径
+	HTTPPath string `gorm:"column:http_path;type:varchar(500);not null;default:'';comment:请求路径" json:"http_path"`
+	// HTTP 状态码
+	HTTPStatus int16 `gorm:"column:http_status;type:smallint;not null;default:0;comment:HTTP 响应状态码" json:"http_status"`
+	// 所属产品标识
+	ProductCode string `gorm:"column:product_code;type:varchar(50);not null;default:'';comment:所属产品标识" json:"product_code"`
+	// 资源类型
+	ResourceType string `gorm:"column:resource_type;type:varchar(50);not null;default:'';comment:资源类型" json:"resource_type"`
+	// 资源 ID
+	ResourceID string `gorm:"column:resource_id;type:varchar(100);not null;default:'';comment:资源 ID" json:"resource_id"`
+	// 请求是否成功
+	IsSuccess bool `gorm:"column:is_success;type:boolean;not null;default:true;comment:请求是否成功" json:"is_success"`
+	// 失败原因
+	ErrorMessage string `gorm:"column:error_message;type:varchar(500);not null;default:'';comment:失败原因" json:"error_message"`
+	// 请求处理耗时（毫秒）
+	DurationMS int32 `gorm:"column:duration_ms;type:integer;not null;default:0;comment:请求处理耗时毫秒" json:"duration_ms"`
+	// 请求时间
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamptz(3);not null;default:now();comment:请求时间" json:"created_at"`
+}
+
+// TableName 指定表名
+func (AccessLog) TableName() string {
+	return "sys_access_logs"
+}
+
+// LoginLog 登录日志记录（认证安全事件专用，含设备指纹和地理位置）
+type LoginLog struct {
+	// 主键 ID
+	ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:主键 ID" json:"id"`
+	// 认证身份 ID（对应 p_identity_identities.id）
+	IdentityID types.IdentityID `gorm:"column:identity_id;type:bigint;not null;default:0;comment:身份 ID" json:"identity_id"`
+	// 操作者类型
+	ActorType ActorType `gorm:"column:actor_type;type:varchar(20);not null;comment:操作者类型" json:"actor_type"`
+	// 客户端 IP 地址
+	ActorIP string `gorm:"column:actor_ip;type:varchar(45);not null;default:'';comment:客户端 IP 地址" json:"actor_ip"`
+	// 客户端 User-Agent
+	ActorUserAgent string `gorm:"column:actor_user_agent;type:text;not null;default:'';comment:客户端 User-Agent" json:"actor_user_agent"`
+	// 认证动作
+	LoginAction LoginAction `gorm:"column:login_action;type:varchar(30);not null;comment:认证动作" json:"login_action"`
+	// 登录方式
+	LoginMethod LoginMethod `gorm:"column:login_method;type:varchar(30);not null;default:'';comment:登录方式" json:"login_method"`
+	// 操作是否成功
+	IsSuccess bool `gorm:"column:is_success;type:boolean;not null;default:true;comment:操作是否成功" json:"is_success"`
+	// 失败原因
+	FailureReason string `gorm:"column:failure_reason;type:varchar(500);not null;default:'';comment:失败原因" json:"failure_reason"`
+	// 登录的目标产品
+	ProductCode string `gorm:"column:product_code;type:varchar(50);not null;default:'';comment:登录的目标产品" json:"product_code"`
+	// 会话 ID
+	SessionID string `gorm:"column:session_id;type:varchar(100);not null;default:'';comment:会话 ID" json:"session_id"`
+	// 关联的 HTTP 请求 ID
+	RequestID string `gorm:"column:request_id;type:varchar(64);not null;default:'';comment:关联的 HTTP 请求 ID" json:"request_id"`
+	// 设备类型
+	DeviceType string `gorm:"column:device_type;type:varchar(30);not null;default:'';comment:设备类型" json:"device_type"`
+	// 设备指纹哈希
+	DeviceFingerprint string `gorm:"column:device_fingerprint;type:varchar(64);not null;default:'';comment:设备指纹哈希" json:"device_fingerprint"`
+	// 操作系统
+	OSName string `gorm:"column:os_name;type:varchar(50);not null;default:'';comment:操作系统" json:"os_name"`
+	// 浏览器
+	BrowserName string `gorm:"column:browser_name;type:varchar(50);not null;default:'';comment:浏览器" json:"browser_name"`
+	// 国家代码
+	GeoCountry string `gorm:"column:geo_country;type:varchar(10);not null;default:'';comment:国家代码" json:"geo_country"`
+	// 城市
+	GeoCity string `gorm:"column:geo_city;type:varchar(100);not null;default:'';comment:城市" json:"geo_city"`
+	// 事件时间
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamptz(3);not null;default:now();comment:事件时间" json:"created_at"`
+}
+
+// TableName 指定表名
+func (LoginLog) TableName() string {
+	return "sys_login_logs"
+}
+
+// AuditEventInbox 审计消费者的持久事件去重记录。
+type AuditEventInbox struct {
+	database.BaseModel
+	// 领域事件唯一标识
+	EventID string `gorm:"column:event_id;type:varchar(64);not null;uniqueIndex:uk_sys_audit_event_inbox_event_id;comment:领域事件唯一标识" json:"event_id"`
+	// 领域事件发生时间
+	OccurredAt time.Time `gorm:"column:occurred_at;type:timestamptz(3);not null;comment:领域事件发生时间" json:"occurred_at"`
+	// 审计消费完成时间
+	ProcessedAt time.Time `gorm:"column:processed_at;type:timestamptz(3);not null;default:now();comment:审计消费完成时间" json:"processed_at"`
+}
+
+// TableName 指定表名。
+func (AuditEventInbox) TableName() string {
+	return "sys_audit_event_inbox"
+}
+
+// OperationLog 管理端操作日志记录（控制面操作的完整证据流）
+type OperationLog struct {
+	// 主键 ID
+	ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:主键 ID" json:"id"`
+	// 分布式追踪 ID
+	TraceID string `gorm:"column:trace_id;type:varchar(64);not null;default:'';comment:分布式追踪 ID" json:"trace_id"`
+	// HTTP 请求唯一 ID
+	RequestID string `gorm:"column:request_id;type:varchar(64);not null;default:'';comment:HTTP 请求唯一 ID" json:"request_id"`
+	// 操作者类型
+	ActorType ActorType `gorm:"column:actor_type;type:varchar(20);not null;comment:操作者类型" json:"actor_type"`
+	// 操作者业务用户 ID
+	ActorID types.UserID `gorm:"column:actor_id;type:bigint;not null;default:0;comment:操作者业务 ID" json:"actor_id"`
+	// 认证主体类型
+	AuthSubjectType string `gorm:"column:auth_subject_type;type:varchar(32);not null;default:'';comment:认证主体类型" json:"auth_subject_type"`
+	// IAM 主体 ID
+	IAMPrincipalID int64 `gorm:"column:iam_principal_id;type:bigint;not null;default:0;comment:IAM 主体 ID" json:"iam_principal_id"`
+	// 凭证公开 ID
+	CredentialPublicID string `gorm:"column:credential_public_id;type:varchar(80);not null;default:'';comment:凭证公开 ID" json:"credential_public_id"`
+	// Token 指纹
+	TokenFingerprint string `gorm:"column:token_fingerprint;type:char(64);not null;default:'';comment:Token 指纹" json:"token_fingerprint"`
+	// 认证机制
+	AuthMechanism string `gorm:"column:auth_mechanism;type:varchar(32);not null;default:'';comment:认证机制" json:"auth_mechanism"`
+	// 客户端 IP 地址
+	ActorIP string `gorm:"column:actor_ip;type:varchar(45);not null;default:'';comment:客户端 IP 地址" json:"actor_ip"`
+	// 客户端 User-Agent
+	ActorUserAgent string `gorm:"column:actor_user_agent;type:text;not null;default:'';comment:客户端 User-Agent" json:"actor_user_agent"`
+	// 操作动作
+	OperationAction AuditAction `gorm:"column:operation_action;type:varchar(50);not null;comment:操作动作" json:"operation_action"`
+	// 操作分类
+	OperationCategory AuditCategory `gorm:"column:operation_category;type:varchar(30);not null;default:'system';comment:操作分类" json:"operation_category"`
+	// 风险级别
+	RiskLevel RiskLevel `gorm:"column:risk_level;type:varchar(10);not null;default:'medium';comment:风险级别" json:"risk_level"`
+	// 来源模块
+	SourceModule string `gorm:"column:source_module;type:varchar(80);not null;default:'';comment:来源模块" json:"source_module"`
+	// IAM 动作
+	IAMAction string `gorm:"column:iam_action;type:varchar(120);not null;default:'';comment:IAM 动作" json:"iam_action"`
+	// IAM 资源
+	IAMResource string `gorm:"column:iam_resource;type:varchar(300);not null;default:'';comment:IAM 资源" json:"iam_resource"`
+	// 授权是否允许
+	DecisionAllowed bool `gorm:"column:decision_allowed;type:boolean;not null;default:false;comment:授权是否允许" json:"decision_allowed"`
+	// 授权原因码
+	DecisionReasonCode string `gorm:"column:decision_reason_code;type:varchar(80);not null;default:'';comment:授权原因码" json:"decision_reason_code"`
+	// 授权原因类别
+	DecisionReasonKind string `gorm:"column:decision_reason_kind;type:varchar(40);not null;default:'';comment:授权原因类别" json:"decision_reason_kind"`
+	// HTTP 方法
+	HTTPMethod string `gorm:"column:http_method;type:varchar(10);not null;default:'';comment:HTTP 方法" json:"http_method"`
+	// 请求路径
+	HTTPPath string `gorm:"column:http_path;type:varchar(500);not null;default:'';comment:请求路径" json:"http_path"`
+	// HTTP 状态码
+	HTTPStatus int16 `gorm:"column:http_status;type:smallint;not null;default:0;comment:HTTP 响应状态码" json:"http_status"`
+	// 请求处理耗时（毫秒）
+	DurationMS int32 `gorm:"column:duration_ms;type:integer;not null;default:0;comment:请求处理耗时毫秒" json:"duration_ms"`
+	// 所属产品标识
+	ProductCode string `gorm:"column:product_code;type:varchar(50);not null;default:'';comment:所属产品标识" json:"product_code"`
+	// 所属租户 ID
+	TenantID string `gorm:"column:tenant_id;type:varchar(50);not null;default:'';comment:所属租户 ID" json:"tenant_id"`
+	// 资源类型
+	ResourceType string `gorm:"column:resource_type;type:varchar(50);not null;default:'';comment:资源类型" json:"resource_type"`
+	// 资源 ID
+	ResourceID string `gorm:"column:resource_id;type:varchar(100);not null;default:'';comment:资源 ID" json:"resource_id"`
+	// 请求是否成功
+	IsSuccess bool `gorm:"column:is_success;type:boolean;not null;default:true;comment:请求是否成功" json:"is_success"`
+	// 失败原因
+	ErrorMessage string `gorm:"column:error_message;type:varchar(500);not null;default:'';comment:失败原因" json:"error_message"`
+	// 请求证据上下文
+	RequestContext datatypes.JSON `gorm:"column:request_context;type:jsonb;not null;default:'{}';comment:请求证据上下文" json:"request_context"`
+	// 响应证据上下文
+	ResponseContext datatypes.JSON `gorm:"column:response_context;type:jsonb;not null;default:'{}';comment:响应证据上下文" json:"response_context"`
+	// 操作元数据
+	OperationMetadata datatypes.JSON `gorm:"column:operation_metadata;type:jsonb;not null;default:'{}';comment:操作元数据" json:"operation_metadata"`
+	// 策略裁决上下文
+	PolicyViolation datatypes.JSON `gorm:"column:policy_violation;type:jsonb;not null;default:'{}';comment:策略裁决上下文" json:"policy_violation"`
+	// 记录状态
+	RecordStatus string `gorm:"column:record_status;type:varchar(20);not null;default:'started';comment:记录状态" json:"record_status"`
+	// 完成时间
+	CompletedAt *time.Time `gorm:"column:completed_at;type:timestamptz(3);comment:完成时间" json:"completed_at"`
+	// 创建时间
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamptz(3);not null;default:now();comment:创建时间" json:"created_at"`
+}
+
+// TableName 指定表名
+func (OperationLog) TableName() string {
+	return "sys_operation_logs"
+}
+
+// AuditLog 审计日志记录（业务变更的合规审计记录，不含 HTTP 请求维度字段）
+// 重构后仅记录业务变更事件，HTTP 请求记录已拆分到 sys_access_logs
+type AuditLog struct {
+	// 主键 ID
+	ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:主键 ID" json:"id"`
+	// 领域事件唯一标识；由 sys_audit_event_inbox 保证消费幂等
+	EventID *string `gorm:"column:event_id;type:varchar(64);comment:领域事件唯一标识" json:"event_id,omitempty"`
+	// 领域事件发生时间；非事件型审计为空
+	OccurredAt *time.Time `gorm:"column:occurred_at;type:timestamptz(3);comment:领域事件发生时间" json:"occurred_at,omitempty"`
+	// 分布式追踪 ID
+	TraceID string `gorm:"column:trace_id;type:varchar(64);not null;default:'';comment:分布式追踪 ID" json:"trace_id"`
+	// 关联的 HTTP 请求 ID（可与 sys_access_logs 关联）
+	RequestID string `gorm:"column:request_id;type:varchar(64);not null;default:'';comment:关联的 HTTP 请求 ID" json:"request_id"`
+	// 操作者类型
+	ActorType ActorType `gorm:"column:actor_type;type:varchar(20);not null;comment:操作者类型" json:"actor_type"`
+	// 操作者业务用户 ID（来自认证上下文，对应 p_user_users.id）
+	ActorID types.UserID `gorm:"column:actor_id;type:bigint;not null;default:0;comment:操作者业务 ID" json:"actor_id"`
+	// 认证主体类型
+	AuthSubjectType string `gorm:"column:auth_subject_type;type:varchar(32);not null;default:'';comment:认证主体类型" json:"auth_subject_type"`
+	// IAM 主体 ID
+	IAMPrincipalID int64 `gorm:"column:iam_principal_id;type:bigint;not null;default:0;comment:IAM 主体 ID" json:"iam_principal_id"`
+	// 凭证公开 ID
+	CredentialPublicID string `gorm:"column:credential_public_id;type:varchar(80);not null;default:'';comment:凭证公开 ID" json:"credential_public_id"`
+	// Token 指纹
+	TokenFingerprint string `gorm:"column:token_fingerprint;type:char(64);not null;default:'';comment:Token 指纹" json:"token_fingerprint"`
+	// 认证机制
+	AuthMechanism string `gorm:"column:auth_mechanism;type:varchar(32);not null;default:'';comment:认证机制" json:"auth_mechanism"`
+	// 客户端 IP 地址
+	ActorIP string `gorm:"column:actor_ip;type:varchar(45);not null;default:'';comment:客户端 IP 地址" json:"actor_ip"`
+	// 客户端 User-Agent（30 天后 access_logs 清理，审计取证需保留设备信息）
+	ActorUserAgent string `gorm:"column:actor_user_agent;type:text;not null;default:'';comment:客户端 User-Agent" json:"actor_user_agent"`
+	// 操作动作
+	Action AuditAction `gorm:"column:action;type:varchar(50);not null;comment:操作动作" json:"action"`
+	// 业务分类
+	Category AuditCategory `gorm:"column:category;type:varchar(30);not null;comment:业务分类" json:"category"`
+	// 风险级别
+	RiskLevel RiskLevel `gorm:"column:risk_level;type:varchar(10);not null;default:'medium';comment:风险级别" json:"risk_level"`
+	// 资源类型
+	ResourceType string `gorm:"column:resource_type;type:varchar(50);not null;default:'';comment:资源类型" json:"resource_type"`
+	// 资源 ID
+	ResourceID string `gorm:"column:resource_id;type:varchar(100);not null;default:'';comment:资源 ID" json:"resource_id"`
+	// 所属产品标识
+	ProductCode string `gorm:"column:product_code;type:varchar(50);not null;default:'';comment:所属产品标识" json:"product_code"`
+	// 所属租户 ID
+	TenantID string `gorm:"column:tenant_id;type:varchar(50);not null;default:'';comment:所属租户 ID" json:"tenant_id"`
+	// 数据变更前后快照
+	Changes datatypes.JSON `gorm:"column:changes;type:jsonb;comment:数据变更前后快照" json:"changes,omitempty"`
+	// 扩展上下文信息
+	Metadata datatypes.JSON `gorm:"column:metadata;type:jsonb;comment:扩展上下文信息" json:"metadata,omitempty"`
+	// 操作是否成功
+	IsSuccess bool `gorm:"column:is_success;type:boolean;not null;default:true;comment:操作是否成功" json:"is_success"`
+	// 失败原因
+	ErrorMessage string `gorm:"column:error_message;type:varchar(500);not null;default:'';comment:失败原因" json:"error_message"`
+	// 审计记录写入时间
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamptz(3);not null;default:now();comment:审计记录写入时间" json:"created_at"`
+}
+
+// TableName 指定表名
+func (AuditLog) TableName() string {
+	return "sys_audit_logs"
+}
+
+// ChangesPayload 变更详情结构（用于 Service 层构造）
+type ChangesPayload struct {
+	// 变更前数据
+	Before any `json:"before,omitempty"`
+	// 变更后数据
+	After any `json:"after,omitempty"`
+}
+
+// MetadataPayload 扩展元数据结构
+type MetadataPayload struct {
+	// 业务错误码
+	ErrorCode string `json:"error_code,omitempty"`
+	// 操作原因
+	Reason string `json:"reason,omitempty"`
+	// 会话 ID
+	SessionID int64 `json:"session_id,omitempty"`
+	// 关联资源 ID（如订单关联的订阅 ID）
+	RelatedResourceID string `json:"related_resource_id,omitempty"`
+	// 关联资源类型
+	RelatedResourceType string `json:"related_resource_type,omitempty"`
+	// APISIX 网关事件 ID
+	GatewayEventID string `json:"gateway_event_id,omitempty"`
+	// 扩展字段，承载模块私有且不含敏感信息的审计上下文
+	Extra map[string]any `json:"extra,omitempty"`
+}
+
+// ResourceIDStr 将 int64 类型的资源 ID 转换为字符串
+func ResourceIDStr(id int64) string {
+	return strconv.FormatInt(id, 10)
+}