@stackonward/cli 1.4.0 → 1.5.0

package/dist/resources/templates/go-backend/internal/common/locale/locale_test.go

@@ -3,73 +3,196 @@ package locale
 import (
 	"encoding/json"
 	"reflect"
+	"strings"
 	"testing"
 )
 
-func TestNormalizeCode(t *testing.T) {
-	cases := map[string]string{
-		"en-US": "en",
-		"zh-CN": "cn",
-		"zh-TW": "tw",
-		"zh-HK": "tw",
-		"ja-JP": "ja",
-		"jp":    "ja",
-		"hi-IN": "hi",
-		"in":    "hi",
-		"de":    "de",
-		"id-ID": "",
-		"bad-x": "",
-	}
-	for input, want := range cases {
-		if got := NormalizeCode(input); got != want {
-			t.Fatalf("NormalizeCode(%q) = %q, want %q", input, got, want)
+var expectedMappings = []Mapping{
+	{ExternalTag: "en", ShortCode: "en", Direction: DirectionLTR},
+	{ExternalTag: "zh-Hans", ShortCode: "cn", Direction: DirectionLTR},
+	{ExternalTag: "zh-Hant", ShortCode: "tw", Direction: DirectionLTR},
+	{ExternalTag: "ja", ShortCode: "ja", Direction: DirectionLTR},
+	{ExternalTag: "ko", ShortCode: "ko", Direction: DirectionLTR},
+	{ExternalTag: "es", ShortCode: "es", Direction: DirectionLTR},
+	{ExternalTag: "fr", ShortCode: "fr", Direction: DirectionLTR},
+	{ExternalTag: "de", ShortCode: "de", Direction: DirectionLTR},
+	{ExternalTag: "pt-BR", ShortCode: "pt", Direction: DirectionLTR},
+	{ExternalTag: "it", ShortCode: "it", Direction: DirectionLTR},
+	{ExternalTag: "ru", ShortCode: "ru", Direction: DirectionLTR},
+	{ExternalTag: "ar", ShortCode: "ar", Direction: DirectionRTL},
+	{ExternalTag: "hi", ShortCode: "hi", Direction: DirectionLTR},
+	{ExternalTag: "id", ShortCode: "id", Direction: DirectionLTR},
+	{ExternalTag: "th", ShortCode: "th", Direction: DirectionLTR},
+	{ExternalTag: "vi", ShortCode: "vi", Direction: DirectionLTR},
+	{ExternalTag: "tr", ShortCode: "tr", Direction: DirectionLTR},
+	{ExternalTag: "pl", ShortCode: "pl", Direction: DirectionLTR},
+	{ExternalTag: "nl", ShortCode: "nl", Direction: DirectionLTR},
+}
+
+func TestMappingsRoundTripAllSupportedLocales(t *testing.T) {
+	if got := Mappings(); !reflect.DeepEqual(got, expectedMappings) {
+		t.Fatalf("Mappings() = %#v, want %#v", got, expectedMappings)
+	}
+
+	wantCodes := make([]string, 0, len(expectedMappings))
+	for _, mapping := range expectedMappings {
+		wantCodes = append(wantCodes, mapping.ShortCode)
+
+		if got, ok := ShortCodeForExternalTag(mapping.ExternalTag); !ok || got != mapping.ShortCode {
+			t.Errorf("ShortCodeForExternalTag(%q) = %q, %v; want %q, true", mapping.ExternalTag, got, ok, mapping.ShortCode)
+		}
+		if got, ok := ExternalTagForShortCode(mapping.ShortCode); !ok || got != mapping.ExternalTag {
+			t.Errorf("ExternalTagForShortCode(%q) = %q, %v; want %q, true", mapping.ShortCode, got, ok, mapping.ExternalTag)
+		}
+		if got, ok := DirectionForShortCode(mapping.ShortCode); !ok || got != mapping.Direction {
+			t.Errorf("DirectionForShortCode(%q) = %q, %v; want %q, true", mapping.ShortCode, got, ok, mapping.Direction)
+		}
+		if got := NormalizeCode(mapping.ExternalTag); got != mapping.ShortCode {
+			t.Errorf("NormalizeCode(%q) = %q, want %q", mapping.ExternalTag, got, mapping.ShortCode)
+		}
+		if got := NormalizeCode(mapping.ShortCode); got != mapping.ShortCode {
+			t.Errorf("NormalizeCode(%q) = %q, want %q", mapping.ShortCode, got, mapping.ShortCode)
+		}
+		if !IsShortCode(mapping.ShortCode) {
+			t.Errorf("IsShortCode(%q) = false, want true", mapping.ShortCode)
+		}
+
+		caseVariantExternal := strings.ToUpper(mapping.ExternalTag)
+		if got, ok := ShortCodeForExternalTag(caseVariantExternal); ok || got != "" {
+			t.Errorf("ShortCodeForExternalTag(%q) accepted case variant", caseVariantExternal)
 		}
+		caseVariantShort := strings.ToUpper(mapping.ShortCode)
+		if got, ok := ExternalTagForShortCode(caseVariantShort); ok || got != "" {
+			t.Errorf("ExternalTagForShortCode(%q) accepted case variant", caseVariantShort)
+		}
+	}
+
+	if got := SupportedCodes(); !reflect.DeepEqual(got, wantCodes) {
+		t.Fatalf("SupportedCodes() = %#v, want %#v", got, wantCodes)
+	}
+}
+
+func TestLocaleLookupsRequireExactMatches(t *testing.T) {
+	for _, value := range []string{"zh", "pt-PT", "in", "EN", "zh-hans", "pt-br", "en-US", " en", "en_", "en!", "unknown"} {
+		if got, ok := ShortCodeForExternalTag(value); ok || got != "" {
+			t.Errorf("ShortCodeForExternalTag(%q) = %q, %v; want empty, false", value, got, ok)
+		}
+	}
+	for _, value := range []string{"zh", "pt-BR", "in", "EN", " en", "en!", "unknown"} {
+		if got, ok := ExternalTagForShortCode(value); ok || got != "" {
+			t.Errorf("ExternalTagForShortCode(%q) = %q, %v; want empty, false", value, got, ok)
+		}
+		if got, ok := DirectionForShortCode(value); ok || got != "" {
+			t.Errorf("DirectionForShortCode(%q) = %q, %v; want empty, false", value, got, ok)
+		}
+		if IsShortCode(value) {
+			t.Errorf("IsShortCode(%q) = true, want false", value)
+		}
+	}
+	for _, value := range []string{"zh", "pt-PT", "in", "EN", "zh-hans", "pt-br", "en-US", " en", "en!", "unknown"} {
+		if got := NormalizeCode(value); got != "" {
+			t.Errorf("NormalizeCode(%q) = %q, want empty", value, got)
+		}
+	}
+}
+
+func TestMappingsReturnsDefensiveCopy(t *testing.T) {
+	got := Mappings()
+	got[0] = Mapping{ExternalTag: "changed", ShortCode: "changed", Direction: DirectionRTL}
+	if current := Mappings()[0]; current != expectedMappings[0] {
+		t.Fatalf("Mappings() exposed mutable owner data: %#v", current)
 	}
 }
 
 func TestNormalizeTextMap(t *testing.T) {
-	got := NormalizeTextMap(map[string]string{
-		"en-US": "English",
-		"zh-CN": "中文",
-		"ja-JP": "日本語",
-		"hi-IN": "हिंदी",
-		"bad-x": "ignored",
+	got, err := NormalizeTextMap(map[string]string{
+		"en":      "English",
+		"zh-Hans": " 简体中文 ",
+		"pt-BR":   "Português",
+		"ar":      "العربية",
 	})
+	if err != nil {
+		t.Fatalf("NormalizeTextMap() error = %v", err)
+	}
 	want := map[string]string{
 		"en": "English",
-		"cn": "中文",
-		"ja": "日本語",
-		"hi": "हिंदी",
+		"cn": "简体中文",
+		"pt": "Português",
+		"ar": "العربية",
 	}
 	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("NormalizeTextMap() = %v, want %v", got, want)
+		t.Fatalf("NormalizeTextMap() = %#v, want %#v", got, want)
 	}
 }
 
-func TestIsShortCode(t *testing.T) {
-	if !IsShortCode("cn") {
-		t.Fatal("IsShortCode(cn) = false, want true")
+func TestNormalizeTextMapRejectsInvalidInput(t *testing.T) {
+	tests := []struct {
+		name  string
+		input map[string]string
+	}{
+		{name: "generic Chinese alias", input: map[string]string{"zh": "中文"}},
+		{name: "unsupported Portuguese region", input: map[string]string{"pt-PT": "Português"}},
+		{name: "legacy Indonesian alias", input: map[string]string{"in": "Bahasa Indonesia"}},
+		{name: "case variant", input: map[string]string{"EN": "English"}},
+		{name: "empty text", input: map[string]string{"en": "  "}},
+		{name: "duplicate canonical target", input: map[string]string{"zh-Hans": "简体中文", "cn": "中文"}},
 	}
-	if IsShortCode("zh-CN") {
-		t.Fatal("IsShortCode(zh-CN) = true, want false")
-	}
-	if IsShortCode("jp") {
-		t.Fatal("IsShortCode(jp) = true, want false")
-	}
-	if IsShortCode("zz") {
-		t.Fatal("IsShortCode(zz) = true, want false")
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if _, err := NormalizeTextMap(tt.input); err == nil {
+				t.Fatal("NormalizeTextMap() error = nil, want rejection")
+			}
+		})
 	}
 }
 
 func TestNormalizeLocaleRootedMap(t *testing.T) {
-	got := NormalizeLocaleRootedMap(map[string]json.RawMessage{
-		"en-US": json.RawMessage(`{"email":{}}`),
-		"zh-CN": json.RawMessage(`{"sms":{}}`),
+	got, err := NormalizeLocaleRootedMap(map[string]json.RawMessage{
+		"zh-Hant": json.RawMessage(`{"sms":{}}`),
+		"id":      json.RawMessage(`{"email":{}}`),
 	})
-	if _, ok := got["en"]; !ok {
-		t.Fatalf("normalized map missing en: %v", got)
+	if err != nil {
+		t.Fatalf("NormalizeLocaleRootedMap() error = %v", err)
+	}
+	if _, ok := got["tw"]; !ok {
+		t.Fatalf("normalized map missing tw: %#v", got)
+	}
+	if _, ok := got["id"]; !ok {
+		t.Fatalf("normalized map missing id: %#v", got)
+	}
+}
+
+func TestNormalizeLocaleRootedMapRejectsInvalidInput(t *testing.T) {
+	if _, err := NormalizeLocaleRootedMap(map[string]int{"zh": 1}); err == nil {
+		t.Fatal("NormalizeLocaleRootedMap() accepted zh alias")
+	}
+	if _, err := NormalizeLocaleRootedMap(map[string]int{"pt-BR": 1, "pt": 2}); err == nil {
+		t.Fatal("NormalizeLocaleRootedMap() accepted duplicate canonical target")
+	}
+}
+
+func TestNormalizeRawTextMap(t *testing.T) {
+	got, err := NormalizeRawTextMap(json.RawMessage(`{"pt-BR":"Português","ar":"العربية"}`))
+	if err != nil {
+		t.Fatalf("NormalizeRawTextMap() error = %v", err)
 	}
-	if _, ok := got["cn"]; !ok {
-		t.Fatalf("normalized map missing cn: %v", got)
+	var normalized map[string]string
+	if err := json.Unmarshal(got, &normalized); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+	want := map[string]string{"pt": "Português", "ar": "العربية"}
+	if !reflect.DeepEqual(normalized, want) {
+		t.Fatalf("NormalizeRawTextMap() = %#v, want %#v", normalized, want)
+	}
+}
+
+func TestNormalizeRawTextMapRejectsInvalidInput(t *testing.T) {
+	for _, raw := range []json.RawMessage{
+		json.RawMessage(`null`),
+		json.RawMessage(`{"pt-PT":"Português"}`),
+	} {
+		if _, err := NormalizeRawTextMap(raw); err == nil {
+			t.Fatalf("NormalizeRawTextMap(%s) error = nil, want rejection", raw)
+		}
 	}
 }

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

@@ -34,12 +34,12 @@ func (s CommandReplayStatus) IsTerminal() bool {
 // CommandReplayRecord 跨领域命令幂等回放记录。
 type CommandReplayRecord struct {
 	database.BaseModel
-	Namespace       string              `gorm:"column:namespace;type:varchar(200);not null;uniqueIndex:uk_sys_command_replay_records_namespace_scope_key,priority:1;comment:命令所有者全局命名空间" json:"namespace"`
-	CommandScope    string              `gorm:"column:command_scope;type:varchar(128);not null;uniqueIndex:uk_sys_command_replay_records_namespace_scope_key,priority:2;comment:命令幂等作用域" json:"command_scope"`
-	IdempotencyKey  string              `gorm:"column:idempotency_key;type:varchar(191);not null;uniqueIndex:uk_sys_command_replay_records_namespace_scope_key,priority:3;comment:请求幂等键" json:"idempotency_key"`
+	Namespace       string              `gorm:"column:namespace;type:varchar(200);not null;uniqueIndex:uk_sys_command_replay_records_principal_scope_key,priority:1;comment:命令所有者全局命名空间" json:"namespace"`
+	CommandScope    string              `gorm:"column:command_scope;type:varchar(128);not null;uniqueIndex:uk_sys_command_replay_records_principal_scope_key,priority:4;comment:命令幂等作用域" json:"command_scope"`
+	IdempotencyKey  string              `gorm:"column:idempotency_key;type:varchar(191);not null;uniqueIndex:uk_sys_command_replay_records_principal_scope_key,priority:5;comment:请求幂等键" json:"idempotency_key"`
 	RequestHash     string              `gorm:"column:request_hash;type:varchar(64);not null;comment:请求载荷指纹" json:"request_hash"`
-	PrincipalType   *string             `gorm:"column:principal_type;type:varchar(32);comment:请求主体类型" json:"principal_type"`
-	PrincipalRef    *string             `gorm:"column:principal_ref;type:varchar(64);comment:请求主体公开引用" json:"principal_ref"`
+	PrincipalType   string              `gorm:"column:principal_type;type:varchar(32);not null;uniqueIndex:uk_sys_command_replay_records_principal_scope_key,priority:2;comment:参与幂等作用域的可信调用主体类型" json:"principal_type"`
+	PrincipalRef    string              `gorm:"column:principal_ref;type:varchar(64);not null;uniqueIndex:uk_sys_command_replay_records_principal_scope_key,priority:3;comment:参与幂等作用域的可信调用主体公开引用" json:"principal_ref"`
 	Status          CommandReplayStatus `gorm:"column:status;type:varchar(20);not null;default:'started';comment:命令执行状态" json:"status"`
 	ResponsePayload json.RawMessage     `gorm:"column:response_payload;type:jsonb;not null;default:'{}';comment:回放响应载荷" json:"response_payload"`
 	ErrorCode       *string             `gorm:"column:error_code;type:varchar(120);comment:失败错误码" json:"error_code"`

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

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"strconv"
 	"strings"
 	"time"
 
@@ -32,11 +33,13 @@ func NewCommandReplayRepository(db *gorm.DB) CommandReplayRepository {
 	return &commandReplayRepository{db: db}
 }
 
-func (r *commandReplayRepository) FindByScope(ctx context.Context, namespace, commandScope, idempotencyKey string) (*CommandReplayRecord, error) {
+func (r *commandReplayRepository) FindByScope(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (*CommandReplayRecord, error) {
 	var record CommandReplayRecord
 	err := database.GetDB(ctx, r.db).
 		Select(commandReplayRecordColumns).
 		Where("namespace = ?", strings.TrimSpace(namespace)).
+		Where("principal_type = ?", strings.TrimSpace(principalType)).
+		Where("principal_ref = ?", strings.TrimSpace(principalRef)).
 		Where("command_scope = ?", strings.TrimSpace(commandScope)).
 		Where("idempotency_key = ?", strings.TrimSpace(idempotencyKey)).
 		First(&record).Error
@@ -65,17 +68,13 @@ func (r *commandReplayRepository) FindByIDForUpdate(ctx context.Context, id int6
 	return &record, nil
 }
 
-func (r *commandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, commandScope, idempotencyKey string) (bool, error) {
+func (r *commandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (bool, error) {
 	db := database.GetDB(ctx, r.db)
 	if db.Dialector.Name() != "postgres" {
 		return false, fmt.Errorf("unsupported database dialect for command replay scope lock: %s", db.Dialector.Name())
 	}
 
-	scopeKey := strings.Join([]string{
-		strings.TrimSpace(namespace),
-		strings.TrimSpace(commandScope),
-		strings.TrimSpace(idempotencyKey),
-	}, "\x1f")
+	scopeKey := commandReplayScopeKey(namespace, principalType, principalRef, commandScope, idempotencyKey)
 
 	var acquired bool
 	if err := db.Raw(
@@ -92,6 +91,8 @@ func (r *commandReplayRepository) Create(ctx context.Context, record *CommandRep
 		Clauses(clause.OnConflict{
 			Columns: []clause.Column{
 				{Name: "namespace"},
+				{Name: "principal_type"},
+				{Name: "principal_ref"},
 				{Name: "command_scope"},
 				{Name: "idempotency_key"},
 			},
@@ -107,6 +108,18 @@ func (r *commandReplayRepository) Create(ctx context.Context, record *CommandRep
 	return nil
 }
 
+func commandReplayScopeKey(namespace, principalType, principalRef, commandScope, idempotencyKey string) string {
+	fields := [...]string{namespace, principalType, principalRef, commandScope, idempotencyKey}
+	var key strings.Builder
+	for _, field := range fields {
+		normalized := strings.TrimSpace(field)
+		key.WriteString(strconv.Itoa(len(normalized)))
+		key.WriteByte(':')
+		key.WriteString(normalized)
+	}
+	return key.String()
+}
+
 func (r *commandReplayRepository) MarkSucceeded(ctx context.Context, id int64, responsePayload json.RawMessage, completedAt time.Time) error {
 	result := database.GetDB(ctx, r.db).
 		Model(&CommandReplayRecord{}).

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

@@ -22,17 +22,21 @@ func TestCommandReplayRepositoryCreateAndFindByScope(t *testing.T) {
 	repo := NewCommandReplayRepository(db)
 	ctx := context.Background()
 
-	record := newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-1", time.Now().Add(time.Hour))
+	record := newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-1", time.Now().Add(time.Hour))
 	require.NoError(t, repo.Create(ctx, record))
 
-	found, err := repo.FindByScope(ctx, " test.command.checkout ", " quote:create ", " idem-1 ")
+	found, err := repo.FindByScope(ctx, " test.command.checkout ", " identity ", " user_123 ", " quote:create ", " idem-1 ")
 	require.NoError(t, err)
 	require.NotNil(t, found)
 	require.Equal(t, "test.command.checkout", found.Namespace)
 	require.Equal(t, "quote:create", found.CommandScope)
 	require.Equal(t, "idem-1", found.IdempotencyKey)
 
-	missing, err := repo.FindByScope(ctx, "test.command.checkout", "quote:create", "idem-missing")
+	wrongPrincipal, err := repo.FindByScope(ctx, "test.command.checkout", "identity", "user_456", "quote:create", "idem-1")
+	require.NoError(t, err)
+	require.Nil(t, wrongPrincipal)
+
+	missing, err := repo.FindByScope(ctx, "test.command.checkout", "identity", "user_123", "quote:create", "idem-missing")
 	require.NoError(t, err)
 	require.Nil(t, missing)
 }
@@ -43,41 +47,64 @@ func TestCommandReplayRepositoryDuplicateCreateReturnsSentinel(t *testing.T) {
 	ctx := context.Background()
 	expiresAt := time.Now().Add(time.Hour)
 
-	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-1", expiresAt)))
-	err := repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-1", expiresAt))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-1", expiresAt)))
+	err := repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-1", expiresAt))
 	require.Error(t, err)
 	require.True(t, errors.Is(err, ErrCommandReplayRecordExists))
 
-	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-2", expiresAt)))
-	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:update", "idem-1", expiresAt)))
-	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.fulfillment", "quote:create", "idem-1", expiresAt)))
-	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("other.command.checkout", "quote:create", "idem-1", expiresAt)))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_456", "quote:create", "idem-1", expiresAt)))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "service", "worker_123", "quote:create", "idem-1", expiresAt)))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-2", expiresAt)))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:update", "idem-1", expiresAt)))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("test.command.fulfillment", "identity", "user_123", "quote:create", "idem-1", expiresAt)))
+	require.NoError(t, repo.Create(ctx, newPersistenceTestCommandReplayRecord("other.command.checkout", "identity", "user_123", "quote:create", "idem-1", expiresAt)))
 	var total int64
 	require.NoError(t, db.Model(&CommandReplayRecord{}).Count(&total).Error)
-	require.Equal(t, int64(5), total)
+	require.Equal(t, int64(7), total)
 }
 
 func TestCommandReplayRepositoryTryAcquireScopeLockRejectsSQLite(t *testing.T) {
 	db := newCommandReplayTestDB(t)
 	repo := NewCommandReplayRepository(db)
 
-	acquired, err := repo.TryAcquireScopeLock(context.Background(), "test.command.checkout", "quote:create", "idem-1")
+	acquired, err := repo.TryAcquireScopeLock(context.Background(), "test.command.checkout", "identity", "user_123", "quote:create", "idem-1")
 	require.Error(t, err)
 	require.False(t, acquired)
 }
 
+func TestCommandReplayScopeKeyPreservesFiveFieldBoundaries(t *testing.T) {
+	base := commandReplayScopeKey(" test.command.checkout ", " identity ", " user_123 ", " quote:create ", " idem-1 ")
+	require.Equal(t, commandReplayScopeKey("test.command.checkout", "identity", "user_123", "quote:create", "idem-1"), base)
+
+	variants := []string{
+		commandReplayScopeKey("other.command.checkout", "identity", "user_123", "quote:create", "idem-1"),
+		commandReplayScopeKey("test.command.checkout", "service", "user_123", "quote:create", "idem-1"),
+		commandReplayScopeKey("test.command.checkout", "identity", "user_456", "quote:create", "idem-1"),
+		commandReplayScopeKey("test.command.checkout", "identity", "user_123", "quote:update", "idem-1"),
+		commandReplayScopeKey("test.command.checkout", "identity", "user_123", "quote:create", "idem-2"),
+	}
+	for _, variant := range variants {
+		require.NotEqual(t, base, variant)
+	}
+	require.NotEqual(
+		t,
+		commandReplayScopeKey("test.command.checkout", "ab", "c", "quote:create", "idem-1"),
+		commandReplayScopeKey("test.command.checkout", "a", "bc", "quote:create", "idem-1"),
+	)
+}
+
 func TestCommandReplayRepositoryMarkTerminalStates(t *testing.T) {
 	db := newCommandReplayTestDB(t)
 	repo := NewCommandReplayRepository(db)
 	ctx := context.Background()
 	expiresAt := time.Now().Add(time.Hour)
 
-	succeededRecord := newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-success", expiresAt)
+	succeededRecord := newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-success", expiresAt)
 	require.NoError(t, repo.Create(ctx, succeededRecord))
 	succeededAt := time.Now().Add(time.Minute)
 	require.NoError(t, repo.MarkSucceeded(ctx, succeededRecord.ID, json.RawMessage(`{"quote_no":"quote_1"}`), succeededAt))
 
-	loaded, err := repo.FindByScope(ctx, "test.command.checkout", "quote:create", "idem-success")
+	loaded, err := repo.FindByScope(ctx, "test.command.checkout", "identity", "user_123", "quote:create", "idem-success")
 	require.NoError(t, err)
 	require.NotNil(t, loaded)
 	require.Equal(t, CommandReplayStatusSucceeded, loaded.Status)
@@ -88,12 +115,12 @@ func TestCommandReplayRepositoryMarkTerminalStates(t *testing.T) {
 	err = repo.MarkFailed(ctx, succeededRecord.ID, "COMMERCE_QUOTE_FAILED", http.StatusConflict, json.RawMessage(`{"error":"failed"}`), time.Now().Add(2*time.Minute))
 	require.Error(t, err)
 
-	failedRecord := newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-failed", expiresAt)
+	failedRecord := newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-failed", expiresAt)
 	require.NoError(t, repo.Create(ctx, failedRecord))
 	failedAt := time.Now().Add(3 * time.Minute)
 	require.NoError(t, repo.MarkFailed(ctx, failedRecord.ID, " COMMERCE_QUOTE_FAILED ", http.StatusConflict, json.RawMessage(`{"error":"failed"}`), failedAt))
 
-	loaded, err = repo.FindByScope(ctx, "test.command.checkout", "quote:create", "idem-failed")
+	loaded, err = repo.FindByScope(ctx, "test.command.checkout", "identity", "user_123", "quote:create", "idem-failed")
 	require.NoError(t, err)
 	require.NotNil(t, loaded)
 	require.Equal(t, CommandReplayStatusFailed, loaded.Status)
@@ -116,13 +143,13 @@ func TestCommandReplayRepositoryJoinsAmbientTransaction(t *testing.T) {
 	rollbackErr := errors.New("rollback command idempotency transaction")
 
 	err := manager.WithTransaction(ctx, func(txCtx context.Context) error {
-		record := newPersistenceTestCommandReplayRecord("test.command.checkout", "quote:create", "idem-rollback", time.Now().Add(time.Hour))
+		record := newPersistenceTestCommandReplayRecord("test.command.checkout", "identity", "user_123", "quote:create", "idem-rollback", time.Now().Add(time.Hour))
 		require.NoError(t, repo.Create(txCtx, record))
 		return rollbackErr
 	})
 	require.ErrorIs(t, err, rollbackErr)
 
-	found, err := repo.FindByScope(ctx, "test.command.checkout", "quote:create", "idem-rollback")
+	found, err := repo.FindByScope(ctx, "test.command.checkout", "identity", "user_123", "quote:create", "idem-rollback")
 	require.NoError(t, err)
 	require.Nil(t, found)
 }
@@ -147,8 +174,8 @@ func createCommandReplayRecordSchema(t *testing.T, db *gorm.DB) {
 			command_scope TEXT NOT NULL,
 			idempotency_key TEXT NOT NULL,
 			request_hash TEXT NOT NULL,
-			principal_type TEXT,
-			principal_ref TEXT,
+			principal_type TEXT NOT NULL,
+			principal_ref TEXT NOT NULL,
 			status TEXT NOT NULL DEFAULT 'started',
 			response_payload TEXT NOT NULL DEFAULT '{}',
 			error_code TEXT,
@@ -166,14 +193,16 @@ func createCommandReplayRecordSchema(t *testing.T, db *gorm.DB) {
 		)
 	`).Error)
 	require.NoError(t, db.Exec(`
-		CREATE UNIQUE INDEX uk_sys_command_replay_records_namespace_scope_key
-		ON sys_command_replay_records (namespace, command_scope, idempotency_key)
+		CREATE UNIQUE INDEX uk_sys_command_replay_records_principal_scope_key
+		ON sys_command_replay_records (namespace, principal_type, principal_ref, command_scope, idempotency_key)
 	`).Error)
 }
 
-func newPersistenceTestCommandReplayRecord(namespace, commandScope, idempotencyKey string, expiresAt time.Time) *CommandReplayRecord {
+func newPersistenceTestCommandReplayRecord(namespace, principalType, principalRef, commandScope, idempotencyKey string, expiresAt time.Time) *CommandReplayRecord {
 	return &CommandReplayRecord{
 		Namespace:       namespace,
+		PrincipalType:   principalType,
+		PrincipalRef:    principalRef,
 		CommandScope:    commandScope,
 		IdempotencyKey:  idempotencyKey,
 		RequestHash:     strings.Repeat("a", 64),

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

@@ -8,8 +8,8 @@ import (
 
 // CommandReplayRepository 命令幂等回放仓储接口。
 type CommandReplayRepository interface {
-	FindByScope(ctx context.Context, namespace, commandScope, idempotencyKey string) (*CommandReplayRecord, error)
-	TryAcquireScopeLock(ctx context.Context, namespace, commandScope, idempotencyKey string) (bool, error)
+	FindByScope(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (*CommandReplayRecord, error)
+	TryAcquireScopeLock(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (bool, error)
 	Create(ctx context.Context, record *CommandReplayRecord) error
 	MarkSucceeded(ctx context.Context, id int64, responsePayload json.RawMessage, completedAt time.Time) error
 	MarkFailed(ctx context.Context, id int64, errorCode string, errorStatus int, responsePayload json.RawMessage, completedAt time.Time) error

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

@@ -74,6 +74,8 @@ func (s *CommandReplayService) Execute(ctx context.Context, req CommandReplayBeg
 		acquired, lockErr := s.repo.TryAcquireScopeLock(
 			txCtx,
 			normalized.namespace,
+			normalized.principalType,
+			normalized.principalRef,
 			normalized.commandScope,
 			normalized.idempotencyKey,
 		)
@@ -87,6 +89,8 @@ func (s *CommandReplayService) Execute(ctx context.Context, req CommandReplayBeg
 		existing, findErr := s.repo.FindByScope(
 			txCtx,
 			normalized.namespace,
+			normalized.principalType,
+			normalized.principalRef,
 			normalized.commandScope,
 			normalized.idempotencyKey,
 		)
@@ -112,8 +116,8 @@ func (s *CommandReplayService) Execute(ctx context.Context, req CommandReplayBeg
 			CommandScope:    normalized.commandScope,
 			IdempotencyKey:  normalized.idempotencyKey,
 			RequestHash:     normalized.requestHash,
-			PrincipalType:   cloneStringPtr(normalized.principalType),
-			PrincipalRef:    cloneStringPtr(normalized.principalRef),
+			PrincipalType:   normalized.principalType,
+			PrincipalRef:    normalized.principalRef,
 			Status:          CommandReplayStatusStarted,
 			ResponsePayload: json.RawMessage(`{}`),
 			ExpiresAt:       expiresAt,
@@ -126,6 +130,8 @@ func (s *CommandReplayService) Execute(ctx context.Context, req CommandReplayBeg
 			duplicate, reloadErr := s.repo.FindByScope(
 				txCtx,
 				normalized.namespace,
+				normalized.principalType,
+				normalized.principalRef,
 				normalized.commandScope,
 				normalized.idempotencyKey,
 			)
@@ -219,14 +225,14 @@ func (s *CommandReplayService) BeginExternal(
 	var lease *CommandReplayExternalLease
 	err = s.withTransaction(ctx, func(txCtx context.Context) error {
 		now := s.now().UTC()
-		acquired, lockErr := s.repo.TryAcquireScopeLock(txCtx, normalized.namespace, normalized.commandScope, normalized.idempotencyKey)
+		acquired, lockErr := s.repo.TryAcquireScopeLock(txCtx, normalized.namespace, normalized.principalType, normalized.principalRef, normalized.commandScope, normalized.idempotencyKey)
 		if lockErr != nil {
 			return apierror.Internal("Failed to acquire command replay scope lock")
 		}
 		if !acquired {
 			return apierror.Conflict(errCodeCommandReplayInProgress, "Command replay is already in progress")
 		}
-		existing, findErr := s.repo.FindByScope(txCtx, normalized.namespace, normalized.commandScope, normalized.idempotencyKey)
+		existing, findErr := s.repo.FindByScope(txCtx, normalized.namespace, normalized.principalType, normalized.principalRef, normalized.commandScope, normalized.idempotencyKey)
 		if findErr != nil {
 			return apierror.Internal("Failed to load command replay record")
 		}
@@ -514,7 +520,7 @@ func newCommandReplayRecord(normalized *normalizedCommandReplayBeginRequest, now
 	return &CommandReplayRecord{
 		Namespace: normalized.namespace, CommandScope: normalized.commandScope,
 		IdempotencyKey: normalized.idempotencyKey, RequestHash: normalized.requestHash,
-		PrincipalType: cloneStringPtr(normalized.principalType), PrincipalRef: cloneStringPtr(normalized.principalRef),
+		PrincipalType: normalized.principalType, PrincipalRef: normalized.principalRef,
 		Status: CommandReplayStatusStarted, ResponsePayload: json.RawMessage(`{}`),
 		ExpiresAt: now.Add(normalized.ttl), Metadata: normalized.metadata,
 	}
@@ -609,17 +615,14 @@ func normalizeCommandReplayBeginRequest(req CommandReplayBeginRequest) (*normali
 	if err != nil {
 		return nil, err
 	}
-	principalType, err := normalizeOptionalString("principalType", req.PrincipalType, maxPrincipalTypeLength)
+	principalType, err := normalizeRequiredString("principalType", req.PrincipalType, maxPrincipalTypeLength)
 	if err != nil {
 		return nil, err
 	}
-	principalRef, err := normalizeOptionalString("principalRef", req.PrincipalRef, maxPrincipalRefLength)
+	principalRef, err := normalizeRequiredString("principalRef", req.PrincipalRef, maxPrincipalRefLength)
 	if err != nil {
 		return nil, err
 	}
-	if (principalType == nil) != (principalRef == nil) {
-		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "principalType and principalRef must be provided together")
-	}
 	ttl := req.TTL
 	if ttl <= 0 {
 		ttl = defaultCommandReplayTTL
@@ -789,20 +792,6 @@ func normalizeRequiredString(fieldName, value string, maxLength int) (string, er
 	return normalized, nil
 }
 
-func normalizeOptionalString(fieldName string, value *string, maxLength int) (*string, error) {
-	if value == nil {
-		return nil, nil
-	}
-	normalized := strings.TrimSpace(*value)
-	if normalized == "" {
-		return nil, apierror.BadRequest(apierror.CodeValidationFailed, fieldName+" must not be blank")
-	}
-	if utf8.RuneCountInString(normalized) > maxLength {
-		return nil, apierror.BadRequest(apierror.CodeValidationFailed, fieldName+" is too long")
-	}
-	return &normalized, nil
-}
-
 func (s *CommandReplayService) markSucceeded(ctx context.Context, recordID int64, responsePayload json.RawMessage, completedAt time.Time) error {
 	if markErr := s.repo.MarkSucceeded(ctx, recordID, responsePayload, completedAt); markErr != nil {
 		return apierror.Internal("Failed to mark command replay record as succeeded")