@stackonward/cli 1.3.3 → 1.5.0

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

@@ -18,14 +18,16 @@ import (
 	"{{module}}/pkg/apierror"
 )
 
-const commandReplayTestNamespace = "test.command.replay"
+const (
+	commandReplayTestNamespace     = "test.command.replay"
+	commandReplayTestPrincipalType = "identity"
+	commandReplayTestPrincipalRef  = "user_123"
+)
 
 var commandReplayTestNow = time.Date(2026, 5, 28, 10, 0, 0, 0, time.UTC)
 
 func TestCommandReplayExecuteSucceeds(t *testing.T) {
 	service, repo := newTestCommandReplayService(t)
-	principalType := "identity"
-	principalRef := "user_123"
 	fnCalled := 0
 
 	result, err := service.Execute(context.Background(), CommandReplayBeginRequest{
@@ -33,8 +35,8 @@ func TestCommandReplayExecuteSucceeds(t *testing.T) {
 		CommandScope:   " quote:123 ",
 		IdempotencyKey: " key-123 ",
 		RequestPayload: json.RawMessage(`{"currency":"USD","amount":100}`),
-		PrincipalType:  &principalType,
-		PrincipalRef:   &principalRef,
+		PrincipalType:  " identity ",
+		PrincipalRef:   " user_123 ",
 	}, func(ctx context.Context, record *CommandReplayRecord) (*CommandReplayCommandResult, error) {
 		fnCalled++
 		if record.ID == 0 {
@@ -61,7 +63,7 @@ func TestCommandReplayExecuteSucceeds(t *testing.T) {
 		t.Fatalf("Execute() ResponsePayload = %s, want canonical object", result.ResponsePayload)
 	}
 
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.Status != CommandReplayStatusSucceeded {
 		t.Fatalf("stored Status = %q, want succeeded", stored.Status)
 	}
@@ -77,11 +79,11 @@ func TestCommandReplayExecuteSucceeds(t *testing.T) {
 	if stored.CompletedAt == nil || !stored.CompletedAt.Equal(commandReplayTestNow) {
 		t.Fatalf("stored CompletedAt = %v, want %s", stored.CompletedAt, commandReplayTestNow)
 	}
-	if stored.PrincipalType == nil || *stored.PrincipalType != principalType {
-		t.Fatalf("stored PrincipalType = %v, want %q", stored.PrincipalType, principalType)
+	if stored.PrincipalType != commandReplayTestPrincipalType {
+		t.Fatalf("stored PrincipalType = %q, want %q", stored.PrincipalType, commandReplayTestPrincipalType)
 	}
-	if stored.PrincipalRef == nil || *stored.PrincipalRef != principalRef {
-		t.Fatalf("stored PrincipalRef = %v, want %q", stored.PrincipalRef, principalRef)
+	if stored.PrincipalRef != commandReplayTestPrincipalRef {
+		t.Fatalf("stored PrincipalRef = %q, want %q", stored.PrincipalRef, commandReplayTestPrincipalRef)
 	}
 }
 
@@ -140,6 +142,29 @@ func TestCommandReplayExecuteRejectsHashConflict(t *testing.T) {
 	assertAPIError(t, err, http.StatusConflict, errCodeCommandReplayConflict)
 }
 
+func TestCommandReplayExecuteIsolatesSameKeyByPrincipal(t *testing.T) {
+	service, repo := newTestCommandReplayService(t)
+	first := beginRequest(json.RawMessage(`{"amount":100}`))
+	second := beginRequest(json.RawMessage(`{"amount":100}`))
+	second.PrincipalRef = "user_456"
+
+	firstResult, err := service.Execute(context.Background(), first, successCommandReplayFunc(t))
+	if err != nil {
+		t.Fatalf("Execute(first) error = %v", err)
+	}
+	secondResult, err := service.Execute(context.Background(), second, successCommandReplayFunc(t))
+	if err != nil {
+		t.Fatalf("Execute(second) error = %v", err)
+	}
+	if firstResult.Replayed || secondResult.Replayed {
+		t.Fatalf("new principal-scoped commands must not replay: first=%v second=%v", firstResult.Replayed, secondResult.Replayed)
+	}
+	if repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123").RequestHash !=
+		repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, "user_456", "quote:123", "key-123").RequestHash {
+		t.Fatal("principal unexpectedly changed the payload-only request fingerprint")
+	}
+}
+
 func TestCommandReplayExecuteRejectsExpiredRecord(t *testing.T) {
 	service, repo := newTestCommandReplayService(t)
 	repo.seed(seedCommandReplayRecord(t, json.RawMessage(`{"amount":100}`), func(record *CommandReplayRecord) {
@@ -169,7 +194,7 @@ func TestCommandReplayExecuteBusinessFailureCommitsAndReturnsBusinessError(t *te
 		t.Fatalf("Execute() result = %#v, want failed result", result)
 	}
 
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.Status != CommandReplayStatusFailed {
 		t.Fatalf("stored Status = %q, want failed", stored.Status)
 	}
@@ -198,7 +223,7 @@ func TestCommandReplayExecuteInfrastructureErrorDoesNotMarkTerminal(t *testing.T
 		t.Fatalf("Execute() error = %v, want infraErr", err)
 	}
 
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.Status.IsTerminal() {
 		t.Fatalf("stored Status = %q, want non-terminal", stored.Status)
 	}
@@ -258,19 +283,17 @@ func TestCommandReplayExecuteRejectsInvalidNamespace(t *testing.T) {
 	assertAPIError(t, err, http.StatusBadRequest, apierror.CodeValidationFailed)
 }
 
-func TestCommandReplayExecuteRejectsIncompletePrincipal(t *testing.T) {
-	principalType := "identity"
-	principalRef := "ipr_123"
-	blank := " \t "
+func TestCommandReplayExecuteRejectsInvalidPrincipal(t *testing.T) {
 	tests := []struct {
 		name          string
-		principalType *string
-		principalRef  *string
+		principalType string
+		principalRef  string
 	}{
-		{name: "missing principal ref", principalType: &principalType},
-		{name: "missing principal type", principalRef: &principalRef},
-		{name: "blank principal pair", principalType: &blank, principalRef: &blank},
-		{name: "blank principal ref", principalType: &principalType, principalRef: &blank},
+		{name: "missing principal ref", principalType: commandReplayTestPrincipalType},
+		{name: "missing principal type", principalRef: commandReplayTestPrincipalRef},
+		{name: "blank principal pair", principalType: " \t ", principalRef: " \t "},
+		{name: "overlong principal type", principalType: strings.Repeat("a", maxPrincipalTypeLength+1), principalRef: commandReplayTestPrincipalRef},
+		{name: "overlong principal ref", principalType: commandReplayTestPrincipalType, principalRef: strings.Repeat("a", maxPrincipalRefLength+1)},
 	}
 
 	for _, tt := range tests {
@@ -372,7 +395,7 @@ func TestCommandReplayExternalLifecycle(t *testing.T) {
 	if lease.ExecutionToken == "" || lease.AttemptCount != 1 || lease.Reservation.ReferenceNo != "cpo_1" {
 		t.Fatalf("lease = %#v", lease)
 	}
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if !stored.HasExternalReservation() || stored.ExecutionTokenHash == nil || stored.ExternalAttemptCount != 1 {
 		t.Fatalf("stored external record = %#v", stored)
 	}
@@ -389,7 +412,7 @@ func TestCommandReplayExternalLifecycle(t *testing.T) {
 	if err != nil || result.Status != CommandReplayStatusSucceeded {
 		t.Fatalf("CompleteExternal() = %#v, %v", result, err)
 	}
-	stored = repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored = repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.HasExternalReservation() || stored.ExecutionTokenHash != nil || stored.Status != CommandReplayStatusSucceeded {
 		t.Fatalf("completed stored record = %#v", stored)
 	}
@@ -453,7 +476,7 @@ func TestCommandReplayExternalDeferAndRecoveryClaim(t *testing.T) {
 	if err := service.DeferExternal(context.Background(), lease.RecordID, lease.ExecutionToken, "provider_timeout", nextRecoveryAt); err != nil {
 		t.Fatalf("DeferExternal() error = %v", err)
 	}
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.ExecutionTokenHash != nil || stored.ExternalLastErrorCode == nil || *stored.ExternalLastErrorCode != "provider_timeout" {
 		t.Fatalf("deferred record = %#v", stored)
 	}
@@ -586,6 +609,8 @@ func newTestCommandReplayService(t *testing.T) (*CommandReplayService, *fakeComm
 func beginRequest(payload json.RawMessage) CommandReplayBeginRequest {
 	return CommandReplayBeginRequest{
 		Namespace:      commandReplayTestNamespace,
+		PrincipalType:  commandReplayTestPrincipalType,
+		PrincipalRef:   commandReplayTestPrincipalRef,
 		CommandScope:   "quote:123",
 		IdempotencyKey: "key-123",
 		RequestPayload: payload,
@@ -599,6 +624,8 @@ func seedCommandReplayRecord(t *testing.T, payload json.RawMessage, mutate func(
 
 	record := &CommandReplayRecord{
 		Namespace:       commandReplayTestNamespace,
+		PrincipalType:   commandReplayTestPrincipalType,
+		PrincipalRef:    commandReplayTestPrincipalRef,
 		CommandScope:    "quote:123",
 		IdempotencyKey:  "key-123",
 		RequestHash:     mustCanonicalHash(t, payload),
@@ -669,18 +696,18 @@ func newFakeCommandReplayRepository() *fakeCommandReplayRepository {
 	}
 }
 
-func (r *fakeCommandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, commandScope, idempotencyKey string) (bool, error) {
+func (r *fakeCommandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (bool, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
 	return r.lockAcquired, nil
 }
 
-func (r *fakeCommandReplayRepository) FindByScope(ctx context.Context, namespace, commandScope, idempotencyKey string) (*CommandReplayRecord, error) {
+func (r *fakeCommandReplayRepository) FindByScope(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (*CommandReplayRecord, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
-	record := r.records[commandReplayRecordKey(namespace, commandScope, idempotencyKey)]
+	record := r.records[commandReplayRecordKey(namespace, principalType, principalRef, commandScope, idempotencyKey)]
 	return cloneCommandReplayRecord(record), nil
 }
 
@@ -692,7 +719,7 @@ func (r *fakeCommandReplayRepository) Create(ctx context.Context, record *Comman
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
-	key := commandReplayRecordKey(record.Namespace, record.CommandScope, record.IdempotencyKey)
+	key := commandReplayRecordKey(record.Namespace, record.PrincipalType, record.PrincipalRef, record.CommandScope, record.IdempotencyKey)
 	if _, exists := r.records[key]; exists {
 		return ErrCommandReplayRecordExists
 	}
@@ -835,17 +862,17 @@ func (r *fakeCommandReplayRepository) seed(record *CommandReplayRecord) {
 		r.nextID++
 	}
 	record.ID = stored.ID
-	key := commandReplayRecordKey(stored.Namespace, stored.CommandScope, stored.IdempotencyKey)
+	key := commandReplayRecordKey(stored.Namespace, stored.PrincipalType, stored.PrincipalRef, stored.CommandScope, stored.IdempotencyKey)
 	r.records[key] = stored
 }
 
-func (r *fakeCommandReplayRepository) mustFind(t *testing.T, namespace, commandScope, idempotencyKey string) *CommandReplayRecord {
+func (r *fakeCommandReplayRepository) mustFind(t *testing.T, namespace, principalType, principalRef, commandScope, idempotencyKey string) *CommandReplayRecord {
 	t.Helper()
 
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
-	record := r.records[commandReplayRecordKey(namespace, commandScope, idempotencyKey)]
+	record := r.records[commandReplayRecordKey(namespace, principalType, principalRef, commandScope, idempotencyKey)]
 	if record == nil {
 		t.Fatalf("record not found")
 	}
@@ -861,8 +888,8 @@ func (r *fakeCommandReplayRepository) findByIDLocked(id int64) *CommandReplayRec
 	return nil
 }
 
-func commandReplayRecordKey(namespace, commandScope, idempotencyKey string) string {
-	return namespace + "\x00" + commandScope + "\x00" + idempotencyKey
+func commandReplayRecordKey(namespace, principalType, principalRef, commandScope, idempotencyKey string) string {
+	return namespace + "\x00" + principalType + "\x00" + principalRef + "\x00" + commandScope + "\x00" + idempotencyKey
 }
 
 func cloneCommandReplayRecord(record *CommandReplayRecord) *CommandReplayRecord {
@@ -870,8 +897,6 @@ func cloneCommandReplayRecord(record *CommandReplayRecord) *CommandReplayRecord
 		return nil
 	}
 	cloned := *record
-	cloned.PrincipalType = cloneStringPtr(record.PrincipalType)
-	cloned.PrincipalRef = cloneStringPtr(record.PrincipalRef)
 	cloned.ErrorCode = cloneStringPtr(record.ErrorCode)
 	cloned.ErrorStatus = cloneIntPtr(record.ErrorStatus)
 	cloned.ResponsePayload = append(json.RawMessage(nil), record.ResponsePayload...)

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

@@ -18,10 +18,10 @@ type CommandReplayBeginRequest struct {
 	IdempotencyKey string
 	// RequestPayload 命令请求的规范 JSON 对象载荷。
 	RequestPayload json.RawMessage
-	// PrincipalType 请求主体类型。
-	PrincipalType *string
-	// PrincipalRef 请求主体公开引用。
-	PrincipalRef *string
+	// PrincipalType 是参与幂等作用域的可信调用主体类型。
+	PrincipalType string
+	// PrincipalRef 是参与幂等作用域的可信调用主体公开引用。
+	PrincipalRef string
 	// Metadata 扩展元数据 JSON 对象。
 	Metadata json.RawMessage
 	// TTL 幂等记录保留时长。
@@ -106,8 +106,8 @@ type normalizedCommandReplayBeginRequest struct {
 	commandScope   string
 	idempotencyKey string
 	requestHash    string
-	principalType  *string
-	principalRef   *string
+	principalType  string
+	principalRef   string
 	metadata       json.RawMessage
 	ttl            time.Duration
 }

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

@@ -0,0 +1,24 @@
+package integrationevent
+
+import (
+	"fmt"
+	"strings"
+)
+
+const maxSubscriberCodeLength = 64
+
+// ReceiverConfig 定义单个入站事件接收方的稳定订阅者身份。
+type ReceiverConfig struct {
+	SubscriberCode string
+}
+
+func (c ReceiverConfig) normalized() (ReceiverConfig, error) {
+	c.SubscriberCode = strings.TrimSpace(c.SubscriberCode)
+	if c.SubscriberCode == "" {
+		return ReceiverConfig{}, fmt.Errorf("integration event subscriber code is required")
+	}
+	if len(c.SubscriberCode) > maxSubscriberCodeLength {
+		return ReceiverConfig{}, fmt.Errorf("integration event subscriber code exceeds %d bytes", maxSubscriberCodeLength)
+	}
+	return c, nil
+}

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

@@ -0,0 +1,53 @@
+package integrationevent
+
+import (
+	"errors"
+	"fmt"
+)
+
+var (
+	// ErrEnvelopeInvalid 表示接收方提交的已验证信封不满足核心持久化合同。
+	ErrEnvelopeInvalid = errors.New("integration event envelope is invalid")
+	// ErrHandlerNotRegistered 表示没有消费者为精确 source/type/schema 注册处理器。
+	ErrHandlerNotRegistered = errors.New("integration event handler is not registered")
+	// ErrIdentityConflict 表示同一全局事件身份绑定了不同规范信封。
+	ErrIdentityConflict = errors.New("integration event identity conflicts with the persisted envelope")
+	// ErrVersionConflict 表示事件版本不高于水位且无法证明是已处理事件。
+	ErrVersionConflict = errors.New("integration event aggregate version conflicts with the checkpoint")
+	// ErrReceiptStateConflict 表示持久回执处于无法安全重放的状态。
+	ErrReceiptStateConflict = errors.New("integration event receipt state conflicts with replay")
+)
+
+// VersionGapError 表示事件版本领先于当前连续水位，调用方应稍后重试同一事件。
+type VersionGapError struct {
+	Expected int64
+	Actual   int64
+}
+
+func (e *VersionGapError) Error() string {
+	return fmt.Sprintf("integration event aggregate version gap: expected %d, got %d", e.Expected, e.Actual)
+}
+
+// Retryable 标识版本缺口可以在前序事件到达后重试。
+func (e *VersionGapError) Retryable() bool { return true }
+
+// HandlerError 表示消费者处理失败，整个入站事务已回滚并可重试。
+type HandlerError struct {
+	Cause error
+}
+
+func (e *HandlerError) Error() string {
+	return fmt.Sprintf("integration event handler failed: %v", e.Cause)
+}
+
+// Unwrap 返回消费者处理器的原始错误。
+func (e *HandlerError) Unwrap() error { return e.Cause }
+
+// Retryable 保留消费者对失败是否可重试的显式分类。
+func (e *HandlerError) Retryable() bool { return IsRetryable(e.Cause) }
+
+// IsRetryable 判断错误是否允许发送方稍后重试同一事件身份。
+func IsRetryable(err error) bool {
+	var retryable interface{ Retryable() bool }
+	return errors.As(err, &retryable) && retryable.Retryable()
+}

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

@@ -0,0 +1,71 @@
+package integrationevent
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// ReceiptProcessingStatus 表示订阅者回执的持久处理状态。
+type ReceiptProcessingStatus string
+
+const (
+	ReceiptProcessingStatusProcessing ReceiptProcessingStatus = "processing"
+	ReceiptProcessingStatusProcessed  ReceiptProcessingStatus = "processed"
+	ReceiptProcessingStatusFailed     ReceiptProcessingStatus = "failed"
+)
+
+// InboxRecord 保存全局唯一事件身份及其规范信封。
+type InboxRecord struct {
+	ID               int64           `gorm:"column:id;primaryKey;autoIncrement"`
+	SourceSystem     string          `gorm:"column:source_system;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_inbox_identity,priority:1"`
+	EventID          string          `gorm:"column:event_id;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_inbox_identity,priority:2"`
+	EventType        string          `gorm:"column:event_type;type:varchar(191);not null"`
+	SchemaVersion    string          `gorm:"column:schema_version;type:varchar(32);not null"`
+	ProductCode      string          `gorm:"column:product_code;type:varchar(50);not null"`
+	AggregateType    string          `gorm:"column:aggregate_type;type:varchar(128);not null"`
+	AggregateRef     string          `gorm:"column:aggregate_ref;type:varchar(191);not null"`
+	AggregateVersion int64           `gorm:"column:aggregate_version;not null"`
+	PayloadHash      string          `gorm:"column:payload_hash;type:char(64);not null"`
+	EventPayload     json.RawMessage `gorm:"column:event_payload;type:jsonb;not null"`
+	ReceivedAt       time.Time       `gorm:"column:received_at;type:timestamptz(3);not null"`
+	CreatedAt        time.Time       `gorm:"column:created_at;type:timestamptz(3);not null"`
+}
+
+// TableName 指定全局入站事件身份表。
+func (InboxRecord) TableName() string { return "sys_integration_event_inbox" }
+
+// ReceiptRecord 保存单个订阅者对一个全局事件的处理回执。
+type ReceiptRecord struct {
+	ID                  int64                   `gorm:"column:id;primaryKey;autoIncrement"`
+	SourceSystem        string                  `gorm:"column:source_system;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_receipts_subscriber_event,priority:1"`
+	SubscriberCode      string                  `gorm:"column:subscriber_code;type:varchar(64);not null;uniqueIndex:uk_sys_integration_event_receipts_subscriber_event,priority:2"`
+	EventID             string                  `gorm:"column:event_id;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_receipts_subscriber_event,priority:3"`
+	Status              ReceiptProcessingStatus `gorm:"column:status;type:varchar(20);not null"`
+	ReceiptStatus       *ReceiptOutcome         `gorm:"column:receipt_status;type:varchar(20)"`
+	ErrorCode           *string                 `gorm:"column:error_code;type:varchar(120)"`
+	ProcessingStartedAt time.Time               `gorm:"column:processing_started_at;type:timestamptz(3);not null"`
+	ProcessedAt         *time.Time              `gorm:"column:processed_at;type:timestamptz(3)"`
+	CreatedAt           time.Time               `gorm:"column:created_at;type:timestamptz(3);not null"`
+	UpdatedAt           time.Time               `gorm:"column:updated_at;type:timestamptz(3);not null"`
+}
+
+// TableName 指定订阅者事件回执表。
+func (ReceiptRecord) TableName() string { return "sys_integration_event_receipts" }
+
+// AggregateCheckpoint 保存单个订阅者对一个上游聚合的最后连续版本。
+type AggregateCheckpoint struct {
+	ID                   int64     `gorm:"column:id;primaryKey;autoIncrement"`
+	SourceSystem         string    `gorm:"column:source_system;type:varchar(191);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:1"`
+	SubscriberCode       string    `gorm:"column:subscriber_code;type:varchar(64);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:2"`
+	AggregateType        string    `gorm:"column:aggregate_type;type:varchar(128);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:3"`
+	AggregateRef         string    `gorm:"column:aggregate_ref;type:varchar(191);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:4"`
+	LastAggregateVersion int64     `gorm:"column:last_aggregate_version;not null"`
+	LastEventID          string    `gorm:"column:last_event_id;type:varchar(191);not null"`
+	LastPayloadHash      string    `gorm:"column:last_payload_hash;type:char(64);not null"`
+	RevisionNo           int64     `gorm:"column:revision_no;not null"`
+	CreatedAt            time.Time `gorm:"column:created_at;type:timestamptz(3);not null"`
+	UpdatedAt            time.Time `gorm:"column:updated_at;type:timestamptz(3);not null"`
+}
+
+// TableName 指定订阅者聚合连续水位表。
+func (AggregateCheckpoint) TableName() string { return "sys_integration_aggregate_checkpoints" }

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

@@ -0,0 +1,193 @@
+package integrationevent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"{{module}}/internal/core/database"
+)
+
+var (
+	inboxColumns = []string{
+		"id", "source_system", "event_id", "event_type", "schema_version", "product_code",
+		"aggregate_type", "aggregate_ref", "aggregate_version", "payload_hash", "event_payload",
+		"received_at", "created_at",
+	}
+	receiptColumns = []string{
+		"id", "source_system", "subscriber_code", "event_id", "status", "receipt_status", "error_code",
+		"processing_started_at", "processed_at", "created_at", "updated_at",
+	}
+	checkpointColumns = []string{
+		"id", "source_system", "subscriber_code", "aggregate_type", "aggregate_ref", "last_aggregate_version",
+		"last_event_id", "last_payload_hash", "revision_no", "created_at", "updated_at",
+	}
+)
+
+type repository struct {
+	db *gorm.DB
+}
+
+// NewRepository 创建入站事件事务仓储。
+func NewRepository(db *gorm.DB) Repository {
+	return &repository{db: db}
+}
+
+func (r *repository) CreateOrLoadInbox(ctx context.Context, record *InboxRecord) (*InboxRecord, bool, error) {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return nil, false, err
+	}
+	db := database.GetDB(ctx, r.db)
+	result := db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "source_system"}, {Name: "event_id"}},
+		DoNothing: true,
+	}).Create(record)
+	if result.Error != nil {
+		return nil, false, fmt.Errorf("create integration event inbox record: %w", result.Error)
+	}
+	if result.RowsAffected == 1 {
+		return record, true, nil
+	}
+
+	var existing InboxRecord
+	if err := db.Select(inboxColumns).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("source_system = ? AND event_id = ?", record.SourceSystem, record.EventID).
+		Take(&existing).Error; err != nil {
+		return nil, false, fmt.Errorf("load integration event inbox record: %w", err)
+	}
+	return &existing, false, nil
+}
+
+func (r *repository) CreateOrLockReceipt(ctx context.Context, record *ReceiptRecord) (*ReceiptRecord, bool, error) {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return nil, false, err
+	}
+	db := database.GetDB(ctx, r.db)
+	result := db.Clauses(clause.OnConflict{
+		Columns: []clause.Column{
+			{Name: "source_system"},
+			{Name: "subscriber_code"},
+			{Name: "event_id"},
+		},
+		DoNothing: true,
+	}).Create(record)
+	if result.Error != nil {
+		return nil, false, fmt.Errorf("create integration event receipt: %w", result.Error)
+	}
+
+	var locked ReceiptRecord
+	if err := db.Select(receiptColumns).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("source_system = ? AND subscriber_code = ? AND event_id = ?", record.SourceSystem, record.SubscriberCode, record.EventID).
+		Take(&locked).Error; err != nil {
+		return nil, false, fmt.Errorf("lock integration event receipt: %w", err)
+	}
+	return &locked, result.RowsAffected == 1, nil
+}
+
+func (r *repository) LockAggregateScope(ctx context.Context, sourceSystem, subscriberCode, aggregateType, aggregateRef string) error {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return err
+	}
+	db := database.GetDB(ctx, r.db)
+	switch db.Dialector.Name() {
+	case "postgres":
+		scope := strings.Join([]string{sourceSystem, subscriberCode, aggregateType, aggregateRef}, "\x1f")
+		if err := db.Exec("SELECT pg_advisory_xact_lock(('x' || substr(md5(?), 1, 16))::bit(64)::bigint)", scope).Error; err != nil {
+			return fmt.Errorf("lock integration event aggregate scope: %w", err)
+		}
+		return nil
+	case "sqlite":
+		// SQLite 的写事务串行化由数据库引擎保证，此分支仅用于模板持久化测试。
+		return nil
+	default:
+		return fmt.Errorf("unsupported database dialect for integration event aggregate lock: %s", db.Dialector.Name())
+	}
+}
+
+func (r *repository) FindCheckpointForUpdate(ctx context.Context, sourceSystem, subscriberCode, aggregateType, aggregateRef string) (*AggregateCheckpoint, error) {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return nil, err
+	}
+	var checkpoint AggregateCheckpoint
+	err := database.GetDB(ctx, r.db).
+		Select(checkpointColumns).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("source_system = ? AND subscriber_code = ? AND aggregate_type = ? AND aggregate_ref = ?", sourceSystem, subscriberCode, aggregateType, aggregateRef).
+		Take(&checkpoint).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("load integration event aggregate checkpoint: %w", err)
+	}
+	return &checkpoint, nil
+}
+
+func (r *repository) CreateCheckpoint(ctx context.Context, checkpoint *AggregateCheckpoint) error {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return err
+	}
+	if err := database.GetDB(ctx, r.db).Create(checkpoint).Error; err != nil {
+		return fmt.Errorf("create integration event aggregate checkpoint: %w", err)
+	}
+	return nil
+}
+
+func (r *repository) AdvanceCheckpoint(ctx context.Context, checkpoint *AggregateCheckpoint, expectedRevision int64) error {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return err
+	}
+	result := database.GetDB(ctx, r.db).
+		Model(&AggregateCheckpoint{}).
+		Where(
+			"id = ? AND revision_no = ? AND last_aggregate_version = ?",
+			checkpoint.ID,
+			expectedRevision,
+			checkpoint.LastAggregateVersion-1,
+		).
+		Updates(map[string]any{
+			"last_aggregate_version": checkpoint.LastAggregateVersion,
+			"last_event_id":          checkpoint.LastEventID,
+			"last_payload_hash":      checkpoint.LastPayloadHash,
+			"revision_no":            checkpoint.RevisionNo,
+			"updated_at":             checkpoint.UpdatedAt,
+		})
+	if result.Error != nil {
+		return fmt.Errorf("advance integration event aggregate checkpoint: %w", result.Error)
+	}
+	if result.RowsAffected != 1 {
+		return fmt.Errorf("integration event aggregate checkpoint revision conflict")
+	}
+	return nil
+}
+
+func (r *repository) MarkReceiptProcessed(ctx context.Context, id int64, outcome ReceiptOutcome, processedAt time.Time) error {
+	if err := database.RequireTransaction(ctx); err != nil {
+		return err
+	}
+	result := database.GetDB(ctx, r.db).
+		Model(&ReceiptRecord{}).
+		Where("id = ?", id).
+		Where("status = ?", ReceiptProcessingStatusProcessing).
+		Updates(map[string]any{
+			"status":         ReceiptProcessingStatusProcessed,
+			"receipt_status": outcome,
+			"error_code":     nil,
+			"processed_at":   processedAt,
+			"updated_at":     processedAt,
+		})
+	if result.Error != nil {
+		return fmt.Errorf("finalize integration event receipt: %w", result.Error)
+	}
+	if result.RowsAffected != 1 {
+		return fmt.Errorf("integration event receipt is not processing")
+	}
+	return nil
+}