@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/observability/tracing.go

@@ -0,0 +1,187 @@
+package observability
+
+import (
+	"context"
+	"fmt"
+	"math/rand"
+	"time"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 追踪服务
+// ═══════════════════════════════════════════════════════════════
+
+// TracingService OpenTelemetry 追踪服务
+type TracingService struct {
+	logger   *zap.Logger
+	config   config.TracingConfig
+	provider *sdktrace.TracerProvider
+	tracer   trace.Tracer
+}
+
+// NewTracingService 创建追踪服务
+func NewTracingService(logger *zap.Logger, cfg *config.TracingConfig) (*TracingService, error) {
+	ts := &TracingService{
+		logger: logger.Named("Tracing"),
+		config: *cfg,
+		tracer: otel.Tracer(cfg.ServiceName),
+	}
+
+	if !cfg.Enabled {
+		ts.logger.Info("tracing is disabled")
+		return ts, nil
+	}
+
+	if err := ts.initialize(); err != nil {
+		return nil, fmt.Errorf("initialize tracing: %w", err)
+	}
+
+	ts.logger.Info("OpenTelemetry tracing initialized (OTLP)")
+	return ts, nil
+}
+
+func (ts *TracingService) initialize() error {
+	ctx := context.Background()
+
+	exp, err := otlptracehttp.New(ctx,
+		otlptracehttp.WithEndpoint(ts.config.Endpoint),
+		otlptracehttp.WithInsecure(),
+	)
+	if err != nil {
+		return fmt.Errorf("create OTLP exporter: %w", err)
+	}
+
+	res, err := resource.New(
+		ctx,
+		resource.WithAttributes(
+			semconv.ServiceNameKey.String(ts.config.ServiceName),
+			semconv.ServiceVersionKey.String(ts.config.ServiceVersion),
+			semconv.DeploymentEnvironmentKey.String(ts.config.Environment),
+		),
+	)
+	if err != nil {
+		return fmt.Errorf("create resource: %w", err)
+	}
+
+	sampler := sdktrace.ParentBased(
+		sdktrace.TraceIDRatioBased(ts.config.SamplingRatio),
+	)
+
+	ts.provider = sdktrace.NewTracerProvider(
+		sdktrace.WithBatcher(exp),
+		sdktrace.WithResource(res),
+		sdktrace.WithSampler(sampler),
+	)
+
+	otel.SetTracerProvider(ts.provider)
+	ts.tracer = ts.provider.Tracer(ts.config.ServiceName, trace.WithInstrumentationVersion(ts.config.ServiceVersion))
+
+	return nil
+}
+
+// Shutdown 关闭追踪服务
+func (ts *TracingService) Shutdown(ctx context.Context) error {
+	if ts.provider == nil {
+		return nil
+	}
+
+	if err := ts.provider.Shutdown(ctx); err != nil {
+		ts.logger.Error("shutdown tracing provider failed", zap.Error(err))
+		return err
+	}
+
+	ts.logger.Info("tracing provider shut down")
+	return nil
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Span 操作
+// ═══════════════════════════════════════════════════════════════
+
+// Tracer 获取追踪器实例
+func (ts *TracingService) Tracer() trace.Tracer {
+	return ts.tracer
+}
+
+// StartSpan 启动新的 Span
+func (ts *TracingService) StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span) {
+	return ts.tracer.Start(ctx, name, opts...)
+}
+
+// WithSpan 在 Span 上下文中执行函数
+func (ts *TracingService) WithSpan(ctx context.Context, name string, fn func(ctx context.Context, span trace.Span) error, opts ...trace.SpanStartOption) error {
+	ctx, span := ts.tracer.Start(ctx, name, opts...)
+	defer span.End()
+
+	if err := fn(ctx, span); err != nil {
+		span.SetStatus(codes.Error, err.Error())
+		span.RecordError(err)
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// GetCurrentSpan 获取当前活跃的 Span
+func (ts *TracingService) GetCurrentSpan(ctx context.Context) trace.Span {
+	return trace.SpanFromContext(ctx)
+}
+
+// AddSpanAttributes 向当前 Span 添加属性
+func (ts *TracingService) AddSpanAttributes(ctx context.Context, attrs ...attribute.KeyValue) {
+	span := trace.SpanFromContext(ctx)
+	span.SetAttributes(attrs...)
+}
+
+// RecordError 在当前 Span 上记录异常
+func (ts *TracingService) RecordError(ctx context.Context, err error) {
+	span := trace.SpanFromContext(ctx)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+}
+
+// AddSpanEvent 向当前 Span 添加事件
+func (ts *TracingService) AddSpanEvent(ctx context.Context, name string, attrs ...attribute.KeyValue) {
+	span := trace.SpanFromContext(ctx)
+	span.AddEvent(name, trace.WithAttributes(attrs...))
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 关联 ID
+// ═══════════════════════════════════════════════════════════════
+
+type correlationIDKey struct{}
+
+// ContextWithCorrelationID 将关联 ID 存入上下文
+func ContextWithCorrelationID(ctx context.Context, id string) context.Context {
+	return context.WithValue(ctx, correlationIDKey{}, id)
+}
+
+// CorrelationIDFromContext 从上下文提取关联 ID
+func CorrelationIDFromContext(ctx context.Context) string {
+	id, _ := ctx.Value(correlationIDKey{}).(string)
+	return id
+}
+
+// GenerateCorrelationID 生成新的关联 ID
+func GenerateCorrelationID() string {
+	const chars = "abcdefghijklmnopqrstuvwxyz0123456789"
+	b := make([]byte, 13)
+	for i := range b {
+		b[i] = chars[rand.Intn(len(chars))] //nolint:gosec // 关联 ID 仅用于请求追踪，无安全需求
+	}
+	return fmt.Sprintf("%d-%s", time.Now().UnixMilli(), string(b))
+}

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

@@ -0,0 +1,314 @@
+package outbox
+
+import (
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"gorm.io/datatypes"
+
+	"{{module}}/internal/common/productcode"
+	"{{module}}/internal/core/eventbus"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// Outbox 事件状态
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// StatusPending 待处理
+	StatusPending = "pending"
+	// StatusLocked Relay 已抢占，仍在分发中
+	StatusLocked = "locked"
+	// StatusDispatched 已分发
+	StatusDispatched = "dispatched"
+	// StatusRetryPending 等待重试
+	StatusRetryPending = "retry_pending"
+	// StatusDeadLetter 死信（超过最大重试次数）
+	StatusDeadLetter = "dead_letter"
+)
+
+const (
+	// TargetLocalEventBus 进程内 EventBus 投递目标
+	TargetLocalEventBus = "local_eventbus"
+	// TargetAsynq Asynq 跨进程任务投递目标
+	TargetAsynq = "asynq"
+	// TargetRedisStream Redis Stream 投递目标
+	TargetRedisStream = "redis_stream"
+)
+
+var (
+	// ErrEventLocked 表示目标事件正在被 Relay 实例处理，调用方应稍后重试。
+	ErrEventLocked = errors.New("outbox event is locked")
+)
+
+// EventSourceScope 定义事件事实的权威来源范围。
+type EventSourceScope string
+
+const (
+	EventSourceScopePlatform EventSourceScope = "platform"
+	EventSourceScopeProduct  EventSourceScope = "product"
+)
+
+// AudienceScope 定义事件创建时冻结的可见受众范围。
+type AudienceScope string
+
+const (
+	AudienceScopePlatform      AudienceScope = "platform"
+	AudienceScopeSourceProduct AudienceScope = "source_product"
+	AudienceScopeProducts      AudienceScope = "products"
+)
+
+// EventSource 是事件权威来源，不从请求上下文推断。
+type EventSource struct {
+	Scope       EventSourceScope
+	ProductCode string
+}
+
+// EventAudience 是事件写入时冻结的受众事实。
+type EventAudience struct {
+	Scope        AudienceScope
+	ProductCodes []string
+}
+
+// PlatformSource 返回平台来源。
+func PlatformSource() EventSource {
+	return EventSource{Scope: EventSourceScopePlatform}
+}
+
+// ProductSource 返回待校验的产品来源。
+func ProductSource(productCode string) EventSource {
+	return EventSource{Scope: EventSourceScopeProduct, ProductCode: productCode}
+}
+
+// PlatformAudience 返回仅平台可见的受众。
+func PlatformAudience() EventAudience {
+	return EventAudience{Scope: AudienceScopePlatform, ProductCodes: cloneProductCodes(nil)}
+}
+
+// SourceProductAudience 返回平台与来源产品可见的受众。
+func SourceProductAudience() EventAudience {
+	return EventAudience{Scope: AudienceScopeSourceProduct, ProductCodes: cloneProductCodes(nil)}
+}
+
+// ProductsAudience 返回待归一化的明确产品受众。
+func ProductsAudience(productCodes ...string) EventAudience {
+	return EventAudience{Scope: AudienceScopeProducts, ProductCodes: cloneProductCodes(productCodes)}
+}
+
+func cloneProductCodes(productCodes []string) []string {
+	return append(make([]string, 0, len(productCodes)), productCodes...)
+}
+
+// Normalize 校验并归一化事件来源。
+func (s EventSource) Normalize() (EventSource, error) {
+	if s.Scope == "" && strings.TrimSpace(s.ProductCode) == "" {
+		return PlatformSource(), nil
+	}
+	switch s.Scope {
+	case EventSourceScopePlatform:
+		if strings.TrimSpace(s.ProductCode) != "" {
+			return EventSource{}, fmt.Errorf("platform event source cannot contain a product code")
+		}
+		return PlatformSource(), nil
+	case EventSourceScopeProduct:
+		productCode, err := productcode.Normalize(s.ProductCode)
+		if err != nil {
+			return EventSource{}, fmt.Errorf("normalize event source product code: %w", err)
+		}
+		return ProductSource(productCode), nil
+	default:
+		return EventSource{}, fmt.Errorf("unsupported event source scope %q", s.Scope)
+	}
+}
+
+// Normalize 校验并归一化事件受众。
+func (a EventAudience) Normalize(source EventSource) (EventAudience, error) {
+	if a.Scope == "" && len(a.ProductCodes) == 0 {
+		return PlatformAudience(), nil
+	}
+	switch a.Scope {
+	case AudienceScopePlatform:
+		if len(a.ProductCodes) != 0 {
+			return EventAudience{}, fmt.Errorf("platform audience cannot contain product codes")
+		}
+		return PlatformAudience(), nil
+	case AudienceScopeSourceProduct:
+		if source.Scope != EventSourceScopeProduct || len(a.ProductCodes) != 0 {
+			return EventAudience{}, fmt.Errorf("source_product audience requires a product event source and no product list")
+		}
+		return SourceProductAudience(), nil
+	case AudienceScopeProducts:
+		if len(a.ProductCodes) == 0 {
+			return EventAudience{}, fmt.Errorf("products audience requires at least one product code")
+		}
+		seen := make(map[string]struct{}, len(a.ProductCodes))
+		productCodes := make([]string, 0, len(a.ProductCodes))
+		for _, value := range a.ProductCodes {
+			productCode, err := productcode.Normalize(value)
+			if err != nil {
+				return EventAudience{}, fmt.Errorf("normalize event audience product code: %w", err)
+			}
+			if _, exists := seen[productCode]; exists {
+				return EventAudience{}, fmt.Errorf("products audience contains duplicate product code %q", productCode)
+			}
+			seen[productCode] = struct{}{}
+			productCodes = append(productCodes, productCode)
+		}
+		sort.Strings(productCodes)
+		return EventAudience{Scope: AudienceScopeProducts, ProductCodes: productCodes}, nil
+	default:
+		return EventAudience{}, fmt.Errorf("unsupported event audience scope %q", a.Scope)
+	}
+}
+
+// PermanentDeliveryError 表示重复投递无法改变结果，Relay 应立即进入死信。
+type PermanentDeliveryError interface {
+	error
+	PermanentDelivery() bool
+}
+
+type permanentDeliveryError struct {
+	cause error
+}
+
+func (e *permanentDeliveryError) Error() string { return e.cause.Error() }
+func (e *permanentDeliveryError) Unwrap() error { return e.cause }
+func (e *permanentDeliveryError) PermanentDelivery() bool {
+	return true
+}
+
+// MarkPermanentDelivery 将不可重试的处理失败标记为永久投递错误。
+func MarkPermanentDelivery(err error) error {
+	if err == nil || IsPermanentDeliveryError(err) {
+		return err
+	}
+	return &permanentDeliveryError{cause: err}
+}
+
+// IsPermanentDeliveryError 判断事件处理失败是否应立即进入死信。
+func IsPermanentDeliveryError(err error) bool {
+	var permanent PermanentDeliveryError
+	return errors.As(err, &permanent) && permanent.PermanentDelivery()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Outbox 事件实体
+// ═══════════════════════════════════════════════════════════════
+
+// OutboxEvent Outbox 事件持久化实体，映射 sys_outbox_events 表
+type OutboxEvent struct {
+	// 事件唯一标识
+	ID string `gorm:"column:id;type:uuid;default:gen_random_uuid();primaryKey;comment:事件唯一标识"`
+	// OutboxRef 是 outbox 记录自身的稳定引用，与事件 ID 语义隔离。
+	OutboxRef string `gorm:"column:outbox_ref;type:varchar(80);not null;uniqueIndex:uk_sys_outbox_events_outbox_ref;comment:Outbox 记录引用"`
+	// 聚合根类型
+	AggregateType string `gorm:"column:aggregate_type;type:varchar(100);not null;comment:聚合根类型"`
+	// 聚合根 ID
+	AggregateID string `gorm:"column:aggregate_id;type:varchar(100);not null;comment:聚合根 ID"`
+	// AggregateVersion 仅由声明了版本合同的事件生产者固化；无版本合同的事件保持为空。
+	AggregateVersion *int64 `gorm:"column:aggregate_version;type:bigint;comment:聚合版本"`
+	// SourceProductCode 固化产品来源；平台来源事件为空。
+	SourceProductCode *string `gorm:"column:source_product_code;type:varchar(50);comment:来源产品编码"`
+	// AudienceScope 固化事件创建时的受众策略。
+	AudienceScope AudienceScope `gorm:"column:audience_scope;type:varchar(24);not null;comment:受众范围"`
+	// AudienceProductCodes 固化 products 受众的有序 Product 集合。
+	AudienceProductCodes datatypes.JSONSlice[string] `gorm:"column:audience_product_codes;type:jsonb;not null;comment:受众产品编码"`
+	// 事件类型
+	EventType string `gorm:"column:event_type;type:varchar(200);not null;comment:事件类型"`
+	// 事件产生时绑定的 Integration Event schema 版本
+	SchemaVersion *string `gorm:"column:schema_version;type:varchar(40);->;comment:事件产生时绑定的 Integration Event schema 版本"`
+	// 事件载荷（JSON）
+	Payload []byte `gorm:"column:payload;type:jsonb;not null;comment:事件载荷"`
+	// 事件元数据（JSON）
+	Metadata []byte `gorm:"column:metadata;type:jsonb;comment:事件元数据"`
+	// 审计变更信封（JSON）— CloudTrail 风格一等公民列，对应 DomainEvent.AuditChanges
+	AuditChanges []byte `gorm:"column:audit_changes;type:jsonb;comment:审计变更信封"`
+	// 审计元信息信封（JSON）— 对应 DomainEvent.AuditMeta
+	AuditMeta []byte `gorm:"column:audit_meta;type:jsonb;comment:审计元信息信封"`
+	// 事件发生时间
+	OccurredAt time.Time `gorm:"column:occurred_at;type:timestamptz(3);not null;default:now();comment:事件发生时间"`
+	// 记录创建时间
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamptz(3);not null;default:now();comment:创建时间"`
+	// 处理状态：pending / dispatched / retry_pending / dead_letter
+	Status string `gorm:"column:status;type:varchar(20);not null;default:'pending';comment:处理状态"`
+	// 锁定时间（Relay 处理期间设置）
+	LockedAt *time.Time `gorm:"column:locked_at;type:timestamptz(3);comment:锁定时间"`
+	// 锁定者标识（Relay 实例 ID）
+	LockedBy *string `gorm:"column:locked_by;type:varchar(100);comment:锁定者"`
+	// 已重试次数
+	RetryCount int `gorm:"column:retry_count;type:smallint;not null;default:0;comment:重试次数"`
+	// 最大重试次数
+	MaxRetries int `gorm:"column:max_retries;type:smallint;not null;default:10;comment:最大重试次数"`
+	// 下次重试时间
+	NextRetryAt *time.Time `gorm:"column:next_retry_at;type:timestamptz(3);comment:下次重试时间"`
+	// 最后错误信息
+	LastError *string `gorm:"column:last_error;type:text;comment:最后错误信息"`
+}
+
+// TableName GORM 表名映射
+func (OutboxEvent) TableName() string { return "sys_outbox_events" }
+
+// OutboxEventDelivery Outbox 事件按目标拆分的投递状态，映射 sys_outbox_event_deliveries 表
+type OutboxEventDelivery struct {
+	// 事件唯一标识
+	EventID string `gorm:"column:event_id;type:uuid;primaryKey;comment:事件唯一标识"`
+	// 投递目标
+	Target string `gorm:"column:target;type:varchar(40);primaryKey;comment:投递目标"`
+	// 处理状态：pending / dispatched / retry_pending / dead_letter
+	Status string `gorm:"column:status;type:varchar(20);not null;default:'pending';comment:处理状态"`
+	// 已重试次数
+	RetryCount int `gorm:"column:retry_count;type:smallint;not null;default:0;comment:重试次数"`
+	// 最大重试次数
+	MaxRetries int `gorm:"column:max_retries;type:smallint;not null;default:10;comment:最大重试次数"`
+	// 下次重试时间
+	NextRetryAt *time.Time `gorm:"column:next_retry_at;type:timestamptz(3);comment:下次重试时间"`
+	// 最后错误信息
+	LastError *string `gorm:"column:last_error;type:text;comment:最后错误信息"`
+	// 投递完成时间
+	DispatchedAt *time.Time `gorm:"column:dispatched_at;type:timestamptz(3);comment:投递完成时间"`
+	// 锁定时间
+	LockedAt *time.Time `gorm:"column:locked_at;type:timestamptz(3);comment:锁定时间"`
+	// 锁定者标识
+	LockedBy *string `gorm:"column:locked_by;type:varchar(100);comment:锁定者"`
+	// 记录创建时间
+	CreatedAt time.Time `gorm:"column:created_at;type:timestamptz(3);not null;default:now();autoCreateTime:milli;comment:创建时间"`
+	// 记录更新时间
+	UpdatedAt time.Time `gorm:"column:updated_at;type:timestamptz(3);not null;default:now();autoUpdateTime:milli;comment:更新时间"`
+}
+
+// TableName GORM 表名映射
+func (OutboxEventDelivery) TableName() string { return "sys_outbox_event_deliveries" }
+
+// ═══════════════════════════════════════════════════════════════
+// 服务层写入事件参数
+// ═══════════════════════════════════════════════════════════════
+
+// Event 服务层写入 outbox 的事件参数
+type Event struct {
+	// 事件唯一标识；为空时由数据库生成
+	ID string
+	// 聚合根类型（如 "identity"、"order"）
+	AggregateType string
+	// 聚合根 ID
+	AggregateID string
+	// AggregateVersion 聚合版本；零表示该事件没有版本合同。
+	AggregateVersion int64
+	// Source 是事件权威来源。
+	Source EventSource
+	// Audience 是事件写入时冻结的受众事实。
+	Audience EventAudience
+	// 事件类型（如 "identity.created"）
+	EventType string
+	// 事件载荷，序列化为 JSON 存储
+	// any: 接受任意可 JSON 序列化的结构体
+	Payload any
+	// 事件元数据
+	Metadata map[string]any
+	// 审计变更快照（可选，仅写操作需要）— 写入 sys_outbox_events.audit_changes 顶层列（CloudTrail 信封）
+	AuditChanges *eventbus.AuditChangesPayload
+	// 审计扩展元数据（可选）— 写入 sys_outbox_events.audit_meta 顶层列
+	AuditMeta *eventbus.AuditMetadataPayload
+}

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

@@ -0,0 +1,77 @@
+package outbox
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestEventSourceNormalize(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		source  EventSource
+		want    EventSource
+		wantErr bool
+	}{
+		{name: "zero is platform", want: PlatformSource()},
+		{name: "platform", source: PlatformSource(), want: PlatformSource()},
+		{name: "product", source: ProductSource(" product_alpha "), want: ProductSource("product_alpha")},
+		{name: "platform with product", source: EventSource{Scope: EventSourceScopePlatform, ProductCode: "product_alpha"}, wantErr: true},
+		{name: "product without code", source: EventSource{Scope: EventSourceScopeProduct}, wantErr: true},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := test.source.Normalize()
+			if test.wantErr {
+				if err == nil {
+					t.Fatal("normalize() expected error")
+				}
+				return
+			}
+			if err != nil || got != test.want {
+				t.Fatalf("normalize() = %#v, %v; want %#v", got, err, test.want)
+			}
+		})
+	}
+}
+
+func TestEventAudienceNormalize(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		audience EventAudience
+		source   EventSource
+		want     EventAudience
+		wantErr  bool
+	}{
+		{name: "zero nil is platform with empty product codes", source: PlatformSource(), want: PlatformAudience()},
+		{name: "platform nil becomes empty product codes", source: PlatformSource(), audience: EventAudience{Scope: AudienceScopePlatform}, want: PlatformAudience()},
+		{name: "platform empty remains empty product codes", source: PlatformSource(), audience: EventAudience{Scope: AudienceScopePlatform, ProductCodes: []string{}}, want: PlatformAudience()},
+		{name: "source product nil becomes empty product codes", source: ProductSource("product_alpha"), audience: EventAudience{Scope: AudienceScopeSourceProduct}, want: SourceProductAudience()},
+		{name: "source product empty remains empty product codes", source: ProductSource("product_alpha"), audience: EventAudience{Scope: AudienceScopeSourceProduct, ProductCodes: []string{}}, want: SourceProductAudience()},
+		{name: "products sorted", source: PlatformSource(), audience: ProductsAudience("product_beta", "product_alpha"), want: ProductsAudience("product_alpha", "product_beta")},
+		{name: "duplicate product", source: PlatformSource(), audience: ProductsAudience("product_alpha", "product_alpha"), wantErr: true},
+		{name: "source product without product source", source: PlatformSource(), audience: SourceProductAudience(), wantErr: true},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := test.audience.Normalize(test.source)
+			if test.wantErr {
+				if err == nil {
+					t.Fatal("normalize() expected error")
+				}
+				return
+			}
+			if err != nil || !reflect.DeepEqual(got, test.want) {
+				t.Fatalf("normalize() = %#v, %v; want %#v", got, err, test.want)
+			}
+			if got.ProductCodes == nil {
+				t.Fatal("normalize() returned nil product codes")
+			}
+		})
+	}
+}

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

@@ -0,0 +1,51 @@
+package outbox
+
+import (
+	"time"
+
+	"gorm.io/datatypes"
+)
+
+type outboxEventInsert struct {
+	ID                   string                      `gorm:"column:id;type:uuid;default:gen_random_uuid();primaryKey"`
+	OutboxRef            string                      `gorm:"column:outbox_ref"`
+	AggregateType        string                      `gorm:"column:aggregate_type"`
+	AggregateID          string                      `gorm:"column:aggregate_id"`
+	AggregateVersion     *int64                      `gorm:"column:aggregate_version"`
+	SourceProductCode    *string                     `gorm:"column:source_product_code"`
+	AudienceScope        AudienceScope               `gorm:"column:audience_scope"`
+	AudienceProductCodes datatypes.JSONSlice[string] `gorm:"column:audience_product_codes;type:jsonb"`
+	EventType            string                      `gorm:"column:event_type"`
+	Payload              datatypes.JSON              `gorm:"column:payload;type:jsonb"`
+	Metadata             datatypes.JSON              `gorm:"column:metadata;type:jsonb"`
+	AuditChanges         datatypes.JSON              `gorm:"column:audit_changes;type:jsonb"`
+	AuditMeta            datatypes.JSON              `gorm:"column:audit_meta;type:jsonb"`
+	OccurredAt           time.Time                   `gorm:"column:occurred_at"`
+	Status               string                      `gorm:"column:status"`
+	RetryCount           int                         `gorm:"column:retry_count"`
+	MaxRetries           int                         `gorm:"column:max_retries"`
+}
+
+func (outboxEventInsert) TableName() string { return "sys_outbox_events" }
+
+func newOutboxEventInsert(event *OutboxEvent) *outboxEventInsert {
+	return &outboxEventInsert{
+		ID:                   event.ID,
+		OutboxRef:            event.OutboxRef,
+		AggregateType:        event.AggregateType,
+		AggregateID:          event.AggregateID,
+		AggregateVersion:     event.AggregateVersion,
+		SourceProductCode:    event.SourceProductCode,
+		AudienceScope:        event.AudienceScope,
+		AudienceProductCodes: event.AudienceProductCodes,
+		EventType:            event.EventType,
+		Payload:              datatypes.JSON(event.Payload),
+		Metadata:             datatypes.JSON(event.Metadata),
+		AuditChanges:         datatypes.JSON(event.AuditChanges),
+		AuditMeta:            datatypes.JSON(event.AuditMeta),
+		OccurredAt:           event.OccurredAt,
+		Status:               event.Status,
+		RetryCount:           event.RetryCount,
+		MaxRetries:           event.MaxRetries,
+	}
+}

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

@@ -0,0 +1,23 @@
+package outbox
+
+import "github.com/google/wire"
+
+// ProviderSet Outbox 基础设施 Wire 依赖注入集合
+//
+// 提供以下依赖：
+//   - *Writer — Outbox 事件写入器（事务内使用）
+//   - *Rescheduler — Outbox 事件重入队器（后台人工恢复使用）
+//   - *Relay — Outbox 事件中继器（后台轮询 + 分发）
+//
+// 前置依赖：
+//   - *gorm.DB — 数据库连接
+//   - *zap.Logger — 结构化日志
+//   - *eventbus.EventBus — 进程内事件总线
+//   - *queue.Client — 任务队列客户端（跨进程转发）
+//   - eventstream.EventStreamPublisher — 事件流发布器（可为 nil，禁用 Stream 分发）
+//   - RelayConfig — Relay 配置（由各 cmd/ 通过 Provide 函数提供）
+var ProviderSet = wire.NewSet(
+	NewWriter,
+	NewRescheduler,
+	NewRelay,
+)