@stackonward/cli 0.0.1 → 1.0.1

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

@@ -0,0 +1,770 @@
+package audit
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"go.uber.org/zap"
+	"gorm.io/datatypes"
+	"gorm.io/gorm"
+
+	"{{module}}/internal/common/iamscope"
+	"{{module}}/pkg/apierror"
+)
+
+// ---------------------------------------------------------------------------
+// 写入服务接口
+// ---------------------------------------------------------------------------
+
+// AuditService 审计写入服务（三缓冲区异步批量写入）
+type AuditService interface {
+	// LogAccess 异步写入访问日志条目（L1 中间件调用）
+	LogAccess(ctx context.Context, entry AccessEntry)
+	// LogAudit 异步写入审计日志条目（L2 EventBus 非认证事件 + L3 Enrich）
+	LogAudit(ctx context.Context, entry AuditEntry)
+	// LogLogin 异步写入登录日志条目（L2 EventBus 认证事件）
+	LogLogin(ctx context.Context, entry LoginEntry)
+	// LogSync 同步写入审计条目（用于 critical 级别操作）
+	LogSync(ctx context.Context, entry AuditEntry) error
+	// ProjectEventSync 同步、幂等地把来源事件投影为审计条目。
+	ProjectEventSync(ctx context.Context, sourceEventID string, eventName string, entry AuditEntry) error
+	// BeginOperation 同步创建操作日志 started 记录
+	BeginOperation(ctx context.Context, entry BeginOperationEntry) (int64, error)
+	// CompleteOperation 同步补齐操作日志 completed 记录
+	CompleteOperation(ctx context.Context, operationLogID int64, entry CompleteOperationEntry) error
+	// Flush 手动 flush 全部 buffer
+	Flush(ctx context.Context) error
+	// Stop 优雅关闭
+	Stop()
+}
+
+// ---------------------------------------------------------------------------
+// 查询服务接口
+// ---------------------------------------------------------------------------
+
+// AuditQueryService 审计只读查询服务
+type AuditQueryService interface {
+	// ListAccessLogs 分页查询访问日志
+	ListAccessLogs(ctx context.Context, req *AdminListAccessLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AccessLog, int64, error)
+	// GetAccessLog 查询单条访问日志详情
+	GetAccessLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AccessLog, error)
+	// ListAuditLogs 分页查询审计日志
+	ListAuditLogs(ctx context.Context, req *AdminListAuditLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AuditLog, int64, error)
+	// GetAuditLog 查询单条审计日志详情
+	GetAuditLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AuditLog, error)
+	// ListOperationLogs 分页查询操作日志
+	ListOperationLogs(ctx context.Context, req *AdminListOperationLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*OperationLog, int64, error)
+	// GetOperationLog 查询单条操作日志详情
+	GetOperationLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*OperationLog, error)
+	// ListLoginLogs 分页查询登录日志
+	ListLoginLogs(ctx context.Context, req *AdminListLoginLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*LoginLog, int64, error)
+	// GetLoginLog 查询单条登录日志详情
+	GetLoginLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*LoginLog, error)
+	// CountFailedLoginsByIP 统计指定 IP 的失败登录次数
+	CountFailedLoginsByIP(ctx context.Context, ip string, since time.Time) (int64, error)
+	// GetAuditStats 获取审计统计
+	GetAuditStats(ctx context.Context, from, to time.Time, scope iamscope.ScopeConstraint, principalID int64) (*StatsResponse, error)
+}
+
+// ---------------------------------------------------------------------------
+// 常量
+// ---------------------------------------------------------------------------
+
+const (
+	// accessBufferCap 访问日志 buffer 容量（L1 高频）
+	accessBufferCap = 1024
+	// auditBufferCap 审计日志 buffer 容量
+	auditBufferCap = 512
+	// loginBufferCap 登录日志 buffer 容量（最低频）
+	loginBufferCap = 128
+	// flushInterval 定期 flush 间隔
+	flushInterval = 5 * time.Second
+	// batchSize 单次 flush 最大条数
+	batchSize = 100
+	// dropWarnInterval 控制缓冲区溢出告警频率
+	dropWarnInterval = time.Minute
+	// synchronousAuditWriteTimeout 高风险审计同步写入的独立超时。
+	synchronousAuditWriteTimeout = 5 * time.Second
+	// auditErrorMessageMaxLength 对齐 sys_access_logs/sys_audit_logs.error_message 字段长度。
+	auditErrorMessageMaxLength = 500
+)
+
+// ---------------------------------------------------------------------------
+// 写入服务实现
+// ---------------------------------------------------------------------------
+
+// auditService 三缓冲区异步写入实现
+type auditService struct {
+	accessRepo    AccessLogRepository
+	auditRepo     AuditRepository
+	loginRepo     LoginLogRepository
+	operationRepo OperationLogRepository
+	txManager     AuditTransactionManager
+	accessPolicy  AccessLogPolicy
+	logger        *zap.Logger
+
+	accessBuffer chan AccessEntry
+	auditBuffer  chan AuditEntry
+	loginBuffer  chan LoginEntry
+
+	accessDrop auditDropState
+	auditDrop  auditDropState
+	loginDrop  auditDropState
+
+	wg     sync.WaitGroup
+	stopCh chan struct{}
+}
+
+type auditDropState struct {
+	dropped        atomic.Int64
+	lastWarnUnixNs atomic.Int64
+}
+
+// NewAuditService 构建 AuditService，启动三个独立 flush goroutine
+func NewAuditService(
+	accessRepo AccessLogRepository,
+	auditRepo AuditRepository,
+	loginRepo LoginLogRepository,
+	operationRepo OperationLogRepository,
+	txManager AuditTransactionManager,
+	accessPolicy AccessLogPolicy,
+	logger *zap.Logger,
+) AuditService {
+	svc := &auditService{
+		accessRepo:    accessRepo,
+		auditRepo:     auditRepo,
+		loginRepo:     loginRepo,
+		operationRepo: operationRepo,
+		txManager:     txManager,
+		accessPolicy:  accessPolicy,
+		logger:        logger.Named("AuditService"),
+		accessBuffer:  make(chan AccessEntry, accessBufferCap),
+		auditBuffer:   make(chan AuditEntry, auditBufferCap),
+		loginBuffer:   make(chan LoginEntry, loginBufferCap),
+		stopCh:        make(chan struct{}),
+	}
+	svc.wg.Add(3)
+	go svc.flushAccessLoop()
+	go svc.flushAuditLoop()
+	go svc.flushLoginLoop()
+	return svc
+}
+
+// LogAccess 异步写入访问日志，高频成功读请求由策略降采样。
+func (s *auditService) LogAccess(_ context.Context, entry AccessEntry) {
+	if !s.accessPolicy.ShouldRecord(entry) {
+		return
+	}
+	select {
+	case s.accessBuffer <- entry:
+	default:
+		s.warnDropped(&s.accessDrop, "access",
+			zap.String("method", entry.HTTPMethod),
+			zap.String("path", entry.HTTPPath),
+		)
+	}
+}
+
+// LogAudit 写入审计日志；高风险 IAM 治理事件同步落库，其余事件进入异步缓冲。
+func (s *auditService) LogAudit(ctx context.Context, entry AuditEntry) {
+	if shouldWriteAuditSynchronously(entry) {
+		writeCtx, cancel := detachedAuditWriteContext(ctx)
+		defer cancel()
+		if err := s.LogSync(writeCtx, entry); err != nil {
+			s.logger.Error("write synchronous audit log failed",
+				zap.String("action", string(entry.Action)),
+				zap.String("category", string(entry.Category)),
+				zap.String("riskLevel", string(entry.RiskLevel)),
+				zap.String("resourceType", entry.ResourceType),
+				zap.Int64("actorId", entry.ActorID.Int64()),
+				zap.Error(err),
+			)
+		}
+		return
+	}
+	select {
+	case s.auditBuffer <- entry:
+	default:
+		if entry.RiskLevel == RiskLevelCritical || entry.RiskLevel == RiskLevelHigh {
+			writeCtx, cancel := detachedAuditWriteContext(ctx)
+			defer cancel()
+			if err := s.auditRepo.BatchCreate(writeCtx, []*AuditLog{toAuditLog(entry)}); err != nil {
+				s.logger.Error("write high risk audit log failed",
+					zap.String("action", string(entry.Action)),
+					zap.String("category", string(entry.Category)),
+					zap.String("riskLevel", string(entry.RiskLevel)),
+					zap.Int64("actorId", entry.ActorID.Int64()),
+					zap.Error(err),
+				)
+			}
+			return
+		}
+		s.warnDropped(&s.auditDrop, "audit",
+			zap.String("action", string(entry.Action)),
+			zap.String("category", string(entry.Category)),
+			zap.String("riskLevel", string(entry.RiskLevel)),
+		)
+	}
+}
+
+func shouldWriteAuditSynchronously(entry AuditEntry) bool {
+	if entry.RiskLevel != RiskLevelCritical && entry.RiskLevel != RiskLevelHigh {
+		return false
+	}
+	switch AuditResource(entry.ResourceType) {
+	case AuditResourceIAMPolicy,
+		AuditResourceIAMPrincipal,
+		AuditResourceIAMServiceAccount,
+		AuditResourceIAMCredential,
+		AuditResourceIAMCredentialTrust,
+		AuditResourceIAMRole,
+		AuditResourceIAMGroup,
+		AuditResourceIAMBinding,
+		AuditResourceIAMPageAction,
+		AuditResourceOutboxEvent:
+		return true
+	default:
+		return false
+	}
+}
+
+func detachedAuditWriteContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return context.WithTimeout(context.WithoutCancel(ctx), synchronousAuditWriteTimeout)
+}
+
+// LogLogin 异步写入登录日志，缓冲区满时按频率聚合告警。
+func (s *auditService) LogLogin(_ context.Context, entry LoginEntry) {
+	select {
+	case s.loginBuffer <- entry:
+	default:
+		s.warnDropped(&s.loginDrop, "login",
+			zap.String("loginAction", string(entry.LoginAction)),
+		)
+	}
+}
+
+func (s *auditService) warnDropped(state *auditDropState, buffer string, fields ...zap.Field) {
+	dropped := state.dropped.Add(1)
+	now := time.Now().UnixNano()
+	last := state.lastWarnUnixNs.Load()
+	if now-last < int64(dropWarnInterval) {
+		return
+	}
+	if !state.lastWarnUnixNs.CompareAndSwap(last, now) {
+		return
+	}
+	allFields := []zap.Field{
+		zap.String("buffer", buffer),
+		zap.Int64("suppressed", dropped),
+	}
+	allFields = append(allFields, fields...)
+	s.logger.Warn("audit buffer overflow", allFields...)
+}
+
+// LogSync 同步写入审计条目（绕过 buffer，直接写库）
+func (s *auditService) LogSync(ctx context.Context, entry AuditEntry) error {
+	log := toAuditLog(entry)
+	if log.EventID != nil {
+		if *log.EventID == "" || log.OccurredAt == nil {
+			return fmt.Errorf("event audit requires event_id and occurred_at")
+		}
+		return s.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+			claimed, err := s.auditRepo.ClaimEventAudit(txCtx, &AuditEventInbox{
+				EventID:     *log.EventID,
+				OccurredAt:  *log.OccurredAt,
+				ProcessedAt: time.Now().UTC(),
+			})
+			if err != nil || !claimed {
+				return err
+			}
+			return s.auditRepo.BatchCreate(txCtx, []*AuditLog{log})
+		})
+	}
+	return s.auditRepo.BatchCreate(ctx, []*AuditLog{log})
+}
+
+// ProjectEventSync 将来源事件幂等键与审计事实放在同一事务中持久化。
+func (s *auditService) ProjectEventSync(
+	ctx context.Context,
+	sourceEventID string,
+	eventName string,
+	entry AuditEntry,
+) error {
+	if strings.TrimSpace(sourceEventID) == "" || strings.TrimSpace(eventName) == "" {
+		return errors.New("audit event projection identity is required")
+	}
+	entry.EventID = strings.TrimSpace(sourceEventID)
+	return s.LogSync(ctx, entry)
+}
+
+// BeginOperation 同步创建控制面操作 started 记录。
+func (s *auditService) BeginOperation(ctx context.Context, entry BeginOperationEntry) (int64, error) {
+	log := toOperationLog(entry)
+	if err := s.operationRepo.Create(ctx, log); err != nil {
+		return 0, err
+	}
+	return log.ID, nil
+}
+
+// CompleteOperation 同步补齐控制面操作 completed 记录。
+func (s *auditService) CompleteOperation(ctx context.Context, operationLogID int64, entry CompleteOperationEntry) error {
+	completedAt := time.Now().UTC()
+	if err := s.operationRepo.Complete(ctx, operationLogID, entry, completedAt); err != nil {
+		s.logger.Error("operation log completion failed",
+			zap.String("event", "audit.operation.complete"),
+			zap.String("table", (OperationLog{}).TableName()),
+			zap.String("outcome", "failed"),
+			zap.String("errorKind", operationCompletionErrorKind(err)),
+			zap.String("expectedRecordStatus", operationRecordStatusStarted),
+			zap.Int64("operationLogId", operationLogID),
+			zap.String("requestId", entry.RequestID),
+			zap.Int("httpStatus", int(entry.HTTPStatus)),
+			zap.Bool("isSuccess", entry.IsSuccess),
+			zap.Error(err),
+		)
+		return err
+	}
+	return nil
+}
+
+func operationCompletionErrorKind(err error) string {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return "not_started_or_already_completed"
+	}
+	return "write_failed"
+}
+
+// Flush 手动 flush 全部 buffer
+func (s *auditService) Flush(ctx context.Context) error {
+	var firstErr error
+	if err := s.flushAccess(ctx); err != nil && firstErr == nil {
+		firstErr = err
+	}
+	if err := s.flushAudit(ctx); err != nil && firstErr == nil {
+		firstErr = err
+	}
+	if err := s.flushLogin(ctx); err != nil && firstErr == nil {
+		firstErr = err
+	}
+	return firstErr
+}
+
+// Stop 优雅关闭：通知三个 flush goroutine 停止并等待完成
+func (s *auditService) Stop() {
+	close(s.stopCh)
+	s.wg.Wait()
+}
+
+// ---------------------------------------------------------------------------
+// flush goroutine 循环
+// ---------------------------------------------------------------------------
+
+func (s *auditService) flushAccessLoop() {
+	defer s.wg.Done()
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			_ = s.flushAccess(context.Background()) //nolint:errcheck // 定时 flush 失败已在 flushAccess 内部记录日志
+		case <-s.stopCh:
+			_ = s.flushAccess(context.Background()) //nolint:errcheck // 关闭时 best-effort flush
+			return
+		}
+	}
+}
+
+func (s *auditService) flushAuditLoop() {
+	defer s.wg.Done()
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			_ = s.flushAudit(context.Background()) //nolint:errcheck // 定时 flush 失败已在 flushAudit 内部记录日志
+		case <-s.stopCh:
+			_ = s.flushAudit(context.Background()) //nolint:errcheck // 关闭时 best-effort flush
+			return
+		}
+	}
+}
+
+func (s *auditService) flushLoginLoop() {
+	defer s.wg.Done()
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			_ = s.flushLogin(context.Background()) //nolint:errcheck // 定时 flush 失败已在 flushLogin 内部记录日志
+		case <-s.stopCh:
+			_ = s.flushLogin(context.Background()) //nolint:errcheck // 关闭时 best-effort flush
+			return
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// flush 实现（drain buffer → batch insert）
+// ---------------------------------------------------------------------------
+
+func (s *auditService) flushAccess(ctx context.Context) error {
+	entries := drainChannel(s.accessBuffer, batchSize)
+	if len(entries) == 0 {
+		return nil
+	}
+	logs := make([]*AccessLog, 0, len(entries))
+	for i := range entries {
+		logs = append(logs, toAccessLog(entries[i]))
+	}
+	if err := s.accessRepo.BatchCreate(ctx, logs); err != nil {
+		s.logger.Error("flush access logs failed",
+			zap.Error(err),
+			zap.Int("count", len(logs)),
+		)
+		return err
+	}
+	s.logger.Debug("access logs flushed", zap.Int("count", len(logs)))
+	return nil
+}
+
+func (s *auditService) flushAudit(ctx context.Context) error {
+	entries := drainChannel(s.auditBuffer, batchSize)
+	if len(entries) == 0 {
+		return nil
+	}
+	logs := make([]*AuditLog, 0, len(entries))
+	for i := range entries {
+		logs = append(logs, toAuditLog(entries[i]))
+	}
+	if err := s.auditRepo.BatchCreate(ctx, logs); err != nil {
+		s.logger.Error("flush audit logs failed",
+			zap.Error(err),
+			zap.Int("count", len(logs)),
+		)
+		return err
+	}
+	s.logger.Debug("audit logs flushed", zap.Int("count", len(logs)))
+	return nil
+}
+
+func (s *auditService) flushLogin(ctx context.Context) error {
+	entries := drainChannel(s.loginBuffer, batchSize)
+	if len(entries) == 0 {
+		return nil
+	}
+	logs := make([]*LoginLog, 0, len(entries))
+	for i := range entries {
+		logs = append(logs, toLoginLog(entries[i]))
+	}
+	if err := s.loginRepo.BatchCreate(ctx, logs); err != nil {
+		s.logger.Error("flush login logs failed",
+			zap.Error(err),
+			zap.Int("count", len(logs)),
+		)
+		return err
+	}
+	s.logger.Debug("login logs flushed", zap.Int("count", len(logs)))
+	return nil
+}
+
+// drainChannel 从 channel 中非阻塞读取最多 limit 条数据
+func drainChannel[T any](ch <-chan T, limit int) []T {
+	var items []T
+	for {
+		select {
+		case item := <-ch:
+			items = append(items, item)
+			if len(items) >= limit {
+				return items
+			}
+		default:
+			return items
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// 转换函数：Entry → Model
+// ---------------------------------------------------------------------------
+
+// toAccessLog 将 AccessEntry 转换为 AccessLog。
+func toAccessLog(e AccessEntry) *AccessLog {
+	return &AccessLog{
+		TraceID:            e.TraceID,
+		RequestID:          e.RequestID,
+		ActorType:          e.ActorType,
+		ActorID:            e.ActorID,
+		AuthSubjectType:    e.AuthSubjectType,
+		IAMPrincipalID:     e.IAMPrincipalID,
+		CredentialPublicID: e.CredentialPublicID,
+		TokenFingerprint:   e.TokenFingerprint,
+		AuthMechanism:      e.AuthMechanism,
+		ActorIP:            e.ActorIP,
+		ActorUserAgent:     e.ActorUserAgent,
+		HTTPMethod:         e.HTTPMethod,
+		HTTPPath:           e.HTTPPath,
+		HTTPStatus:         e.HTTPStatus,
+		ProductCode:        e.ProductCode,
+		ResourceType:       e.ResourceType,
+		ResourceID:         e.ResourceID,
+		IsSuccess:          e.IsSuccess,
+		ErrorMessage:       normalizeAuditErrorMessage(e.ErrorMessage),
+		DurationMS:         e.DurationMS,
+	}
+}
+
+// toAuditLog 将 AuditEntry 转换为 AuditLog（含 JSON 序列化）
+func toAuditLog(e AuditEntry) *AuditLog {
+	log := &AuditLog{
+		TraceID:            e.TraceID,
+		RequestID:          e.RequestID,
+		ActorType:          e.ActorType,
+		ActorID:            e.ActorID,
+		AuthSubjectType:    e.AuthSubjectType,
+		IAMPrincipalID:     e.IAMPrincipalID,
+		CredentialPublicID: e.CredentialPublicID,
+		TokenFingerprint:   e.TokenFingerprint,
+		AuthMechanism:      e.AuthMechanism,
+		ActorIP:            e.ActorIP,
+		ActorUserAgent:     e.ActorUserAgent,
+		Action:             e.Action,
+		Category:           e.Category,
+		RiskLevel:          e.RiskLevel,
+		ResourceType:       e.ResourceType,
+		ResourceID:         e.ResourceID,
+		ProductCode:        e.ProductCode,
+		TenantID:           e.TenantID,
+		IsSuccess:          e.IsSuccess,
+		ErrorMessage:       normalizeAuditErrorMessage(e.ErrorMessage),
+	}
+	if e.EventID != "" {
+		log.EventID = &e.EventID
+	}
+	if !e.OccurredAt.IsZero() {
+		occurredAt := e.OccurredAt.UTC()
+		log.OccurredAt = &occurredAt
+	}
+	if e.Changes != nil {
+		if b, err := json.Marshal(e.Changes); err == nil {
+			log.Changes = datatypes.JSON(b)
+		}
+	}
+	if e.Metadata != nil {
+		if b, err := json.Marshal(e.Metadata); err == nil {
+			log.Metadata = datatypes.JSON(b)
+		}
+	}
+	return log
+}
+
+// toOperationLog 将 BeginOperationEntry 转换为 OperationLog。
+func toOperationLog(e BeginOperationEntry) *OperationLog {
+	return &OperationLog{
+		TraceID:            e.TraceID,
+		RequestID:          e.RequestID,
+		ActorType:          e.ActorType,
+		ActorID:            e.ActorID,
+		AuthSubjectType:    e.AuthSubjectType,
+		IAMPrincipalID:     e.IAMPrincipalID,
+		CredentialPublicID: e.CredentialPublicID,
+		TokenFingerprint:   e.TokenFingerprint,
+		AuthMechanism:      e.AuthMechanism,
+		ActorIP:            e.ActorIP,
+		ActorUserAgent:     e.ActorUserAgent,
+		OperationAction:    e.OperationAction,
+		OperationCategory:  e.OperationCategory,
+		RiskLevel:          e.RiskLevel,
+		SourceModule:       e.SourceModule,
+		HTTPMethod:         e.HTTPMethod,
+		HTTPPath:           e.HTTPPath,
+		ProductCode:        e.ProductCode,
+		TenantID:           e.TenantID,
+		ResourceType:       e.ResourceType,
+		ResourceID:         e.ResourceID,
+		IsSuccess:          true,
+		RequestContext:     normalizeOperationJSON(e.RequestContext),
+		ResponseContext:    datatypes.JSON([]byte("{}")),
+		OperationMetadata:  normalizeOperationJSON(e.OperationMetadata),
+		PolicyViolation:    datatypes.JSON([]byte("{}")),
+		RecordStatus:       operationRecordStatusStarted,
+	}
+}
+
+func normalizeOperationJSON(value datatypes.JSON) datatypes.JSON {
+	if len(value) == 0 {
+		return datatypes.JSON([]byte("{}"))
+	}
+	return value
+}
+
+func normalizeAuditErrorMessage(value string) string {
+	if value == "" {
+		return ""
+	}
+	runes := []rune(value)
+	if len(runes) <= auditErrorMessageMaxLength {
+		return value
+	}
+	const suffix = "..."
+	return string(runes[:auditErrorMessageMaxLength-len(suffix)]) + suffix
+}
+
+// toLoginLog 将 LoginEntry 转换为 LoginLog（直接字段映射）
+func toLoginLog(e LoginEntry) *LoginLog {
+	return &LoginLog{
+		IdentityID:        e.IdentityID,
+		ActorType:         e.ActorType,
+		ActorIP:           e.ActorIP,
+		ActorUserAgent:    e.ActorUserAgent,
+		LoginAction:       e.LoginAction,
+		LoginMethod:       e.LoginMethod,
+		IsSuccess:         e.IsSuccess,
+		FailureReason:     e.FailureReason,
+		ProductCode:       e.ProductCode,
+		SessionID:         e.SessionID,
+		RequestID:         e.RequestID,
+		DeviceType:        e.DeviceType,
+		DeviceFingerprint: e.DeviceFingerprint,
+		OSName:            e.OSName,
+		BrowserName:       e.BrowserName,
+		GeoCountry:        e.GeoCountry,
+		GeoCity:           e.GeoCity,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// 查询服务实现
+// ---------------------------------------------------------------------------
+
+// auditQueryService 审计只读查询服务实现
+type auditQueryService struct {
+	accessRepo    AccessLogRepository
+	auditRepo     AuditRepository
+	loginRepo     LoginLogRepository
+	operationRepo OperationLogRepository
+	logger        *zap.Logger
+}
+
+// NewAuditQueryService 构建只读查询服务
+func NewAuditQueryService(
+	accessRepo AccessLogRepository,
+	auditRepo AuditRepository,
+	loginRepo LoginLogRepository,
+	operationRepo OperationLogRepository,
+	logger *zap.Logger,
+) AuditQueryService {
+	return &auditQueryService{
+		accessRepo:    accessRepo,
+		auditRepo:     auditRepo,
+		loginRepo:     loginRepo,
+		operationRepo: operationRepo,
+		logger:        logger.Named("AuditQueryService"),
+	}
+}
+
+// ListAccessLogs 分页查询访问日志
+func (s *auditQueryService) ListAccessLogs(ctx context.Context, req *AdminListAccessLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AccessLog, int64, error) {
+	return s.accessRepo.FindByQuery(ctx, req, scope, principalID)
+}
+
+// GetAccessLog 查询单条访问日志详情
+func (s *auditQueryService) GetAccessLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AccessLog, error) {
+	log, err := s.accessRepo.FindByID(ctx, id, scope, principalID)
+	if err != nil {
+		return nil, auditNotFoundOrError("access_log", id, err)
+	}
+	return log, nil
+}
+
+// ListAuditLogs 分页查询审计日志
+func (s *auditQueryService) ListAuditLogs(ctx context.Context, req *AdminListAuditLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*AuditLog, int64, error) {
+	return s.auditRepo.FindByQuery(ctx, req, scope, principalID)
+}
+
+// GetAuditLog 查询单条审计日志详情
+func (s *auditQueryService) GetAuditLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*AuditLog, error) {
+	log, err := s.auditRepo.FindByID(ctx, id, scope, principalID)
+	if err != nil {
+		return nil, auditNotFoundOrError("audit_log", id, err)
+	}
+	return log, nil
+}
+
+// ListOperationLogs 分页查询操作日志
+func (s *auditQueryService) ListOperationLogs(ctx context.Context, req *AdminListOperationLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*OperationLog, int64, error) {
+	return s.operationRepo.FindByQuery(ctx, req, scope, principalID)
+}
+
+// GetOperationLog 查询单条操作日志详情
+func (s *auditQueryService) GetOperationLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*OperationLog, error) {
+	log, err := s.operationRepo.FindByID(ctx, id, scope, principalID)
+	if err != nil {
+		return nil, auditNotFoundOrError("operation_log", id, err)
+	}
+	return log, nil
+}
+
+// ListLoginLogs 分页查询登录日志
+func (s *auditQueryService) ListLoginLogs(ctx context.Context, req *AdminListLoginLogsRequest, scope iamscope.ScopeConstraint, principalID int64) ([]*LoginLog, int64, error) {
+	return s.loginRepo.FindByQuery(ctx, req, scope, principalID)
+}
+
+// GetLoginLog 查询单条登录日志详情
+func (s *auditQueryService) GetLoginLog(ctx context.Context, id int64, scope iamscope.ScopeConstraint, principalID int64) (*LoginLog, error) {
+	log, err := s.loginRepo.FindByID(ctx, id, scope, principalID)
+	if err != nil {
+		return nil, auditNotFoundOrError("login_log", id, err)
+	}
+	return log, nil
+}
+
+// CountFailedLoginsByIP 统计指定 IP 的失败登录次数
+func (s *auditQueryService) CountFailedLoginsByIP(ctx context.Context, ip string, since time.Time) (int64, error) {
+	return s.loginRepo.CountFailedByIP(ctx, ip, since)
+}
+
+// GetAuditStats 获取审计统计（按分类 + 风险级别汇总）
+func (s *auditQueryService) GetAuditStats(ctx context.Context, from, to time.Time, scope iamscope.ScopeConstraint, principalID int64) (*StatsResponse, error) {
+	byCategory, err := s.auditRepo.CountByCategory(ctx, from, to, scope, principalID)
+	if err != nil {
+		s.logger.Error("count by category failed", zap.Error(err))
+		return nil, err
+	}
+
+	byRiskLevel, err := s.auditRepo.CountByRiskLevel(ctx, from, to, scope, principalID)
+	if err != nil {
+		s.logger.Error("count by risk level failed", zap.Error(err))
+		return nil, err
+	}
+
+	var total int64
+	for _, item := range byCategory {
+		total += item.Count
+	}
+
+	resp := &StatsResponse{
+		Total:       total,
+		ByCategory:  byCategory,
+		ByRiskLevel: byRiskLevel,
+	}
+	resp.Period.From = from
+	resp.Period.To = to
+	return resp, nil
+}
+
+func auditNotFoundOrError(resource string, id int64, err error) error {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return apierror.NotFound(resource, id)
+	}
+	return err
+}