@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,1007 @@
+package audit
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"{{module}}/internal/common/iamscope"
+	"{{module}}/internal/core/database"
+)
+
+// batchInsertSize 单次批量插入条数，平衡内存与写入效率
+const batchInsertSize = 100
+
+var iamPrincipalResourceTypes = []string{
+	string(AuditResourceIAMPrincipal),
+	string(AuditResourceIAMServiceAccount),
+}
+
+func normalizeKeyword(keyword string) (string, string, bool) {
+	kw := strings.TrimSpace(keyword)
+	if kw == "" {
+		return "", "", false
+	}
+	return kw, "%" + strings.ToLower(kw) + "%", true
+}
+
+func keywordTextCondition(column string) string {
+	return "LOWER(" + column + ") LIKE ?"
+}
+
+type auditScopeBinding struct {
+	productColumn string
+	tenantColumn  string
+	selfColumn    string
+}
+
+func (b auditScopeBinding) Column(dim iamscope.ScopeDimension) (string, bool) {
+	switch dim {
+	case iamscope.ScopeDimensionProduct:
+		return b.productColumn, b.productColumn != ""
+	case iamscope.ScopeDimensionTenant:
+		return b.tenantColumn, b.tenantColumn != ""
+	case iamscope.ScopeDimensionAssignedToSelf, iamscope.ScopeDimensionCreatedBySelf:
+		return b.selfColumn, b.selfColumn != ""
+	default:
+		return "", false
+	}
+}
+
+var (
+	auditLogScopeBinding = auditScopeBinding{
+		productColumn: "product_code",
+		tenantColumn:  "tenant_id",
+		selfColumn:    "iam_principal_id",
+	}
+	operationLogScopeBinding = auditScopeBinding{
+		productColumn: "product_code",
+		tenantColumn:  "tenant_id",
+		selfColumn:    "iam_principal_id",
+	}
+	accessLogScopeBinding = auditScopeBinding{
+		productColumn: "product_code",
+		selfColumn:    "iam_principal_id",
+	}
+	loginLogScopeBinding = auditScopeBinding{
+		productColumn: "product_code",
+	}
+)
+
+// ---------------------------------------------------------------------------
+// AccessLogRepository — 访问日志仓储
+// ---------------------------------------------------------------------------
+
+// AccessLogRepository 访问日志仓储接口（append-only，严禁 Update/Delete）
+type AccessLogRepository interface {
+	// BatchCreate 批量插入访问日志
+	BatchCreate(ctx context.Context, logs []*AccessLog) error
+	// FindByQuery 分页查询访问日志
+	FindByQuery(ctx context.Context, query *AdminListAccessLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AccessLog, int64, error)
+	// FindByID 根据 ID 查询单条访问日志
+	FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AccessLog, error)
+}
+
+// accessLogRepository GORM 实现
+type accessLogRepository struct {
+	db          *gorm.DB
+	actorSearch ActorReferenceSearcher
+}
+
+// NewAccessLogRepository 构建访问日志仓储实例
+func NewAccessLogRepository(db *gorm.DB, actorSearch ActorReferenceSearcher) AccessLogRepository {
+	return &accessLogRepository{db: db, actorSearch: actorSearch}
+}
+
+// BatchCreate 批量插入，使用 CreateInBatches 优化大批量写入
+func (r *accessLogRepository) BatchCreate(ctx context.Context, logs []*AccessLog) error {
+	return database.GetDB(ctx, r.db).
+		Table((AccessLog{}).TableName()).
+		CreateInBatches(accessLogCreateMaps(logs), batchInsertSize).Error
+}
+
+func accessLogCreateMaps(logs []*AccessLog) []map[string]any {
+	// GORM 批量插入的列值 map 需要承载 string、int、bool、指针等不同列类型。
+	items := make([]map[string]any, 0, len(logs))
+	for _, log := range logs {
+		items = append(items, map[string]any{
+			"trace_id":             log.TraceID,
+			"request_id":           log.RequestID,
+			"actor_type":           log.ActorType,
+			"actor_id":             log.ActorID,
+			"auth_subject_type":    log.AuthSubjectType,
+			"iam_principal_id":     log.IAMPrincipalID,
+			"credential_public_id": log.CredentialPublicID,
+			"token_fingerprint":    log.TokenFingerprint,
+			"auth_mechanism":       log.AuthMechanism,
+			"actor_ip":             log.ActorIP,
+			"actor_user_agent":     log.ActorUserAgent,
+			"http_method":          log.HTTPMethod,
+			"http_path":            log.HTTPPath,
+			"http_status":          log.HTTPStatus,
+			"product_code":         log.ProductCode,
+			"resource_type":        log.ResourceType,
+			"resource_id":          log.ResourceID,
+			"is_success":           log.IsSuccess,
+			"error_message":        log.ErrorMessage,
+			"duration_ms":          log.DurationMS,
+		})
+	}
+	return items
+}
+
+// FindByQuery 分页查询，明确指定查询字段（禁止全列查询）
+func (r *accessLogRepository) FindByQuery(ctx context.Context, query *AdminListAccessLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AccessLog, int64, error) {
+	db := database.GetDB(ctx, r.db).Model(&AccessLog{}).
+		Select(
+			"id", "trace_id", "request_id",
+			"actor_type", "actor_id", "actor_ip",
+			"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+			"http_method", "http_path", "http_status",
+			"product_code", "resource_type", "resource_id",
+			"is_success", "error_message", "duration_ms",
+			"created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, accessLogScopeBinding, principalID)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	// 可选过滤条件
+	if query.PrincipalID != nil {
+		db = db.Where("iam_principal_id = ?", *query.PrincipalID)
+	}
+	if query.ActorID != nil {
+		db = db.Where("actor_id = ?", *query.ActorID)
+	}
+	if query.HTTPMethod != nil && *query.HTTPMethod != "" {
+		db = db.Where("http_method = ?", *query.HTTPMethod)
+	}
+	if query.HTTPStatus != nil {
+		db = db.Where("http_status = ?", *query.HTTPStatus)
+	}
+	if query.ProductCode != nil && *query.ProductCode != "" {
+		db = db.Where("product_code = ?", *query.ProductCode)
+	}
+	if query.ResourceType != nil && *query.ResourceType != "" {
+		db = db.Where("resource_type = ?", *query.ResourceType)
+	}
+	if query.ResourceID != nil && *query.ResourceID != "" {
+		db = db.Where("resource_id = ?", *query.ResourceID)
+	}
+	if query.IsSuccess != nil {
+		db = db.Where("is_success = ?", *query.IsSuccess)
+	}
+	if query.DateFrom != nil {
+		db = db.Where("created_at >= ?", *query.DateFrom)
+	}
+	if query.DateTo != nil {
+		db = db.Where("created_at <= ?", *query.DateTo)
+	}
+	if query.PathKeyword != nil {
+		if _, like, ok := normalizeKeyword(*query.PathKeyword); ok {
+			db = db.Where(keywordTextCondition("http_path"), like)
+		}
+	}
+	if query.RequestID != nil && *query.RequestID != "" {
+		db = db.Where("request_id = ?", *query.RequestID)
+	}
+	if query.TraceID != nil && *query.TraceID != "" {
+		db = db.Where("trace_id = ?", *query.TraceID)
+	}
+	if query.Keyword != nil {
+		if kw, like, ok := normalizeKeyword(*query.Keyword); ok {
+			matches, err := r.actorSearch.Search(ctx, kw)
+			if err != nil {
+				return nil, 0, err
+			}
+			actorSubQuery := matches.ActorIDs
+			principalSubQuery := matches.PrincipalIDs
+			principalTextSubQuery := make([]string, len(matches.PrincipalIDs))
+			for i, id := range matches.PrincipalIDs {
+				principalTextSubQuery[i] = strconv.FormatInt(id, 10)
+			}
+			conditions := r.db.
+				Where(keywordTextCondition("http_path"), like).
+				Or(keywordTextCondition("resource_type"), like).
+				Or(keywordTextCondition("resource_id"), like).
+				Or(keywordTextCondition("trace_id"), like).
+				Or(keywordTextCondition("request_id"), like).
+				Or(keywordTextCondition("actor_ip"), like).
+				Or("actor_id IN (?)", actorSubQuery).
+				Or("iam_principal_id IN (?)", principalSubQuery).
+				Or("resource_type IN ? AND resource_id IN (?)", iamPrincipalResourceTypes, principalTextSubQuery)
+			if parsedID, parseErr := strconv.ParseInt(kw, 10, 64); parseErr == nil {
+				conditions = conditions.
+					Or("actor_id = ?", parsedID).
+					Or("iam_principal_id = ?", parsedID).
+					Or("resource_type IN ? AND resource_id = ?", iamPrincipalResourceTypes, strconv.FormatInt(parsedID, 10))
+			}
+			db = db.Where(conditions)
+		}
+	}
+
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	var logs []*AccessLog
+	if err := db.Order("created_at DESC").
+		Order("id DESC").
+		Offset(query.Offset()).
+		Limit(query.PageSize).
+		Find(&logs).Error; err != nil {
+		return nil, 0, err
+	}
+	return logs, total, nil
+}
+
+// FindByID 查询单条访问日志（包含 actor_user_agent 等完整字段）
+func (r *accessLogRepository) FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AccessLog, error) {
+	db := database.GetDB(ctx, r.db).Model(&AccessLog{}).
+		Select(
+			"id", "trace_id", "request_id",
+			"actor_type", "actor_id", "actor_ip", "actor_user_agent",
+			"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+			"http_method", "http_path", "http_status",
+			"product_code", "resource_type", "resource_id",
+			"is_success", "error_message", "duration_ms",
+			"created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, accessLogScopeBinding, principalID)
+	if err != nil {
+		return nil, err
+	}
+
+	var log AccessLog
+	if err := db.First(&log, "id = ?", id).Error; err != nil {
+		return nil, err
+	}
+	return &log, nil
+}
+
+// ---------------------------------------------------------------------------
+// LoginLogRepository — 登录日志仓储
+// ---------------------------------------------------------------------------
+
+// LoginLogRepository 登录日志仓储接口（append-only，严禁 Update/Delete）
+type LoginLogRepository interface {
+	// BatchCreate 批量插入登录日志
+	BatchCreate(ctx context.Context, logs []*LoginLog) error
+	// FindByQuery 分页查询登录日志
+	FindByQuery(ctx context.Context, query *AdminListLoginLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*LoginLog, int64, error)
+	// FindByID 根据 ID 查询单条登录日志
+	FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*LoginLog, error)
+	// CountFailedByIP 统计指定 IP 在指定时间之后的失败次数（用于安全策略）
+	CountFailedByIP(ctx context.Context, ip string, since time.Time) (int64, error)
+	// FindByIdentity 查询指定身份的最近登录记录
+	FindByIdentity(ctx context.Context, identityID int64, limit int) ([]*LoginLog, error)
+}
+
+// loginLogRepository GORM 实现
+type loginLogRepository struct {
+	db          *gorm.DB
+	actorSearch ActorReferenceSearcher
+}
+
+// NewLoginLogRepository 构建登录日志仓储实例
+func NewLoginLogRepository(db *gorm.DB, actorSearch ActorReferenceSearcher) LoginLogRepository {
+	return &loginLogRepository{db: db, actorSearch: actorSearch}
+}
+
+// BatchCreate 批量插入，使用 CreateInBatches 优化大批量写入
+func (r *loginLogRepository) BatchCreate(ctx context.Context, logs []*LoginLog) error {
+	return database.GetDB(ctx, r.db).
+		Table((LoginLog{}).TableName()).
+		CreateInBatches(loginLogCreateMaps(logs), batchInsertSize).Error
+}
+
+func loginLogCreateMaps(logs []*LoginLog) []map[string]any {
+	// GORM 批量插入的列值 map 需要承载 string、int、bool、指针等不同列类型。
+	items := make([]map[string]any, 0, len(logs))
+	for _, log := range logs {
+		items = append(items, map[string]any{
+			"identity_id":        log.IdentityID,
+			"actor_type":         log.ActorType,
+			"actor_ip":           log.ActorIP,
+			"actor_user_agent":   log.ActorUserAgent,
+			"login_action":       log.LoginAction,
+			"login_method":       log.LoginMethod,
+			"is_success":         log.IsSuccess,
+			"failure_reason":     log.FailureReason,
+			"product_code":       log.ProductCode,
+			"session_id":         log.SessionID,
+			"request_id":         log.RequestID,
+			"device_type":        log.DeviceType,
+			"device_fingerprint": log.DeviceFingerprint,
+			"os_name":            log.OSName,
+			"browser_name":       log.BrowserName,
+			"geo_country":        log.GeoCountry,
+			"geo_city":           log.GeoCity,
+		})
+	}
+	return items
+}
+
+// FindByQuery 分页查询，列表不返回 actor_user_agent（减少传输量）
+func (r *loginLogRepository) FindByQuery(ctx context.Context, query *AdminListLoginLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*LoginLog, int64, error) {
+	db := database.GetDB(ctx, r.db).Model(&LoginLog{}).
+		Select(
+			"id", "identity_id", "actor_type", "actor_ip",
+			"login_action", "login_method",
+			"is_success", "failure_reason",
+			"product_code", "session_id", "request_id",
+			"device_type", "os_name", "browser_name",
+			"geo_country", "geo_city",
+			"created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, loginLogScopeBinding, principalID)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	// 可选过滤条件
+	if query.ActorIP != nil && *query.ActorIP != "" {
+		db = db.Where("actor_ip = ?", *query.ActorIP)
+	}
+	if query.LoginAction != nil && *query.LoginAction != "" {
+		db = db.Where("login_action = ?", *query.LoginAction)
+	}
+	if query.LoginMethod != nil && *query.LoginMethod != "" {
+		db = db.Where("login_method = ?", *query.LoginMethod)
+	}
+	if query.IsSuccess != nil {
+		db = db.Where("is_success = ?", *query.IsSuccess)
+	}
+	if query.ProductCode != nil && *query.ProductCode != "" {
+		db = db.Where("product_code = ?", *query.ProductCode)
+	}
+	if query.DateFrom != nil {
+		db = db.Where("created_at >= ?", *query.DateFrom)
+	}
+	if query.DateTo != nil {
+		db = db.Where("created_at <= ?", *query.DateTo)
+	}
+	if query.RequestID != nil && *query.RequestID != "" {
+		db = db.Where("request_id = ?", *query.RequestID)
+	}
+	if query.Keyword != nil {
+		if kw, like, ok := normalizeKeyword(*query.Keyword); ok {
+			matches, err := r.actorSearch.Search(ctx, kw)
+			if err != nil {
+				return nil, 0, err
+			}
+			identitySubQuery := matches.IdentityIDs
+			conditions := r.db.
+				Where(keywordTextCondition("actor_ip"), like).
+				Or(keywordTextCondition("session_id"), like).
+				Or(keywordTextCondition("request_id"), like).
+				Or(keywordTextCondition("device_type"), like).
+				Or(keywordTextCondition("os_name"), like).
+				Or(keywordTextCondition("browser_name"), like).
+				Or(keywordTextCondition("geo_country"), like).
+				Or(keywordTextCondition("geo_city"), like).
+				Or("identity_id IN (?)", identitySubQuery)
+			db = db.Where(conditions)
+		}
+	}
+
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	var logs []*LoginLog
+	if err := db.Order("created_at DESC").
+		Offset(query.Offset()).
+		Limit(query.PageSize).
+		Find(&logs).Error; err != nil {
+		return nil, 0, err
+	}
+	return logs, total, nil
+}
+
+// FindByID 查询单条登录日志（包含设备指纹和 User-Agent）
+func (r *loginLogRepository) FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*LoginLog, error) {
+	db := database.GetDB(ctx, r.db).Model(&LoginLog{}).
+		Select(
+			"id", "identity_id", "actor_type", "actor_ip", "actor_user_agent",
+			"login_action", "login_method",
+			"is_success", "failure_reason",
+			"product_code", "session_id", "request_id",
+			"device_type", "device_fingerprint", "os_name", "browser_name",
+			"geo_country", "geo_city",
+			"created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, loginLogScopeBinding, principalID)
+	if err != nil {
+		return nil, err
+	}
+
+	var log LoginLog
+	if err := db.First(&log, "id = ?", id).Error; err != nil {
+		return nil, err
+	}
+	return &log, nil
+}
+
+// CountFailedByIP 统计指定 IP 在 since 之后的登录失败次数
+// 用于安全策略判断是否需要触发 IP 封禁或验证码
+func (r *loginLogRepository) CountFailedByIP(ctx context.Context, ip string, since time.Time) (int64, error) {
+	var count int64
+	err := database.GetDB(ctx, r.db).Model(&LoginLog{}).
+		Where("actor_ip = ? AND is_success = false AND created_at >= ?", ip, since).
+		Count(&count).Error
+	return count, err
+}
+
+// FindByIdentity 查询指定身份的最近登录记录（用于用户安全页面展示）
+func (r *loginLogRepository) FindByIdentity(ctx context.Context, identityID int64, limit int) ([]*LoginLog, error) {
+	var logs []*LoginLog
+	err := database.GetDB(ctx, r.db).Model(&LoginLog{}).
+		Select(
+			"id", "identity_id", "actor_type", "actor_ip",
+			"login_action", "login_method",
+			"is_success", "failure_reason",
+			"product_code", "session_id", "request_id",
+			"device_type", "os_name", "browser_name",
+			"geo_country", "geo_city",
+			"created_at",
+		).
+		Where("identity_id = ?", identityID).
+		Order("created_at DESC").
+		Limit(limit).
+		Find(&logs).Error
+	return logs, err
+}
+
+// ---------------------------------------------------------------------------
+// AuditRepository — 审计日志仓储
+// ---------------------------------------------------------------------------
+
+// AuditRepository 审计日志仓储接口（append-only，严禁 Update/Delete）
+type AuditRepository interface {
+	// BatchCreate 批量插入审计记录
+	BatchCreate(ctx context.Context, logs []*AuditLog) error
+	// ClaimEventAudit 领取领域事件审计处理权；重复事件返回 false
+	ClaimEventAudit(ctx context.Context, inbox *AuditEventInbox) (bool, error)
+	// FindByQuery 分页查询审计日志
+	FindByQuery(ctx context.Context, query *AdminListAuditLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AuditLog, int64, error)
+	// FindByID 根据 ID 查询单条审计日志（含完整字段）
+	FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AuditLog, error)
+	// CountByCategory 按分类统计（用于统计接口）
+	CountByCategory(ctx context.Context, from, to time.Time, scope iamscope.ScopeConstraint, principalID int64) ([]CategoryCount, error)
+	// CountByRiskLevel 按风险级别统计
+	CountByRiskLevel(ctx context.Context, from, to time.Time, scope iamscope.ScopeConstraint, principalID int64) ([]RiskLevelCount, error)
+}
+
+// CategoryCount 分类统计结果
+type CategoryCount struct {
+	// 分类
+	Category AuditCategory `json:"category"`
+	// 数量
+	Count int64 `json:"count"`
+}
+
+// RiskLevelCount 风险级别统计结果
+type RiskLevelCount struct {
+	// 风险级别
+	RiskLevel RiskLevel `json:"risk_level"`
+	// 数量
+	Count int64 `json:"count"`
+}
+
+// auditRepository GORM 实现
+type auditRepository struct {
+	db          *gorm.DB
+	actorSearch ActorReferenceSearcher
+}
+
+// NewAuditRepository 构建审计日志仓储实例
+func NewAuditRepository(db *gorm.DB, actorSearch ActorReferenceSearcher) AuditRepository {
+	return &auditRepository{db: db, actorSearch: actorSearch}
+}
+
+// BatchCreate 批量插入，使用 CreateInBatches 优化大批量写入
+func (r *auditRepository) BatchCreate(ctx context.Context, logs []*AuditLog) error {
+	return database.GetDB(ctx, r.db).
+		Table((AuditLog{}).TableName()).
+		CreateInBatches(auditLogCreateMaps(logs), batchInsertSize).Error
+}
+
+// ClaimEventAudit 通过 inbox 主键原子领取领域事件审计处理权。
+func (r *auditRepository) ClaimEventAudit(ctx context.Context, inbox *AuditEventInbox) (bool, error) {
+	claim := database.GetDB(ctx, r.db).
+		Clauses(clause.OnConflict{DoNothing: true}).
+		Create(inbox)
+	if claim.Error != nil {
+		return false, claim.Error
+	}
+	return claim.RowsAffected == 1, nil
+}
+
+func auditLogCreateMaps(logs []*AuditLog) []map[string]any {
+	// GORM 批量插入的列值 map 需要承载 string、int、bool、JSON 等不同列类型。
+	items := make([]map[string]any, 0, len(logs))
+	for _, log := range logs {
+		items = append(items, map[string]any{
+			"event_id":             log.EventID,
+			"occurred_at":          log.OccurredAt,
+			"trace_id":             log.TraceID,
+			"request_id":           log.RequestID,
+			"actor_type":           log.ActorType,
+			"actor_id":             log.ActorID,
+			"auth_subject_type":    log.AuthSubjectType,
+			"iam_principal_id":     log.IAMPrincipalID,
+			"credential_public_id": log.CredentialPublicID,
+			"token_fingerprint":    log.TokenFingerprint,
+			"auth_mechanism":       log.AuthMechanism,
+			"actor_ip":             log.ActorIP,
+			"actor_user_agent":     log.ActorUserAgent,
+			"action":               log.Action,
+			"category":             log.Category,
+			"risk_level":           log.RiskLevel,
+			"resource_type":        log.ResourceType,
+			"resource_id":          log.ResourceID,
+			"product_code":         log.ProductCode,
+			"tenant_id":            log.TenantID,
+			"changes":              log.Changes,
+			"metadata":             log.Metadata,
+			"is_success":           log.IsSuccess,
+			"error_message":        log.ErrorMessage,
+		})
+	}
+	return items
+}
+
+// FindByQuery 分页查询，默认轻量列；详情型列表可显式请求 changes/metadata。
+func (r *auditRepository) FindByQuery(ctx context.Context, query *AdminListAuditLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AuditLog, int64, error) {
+	selectedColumns := []string{
+		"id", "event_id", "occurred_at", "trace_id", "request_id",
+		"actor_type", "actor_id", "actor_ip",
+		"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+		"action", "category", "risk_level",
+		"resource_type", "resource_id",
+		"product_code", "tenant_id",
+		"is_success", "error_message",
+		"created_at",
+	}
+	if query.IncludePayload != nil && *query.IncludePayload {
+		selectedColumns = append(selectedColumns, "actor_user_agent", "changes", "metadata")
+	}
+	db := database.GetDB(ctx, r.db).Model(&AuditLog{}).
+		Select(
+			selectedColumns,
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, auditLogScopeBinding, principalID)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	// 可选过滤条件
+	if query.PrincipalID != nil {
+		db = db.Where("iam_principal_id = ?", *query.PrincipalID)
+	}
+	if query.ActorID != nil {
+		db = db.Where("actor_id = ?", *query.ActorID)
+	}
+	if query.ActorType != nil && *query.ActorType != "" {
+		db = db.Where("actor_type = ?", *query.ActorType)
+	}
+	if query.Action != nil && *query.Action != "" {
+		db = db.Where("action = ?", *query.Action)
+	}
+	if query.Category != nil && *query.Category != "" {
+		db = db.Where("category = ?", *query.Category)
+	}
+	if query.RiskLevel != nil && *query.RiskLevel != "" {
+		db = db.Where("risk_level = ?", *query.RiskLevel)
+	}
+	if query.ResourceType != nil && *query.ResourceType != "" &&
+		query.ResourceID != nil && *query.ResourceID != "" &&
+		query.IncludeRelated != nil && *query.IncludeRelated {
+		if *query.ResourceType == string(AuditResourceIAMPrincipal) || *query.ResourceType == string(AuditResourceIAMServiceAccount) {
+			db = db.Where(
+				strings.Join([]string{
+					"(resource_type = ? AND resource_id = ?)",
+					"(metadata ->> 'related_resource_type' = ? AND metadata ->> 'related_resource_id' = ?)",
+					"(changes #>> '{after,principal_id}' = ? OR changes #>> '{before,principal_id}' = ?)",
+				}, " OR "),
+				*query.ResourceType,
+				*query.ResourceID,
+				*query.ResourceType,
+				*query.ResourceID,
+				*query.ResourceID,
+				*query.ResourceID,
+			)
+		} else {
+			db = db.Where(
+				strings.Join([]string{
+					"(resource_type = ? AND resource_id = ?)",
+					"(metadata ->> 'related_resource_type' = ? AND metadata ->> 'related_resource_id' = ?)",
+				}, " OR "),
+				*query.ResourceType,
+				*query.ResourceID,
+				*query.ResourceType,
+				*query.ResourceID,
+			)
+		}
+	} else {
+		if query.ResourceType != nil && *query.ResourceType != "" {
+			db = db.Where("resource_type = ?", *query.ResourceType)
+		} else if resourceTypes := query.ResourceTypeValues(); len(resourceTypes) > 0 {
+			db = db.Where("resource_type IN ?", resourceTypes)
+		}
+		if query.ResourceID != nil && *query.ResourceID != "" {
+			db = db.Where("resource_id = ?", *query.ResourceID)
+		}
+	}
+	if query.ProductCode != nil && *query.ProductCode != "" {
+		db = db.Where("product_code = ?", *query.ProductCode)
+	}
+	if query.TenantID != nil && *query.TenantID != "" {
+		db = db.Where("tenant_id = ?", *query.TenantID)
+	}
+	if query.IsSuccess != nil {
+		db = db.Where("is_success = ?", *query.IsSuccess)
+	}
+	if query.DateFrom != nil {
+		db = db.Where("COALESCE(occurred_at, created_at) >= ?", *query.DateFrom)
+	}
+	if query.DateTo != nil {
+		db = db.Where("COALESCE(occurred_at, created_at) <= ?", *query.DateTo)
+	}
+	if query.TraceID != nil && *query.TraceID != "" {
+		db = db.Where("trace_id = ?", *query.TraceID)
+	}
+	if query.RequestID != nil && *query.RequestID != "" {
+		db = db.Where("request_id = ?", *query.RequestID)
+	}
+	// 审计检索必须覆盖对象、链路和操作者三类证据，支撑控制台单关键词入口。
+	if query.Keyword != nil {
+		if kw, like, ok := normalizeKeyword(*query.Keyword); ok {
+			matches, err := r.actorSearch.Search(ctx, kw)
+			if err != nil {
+				return nil, 0, err
+			}
+			actorSubQuery := matches.ActorIDs
+			principalSubQuery := matches.PrincipalIDs
+			principalTextSubQuery := make([]string, len(matches.PrincipalIDs))
+			for i, id := range matches.PrincipalIDs {
+				principalTextSubQuery[i] = strconv.FormatInt(id, 10)
+			}
+			conditions := r.db.
+				Where("event_id = ?", kw).
+				Or(keywordTextCondition("event_id"), like).
+				Or(keywordTextCondition("resource_type"), like).
+				Or(keywordTextCondition("resource_id"), like).
+				Or(keywordTextCondition("action"), like).
+				Or(keywordTextCondition("category"), like).
+				Or(keywordTextCondition("trace_id"), like).
+				Or(keywordTextCondition("request_id"), like).
+				Or(keywordTextCondition("tenant_id"), like).
+				Or("actor_id IN (?)", actorSubQuery).
+				Or("iam_principal_id IN (?)", principalSubQuery).
+				Or("resource_type IN ? AND resource_id IN (?)", iamPrincipalResourceTypes, principalTextSubQuery)
+			if parsedID, err := strconv.ParseInt(kw, 10, 64); err == nil {
+				conditions = conditions.
+					Or("actor_id = ?", parsedID).
+					Or("iam_principal_id = ?", parsedID).
+					Or("resource_type IN ? AND resource_id = ?", iamPrincipalResourceTypes, strconv.FormatInt(parsedID, 10))
+			}
+			db = db.Where(conditions)
+		}
+	}
+
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	var logs []*AuditLog
+	if err := db.Order("COALESCE(occurred_at, created_at) DESC").
+		Offset(query.Offset()).
+		Limit(query.PageSize).
+		Find(&logs).Error; err != nil {
+		return nil, 0, err
+	}
+	return logs, total, nil
+}
+
+// FindByID 查询单条记录（包含 changes、metadata、actor_user_agent 等完整字段）
+func (r *auditRepository) FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AuditLog, error) {
+	db := database.GetDB(ctx, r.db).Model(&AuditLog{}).
+		Select(
+			"id", "event_id", "occurred_at", "trace_id", "request_id",
+			"actor_type", "actor_id", "actor_ip", "actor_user_agent",
+			"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+			"action", "category", "risk_level",
+			"resource_type", "resource_id",
+			"product_code", "tenant_id",
+			"changes", "metadata",
+			"is_success", "error_message",
+			"created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, auditLogScopeBinding, principalID)
+	if err != nil {
+		return nil, err
+	}
+
+	var log AuditLog
+	if err := db.First(&log, "id = ?", id).Error; err != nil {
+		return nil, err
+	}
+	return &log, nil
+}
+
+// CountByCategory 按分类统计指定事件时间范围内的审计记录数量
+func (r *auditRepository) CountByCategory(ctx context.Context, from, to time.Time, scope iamscope.ScopeConstraint, principalID int64) ([]CategoryCount, error) {
+	var results []CategoryCount
+	db := database.GetDB(ctx, r.db).Model(&AuditLog{}).
+		Select("category", "COUNT(*) as count").
+		Where("COALESCE(occurred_at, created_at) BETWEEN ? AND ?", from, to)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, auditLogScopeBinding, principalID)
+	if err != nil {
+		return nil, err
+	}
+	err = db.
+		Group("category").
+		Order("count DESC").
+		Find(&results).Error
+	return results, err
+}
+
+// CountByRiskLevel 按风险级别统计指定事件时间范围内的审计记录数量
+func (r *auditRepository) CountByRiskLevel(ctx context.Context, from, to time.Time, scope iamscope.ScopeConstraint, principalID int64) ([]RiskLevelCount, error) {
+	var results []RiskLevelCount
+	db := database.GetDB(ctx, r.db).Model(&AuditLog{}).
+		Select("risk_level", "COUNT(*) as count").
+		Where("COALESCE(occurred_at, created_at) BETWEEN ? AND ?", from, to)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, auditLogScopeBinding, principalID)
+	if err != nil {
+		return nil, err
+	}
+	err = db.
+		Group("risk_level").
+		Order("count DESC").
+		Find(&results).Error
+	return results, err
+}
+
+// ---------------------------------------------------------------------------
+// OperationLogRepository — 操作日志仓储
+// ---------------------------------------------------------------------------
+
+// OperationLogRepository 操作日志仓储接口（先插入 started，再补齐 completed）
+type OperationLogRepository interface {
+	// Create 同步创建操作日志 started 记录
+	Create(ctx context.Context, log *OperationLog) error
+	// Complete 补齐操作日志完成态字段
+	Complete(ctx context.Context, id int64, entry CompleteOperationEntry, completedAt time.Time) error
+	// FindByQuery 分页查询操作日志
+	FindByQuery(ctx context.Context, query *AdminListOperationLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*OperationLog, int64, error)
+	// FindByID 根据 ID 查询单条操作日志
+	FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*OperationLog, error)
+}
+
+type operationLogRepository struct {
+	db          *gorm.DB
+	actorSearch ActorReferenceSearcher
+}
+
+// NewOperationLogRepository 构建操作日志仓储实例
+func NewOperationLogRepository(db *gorm.DB, actorSearch ActorReferenceSearcher) OperationLogRepository {
+	return &operationLogRepository{db: db, actorSearch: actorSearch}
+}
+
+// Create 同步创建操作日志 started 记录
+func (r *operationLogRepository) Create(ctx context.Context, log *OperationLog) error {
+	return database.GetDB(ctx, r.db).
+		Select(
+			"trace_id", "request_id",
+			"actor_type", "actor_id", "actor_ip", "actor_user_agent",
+			"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+			"operation_action", "operation_category", "risk_level", "source_module",
+			"http_method", "http_path",
+			"product_code", "tenant_id", "resource_type", "resource_id",
+			"is_success", "request_context", "operation_metadata", "record_status",
+		).
+		Create(log).Error
+}
+
+// Complete 补齐操作日志完成态字段
+func (r *operationLogRepository) Complete(ctx context.Context, id int64, entry CompleteOperationEntry, completedAt time.Time) error {
+	result := database.GetDB(ctx, r.db).
+		Table((OperationLog{}).TableName()).
+		Where("id = ? AND record_status = ?", id, operationRecordStatusStarted).
+		Updates(map[string]any{
+			"request_id":           entry.RequestID,
+			"iam_principal_id":     entry.IAMPrincipalID,
+			"iam_action":           entry.IAMAction,
+			"iam_resource":         entry.IAMResource,
+			"decision_allowed":     entry.DecisionAllowed,
+			"decision_reason_code": entry.DecisionReasonCode,
+			"decision_reason_kind": entry.DecisionReasonKind,
+			"http_status":          entry.HTTPStatus,
+			"duration_ms":          entry.DurationMS,
+			"is_success":           entry.IsSuccess,
+			"error_message":        normalizeAuditErrorMessage(entry.ErrorMessage),
+			"response_context":     entry.ResponseContext,
+			"policy_violation":     entry.PolicyViolation,
+			"record_status":        operationRecordStatusCompleted,
+			"completed_at":         completedAt,
+		})
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+// FindByQuery 分页查询操作日志，列表不返回 JSON 证据载荷。
+func (r *operationLogRepository) FindByQuery(ctx context.Context, query *AdminListOperationLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*OperationLog, int64, error) {
+	db := database.GetDB(ctx, r.db).Model(&OperationLog{}).
+		Select(
+			"id", "trace_id", "request_id",
+			"actor_type", "actor_id", "actor_ip",
+			"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+			"operation_action", "operation_category", "risk_level", "source_module",
+			"iam_action", "iam_resource", "decision_allowed", "decision_reason_code", "decision_reason_kind",
+			"http_method", "http_path", "http_status", "duration_ms",
+			"product_code", "tenant_id", "resource_type", "resource_id",
+			"is_success", "error_message", "record_status", "completed_at", "created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, operationLogScopeBinding, principalID)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	if query.PrincipalID != nil {
+		db = db.Where("iam_principal_id = ?", *query.PrincipalID)
+	}
+	if query.ActorID != nil {
+		db = db.Where("actor_id = ?", *query.ActorID)
+	}
+	if query.OperationAction != nil && *query.OperationAction != "" {
+		db = db.Where("operation_action = ?", *query.OperationAction)
+	}
+	if query.OperationCategory != nil && *query.OperationCategory != "" {
+		db = db.Where("operation_category = ?", *query.OperationCategory)
+	}
+	if query.RiskLevel != nil && *query.RiskLevel != "" {
+		db = db.Where("risk_level = ?", *query.RiskLevel)
+	}
+	if query.IAMAction != nil && *query.IAMAction != "" {
+		db = db.Where("iam_action = ?", *query.IAMAction)
+	}
+	if query.ResourceType != nil && *query.ResourceType != "" {
+		db = db.Where("resource_type = ?", *query.ResourceType)
+	}
+	if query.ResourceID != nil && *query.ResourceID != "" {
+		db = db.Where("resource_id = ?", *query.ResourceID)
+	}
+	if query.HTTPMethod != nil && *query.HTTPMethod != "" {
+		db = db.Where("http_method = ?", *query.HTTPMethod)
+	}
+	if query.HTTPStatus != nil {
+		db = db.Where("http_status = ?", *query.HTTPStatus)
+	}
+	if query.ProductCode != nil && *query.ProductCode != "" {
+		db = db.Where("product_code = ?", *query.ProductCode)
+	}
+	if query.TenantID != nil && *query.TenantID != "" {
+		db = db.Where("tenant_id = ?", *query.TenantID)
+	}
+	if query.IsSuccess != nil {
+		db = db.Where("is_success = ?", *query.IsSuccess)
+	}
+	if query.RecordStatus != nil && *query.RecordStatus != "" {
+		db = db.Where("record_status = ?", *query.RecordStatus)
+	}
+	if query.DateFrom != nil {
+		db = db.Where("created_at >= ?", *query.DateFrom)
+	}
+	if query.DateTo != nil {
+		db = db.Where("created_at <= ?", *query.DateTo)
+	}
+	if query.RequestID != nil && *query.RequestID != "" {
+		db = db.Where("request_id = ?", *query.RequestID)
+	}
+	if query.TraceID != nil && *query.TraceID != "" {
+		db = db.Where("trace_id = ?", *query.TraceID)
+	}
+	if query.Keyword != nil {
+		if kw, like, ok := normalizeKeyword(*query.Keyword); ok {
+			matches, err := r.actorSearch.Search(ctx, kw)
+			if err != nil {
+				return nil, 0, err
+			}
+			actorSubQuery := matches.ActorIDs
+			principalSubQuery := matches.PrincipalIDs
+			principalTextSubQuery := make([]string, len(matches.PrincipalIDs))
+			for i, id := range matches.PrincipalIDs {
+				principalTextSubQuery[i] = strconv.FormatInt(id, 10)
+			}
+			conditions := r.db.
+				Where(keywordTextCondition("http_path"), like).
+				Or(keywordTextCondition("resource_type"), like).
+				Or(keywordTextCondition("resource_id"), like).
+				Or(keywordTextCondition("trace_id"), like).
+				Or(keywordTextCondition("request_id"), like).
+				Or(keywordTextCondition("tenant_id"), like).
+				Or(keywordTextCondition("iam_action"), like).
+				Or(keywordTextCondition("source_module"), like).
+				Or(keywordTextCondition("operation_action"), like).
+				Or(keywordTextCondition("operation_category"), like).
+				Or(keywordTextCondition("actor_ip"), like).
+				Or("actor_id IN (?)", actorSubQuery).
+				Or("iam_principal_id IN (?)", principalSubQuery).
+				Or("resource_type IN ? AND resource_id IN (?)", iamPrincipalResourceTypes, principalTextSubQuery)
+			if parsedID, parseErr := strconv.ParseInt(kw, 10, 64); parseErr == nil {
+				conditions = conditions.
+					Or("actor_id = ?", parsedID).
+					Or("iam_principal_id = ?", parsedID).
+					Or("resource_type IN ? AND resource_id = ?", iamPrincipalResourceTypes, strconv.FormatInt(parsedID, 10))
+			}
+			db = db.Where(conditions)
+		}
+	}
+
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	var logs []*OperationLog
+	if err := db.Order("created_at DESC, id DESC").
+		Offset(query.Offset()).
+		Limit(query.PageSize).
+		Find(&logs).Error; err != nil {
+		return nil, 0, err
+	}
+	return logs, total, nil
+}
+
+// FindByID 查询单条操作日志（包含完整 JSON 证据载荷）
+func (r *operationLogRepository) FindByID(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*OperationLog, error) {
+	db := database.GetDB(ctx, r.db).Model(&OperationLog{}).
+		Select(
+			"id", "trace_id", "request_id",
+			"actor_type", "actor_id", "actor_ip", "actor_user_agent",
+			"auth_subject_type", "iam_principal_id", "credential_public_id", "token_fingerprint", "auth_mechanism",
+			"operation_action", "operation_category", "risk_level", "source_module",
+			"iam_action", "iam_resource", "decision_allowed", "decision_reason_code", "decision_reason_kind",
+			"http_method", "http_path", "http_status", "duration_ms",
+			"product_code", "tenant_id", "resource_type", "resource_id",
+			"is_success", "error_message",
+			"request_context", "response_context", "operation_metadata", "policy_violation",
+			"record_status", "completed_at", "created_at",
+		)
+	var err error
+	db, err = iamscope.ApplyScope(db, scope, operationLogScopeBinding, principalID)
+	if err != nil {
+		return nil, err
+	}
+
+	var log OperationLog
+	if err := db.First(&log, "id = ?", id).Error; err != nil {
+		return nil, err
+	}
+	return &log, nil
+}