@stackonward/cli 0.0.1 → 1.0.1

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

@@ -0,0 +1,164 @@
+package outbox
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"{{module}}/internal/core/database"
+)
+
+// RequeueLatestRequest 定位需要重新入队的最新 outbox 事件。
+type RequeueLatestRequest struct {
+	AggregateType string
+	AggregateID   string
+	EventType     string
+}
+
+// Rescheduler 提供受控 outbox 重入队能力。
+type Rescheduler struct {
+	db        *gorm.DB
+	txManager *database.TransactionManager
+	logger    *zap.Logger
+}
+
+// NewRescheduler 创建 Outbox 重入队器。
+func NewRescheduler(db *gorm.DB, logger *zap.Logger) *Rescheduler {
+	return &Rescheduler{
+		db:        db,
+		txManager: database.NewTransactionManager(db),
+		logger:    logger.Named("OutboxRescheduler"),
+	}
+}
+
+// RequeueLatest 将指定聚合事件的最新 outbox 记录恢复为 pending。
+func (r *Rescheduler) RequeueLatest(ctx context.Context, req RequeueLatestRequest) (bool, error) {
+	aggregateType := strings.TrimSpace(req.AggregateType)
+	aggregateID := strings.TrimSpace(req.AggregateID)
+	eventType := strings.TrimSpace(req.EventType)
+	if aggregateType == "" {
+		return false, fmt.Errorf("aggregate_type is required")
+	}
+	if aggregateID == "" {
+		return false, fmt.Errorf("aggregate_id is required")
+	}
+	if eventType == "" {
+		return false, fmt.Errorf("event_type is required")
+	}
+
+	var requeued bool
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		tx := database.GetDB(txCtx, r.db)
+		var event OutboxEvent
+		findErr := tx.
+			Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("aggregate_type = ? AND aggregate_id = ? AND event_type = ?", aggregateType, aggregateID, eventType).
+			Order("created_at DESC, occurred_at DESC").
+			First(&event).Error
+		if findErr != nil {
+			if errors.Is(findErr, gorm.ErrRecordNotFound) {
+				return nil
+			}
+			return fmt.Errorf("find latest outbox event: %w", findErr)
+		}
+		if event.Status == StatusLocked {
+			return ErrEventLocked
+		}
+
+		ok, requeueErr := r.requeueLockedEvent(tx, event)
+		if requeueErr != nil {
+			return requeueErr
+		}
+		requeued = ok
+		return nil
+	})
+	if err != nil {
+		return false, err
+	}
+	return requeued, nil
+}
+
+// RequeueByID 将指定 outbox 记录恢复为 pending。
+func (r *Rescheduler) RequeueByID(ctx context.Context, id string) (bool, error) {
+	eventID := strings.TrimSpace(id)
+	if eventID == "" {
+		return false, fmt.Errorf("id is required")
+	}
+
+	var requeued bool
+	err := r.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		tx := database.GetDB(txCtx, r.db)
+		var event OutboxEvent
+		findErr := tx.
+			Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("CAST(id AS text) = ?", eventID).
+			First(&event).Error
+		if findErr != nil {
+			if errors.Is(findErr, gorm.ErrRecordNotFound) {
+				return nil
+			}
+			return fmt.Errorf("find outbox event: %w", findErr)
+		}
+		if event.Status == StatusLocked {
+			return ErrEventLocked
+		}
+
+		ok, requeueErr := r.requeueLockedEvent(tx, event)
+		if requeueErr != nil {
+			return requeueErr
+		}
+		requeued = ok
+		return nil
+	})
+	if err != nil {
+		return false, err
+	}
+	return requeued, nil
+}
+
+func (r *Rescheduler) requeueLockedEvent(tx *gorm.DB, event OutboxEvent) (bool, error) {
+	result := tx.Model(&OutboxEvent{}).
+		Where("id = ?", event.ID).
+		Updates(map[string]any{
+			"status":        StatusPending,
+			"locked_at":     nil,
+			"locked_by":     nil,
+			"retry_count":   0,
+			"next_retry_at": nil,
+			"last_error":    nil,
+		})
+	if result.Error != nil {
+		return false, fmt.Errorf("requeue outbox event: %w", result.Error)
+	}
+	requeued := result.RowsAffected > 0
+	if requeued {
+		now := time.Now()
+		if err := tx.Model(&OutboxEventDelivery{}).
+			Where("event_id = ?", event.ID).
+			Updates(map[string]any{
+				"status":        StatusPending,
+				"retry_count":   0,
+				"next_retry_at": nil,
+				"last_error":    nil,
+				"dispatched_at": nil,
+				"locked_at":     nil,
+				"locked_by":     nil,
+				"updated_at":    now,
+			}).Error; err != nil {
+			return false, fmt.Errorf("requeue outbox delivery targets: %w", err)
+		}
+		if notifyErr := tx.Exec("SELECT pg_notify('outbox_events', ?)", event.AggregateType).Error; notifyErr != nil {
+			r.logger.Debug("pg_notify failed, relay will poll",
+				zap.String("aggregateType", event.AggregateType),
+				zap.Error(notifyErr),
+			)
+		}
+	}
+	return requeued, nil
+}

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

@@ -0,0 +1,209 @@
+package outbox
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+)
+
+func TestReschedulerRequeuesLatestMatchingEvent(t *testing.T) {
+	db := openOutboxReschedulerTestDB(t)
+	now := time.Now()
+	lastErr := "handler failed"
+	nextRetry := now.Add(time.Minute)
+	lockedBy := "relay-1"
+
+	older := OutboxEvent{
+		ID:            "00000000-0000-0000-0000-000000000001",
+		OutboxRef:     "obx_00000000000000000000000000000001",
+		AggregateType: "mediagen.generation",
+		AggregateID:   "vgn_1",
+		EventType:     "mediagen.generation.submitted",
+		Payload:       []byte(`{"external_id":"vgn_1"}`),
+		OccurredAt:    now.Add(-2 * time.Hour),
+		CreatedAt:     now.Add(-2 * time.Hour),
+		Status:        StatusDispatched,
+		MaxRetries:    10,
+	}
+	latest := OutboxEvent{
+		ID:            "00000000-0000-0000-0000-000000000002",
+		OutboxRef:     "obx_00000000000000000000000000000002",
+		AggregateType: "mediagen.generation",
+		AggregateID:   "vgn_1",
+		EventType:     "mediagen.generation.submitted",
+		Payload:       []byte(`{"external_id":"vgn_1","attempt":2}`),
+		OccurredAt:    now.Add(-time.Hour),
+		CreatedAt:     now.Add(-time.Hour),
+		Status:        StatusDeadLetter,
+		LockedAt:      &now,
+		LockedBy:      &lockedBy,
+		RetryCount:    7,
+		MaxRetries:    10,
+		NextRetryAt:   &nextRetry,
+		LastError:     &lastErr,
+	}
+	require.NoError(t, db.Create(&older).Error)
+	require.NoError(t, db.Create(&latest).Error)
+
+	rescheduler := NewRescheduler(db, zap.NewNop())
+	ok, err := rescheduler.RequeueLatest(context.Background(), RequeueLatestRequest{
+		AggregateType: "mediagen.generation",
+		AggregateID:   "vgn_1",
+		EventType:     "mediagen.generation.submitted",
+	})
+	require.NoError(t, err)
+	require.True(t, ok)
+
+	var gotLatest OutboxEvent
+	require.NoError(t, db.First(&gotLatest, "id = ?", latest.ID).Error)
+	require.Equal(t, StatusPending, gotLatest.Status)
+	require.Zero(t, gotLatest.RetryCount)
+	require.Nil(t, gotLatest.LockedAt)
+	require.Nil(t, gotLatest.LockedBy)
+	require.Nil(t, gotLatest.NextRetryAt)
+	require.Nil(t, gotLatest.LastError)
+
+	var gotOlder OutboxEvent
+	require.NoError(t, db.First(&gotOlder, "id = ?", older.ID).Error)
+	require.Equal(t, StatusDispatched, gotOlder.Status)
+}
+
+func TestReschedulerRejectsLockedLatestEvent(t *testing.T) {
+	db := openOutboxReschedulerTestDB(t)
+	now := time.Now()
+	event := OutboxEvent{
+		ID:            "00000000-0000-0000-0000-000000000003",
+		OutboxRef:     "obx_00000000000000000000000000000003",
+		AggregateType: "mediagen.generation",
+		AggregateID:   "vgn_locked",
+		EventType:     "mediagen.generation.submitted",
+		Payload:       []byte(`{"external_id":"vgn_locked"}`),
+		OccurredAt:    now,
+		CreatedAt:     now,
+		Status:        StatusLocked,
+		MaxRetries:    10,
+	}
+	require.NoError(t, db.Create(&event).Error)
+
+	rescheduler := NewRescheduler(db, zap.NewNop())
+	ok, err := rescheduler.RequeueLatest(context.Background(), RequeueLatestRequest{
+		AggregateType: "mediagen.generation",
+		AggregateID:   "vgn_locked",
+		EventType:     "mediagen.generation.submitted",
+	})
+	require.ErrorIs(t, err, ErrEventLocked)
+	require.False(t, ok)
+}
+
+func TestReschedulerRequeuesEventByID(t *testing.T) {
+	db := openOutboxReschedulerTestDB(t)
+	now := time.Now()
+	lastErr := "dead letter"
+	nextRetry := now.Add(time.Hour)
+	event := OutboxEvent{
+		ID:            "00000000-0000-0000-0000-000000000004",
+		OutboxRef:     "obx_00000000000000000000000000000004",
+		AggregateType: "iam.credential",
+		AggregateID:   "credential_1",
+		EventType:     "iam.credential.revoked",
+		Payload:       []byte(`{"credential_id":1}`),
+		OccurredAt:    now,
+		CreatedAt:     now,
+		Status:        StatusDeadLetter,
+		RetryCount:    5,
+		MaxRetries:    10,
+		NextRetryAt:   &nextRetry,
+		LastError:     &lastErr,
+	}
+	require.NoError(t, db.Create(&event).Error)
+
+	rescheduler := NewRescheduler(db, zap.NewNop())
+	ok, err := rescheduler.RequeueByID(context.Background(), event.ID)
+	require.NoError(t, err)
+	require.True(t, ok)
+
+	var got OutboxEvent
+	require.NoError(t, db.First(&got, "id = ?", event.ID).Error)
+	require.Equal(t, StatusPending, got.Status)
+	require.Zero(t, got.RetryCount)
+	require.Nil(t, got.NextRetryAt)
+	require.Nil(t, got.LastError)
+}
+
+func TestReschedulerRejectsLockedEventByID(t *testing.T) {
+	db := openOutboxReschedulerTestDB(t)
+	now := time.Now()
+	event := OutboxEvent{
+		ID:            "00000000-0000-0000-0000-000000000005",
+		OutboxRef:     "obx_00000000000000000000000000000005",
+		AggregateType: "iam.credential",
+		AggregateID:   "credential_locked",
+		EventType:     "iam.credential.revoked",
+		Payload:       []byte(`{"credential_id":5}`),
+		OccurredAt:    now,
+		CreatedAt:     now,
+		Status:        StatusLocked,
+		MaxRetries:    10,
+	}
+	require.NoError(t, db.Create(&event).Error)
+
+	rescheduler := NewRescheduler(db, zap.NewNop())
+	ok, err := rescheduler.RequeueByID(context.Background(), event.ID)
+	require.ErrorIs(t, err, ErrEventLocked)
+	require.False(t, ok)
+}
+
+func openOutboxReschedulerTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	require.NoError(t, err)
+	require.NoError(t, db.Exec(`
+		CREATE TABLE sys_outbox_events (
+			id TEXT PRIMARY KEY,
+			outbox_ref TEXT NOT NULL UNIQUE,
+			aggregate_type TEXT NOT NULL,
+			aggregate_id TEXT NOT NULL,
+			aggregate_version INTEGER,
+			source_product_code TEXT,
+			audience_scope TEXT NOT NULL,
+			audience_product_codes BLOB NOT NULL,
+			event_type TEXT NOT NULL,
+			payload BLOB NOT NULL,
+			metadata BLOB,
+			audit_changes BLOB,
+			audit_meta BLOB,
+			occurred_at DATETIME NOT NULL,
+			created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+			status TEXT NOT NULL,
+			locked_at DATETIME,
+			locked_by TEXT,
+			retry_count INTEGER NOT NULL DEFAULT 0,
+			max_retries INTEGER NOT NULL DEFAULT 10,
+			next_retry_at DATETIME,
+			last_error TEXT
+		)
+	`).Error)
+	require.NoError(t, db.Exec(`
+		CREATE TABLE sys_outbox_event_deliveries (
+			event_id TEXT NOT NULL,
+			target TEXT NOT NULL,
+			status TEXT NOT NULL,
+			retry_count INTEGER NOT NULL DEFAULT 0,
+			max_retries INTEGER NOT NULL DEFAULT 10,
+			next_retry_at DATETIME,
+			last_error TEXT,
+			dispatched_at DATETIME,
+			locked_at DATETIME,
+			locked_by TEXT,
+			created_at DATETIME NOT NULL,
+			updated_at DATETIME NOT NULL,
+			PRIMARY KEY (event_id, target)
+		)
+	`).Error)
+	return db
+}

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

@@ -0,0 +1,249 @@
+package outbox
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+	"gorm.io/datatypes"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"{{module}}/internal/core/database"
+	"{{module}}/internal/core/eventbus"
+)
+
+// Writer Outbox 写入器，在 GORM 事务内将领域事件写入 sys_outbox_events 表
+type Writer struct {
+	db     *gorm.DB
+	logger *zap.Logger
+}
+
+// NewWriter 创建 Outbox 写入器
+func NewWriter(db *gorm.DB, logger *zap.Logger) *Writer {
+	return &Writer{
+		db:     db,
+		logger: logger.Named("OutboxWriter"),
+	}
+}
+
+// Write 在当前事务内写入单个 outbox 事件
+//
+// 必须在 TransactionManager.WithTransaction 回调内调用，
+// 以确保事件写入与业务数据变更在同一事务中原子提交。
+// pg_notify 在事务内调用，仅在 COMMIT 时触发通知。
+func (w *Writer) Write(ctx context.Context, event Event) error {
+	event.ID = strings.TrimSpace(event.ID)
+	if event.ID != "" {
+		parsedID, err := uuid.Parse(event.ID)
+		if err != nil {
+			return fmt.Errorf("parse outbox event ID: %w", err)
+		}
+		event.ID = parsedID.String()
+	}
+	payloadJSON, err := json.Marshal(event.Payload)
+	if err != nil {
+		return fmt.Errorf("marshal outbox payload: %w", err)
+	}
+
+	// 如果调用方未显式提供元数据，从 context 自动回填（EventMetadataInjector 中间件
+	// 已把 HTTP 请求上下文 IP/UA/DeviceID/RequestID/ProductCode 注入 ctx）。
+	// 对齐 Stripe SDK 客户端上下文传播：request envelope 在 SDK 层自动携带，publisher
+	// 无需每个调用点手动塞 Metadata —— 让反欺诈 / 审计 / 归因信号统一可达。
+	metadata := event.Metadata
+	if metadata == nil {
+		metadata = metadataFromContextAsMap(ctx)
+	}
+	source, err := event.Source.Normalize()
+	if err != nil {
+		return err
+	}
+	audience, err := event.Audience.Normalize(source)
+	if err != nil {
+		return err
+	}
+	if event.AggregateVersion < 0 {
+		return fmt.Errorf("aggregate_version must be positive")
+	}
+	var aggregateVersion *int64
+	if event.AggregateVersion > 0 {
+		aggregateVersion = &event.AggregateVersion
+	}
+
+	var metadataJSON []byte
+	if metadata != nil {
+		metadataJSON, err = json.Marshal(metadata)
+		if err != nil {
+			return fmt.Errorf("marshal outbox metadata: %w", err)
+		}
+	}
+
+	// 审计数据作为信封一等公民写入独立列（对齐 AWS CloudTrail），
+	// 禁止塞进业务 metadata —— metadata 语义是反欺诈/归因信号，不承担审计存储职责。
+	var auditChangesJSON []byte
+	if event.AuditChanges != nil {
+		auditChangesJSON, err = json.Marshal(event.AuditChanges)
+		if err != nil {
+			return fmt.Errorf("marshal outbox audit_changes: %w", err)
+		}
+	}
+	var auditMetaJSON []byte
+	if event.AuditMeta != nil {
+		auditMetaJSON, err = json.Marshal(event.AuditMeta)
+		if err != nil {
+			return fmt.Errorf("marshal outbox audit_meta: %w", err)
+		}
+	}
+
+	outboxEvent := &OutboxEvent{
+		ID:                   event.ID,
+		OutboxRef:            newOutboxRef(),
+		AggregateType:        event.AggregateType,
+		AggregateID:          event.AggregateID,
+		AggregateVersion:     aggregateVersion,
+		AudienceScope:        audience.Scope,
+		AudienceProductCodes: datatypes.NewJSONSlice(cloneProductCodes(audience.ProductCodes)),
+		EventType:            event.EventType,
+		Payload:              payloadJSON,
+		Metadata:             metadataJSON,
+		AuditChanges:         auditChangesJSON,
+		AuditMeta:            auditMetaJSON,
+		OccurredAt:           time.Now(),
+		Status:               StatusPending,
+		MaxRetries:           10,
+	}
+	if source.Scope == EventSourceScopeProduct {
+		outboxEvent.SourceProductCode = &source.ProductCode
+	}
+	insert := newOutboxEventInsert(outboxEvent)
+
+	tx := database.GetDB(ctx, w.db)
+	create := tx
+	if event.ID != "" {
+		create = create.Clauses(clause.OnConflict{Columns: []clause.Column{{Name: "id"}}, DoNothing: true})
+	}
+	result := create.Create(insert)
+	if result.Error != nil {
+		return fmt.Errorf("insert outbox event: %w", result.Error)
+	}
+	if event.ID != "" && result.RowsAffected == 0 {
+		if err := validateExistingOutboxEvent(tx, outboxEvent); err != nil {
+			return err
+		}
+		return nil
+	}
+	outboxEvent.ID = insert.ID
+	if outboxEvent.ID == "" {
+		return fmt.Errorf("insert outbox event returned an empty ID")
+	}
+
+	// 事务提交后才发送通知，通知失败时由 Relay 轮询兜底。
+	if notifyErr := tx.Exec("SELECT pg_notify('outbox_events', ?)", event.AggregateType).Error; notifyErr != nil {
+		w.logger.Debug("pg_notify failed, relay will poll",
+			zap.String("aggregateType", event.AggregateType),
+			zap.Error(notifyErr),
+		)
+	}
+
+	return nil
+}
+
+func newOutboxRef() string {
+	return "obx_" + strings.ReplaceAll(uuid.NewString(), "-", "")
+}
+
+func validateExistingOutboxEvent(tx *gorm.DB, expected *OutboxEvent) error {
+	var existing OutboxEvent
+	if err := tx.Select("id", "aggregate_type", "aggregate_id", "aggregate_version", "source_product_code", "audience_scope", "audience_product_codes", "event_type", "payload").
+		Where("id = ?", expected.ID).
+		Take(&existing).Error; err != nil {
+		return fmt.Errorf("load existing outbox event: %w", err)
+	}
+	if existing.AggregateType != expected.AggregateType ||
+		existing.AggregateID != expected.AggregateID ||
+		!equalOptionalInt64(existing.AggregateVersion, expected.AggregateVersion) ||
+		!equalOptionalString(existing.SourceProductCode, expected.SourceProductCode) ||
+		existing.AudienceScope != expected.AudienceScope ||
+		!reflect.DeepEqual(existing.AudienceProductCodes, expected.AudienceProductCodes) ||
+		existing.EventType != expected.EventType ||
+		!jsonDocumentsEqual(existing.Payload, expected.Payload) {
+		return fmt.Errorf("outbox event ID %s is already bound to a different event", expected.ID)
+	}
+	return nil
+}
+
+func equalOptionalInt64(left, right *int64) bool {
+	if left == nil || right == nil {
+		return left == nil && right == nil
+	}
+	return *left == *right
+}
+
+func normalizeOptionalString(value *string) *string {
+	if value == nil {
+		return nil
+	}
+	trimmed := strings.TrimSpace(*value)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+func equalOptionalString(left, right *string) bool {
+	left = normalizeOptionalString(left)
+	right = normalizeOptionalString(right)
+	if left == nil || right == nil {
+		return left == nil && right == nil
+	}
+	return *left == *right
+}
+
+func jsonDocumentsEqual(left []byte, right []byte) bool {
+	// JSON 根值可能是对象、数组或标量，只能以任意值承载后再比较其语义结构。
+	var leftValue any
+	if err := json.Unmarshal(left, &leftValue); err != nil {
+		return false
+	}
+	var rightValue any
+	if err := json.Unmarshal(right, &rightValue); err != nil {
+		return false
+	}
+	return reflect.DeepEqual(leftValue, rightValue)
+}
+
+// WriteBatch 在当前事务内批量写入 outbox 事件
+func (w *Writer) WriteBatch(ctx context.Context, events []Event) error {
+	for i := range events {
+		if err := w.Write(ctx, events[i]); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// metadataFromContextAsMap 从 ctx 提取 EventMetadata 并转成 map 形态。
+//
+// 通过 JSON round-trip 保证与 relay 反序列化 (relay.go:395-404) 完全对称 ——
+// relay 将同一 JSON bytes Unmarshal 回 *EventMetadata，json tag 对齐即可。
+// 这种 struct↔map 转换的微小开销只在写入路径发生一次，可忽略。
+func metadataFromContextAsMap(ctx context.Context) map[string]any {
+	meta := eventbus.MetadataFromContext(ctx)
+	if meta == nil {
+		return nil
+	}
+	raw, err := json.Marshal(meta)
+	if err != nil {
+		return nil
+	}
+	var m map[string]any
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil
+	}
+	return m
+}