@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/outbox/relay.go

@@ -0,0 +1,1138 @@
+package outbox
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/stdlib"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"{{module}}/internal/core/database"
+	"{{module}}/internal/core/eventbus"
+	"{{module}}/internal/core/eventstream"
+	"{{module}}/internal/core/queue"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 跨进程事件常量
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// TaskTypeEventRelay Asynq 跨进程事件转发任务类型
+	TaskTypeEventRelay = "event:relay"
+	// QueueEvents 跨进程事件转发专用队列
+	QueueEvents = "events"
+	// defaultRelayMaxRetries Relay 默认最大重试次数
+	defaultRelayMaxRetries = 10
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 跨进程事件载荷
+// ═══════════════════════════════════════════════════════════════
+
+// CrossProcessEventPayload Asynq 跨进程事件载荷
+type CrossProcessEventPayload struct {
+	// OutboxRef 是来源 outbox 记录引用。
+	OutboxRef string `json:"outbox_ref"`
+	// 事件类型
+	EventType string `json:"event_type"`
+	// 聚合根类型
+	AggregateType string `json:"aggregate_type"`
+	// 聚合根 ID
+	AggregateID string `json:"aggregate_id"`
+	// AggregateVersion 聚合版本；没有版本合同的事件不传该字段。
+	AggregateVersion *int64 `json:"aggregate_version,omitempty"`
+	// SourceProductCode 是事件来源产品；平台来源事件为空。
+	SourceProductCode string `json:"source_product_code,omitempty"`
+	// AudienceScope 是事件创建时冻结的受众范围。
+	AudienceScope AudienceScope `json:"audience_scope"`
+	// AudienceProductCodes 是 products 受众的有序 Product 集合。
+	AudienceProductCodes []string `json:"audience_product_codes"`
+	// 事件载荷（原始 JSON）
+	Payload json.RawMessage `json:"payload"`
+	// 事件元数据（原始 JSON）
+	Metadata json.RawMessage `json:"metadata"`
+	// 审计变更信封（原始 JSON）
+	AuditChanges json.RawMessage `json:"audit_changes,omitempty"`
+	// 审计元信息信封（原始 JSON）
+	AuditMeta json.RawMessage `json:"audit_meta,omitempty"`
+	// 事件发生时间
+	OccurredAt time.Time `json:"occurred_at"`
+	// 事件唯一标识
+	EventID string `json:"event_id"`
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Relay 配置
+// ═══════════════════════════════════════════════════════════════
+
+// RelayConfig Outbox Relay 配置
+type RelayConfig struct {
+	// 轮询间隔（默认 2s）
+	PollInterval time.Duration
+	// 每次批量处理大小（默认 100）
+	BatchSize int
+	// 锁超时时间，超时后回收（默认 5m）
+	LockTimeout time.Duration
+	// 最大重试次数（默认 10）
+	MaxRetries int
+	// 清理已处理事件的间隔（默认 1h）
+	CleanupInterval time.Duration
+	// 已处理事件保留时长（默认 72h）
+	RetentionDuration time.Duration
+	// 需要投递到 Asynq 跨进程任务的事件类型模式（支持通配符：identity.* 匹配 identity.created）
+	AsynqEventPatterns []string
+	// 需要投递到 Redis Stream 的事件类型模式（支持通配符：identity.* 匹配 identity.created）
+	RedisStreamEventPatterns []string
+	// 限定本 Relay 实例只处理的聚合类型（为空表示处理所有类型）
+	// 多服务共享同一 outbox 表时，通过此字段实现事件路由隔离（类似 Kafka topic partition）
+	AggregateTypes []string
+	// 必须持续重试的合规关键事件类型模式；失败时使用封顶退避而不进入死信。
+	PersistentRetryEvents []string
+	// 事件载荷反序列化函数（将 JSON 还原为具体 struct 指针，供 EventBus 消费方使用）
+	//
+	// 返回 (payload, nil) 表示成功；返回 (nil, err) 表示未注册事件类型或 JSON 格式错误，
+	// Relay 侧必须按错误路径处理（记录 Outbox 重试或 DLQ），禁止退化成 map[string]any。
+	PayloadDeserializer func(eventType string, data []byte) (any, error)
+	// 当前 Relay 实例标识（默认自动生成）
+	RelayID string
+}
+
+// DefaultRelayConfig 返回默认 Relay 配置
+func DefaultRelayConfig() RelayConfig {
+	return RelayConfig{
+		PollInterval:      2 * time.Second,
+		BatchSize:         100,
+		LockTimeout:       5 * time.Minute,
+		MaxRetries:        defaultRelayMaxRetries,
+		CleanupInterval:   time.Hour,
+		RetentionDuration: 72 * time.Hour,
+		RelayID:           generateRelayID(),
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Relay 核心结构
+// ═══════════════════════════════════════════════════════════════
+
+// Relay Outbox 事件中继器
+//
+// 从 sys_outbox_events 表轮询待处理事件，分发到本地 EventBus，
+// 可选转发到 Asynq 实现跨进程事件传递。
+// 支持 PostgreSQL LISTEN/NOTIFY 低延迟唤醒。
+type Relay struct {
+	db              *gorm.DB
+	logger          *zap.Logger
+	eventBus        *eventbus.EventBus
+	queueClient     *queue.Client
+	streamPublisher eventstream.EventStreamPublisher // nil 表示不启用 Stream 分发
+	txManager       *database.TransactionManager
+	config          RelayConfig
+	wakeup          chan struct{}
+	done            chan struct{}
+	wg              sync.WaitGroup
+}
+
+// NewRelay 创建 Outbox Relay 实例
+//
+// streamPublisher 可传 nil，表示不启用 Redis Stream 分发通道。
+func NewRelay(
+	db *gorm.DB,
+	logger *zap.Logger,
+	eventBus *eventbus.EventBus,
+	queueClient *queue.Client,
+	streamPublisher eventstream.EventStreamPublisher,
+	config RelayConfig,
+) *Relay {
+	if config.RelayID == "" {
+		config.RelayID = generateRelayID()
+	}
+	return &Relay{
+		db:              db,
+		logger:          logger.Named("OutboxRelay"),
+		eventBus:        eventBus,
+		queueClient:     queueClient,
+		streamPublisher: streamPublisher,
+		txManager:       database.NewTransactionManager(db),
+		config:          config,
+		wakeup:          make(chan struct{}, 1),
+		done:            make(chan struct{}),
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 生命周期
+// ═══════════════════════════════════════════════════════════════
+
+// Start 启动 Relay 后台 goroutine（轮询 + 维护 + LISTEN/NOTIFY）
+func (r *Relay) Start(ctx context.Context) {
+	r.wg.Add(1)
+	go r.runPollLoop(ctx)
+
+	r.wg.Add(1)
+	go r.runMaintenanceLoop(ctx)
+
+	r.wg.Add(1)
+	go r.listenNotify(ctx)
+
+	r.logger.Info("outbox relay started",
+		zap.String("relayId", r.config.RelayID),
+		zap.Duration("pollInterval", r.config.PollInterval),
+		zap.Int("batchSize", r.config.BatchSize),
+		zap.Strings("aggregateTypes", r.config.AggregateTypes),
+		zap.Strings("asynqEventPatterns", r.config.AsynqEventPatterns),
+		zap.Strings("redisStreamEventPatterns", r.config.RedisStreamEventPatterns),
+	)
+}
+
+// Stop 优雅关闭 Relay，等待所有 goroutine 退出
+func (r *Relay) Stop() {
+	close(r.done)
+	r.wg.Wait()
+	r.logger.Info("outbox relay stopped", zap.String("relayId", r.config.RelayID))
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 轮询循环
+// ═══════════════════════════════════════════════════════════════
+
+// runPollLoop 主轮询循环，通过定时器和 NOTIFY 唤醒信号触发
+func (r *Relay) runPollLoop(ctx context.Context) {
+	defer r.wg.Done()
+
+	ticker := time.NewTicker(r.config.PollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-r.done:
+			return
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			r.pollUntilEmpty(ctx)
+		case <-r.wakeup:
+			r.pollUntilEmpty(ctx)
+			// 重置定时器避免紧接着再次轮询
+			ticker.Reset(r.config.PollInterval)
+		}
+	}
+}
+
+// pollUntilEmpty 持续轮询直到没有待处理事件
+func (r *Relay) pollUntilEmpty(ctx context.Context) {
+	for {
+		select {
+		case <-r.done:
+			return
+		case <-ctx.Done():
+			return
+		default:
+		}
+
+		dispatched := r.poll(ctx)
+		if dispatched == 0 {
+			return
+		}
+	}
+}
+
+// poll 单次轮询：锁定一批事件并逐个分发
+// 返回成功分发的事件数
+func (r *Relay) poll(ctx context.Context) int {
+	var events []OutboxEvent
+	now := time.Now()
+
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		tx := database.GetDB(txCtx, r.db)
+		// SELECT ... FOR UPDATE SKIP LOCKED 确保多实例安全
+		// 按 AggregateTypes 过滤，实现多服务事件路由隔离
+		args := []any{StatusPending, StatusRetryPending, now}
+		aggregateFilter := ""
+		if len(r.config.AggregateTypes) > 0 {
+			aggregateFilter = "AND aggregate_type IN ?"
+			args = append(args, r.config.AggregateTypes)
+		}
+		args = append(args, r.config.BatchSize)
+		query := fmt.Sprintf(`
+			SELECT id, outbox_ref, aggregate_type, aggregate_id, aggregate_version, source_product_code,
+			       audience_scope, audience_product_codes, event_type, schema_version, payload, metadata,
+			       audit_changes, audit_meta,
+			       occurred_at, created_at, status, locked_at, locked_by,
+			       retry_count, max_retries, next_retry_at, last_error
+			FROM sys_outbox_events
+			WHERE (status = ? OR (status = ? AND next_retry_at <= ?))
+			%s
+			ORDER BY created_at ASC
+			LIMIT ?
+			FOR UPDATE SKIP LOCKED
+		`, aggregateFilter)
+		if err := tx.Raw(query, args...).Scan(&events).Error; err != nil {
+			return fmt.Errorf("select pending outbox events: %w", err)
+		}
+
+		if len(events) == 0 {
+			return nil
+		}
+
+		// 批量标记为锁定状态
+		ids := make([]string, len(events))
+		for i := range events {
+			ids[i] = events[i].ID
+		}
+		relayID := r.config.RelayID
+		// 租约必须使用数据库持久化后的时间精度，后续 CAS 精确比较 locked_at。
+		if err := tx.Model(&events).
+			Clauses(clause.Returning{}).
+			Where("id IN ?", ids).
+			Updates(map[string]any{
+				"status":    StatusLocked,
+				"locked_at": now,
+				"locked_by": relayID,
+			}).Error; err != nil {
+			return fmt.Errorf("lock outbox events: %w", err)
+		}
+		// UPDATE RETURNING 不保证返回顺序，恢复批次的创建时间顺序。
+		sort.SliceStable(events, func(i, j int) bool {
+			return events[i].CreatedAt.Before(events[j].CreatedAt)
+		})
+
+		return nil
+	})
+	if err != nil {
+		r.logger.Error("outbox poll transaction failed", zap.Error(err))
+		return 0
+	}
+
+	if len(events) == 0 {
+		return 0
+	}
+
+	// 在事务外逐个分发事件
+	dispatched := 0
+	for i := range events {
+		event := &events[i]
+		if dispatchErr := r.dispatchEvent(ctx, event); dispatchErr != nil {
+			r.logger.Error("outbox event dispatch failed",
+				zap.String("eventId", event.ID),
+				zap.String("eventType", event.EventType),
+				zap.Error(dispatchErr),
+			)
+			continue
+		}
+		dispatched++
+	}
+
+	r.logger.Debug("outbox poll completed",
+		zap.Int("total", len(events)),
+		zap.Int("dispatched", dispatched),
+		zap.Int("failed", len(events)-dispatched),
+	)
+
+	return dispatched
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 事件分发
+// ═══════════════════════════════════════════════════════════════
+
+// dispatchEvent 分发单个 outbox 事件到按目标拆分的投递通道
+func (r *Relay) dispatchEvent(ctx context.Context, event *OutboxEvent) error {
+	targets := r.requiredDeliveryTargets(event.EventType)
+	if err := r.ensureDeliveryTargets(ctx, event, targets); err != nil {
+		return err
+	}
+
+	deliveries, err := r.claimDueDeliveries(ctx, event.ID, targets, time.Now())
+	if err != nil {
+		return err
+	}
+
+	var firstErr error
+	for i := range deliveries {
+		delivery := &deliveries[i]
+		if err := r.dispatchDeliveryTarget(ctx, event, delivery.Target); err != nil {
+			if markErr := r.markDeliveryRetry(ctx, event, delivery, err); markErr != nil {
+				return markErr
+			}
+			if firstErr == nil {
+				firstErr = fmt.Errorf("%s delivery failed: %w", delivery.Target, err)
+			}
+			continue
+		}
+		if err := r.markDeliveryDispatched(ctx, event.ID, delivery); err != nil {
+			return err
+		}
+	}
+
+	if _, err := r.refreshParentStatus(ctx, event, targets); err != nil {
+		return err
+	}
+	return firstErr
+}
+
+func (r *Relay) dispatchDeliveryTarget(ctx context.Context, event *OutboxEvent, target string) error {
+	switch target {
+	case TargetLocalEventBus:
+		return r.dispatchLocalEventBus(ctx, event)
+	case TargetAsynq:
+		return r.dispatchAsynq(ctx, event)
+	case TargetRedisStream:
+		return r.dispatchRedisStream(ctx, event)
+	default:
+		return fmt.Errorf("unsupported outbox delivery target: %s", target)
+	}
+}
+
+func (r *Relay) dispatchLocalEventBus(ctx context.Context, event *OutboxEvent) error {
+	domainEvent, err := r.toDomainEvent(event)
+	if err != nil {
+		return err
+	}
+
+	r.logger.Debug("dispatching outbox event to local eventbus",
+		zap.String("eventId", event.ID),
+		zap.String("eventType", event.EventType),
+		zap.String("aggregateId", event.AggregateID),
+		zap.String("payloadType", fmt.Sprintf("%T", domainEvent.Payload)),
+	)
+
+	// 发布到本地 EventBus
+	if err := r.eventBus.Publish(ctx, domainEvent); err != nil {
+		return fmt.Errorf("publish to local eventbus: %w", err)
+	}
+
+	r.logger.Debug("outbox event dispatched to local eventbus",
+		zap.String("eventId", event.ID),
+		zap.String("eventType", event.EventType),
+	)
+
+	return nil
+}
+
+func (r *Relay) dispatchAsynq(ctx context.Context, event *OutboxEvent) error {
+	if r.queueClient == nil {
+		return fmt.Errorf("asynq target is not configured")
+	}
+	taskPayload := CrossProcessEventPayload{
+		OutboxRef:            event.OutboxRef,
+		EventType:            event.EventType,
+		AggregateType:        event.AggregateType,
+		AggregateID:          event.AggregateID,
+		AggregateVersion:     event.AggregateVersion,
+		SourceProductCode:    optionalStringValue(event.SourceProductCode),
+		AudienceScope:        event.AudienceScope,
+		AudienceProductCodes: cloneProductCodes(event.AudienceProductCodes),
+		Payload:              event.Payload,
+		Metadata:             event.Metadata,
+		AuditChanges:         event.AuditChanges,
+		AuditMeta:            event.AuditMeta,
+		OccurredAt:           event.OccurredAt,
+		EventID:              event.ID,
+	}
+	_, err := r.queueClient.Enqueue(ctx, TaskTypeEventRelay, taskPayload, queue.EnqueueOptions{
+		Queue:     QueueEvents,
+		UniqueTTL: 24 * time.Hour,
+	})
+	if err != nil {
+		return fmt.Errorf("enqueue cross-process event: %w", err)
+	}
+	return nil
+}
+
+func (r *Relay) dispatchRedisStream(ctx context.Context, event *OutboxEvent) error {
+	if r.streamPublisher == nil {
+		return fmt.Errorf("redis_stream target is not configured")
+	}
+	streamEvt := eventstream.StreamEvent{
+		EventID:       event.ID,
+		EventType:     event.EventType,
+		AggregateID:   event.AggregateID,
+		OccurredAt:    event.OccurredAt,
+		ProductCode:   optionalStringValue(event.SourceProductCode),
+		Payload:       event.Payload,
+		Metadata:      event.Metadata,
+		SchemaVersion: optionalStringValue(event.SchemaVersion),
+	}
+	if err := r.streamPublisher.Publish(ctx, streamEvt); err != nil {
+		return fmt.Errorf("publish to event stream: %w", err)
+	}
+	return nil
+}
+
+func (r *Relay) requiredDeliveryTargets(eventType string) []string {
+	targets := []string{TargetLocalEventBus}
+	if r.queueClient != nil && matchAnyEventPattern(r.config.AsynqEventPatterns, eventType) {
+		targets = append(targets, TargetAsynq)
+	}
+	if r.streamPublisher != nil && matchAnyEventPattern(r.config.RedisStreamEventPatterns, eventType) {
+		targets = append(targets, TargetRedisStream)
+	}
+	return targets
+}
+
+func (r *Relay) ensureDeliveryTargets(ctx context.Context, event *OutboxEvent, targets []string) error {
+	if len(targets) == 0 {
+		return nil
+	}
+	now := time.Now()
+	deliveries := make([]OutboxEventDelivery, 0, len(targets))
+	for _, target := range targets {
+		deliveries = append(deliveries, OutboxEventDelivery{
+			EventID:    event.ID,
+			Target:     target,
+			Status:     StatusPending,
+			MaxRetries: r.deliveryMaxRetries(event),
+			CreatedAt:  now,
+			UpdatedAt:  now,
+		})
+	}
+
+	return r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		db := database.GetDB(txCtx, r.db)
+		err := db.Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "event_id"}, {Name: "target"}},
+			DoNothing: true,
+		}).Create(&deliveries).Error
+		if err != nil {
+			return fmt.Errorf("ensure outbox delivery targets: %w", err)
+		}
+		return nil
+	})
+}
+
+func (r *Relay) claimDueDeliveries(ctx context.Context, eventID string, targets []string, now time.Time) ([]OutboxEventDelivery, error) {
+	if len(targets) == 0 {
+		return nil, nil
+	}
+
+	var deliveries []OutboxEventDelivery
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		db := database.GetDB(txCtx, r.db)
+		if err := db.
+			Clauses(clause.Locking{Strength: "UPDATE"}).
+			Select("event_id", "target", "status", "retry_count", "max_retries", "next_retry_at", "last_error", "dispatched_at", "locked_at", "locked_by", "created_at", "updated_at").
+			Where("event_id = ? AND target IN ? AND (status = ? OR (status = ? AND (next_retry_at IS NULL OR next_retry_at <= ?)))",
+				eventID, targets, StatusPending, StatusRetryPending, now).
+			Order("created_at ASC, target ASC").
+			Find(&deliveries).Error; err != nil {
+			return fmt.Errorf("select due outbox delivery targets: %w", err)
+		}
+		if len(deliveries) == 0 {
+			return nil
+		}
+
+		claimedTargets := make([]string, 0, len(deliveries))
+		for i := range deliveries {
+			claimedTargets = append(claimedTargets, deliveries[i].Target)
+		}
+		// RETURNING 回填实际租约，避免内存纳秒时间与持久化值不一致。
+		if err := db.Model(&deliveries).
+			Clauses(clause.Returning{}).
+			Where("event_id = ? AND target IN ?", eventID, claimedTargets).
+			Updates(map[string]any{
+				"locked_at":  now,
+				"locked_by":  r.config.RelayID,
+				"updated_at": now,
+			}).Error; err != nil {
+			return fmt.Errorf("lock outbox delivery targets: %w", err)
+		}
+		sort.SliceStable(deliveries, func(i, j int) bool {
+			if deliveries[i].CreatedAt.Equal(deliveries[j].CreatedAt) {
+				return deliveries[i].Target < deliveries[j].Target
+			}
+			return deliveries[i].CreatedAt.Before(deliveries[j].CreatedAt)
+		})
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return deliveries, nil
+}
+
+func (r *Relay) markDeliveryDispatched(ctx context.Context, eventID string, delivery *OutboxEventDelivery) error {
+	if delivery == nil || delivery.LockedAt == nil || delivery.LockedBy == nil {
+		return fmt.Errorf("outbox delivery lease is incomplete")
+	}
+	now := time.Now()
+	return r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		result := database.GetDB(txCtx, r.db).Model(&OutboxEventDelivery{}).
+			Where("event_id = ? AND target = ? AND locked_by = ? AND locked_at = ?", eventID, delivery.Target, *delivery.LockedBy, *delivery.LockedAt).
+			Updates(map[string]any{
+				"status":        StatusDispatched,
+				"next_retry_at": nil,
+				"last_error":    nil,
+				"dispatched_at": now,
+				"locked_at":     nil,
+				"locked_by":     nil,
+				"updated_at":    now,
+			})
+		if result.Error != nil {
+			return fmt.Errorf("mark outbox delivery target dispatched: %w", result.Error)
+		}
+		if result.RowsAffected == 0 {
+			return fmt.Errorf("outbox delivery lease was superseded: %s", delivery.Target)
+		}
+		return nil
+	})
+}
+
+func (r *Relay) markDeliveryRetry(ctx context.Context, event *OutboxEvent, delivery *OutboxEventDelivery, dispatchErr error) error {
+	if delivery == nil || delivery.LockedAt == nil || delivery.LockedBy == nil {
+		return fmt.Errorf("outbox delivery lease is incomplete")
+	}
+	now := time.Now()
+	retryCount := nextRelayRetryCount(delivery.RetryCount)
+	maxRetries := delivery.MaxRetries
+	if maxRetries <= 0 {
+		maxRetries = r.deliveryMaxRetries(event)
+	}
+	errMsg := dispatchErr.Error()
+	permanent := IsPermanentDeliveryError(dispatchErr)
+	persistent := r.shouldRetryPersistently(event.EventType)
+
+	updates := map[string]any{
+		"retry_count": retryCount,
+		"max_retries": maxRetries,
+		"last_error":  errMsg,
+		"locked_at":   nil,
+		"locked_by":   nil,
+		"updated_at":  now,
+	}
+	if !persistent && (permanent || retryCount >= maxRetries) {
+		updates["status"] = StatusDeadLetter
+		updates["next_retry_at"] = nil
+		r.logger.Warn("outbox delivery target moved to dead letter",
+			zap.String("eventId", event.ID),
+			zap.String("eventType", event.EventType),
+			zap.String("target", delivery.Target),
+			zap.Int("retryCount", retryCount),
+			zap.Bool("permanent", permanent),
+			zap.String("lastError", errMsg),
+		)
+	} else {
+		updates["status"] = StatusRetryPending
+		updates["next_retry_at"] = now.Add(relayRetryBackoff(retryCount))
+	}
+
+	return r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		result := database.GetDB(txCtx, r.db).Model(&OutboxEventDelivery{}).
+			Where("event_id = ? AND target = ? AND locked_by = ? AND locked_at = ?", event.ID, delivery.Target, *delivery.LockedBy, *delivery.LockedAt).
+			Updates(updates)
+		if result.Error != nil {
+			return fmt.Errorf("mark outbox delivery target retry: %w", result.Error)
+		}
+		if result.RowsAffected == 0 {
+			return fmt.Errorf("outbox delivery lease was superseded: %s", delivery.Target)
+		}
+		return nil
+	})
+}
+
+func (r *Relay) refreshParentStatus(ctx context.Context, event *OutboxEvent, targets []string) (string, error) {
+	if event == nil || event.LockedAt == nil || event.LockedBy == nil {
+		return "", fmt.Errorf("outbox event lease is incomplete")
+	}
+	if len(targets) == 0 {
+		return StatusDispatched, nil
+	}
+	eventID := event.ID
+
+	now := time.Now()
+	parentStatus := StatusDispatched
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		db := database.GetDB(txCtx, r.db)
+		var deliveries []OutboxEventDelivery
+		if err := db.
+			Select("event_id", "target", "status", "retry_count", "next_retry_at", "last_error").
+			Where("event_id = ? AND target IN ?", eventID, targets).
+			Find(&deliveries).Error; err != nil {
+			return fmt.Errorf("select outbox delivery target summary: %w", err)
+		}
+		if len(deliveries) != len(targets) {
+			return fmt.Errorf("outbox delivery target ledger incomplete for event %s", eventID)
+		}
+
+		allDispatched := true
+		hasDeadLetter := false
+		maxRetryCount := 0
+		var nextRetryAt *time.Time
+		var lastError string
+		hasLastError := false
+
+		for i := range deliveries {
+			delivery := &deliveries[i]
+			if delivery.Status != StatusDispatched {
+				allDispatched = false
+			}
+			if delivery.Status == StatusDeadLetter {
+				hasDeadLetter = true
+			}
+			if delivery.RetryCount > maxRetryCount {
+				maxRetryCount = delivery.RetryCount
+			}
+			if delivery.NextRetryAt != nil && (nextRetryAt == nil || delivery.NextRetryAt.Before(*nextRetryAt)) {
+				nextRetry := *delivery.NextRetryAt
+				nextRetryAt = &nextRetry
+			}
+			if delivery.LastError != nil {
+				lastError = *delivery.LastError
+				hasLastError = true
+			}
+		}
+
+		updates := map[string]any{
+			"retry_count": maxRetryCount,
+			"locked_at":   nil,
+			"locked_by":   nil,
+		}
+		switch {
+		case allDispatched:
+			parentStatus = StatusDispatched
+			updates["status"] = StatusDispatched
+			updates["next_retry_at"] = nil
+			updates["last_error"] = nil
+		case hasDeadLetter:
+			parentStatus = StatusDeadLetter
+			updates["status"] = StatusDeadLetter
+			updates["next_retry_at"] = nil
+			if hasLastError {
+				updates["last_error"] = lastError
+			} else {
+				updates["last_error"] = nil
+			}
+		default:
+			parentStatus = StatusRetryPending
+			updates["status"] = StatusRetryPending
+			if nextRetryAt == nil {
+				nextRetry := now
+				nextRetryAt = &nextRetry
+			}
+			updates["next_retry_at"] = nextRetryAt
+			if hasLastError {
+				updates["last_error"] = lastError
+			} else {
+				updates["last_error"] = nil
+			}
+		}
+
+		result := db.Model(&OutboxEvent{}).
+			Where("id = ? AND status = ? AND locked_by = ? AND locked_at = ?", eventID, StatusLocked, *event.LockedBy, *event.LockedAt).
+			Updates(updates)
+		if result.Error != nil {
+			return fmt.Errorf("refresh outbox parent status: %w", result.Error)
+		}
+		if result.RowsAffected == 0 {
+			return fmt.Errorf("outbox event lease was superseded")
+		}
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+	return parentStatus, nil
+}
+
+func (r *Relay) deliveryMaxRetries(event *OutboxEvent) int {
+	if event.MaxRetries > 0 {
+		return event.MaxRetries
+	}
+	if r.config.MaxRetries > 0 {
+		return r.config.MaxRetries
+	}
+	return defaultRelayMaxRetries
+}
+
+func retryBackoff(retryCount int) time.Duration {
+	return relayRetryBackoff(retryCount)
+}
+
+func nextRelayRetryCount(current int) int {
+	const maxSmallInt = 32_767
+	if current >= maxSmallInt {
+		return maxSmallInt
+	}
+	return current + 1
+}
+
+func (r *Relay) shouldRetryPersistently(eventType string) bool {
+	return matchAnyEventPattern(r.config.PersistentRetryEvents, eventType)
+}
+
+func relayRetryBackoff(retryCount int) time.Duration {
+	const maxBackoff = 15 * time.Minute
+	if retryCount < 1 {
+		return time.Second
+	}
+	if retryCount >= 10 {
+		return maxBackoff
+	}
+	return time.Duration(1<<uint(retryCount)) * time.Second //nolint:gosec // retryCount 在位移前限制为 1..9。
+}
+
+// toDomainEvent 将 OutboxEvent 转换为 EventBus DomainEvent
+func (r *Relay) toDomainEvent(event *OutboxEvent) (eventbus.DomainEvent, error) {
+	// 还原事件载荷为具体类型（避免 listener unmarshalPayload 时 json.RawMessage double-encoding）
+	var payload any
+	if r.config.PayloadDeserializer != nil {
+		deserialized, err := r.config.PayloadDeserializer(event.EventType, event.Payload)
+		if err != nil {
+			return eventbus.DomainEvent{}, fmt.Errorf("deserialize outbox event payload %s (%s): %w", event.ID, event.EventType, err)
+		}
+		payload = deserialized
+	} else {
+		payload = json.RawMessage(event.Payload)
+	}
+
+	domainEvent := eventbus.DomainEvent{
+		EventName:   event.EventType,
+		EventID:     event.ID,
+		OccurredAt:  event.OccurredAt,
+		AggregateID: event.AggregateID,
+		Version:     AggregateVersionValue(event.AggregateVersion),
+		Payload:     payload,
+	}
+
+	// 还原元数据
+	if len(event.Metadata) > 0 {
+		var meta eventbus.EventMetadata
+		if err := json.Unmarshal(event.Metadata, &meta); err != nil {
+			r.logger.Warn("failed to unmarshal outbox event metadata",
+				zap.String("eventId", event.ID),
+				zap.Error(err),
+			)
+		} else {
+			domainEvent.Metadata = &meta
+		}
+	}
+	domainEvent.Metadata = eventbus.MetadataWithProductCode(
+		domainEvent.Metadata,
+		optionalStringValue(event.SourceProductCode),
+	)
+
+	// 从顶层信封列还原审计数据（对齐 AWS CloudTrail），失败只告警不阻塞分发。
+	if len(event.AuditChanges) > 0 {
+		changes := &eventbus.AuditChangesPayload{}
+		if err := json.Unmarshal(event.AuditChanges, changes); err != nil {
+			r.logger.Warn("failed to unmarshal outbox audit_changes",
+				zap.String("eventId", event.ID),
+				zap.Error(err),
+			)
+		} else {
+			domainEvent.AuditChanges = changes
+		}
+	}
+	if len(event.AuditMeta) > 0 {
+		meta := &eventbus.AuditMetadataPayload{}
+		if err := json.Unmarshal(event.AuditMeta, meta); err != nil {
+			r.logger.Warn("failed to unmarshal outbox audit_meta",
+				zap.String("eventId", event.ID),
+				zap.Error(err),
+			)
+		} else {
+			domainEvent.AuditMeta = meta
+		}
+	}
+
+	return domainEvent, nil
+}
+
+func matchAnyEventPattern(patterns []string, eventType string) bool {
+	for _, pattern := range patterns {
+		if matchEventPattern(pattern, eventType) {
+			return true
+		}
+	}
+	return false
+}
+
+// optionalStringValue 返回可选字符串的规范化值。
+func optionalStringValue(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return strings.TrimSpace(*value)
+}
+
+// AggregateVersionValue 将持久化信封中的可选聚合版本还原为领域事件版本。
+func AggregateVersionValue(version *int64) int {
+	if version == nil {
+		return 0
+	}
+	return int(*version)
+}
+
+// matchEventPattern 事件类型通配符匹配
+// 支持 * 匹配单段，** 匹配任意后缀
+func matchEventPattern(pattern, eventType string) bool {
+	if pattern == eventType {
+		return true
+	}
+	if pattern == "*" || pattern == "**" {
+		return true
+	}
+
+	patternParts := strings.Split(pattern, ".")
+	eventParts := strings.Split(eventType, ".")
+
+	// ** 结尾匹配任意后续段
+	if len(patternParts) > 0 && patternParts[len(patternParts)-1] == "**" {
+		prefix := patternParts[:len(patternParts)-1]
+		if len(eventParts) < len(prefix) {
+			return false
+		}
+		for i, p := range prefix {
+			if p != "*" && p != eventParts[i] {
+				return false
+			}
+		}
+		return true
+	}
+
+	if len(patternParts) != len(eventParts) {
+		return false
+	}
+	for i, p := range patternParts {
+		if p == "*" {
+			continue
+		}
+		if p != eventParts[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 维护循环
+// ═══════════════════════════════════════════════════════════════
+
+// runMaintenanceLoop 后台维护循环：回收超时锁 + 清理旧事件
+func (r *Relay) runMaintenanceLoop(ctx context.Context) {
+	defer r.wg.Done()
+
+	reclaimTicker := time.NewTicker(r.config.LockTimeout / 2)
+	defer reclaimTicker.Stop()
+
+	cleanupTicker := time.NewTicker(r.config.CleanupInterval)
+	defer cleanupTicker.Stop()
+
+	for {
+		select {
+		case <-r.done:
+			return
+		case <-ctx.Done():
+			return
+		case <-reclaimTicker.C:
+			r.reclaimStaleLocks(ctx)
+		case <-cleanupTicker.C:
+			r.cleanupDispatched(ctx)
+		}
+	}
+}
+
+// reclaimStaleLocks 回收超时的锁定事件，重新设为 pending
+func (r *Relay) reclaimStaleLocks(ctx context.Context) {
+	cutoff := time.Now().Add(-r.config.LockTimeout)
+	now := time.Now()
+	var reclaimed int64
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		db := database.GetDB(txCtx, r.db)
+		var eventIDs []string
+		if err := db.Model(&OutboxEvent{}).
+			Where("status = ? AND locked_at < ?", StatusLocked, cutoff).
+			Pluck("id", &eventIDs).Error; err != nil {
+			return fmt.Errorf("select stale outbox locks: %w", err)
+		}
+		if len(eventIDs) == 0 {
+			return nil
+		}
+		result := db.Model(&OutboxEvent{}).
+			Where("id IN ?", eventIDs).
+			Updates(map[string]any{
+				"status":    StatusPending,
+				"locked_at": nil,
+				"locked_by": nil,
+			})
+		if result.Error != nil {
+			return fmt.Errorf("reclaim stale outbox locks: %w", result.Error)
+		}
+		reclaimed = result.RowsAffected
+		if err := db.Model(&OutboxEventDelivery{}).
+			Where("event_id IN ?", eventIDs).
+			Updates(map[string]any{
+				"locked_at":  nil,
+				"locked_by":  nil,
+				"updated_at": now,
+			}).Error; err != nil {
+			return fmt.Errorf("reclaim stale outbox delivery locks: %w", err)
+		}
+		return nil
+	})
+	if err != nil {
+		r.logger.Error("failed to reclaim stale outbox locks", zap.Error(err))
+		return
+	}
+	if reclaimed > 0 {
+		r.logger.Info("reclaimed stale outbox locks",
+			zap.Int64("count", reclaimed),
+			zap.Time("cutoff", cutoff),
+		)
+	}
+}
+
+// cleanupDispatched 清理已处理的旧事件
+func (r *Relay) cleanupDispatched(ctx context.Context) {
+	cutoff := time.Now().Add(-r.config.RetentionDuration)
+	var cleaned int64
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		db := database.GetDB(txCtx, r.db)
+		var eventIDs []string
+		if err := db.Model(&OutboxEvent{}).
+			Where("status = ? AND created_at < ?", StatusDispatched, cutoff).
+			Pluck("id", &eventIDs).Error; err != nil {
+			return fmt.Errorf("select dispatched outbox events for cleanup: %w", err)
+		}
+		if len(eventIDs) == 0 {
+			return nil
+		}
+		if err := db.Where("event_id IN ?", eventIDs).
+			Delete(&OutboxEventDelivery{}).Error; err != nil {
+			return fmt.Errorf("cleanup outbox delivery targets: %w", err)
+		}
+		result := db.Where("id IN ?", eventIDs).Delete(&OutboxEvent{})
+		if result.Error != nil {
+			return fmt.Errorf("cleanup dispatched outbox events: %w", result.Error)
+		}
+		cleaned = result.RowsAffected
+		return nil
+	})
+	if err != nil {
+		r.logger.Error("failed to cleanup dispatched outbox events", zap.Error(err))
+		return
+	}
+	if cleaned > 0 {
+		r.logger.Info("cleaned up dispatched outbox events",
+			zap.Int64("count", cleaned),
+			zap.Time("cutoff", cutoff),
+		)
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// PostgreSQL LISTEN/NOTIFY
+// ═══════════════════════════════════════════════════════════════
+
+// listenNotify 监听 PostgreSQL NOTIFY 通道实现低延迟唤醒
+//
+// 使用 pgx 驱动原生连接执行 LISTEN 和等待通知。
+// 连接断开时自动重连。
+func (r *Relay) listenNotify(ctx context.Context) {
+	defer r.wg.Done()
+
+	for {
+		select {
+		case <-r.done:
+			return
+		case <-ctx.Done():
+			return
+		default:
+		}
+
+		if err := r.listenOnce(ctx); err != nil {
+			if ctx.Err() != nil {
+				return
+			}
+			select {
+			case <-r.done:
+				return
+			default:
+			}
+			r.logger.Warn("LISTEN/NOTIFY connection lost, reconnecting",
+				zap.Error(err),
+			)
+			// 重连延迟，避免紧密循环
+			select {
+			case <-time.After(3 * time.Second):
+			case <-r.done:
+				return
+			case <-ctx.Done():
+				return
+			}
+		}
+	}
+}
+
+// listenOnce 获取一个原生 pgx 连接，执行 LISTEN 并阻塞等待通知
+func (r *Relay) listenOnce(ctx context.Context) error {
+	sqlDB, err := r.db.DB()
+	if err != nil {
+		return fmt.Errorf("get sql.DB: %w", err)
+	}
+
+	conn, err := sqlDB.Conn(ctx)
+	if err != nil {
+		return fmt.Errorf("acquire connection: %w", err)
+	}
+	defer conn.Close()
+
+	// 通过 Raw 访问底层 pgx 连接执行 LISTEN
+	// any: database/sql.Conn.Raw 回调参数为底层驱动连接
+	return conn.Raw(func(driverConn any) error {
+		stdlibConn, ok := driverConn.(*stdlib.Conn)
+		if !ok {
+			return fmt.Errorf("unsupported driver for LISTEN/NOTIFY: %T", driverConn)
+		}
+
+		pgxConn := stdlibConn.Conn()
+
+		// 执行 LISTEN
+		if _, execErr := pgxConn.Exec(ctx, "LISTEN outbox_events"); execErr != nil {
+			return fmt.Errorf("LISTEN: %w", execErr)
+		}
+
+		r.logger.Debug("LISTEN outbox_events established")
+
+		// 阻塞等待通知（pgx.Conn.WaitForNotification 返回 *pgconn.Notification, error）
+		for {
+			notification, waitErr := pgxConn.WaitForNotification(ctx)
+			if waitErr != nil {
+				return fmt.Errorf("wait for notification: %w", waitErr)
+			}
+
+			r.logger.Debug("pg_notify received",
+				zap.String("channel", notification.Channel),
+				zap.Int("payloadBytes", len(notification.Payload)),
+			)
+			// 非阻塞唤醒轮询循环
+			select {
+			case r.wakeup <- struct{}{}:
+			default:
+				// 已有待处理的唤醒信号，跳过
+			}
+		}
+	})
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 辅助函数
+// ═══════════════════════════════════════════════════════════════
+
+// generateRelayID 生成 Relay 实例标识（hostname + 短 UUID）
+func generateRelayID() string {
+	hostname, err := os.Hostname()
+	if err != nil {
+		hostname = "unknown"
+	}
+	return fmt.Sprintf("%s-%s", hostname, uuid.New().String()[:8])
+}