@stackonward/cli 1.3.3 → 1.5.0

package/dist/resources/templates/go-backend/internal/core/integrationevent/service_test.go

@@ -0,0 +1,433 @@
+package integrationevent
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestReceiverServiceProcessesContinuousVersionsAndReturnsDurableDuplicate(t *testing.T) {
+	service, repo, calls := newFakeReceiverService(t, "subscriber-a", nil)
+
+	first, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1,"nested":{"b":2,"a":1}}`)))
+	if err != nil {
+		t.Fatalf("Receive(version 1) error = %v", err)
+	}
+	if first.Outcome != ReceiptOutcomeProcessed {
+		t.Fatalf("Receive(version 1) outcome = %q, want processed", first.Outcome)
+	}
+	duplicate, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"nested":{"a":1,"b":2},"value":1}`)))
+	if err != nil {
+		t.Fatalf("Receive(duplicate) error = %v", err)
+	}
+	if duplicate.Outcome != ReceiptOutcomeDuplicate {
+		t.Fatalf("Receive(duplicate) outcome = %q, want duplicate", duplicate.Outcome)
+	}
+	second, err := service.Receive(context.Background(), fakeEnvelope("event-2", 2, json.RawMessage(`{"value":2}`)))
+	if err != nil {
+		t.Fatalf("Receive(version 2) error = %v", err)
+	}
+	if second.Outcome != ReceiptOutcomeProcessed {
+		t.Fatalf("Receive(version 2) outcome = %q, want processed", second.Outcome)
+	}
+	if *calls != 2 {
+		t.Fatalf("handler calls = %d, want 2", *calls)
+	}
+	checkpoint := repo.checkpoints[fakeCheckpointKey("subscriber-a")]
+	if checkpoint == nil || checkpoint.LastAggregateVersion != 2 || checkpoint.RevisionNo != 2 {
+		t.Fatalf("checkpoint = %#v, want version/revision 2", checkpoint)
+	}
+}
+
+func TestReceiverServiceRejectsGlobalIdentityWithDifferentEnvelope(t *testing.T) {
+	service, repo, calls := newFakeReceiverService(t, "subscriber-a", nil)
+	if _, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`))); err != nil {
+		t.Fatalf("Receive(first) error = %v", err)
+	}
+	_, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":2}`)))
+	if !errors.Is(err, ErrIdentityConflict) {
+		t.Fatalf("Receive(conflict) error = %v, want ErrIdentityConflict", err)
+	}
+	if *calls != 1 {
+		t.Fatalf("handler calls = %d, want 1", *calls)
+	}
+	if len(repo.inboxes) != 1 || len(repo.receipts) != 1 {
+		t.Fatalf("persistent counts = inbox %d receipt %d, want 1/1", len(repo.inboxes), len(repo.receipts))
+	}
+}
+
+func TestReceiverServiceVersionGapRollsBackInboxAndReceipt(t *testing.T) {
+	service, repo, calls := newFakeReceiverService(t, "subscriber-a", nil)
+	_, err := service.Receive(context.Background(), fakeEnvelope("event-2", 2, json.RawMessage(`{"value":2}`)))
+	var gap *VersionGapError
+	if !errors.As(err, &gap) || !IsRetryable(err) {
+		t.Fatalf("Receive(gap) error = %v, want retryable VersionGapError", err)
+	}
+	if gap.Expected != 1 || gap.Actual != 2 {
+		t.Fatalf("gap = %#v, want expected 1 actual 2", gap)
+	}
+	if len(repo.inboxes) != 0 || len(repo.receipts) != 0 || len(repo.checkpoints) != 0 {
+		t.Fatalf("gap persisted state: inbox=%d receipt=%d checkpoint=%d", len(repo.inboxes), len(repo.receipts), len(repo.checkpoints))
+	}
+	if *calls != 0 {
+		t.Fatalf("handler calls = %d, want 0", *calls)
+	}
+}
+
+func TestReceiverServiceRejectsOldUnprovenVersion(t *testing.T) {
+	service, repo, calls := newFakeReceiverService(t, "subscriber-a", nil)
+	if _, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`))); err != nil {
+		t.Fatalf("Receive(version 1) error = %v", err)
+	}
+	if _, err := service.Receive(context.Background(), fakeEnvelope("event-2", 2, json.RawMessage(`{"value":2}`))); err != nil {
+		t.Fatalf("Receive(version 2) error = %v", err)
+	}
+	_, err := service.Receive(context.Background(), fakeEnvelope("event-other", 1, json.RawMessage(`{"value":1}`)))
+	if !errors.Is(err, ErrVersionConflict) {
+		t.Fatalf("Receive(old) error = %v, want ErrVersionConflict", err)
+	}
+	if _, exists := repo.inboxes["source-a\x1fevent-other"]; exists {
+		t.Fatal("old unproven event inbox survived rollback")
+	}
+	if *calls != 2 {
+		t.Fatalf("handler calls = %d, want 2", *calls)
+	}
+}
+
+func TestReceiverServiceHandlerFailureRollsBackAllCoreState(t *testing.T) {
+	handlerErr := fakeRetryableHandlerError{cause: errors.New("projection unavailable")}
+	service, repo, calls := newFakeReceiverService(t, "subscriber-a", handlerErr)
+	_, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`)))
+	var receivedHandlerErr *HandlerError
+	if !errors.As(err, &receivedHandlerErr) || !errors.Is(err, handlerErr) || !IsRetryable(err) {
+		t.Fatalf("Receive(handler failure) error = %v, want retryable HandlerError", err)
+	}
+	if len(repo.inboxes) != 0 || len(repo.receipts) != 0 || len(repo.checkpoints) != 0 {
+		t.Fatalf("handler failure persisted state: inbox=%d receipt=%d checkpoint=%d", len(repo.inboxes), len(repo.receipts), len(repo.checkpoints))
+	}
+	if *calls != 1 {
+		t.Fatalf("handler calls = %d, want 1", *calls)
+	}
+}
+
+type fakeRetryableHandlerError struct {
+	cause error
+}
+
+func (e fakeRetryableHandlerError) Error() string { return e.cause.Error() }
+
+func (e fakeRetryableHandlerError) Unwrap() error { return e.cause }
+
+func (e fakeRetryableHandlerError) Retryable() bool { return true }
+
+func TestReceiverServiceKeepsSubscriberReceiptsAndCheckpointsIndependent(t *testing.T) {
+	repo := newFakeRepository()
+	txManager := &fakeTransactionManager{repo: repo}
+	first, firstCalls := newFakeReceiverServiceWithDependencies(t, repo, txManager, "subscriber-a")
+	second, secondCalls := newFakeReceiverServiceWithDependencies(t, repo, txManager, "subscriber-b")
+	envelope := fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`))
+
+	if _, err := first.Receive(context.Background(), envelope); err != nil {
+		t.Fatalf("first subscriber Receive() error = %v", err)
+	}
+	if _, err := second.Receive(context.Background(), envelope); err != nil {
+		t.Fatalf("second subscriber Receive() error = %v", err)
+	}
+	if len(repo.inboxes) != 1 || len(repo.receipts) != 2 || len(repo.checkpoints) != 2 {
+		t.Fatalf("persistent counts = inbox %d receipt %d checkpoint %d, want 1/2/2", len(repo.inboxes), len(repo.receipts), len(repo.checkpoints))
+	}
+	if *firstCalls != 1 || *secondCalls != 1 {
+		t.Fatalf("handler calls = %d/%d, want 1/1", *firstCalls, *secondCalls)
+	}
+}
+
+func TestReceiverServiceRequiresExactRegisteredHandler(t *testing.T) {
+	repo := newFakeRepository()
+	registry := NewHandlerRegistry()
+	service, err := NewReceiverService(repo, &fakeTransactionManager{repo: repo}, registry, ReceiverConfig{SubscriberCode: "subscriber-a"})
+	if err != nil {
+		t.Fatalf("NewReceiverService() error = %v", err)
+	}
+	_, err = service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`)))
+	if !errors.Is(err, ErrHandlerNotRegistered) {
+		t.Fatalf("Receive() error = %v, want ErrHandlerNotRegistered", err)
+	}
+	if len(repo.inboxes) != 0 {
+		t.Fatalf("unregistered event persisted %d inbox rows", len(repo.inboxes))
+	}
+}
+
+func TestReceiverServiceRejectsInvalidEnvelopeBeforeTransaction(t *testing.T) {
+	service, repo, calls := newFakeReceiverService(t, "subscriber-a", nil)
+	testCases := []struct {
+		name   string
+		mutate func(*Envelope)
+	}{
+		{name: "nonpositive version", mutate: func(envelope *Envelope) { envelope.AggregateVersion = 0 }},
+		{name: "invalid product code", mutate: func(envelope *Envelope) { envelope.ProductCode = "Product A" }},
+		{name: "non-object envelope", mutate: func(envelope *Envelope) { envelope.CanonicalEnvelope = json.RawMessage(`[]`) }},
+		{name: "invalid JSON", mutate: func(envelope *Envelope) { envelope.CanonicalEnvelope = json.RawMessage(`{"id":`) }},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			envelope := fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`))
+			testCase.mutate(&envelope)
+			_, err := service.Receive(context.Background(), envelope)
+			if !errors.Is(err, ErrEnvelopeInvalid) {
+				t.Fatalf("Receive() error = %v, want ErrEnvelopeInvalid", err)
+			}
+		})
+	}
+	if len(repo.inboxes) != 0 || *calls != 0 {
+		t.Fatalf("invalid envelopes changed state: inbox=%d handler_calls=%d", len(repo.inboxes), *calls)
+	}
+}
+
+func TestReceiverServiceAdvancesCheckpointForConsumerRegisteredNoOpHandler(t *testing.T) {
+	repo := newFakeRepository()
+	registry := NewHandlerRegistry()
+	if err := registry.Register(HandlerRegistration{
+		SourceSystem: "source-a", EventType: "resource.changed", SchemaVersion: "1.0.0",
+		Handler: HandlerFunc(func(context.Context, Envelope) error {
+			return nil
+		}),
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	service, err := NewReceiverService(
+		repo,
+		&fakeTransactionManager{repo: repo},
+		registry,
+		ReceiverConfig{SubscriberCode: "subscriber-a"},
+	)
+	if err != nil {
+		t.Fatalf("NewReceiverService() error = %v", err)
+	}
+	if _, err := service.Receive(context.Background(), fakeEnvelope("event-1", 1, json.RawMessage(`{"value":1}`))); err != nil {
+		t.Fatalf("Receive() error = %v", err)
+	}
+	checkpoint := repo.checkpoints[fakeCheckpointKey("subscriber-a")]
+	if checkpoint == nil || checkpoint.LastAggregateVersion != 1 || checkpoint.LastEventID != "event-1" {
+		t.Fatalf("checkpoint = %#v, want no-op event at version 1", checkpoint)
+	}
+}
+
+func TestHandlerRegistryRejectsDuplicateExactRegistration(t *testing.T) {
+	registry := NewHandlerRegistry()
+	registration := HandlerRegistration{
+		SourceSystem: "source-a", EventType: "resource.changed", SchemaVersion: "1.0.0",
+		Handler: HandlerFunc(func(context.Context, Envelope) error { return nil }),
+	}
+	if err := registry.Register(registration); err != nil {
+		t.Fatalf("Register(first) error = %v", err)
+	}
+	if err := registry.Register(registration); err == nil {
+		t.Fatal("Register(duplicate) error = nil, want duplicate rejection")
+	}
+}
+
+func newFakeReceiverService(t *testing.T, subscriberCode string, handlerErr error) (*ReceiverService, *fakeRepository, *int) {
+	t.Helper()
+	repo := newFakeRepository()
+	txManager := &fakeTransactionManager{repo: repo}
+	service, calls := newFakeReceiverServiceWithDependencies(t, repo, txManager, subscriberCode)
+	if handlerErr != nil {
+		registry := NewHandlerRegistry()
+		calls = new(int)
+		if err := registry.Register(HandlerRegistration{
+			SourceSystem: "source-a", EventType: "resource.changed", SchemaVersion: "1.0.0",
+			Handler: HandlerFunc(func(context.Context, Envelope) error {
+				(*calls)++
+				return handlerErr
+			}),
+		}); err != nil {
+			t.Fatalf("Register() error = %v", err)
+		}
+		var err error
+		service, err = NewReceiverService(repo, txManager, registry, ReceiverConfig{SubscriberCode: subscriberCode})
+		if err != nil {
+			t.Fatalf("NewReceiverService() error = %v", err)
+		}
+	}
+	return service, repo, calls
+}
+
+func newFakeReceiverServiceWithDependencies(t *testing.T, repo *fakeRepository, txManager *fakeTransactionManager, subscriberCode string) (*ReceiverService, *int) {
+	t.Helper()
+	registry := NewHandlerRegistry()
+	calls := new(int)
+	if err := registry.Register(HandlerRegistration{
+		SourceSystem: "source-a", EventType: "resource.changed", SchemaVersion: "1.0.0",
+		Handler: HandlerFunc(func(context.Context, Envelope) error {
+			(*calls)++
+			return nil
+		}),
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	service, err := NewReceiverService(repo, txManager, registry, ReceiverConfig{SubscriberCode: subscriberCode})
+	if err != nil {
+		t.Fatalf("NewReceiverService() error = %v", err)
+	}
+	service.now = func() time.Time { return time.Date(2026, 9, 14, 12, 0, 0, 0, time.UTC) }
+	return service, calls
+}
+
+func fakeEnvelope(eventID string, version int64, data json.RawMessage) Envelope {
+	raw := json.RawMessage(fmt.Sprintf(`{"specversion":"1.0","id":%q,"source":"source-a","type":"resource.changed","dataschema":"schema:1.0.0","aggregateversion":%d,"data":%s}`, eventID, version, data))
+	return Envelope{
+		SourceSystem:      "source-a",
+		EventID:           eventID,
+		EventType:         "resource.changed",
+		SchemaVersion:     "1.0.0",
+		ProductCode:       "product_a",
+		AggregateType:     "resource",
+		AggregateRef:      "resource-1",
+		AggregateVersion:  version,
+		CanonicalEnvelope: raw,
+	}
+}
+
+func fakeCheckpointKey(subscriberCode string) string {
+	return "source-a\x1f" + subscriberCode + "\x1fresource\x1fresource-1"
+}
+
+type fakeRepository struct {
+	nextID      int64
+	inboxes     map[string]*InboxRecord
+	receipts    map[string]*ReceiptRecord
+	checkpoints map[string]*AggregateCheckpoint
+}
+
+func newFakeRepository() *fakeRepository {
+	return &fakeRepository{
+		inboxes:     make(map[string]*InboxRecord),
+		receipts:    make(map[string]*ReceiptRecord),
+		checkpoints: make(map[string]*AggregateCheckpoint),
+	}
+}
+
+func (r *fakeRepository) CreateOrLoadInbox(_ context.Context, record *InboxRecord) (*InboxRecord, bool, error) {
+	key := record.SourceSystem + "\x1f" + record.EventID
+	if existing, found := r.inboxes[key]; found {
+		clone := *existing
+		clone.EventPayload = append(json.RawMessage(nil), existing.EventPayload...)
+		return &clone, false, nil
+	}
+	r.nextID++
+	clone := *record
+	clone.ID = r.nextID
+	clone.EventPayload = append(json.RawMessage(nil), record.EventPayload...)
+	r.inboxes[key] = &clone
+	returned := clone
+	return &returned, true, nil
+}
+
+func (r *fakeRepository) CreateOrLockReceipt(_ context.Context, record *ReceiptRecord) (*ReceiptRecord, bool, error) {
+	key := record.SourceSystem + "\x1f" + record.SubscriberCode + "\x1f" + record.EventID
+	if existing, found := r.receipts[key]; found {
+		clone := *existing
+		return &clone, false, nil
+	}
+	r.nextID++
+	clone := *record
+	clone.ID = r.nextID
+	r.receipts[key] = &clone
+	returned := clone
+	return &returned, true, nil
+}
+
+func (r *fakeRepository) LockAggregateScope(context.Context, string, string, string, string) error {
+	return nil
+}
+
+func (r *fakeRepository) FindCheckpointForUpdate(_ context.Context, sourceSystem, subscriberCode, aggregateType, aggregateRef string) (*AggregateCheckpoint, error) {
+	key := sourceSystem + "\x1f" + subscriberCode + "\x1f" + aggregateType + "\x1f" + aggregateRef
+	checkpoint := r.checkpoints[key]
+	if checkpoint == nil {
+		return nil, nil
+	}
+	clone := *checkpoint
+	return &clone, nil
+}
+
+func (r *fakeRepository) CreateCheckpoint(_ context.Context, checkpoint *AggregateCheckpoint) error {
+	key := checkpoint.SourceSystem + "\x1f" + checkpoint.SubscriberCode + "\x1f" + checkpoint.AggregateType + "\x1f" + checkpoint.AggregateRef
+	if _, exists := r.checkpoints[key]; exists {
+		return errors.New("checkpoint exists")
+	}
+	r.nextID++
+	clone := *checkpoint
+	clone.ID = r.nextID
+	r.checkpoints[key] = &clone
+	return nil
+}
+
+func (r *fakeRepository) AdvanceCheckpoint(_ context.Context, checkpoint *AggregateCheckpoint, expectedRevision int64) error {
+	key := checkpoint.SourceSystem + "\x1f" + checkpoint.SubscriberCode + "\x1f" + checkpoint.AggregateType + "\x1f" + checkpoint.AggregateRef
+	existing := r.checkpoints[key]
+	if existing == nil || existing.RevisionNo != expectedRevision {
+		return errors.New("checkpoint revision conflict")
+	}
+	clone := *checkpoint
+	r.checkpoints[key] = &clone
+	return nil
+}
+
+func (r *fakeRepository) MarkReceiptProcessed(_ context.Context, id int64, outcome ReceiptOutcome, processedAt time.Time) error {
+	for key, receipt := range r.receipts {
+		if receipt.ID != id {
+			continue
+		}
+		if receipt.Status != ReceiptProcessingStatusProcessing {
+			return errors.New("receipt is not processing")
+		}
+		clone := *receipt
+		clone.Status = ReceiptProcessingStatusProcessed
+		clone.ReceiptStatus = &outcome
+		clone.ProcessedAt = &processedAt
+		clone.UpdatedAt = processedAt
+		r.receipts[key] = &clone
+		return nil
+	}
+	return errors.New("receipt not found")
+}
+
+func (r *fakeRepository) clone() *fakeRepository {
+	clone := newFakeRepository()
+	clone.nextID = r.nextID
+	for key, record := range r.inboxes {
+		copied := *record
+		copied.EventPayload = append(json.RawMessage(nil), record.EventPayload...)
+		clone.inboxes[key] = &copied
+	}
+	for key, record := range r.receipts {
+		copied := *record
+		clone.receipts[key] = &copied
+	}
+	for key, record := range r.checkpoints {
+		copied := *record
+		clone.checkpoints[key] = &copied
+	}
+	return clone
+}
+
+type fakeTransactionManager struct {
+	mu   sync.Mutex
+	repo *fakeRepository
+}
+
+func (m *fakeTransactionManager) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	snapshot := m.repo.clone()
+	if err := fn(ctx); err != nil {
+		*m.repo = *snapshot
+		return err
+	}
+	return nil
+}

package/dist/resources/templates/go-backend/internal/core/integrationevent/types.go

@@ -0,0 +1,67 @@
+package integrationevent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+)
+
+// Envelope 是通过 transport 信任、schema 与字段一致性校验后的入站事件。
+// CanonicalEnvelope 必须包含完整事件信封对象；核心层负责 RFC 8785 规范化与摘要。
+type Envelope struct {
+	SourceSystem      string
+	EventID           string
+	EventType         string
+	SchemaVersion     string
+	ProductCode       string
+	AggregateType     string
+	AggregateRef      string
+	AggregateVersion  int64
+	CanonicalEnvelope json.RawMessage
+}
+
+// Handler 由消费者为精确 source/type/schema 注册，并在入站事务内执行。
+// 可重试失败必须由消费者错误显式实现 Retryable() bool，核心层不猜测错误类别。
+type Handler interface {
+	Handle(ctx context.Context, envelope Envelope) error
+}
+
+// HandlerFunc 将函数适配为入站事件处理器。
+type HandlerFunc func(ctx context.Context, envelope Envelope) error
+
+// Handle 执行入站事件函数。
+func (f HandlerFunc) Handle(ctx context.Context, envelope Envelope) error {
+	if f == nil {
+		return fmt.Errorf("integration event handler function is required")
+	}
+	return f(ctx, envelope)
+}
+
+// HandlerRegistration 声明一个精确版本处理器；typed handler 与 no-op 均由消费者提供。
+type HandlerRegistration struct {
+	SourceSystem  string
+	EventType     string
+	SchemaVersion string
+	Handler       Handler
+}
+
+// ReceiptOutcome 是提交后返回给发送方的持久处理结论。
+type ReceiptOutcome string
+
+const (
+	ReceiptOutcomeProcessed ReceiptOutcome = "processed"
+	ReceiptOutcomeDuplicate ReceiptOutcome = "duplicate"
+)
+
+// ReceiveResult 返回已提交的订阅者回执身份与处理结论。
+type ReceiveResult struct {
+	SourceSystem   string
+	SubscriberCode string
+	EventID        string
+	Outcome        ReceiptOutcome
+}
+
+// TransactionManager 定义可加入外层事务的事务执行端口。
+type TransactionManager interface {
+	WithTransaction(ctx context.Context, fn func(context.Context) error) error
+}

package/dist/resources/templates/go-backend/migrations/000001_infrastructure.down.sql

@@ -1,5 +1,8 @@
 BEGIN;
 DROP TABLE public.sys_command_replay_records CASCADE;
+DROP TABLE public.sys_integration_aggregate_checkpoints CASCADE;
+DROP TABLE public.sys_integration_event_receipts CASCADE;
+DROP TABLE public.sys_integration_event_inbox CASCADE;
 DROP TABLE public.sys_outbox_event_deliveries CASCADE;
 DROP TABLE public.sys_outbox_events CASCADE;
 DROP TABLE public.sys_audit_event_inbox CASCADE;
@@ -10,4 +13,7 @@ DROP TABLE public.sys_access_logs CASCADE;
 DROP FUNCTION public.reject_sys_outbox_event_delivery_identity_change();
 DROP FUNCTION public.reject_sys_outbox_event_schema_version_change();
 DROP FUNCTION public.sys_operation_logs_finalization_guard();
+DROP FUNCTION public.guard_sys_integration_aggregate_checkpoint_transition();
+DROP FUNCTION public.guard_sys_integration_event_receipt_transition();
+DROP FUNCTION public.reject_sys_integration_event_inbox_change();
 COMMIT;