@stackonward/cli 1.3.3 → 1.5.0

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

@@ -2,6 +2,7 @@ package locale
 
 import (
 	"encoding/json"
+	"fmt"
 	"strings"
 )
 
@@ -10,124 +11,143 @@ const (
 	AdminDefaultCode = "cn"
 )
 
-var supportedCodes = []string{
-	"en",
-	"cn",
-	"tw",
-	"de",
-	"es",
-	"fr",
-	"it",
-	"ja",
-	"ko",
-	"pt",
-	"hi",
-	"ar",
+// Direction 表示语言内容的排版方向。
+type Direction string
+
+const (
+	DirectionLTR Direction = "ltr"
+	DirectionRTL Direction = "rtl"
+)
+
+// Mapping 定义规范外部语言标签与内部短码之间的唯一映射。
+type Mapping struct {
+	ExternalTag string
+	ShortCode   string
+	Direction   Direction
 }
 
-var supportedCodeSet = buildSupportedCodeSet()
+var mappings = []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},
+}
+
+var externalTagIndex, shortCodeIndex = buildIndexes()
 
-func buildSupportedCodeSet() map[string]struct{} {
-	result := make(map[string]struct{}, len(supportedCodes))
-	for _, code := range supportedCodes {
-		result[code] = struct{}{}
+func buildIndexes() (map[string]Mapping, map[string]Mapping) {
+	byExternalTag := make(map[string]Mapping, len(mappings))
+	byShortCode := make(map[string]Mapping, len(mappings))
+	for _, mapping := range mappings {
+		byExternalTag[mapping.ExternalTag] = mapping
+		byShortCode[mapping.ShortCode] = mapping
 	}
+	return byExternalTag, byShortCode
+}
+
+// Mappings 返回按稳定顺序排列的全部语言映射。
+func Mappings() []Mapping {
+	result := make([]Mapping, len(mappings))
+	copy(result, mappings)
 	return result
 }
 
+// SupportedCodes 返回按稳定顺序排列的全部内部短码。
 func SupportedCodes() []string {
-	result := make([]string, len(supportedCodes))
-	copy(result, supportedCodes)
+	result := make([]string, 0, len(mappings))
+	for _, mapping := range mappings {
+		result = append(result, mapping.ShortCode)
+	}
 	return result
 }
 
-func NormalizeCode(value string) string {
-	code := strings.ToLower(strings.TrimSpace(strings.ReplaceAll(value, "_", "-")))
-	switch code {
-	case "en", "en-us", "en-gb":
-		return "en"
-	case "cn", "zh", "zh-cn", "zh-hans", "zh-hans-cn":
-		return "cn"
-	case "tw", "hk", "zh-tw", "zh-hk", "zh-hant", "zh-hant-tw", "zh-hant-hk":
-		return "tw"
-	case "ja", "jp", "ja-jp":
-		return "ja"
-	case "ko", "ko-kr":
-		return "ko"
-	case "de", "de-de":
-		return "de"
-	case "es", "es-es":
-		return "es"
-	case "fr", "fr-fr":
-		return "fr"
-	case "it", "it-it":
-		return "it"
-	case "pt", "pt-br", "pt-pt":
-		return "pt"
-	case "hi", "in", "hi-in":
-		return "hi"
-	case "ar", "ar-sa":
-		return "ar"
-	}
-	return ""
+// ShortCodeForExternalTag 将规范外部语言标签精确映射为内部短码。
+func ShortCodeForExternalTag(externalTag string) (string, bool) {
+	mapping, ok := externalTagIndex[externalTag]
+	return mapping.ShortCode, ok
 }
 
-func NormalizeCodeOrDefault(value string, fallback string) string {
-	if code := NormalizeCode(value); code != "" {
-		return code
+// ExternalTagForShortCode 将内部短码精确映射为规范外部语言标签。
+func ExternalTagForShortCode(shortCode string) (string, bool) {
+	mapping, ok := shortCodeIndex[shortCode]
+	return mapping.ExternalTag, ok
+}
+
+// DirectionForShortCode 返回内部短码对应的排版方向。
+func DirectionForShortCode(shortCode string) (Direction, bool) {
+	mapping, ok := shortCodeIndex[shortCode]
+	return mapping.Direction, ok
+}
+
+// NormalizeCode 将规范外部语言标签或内部短码精确转换为内部短码。
+func NormalizeCode(value string) string {
+	if mapping, ok := externalTagIndex[value]; ok {
+		return mapping.ShortCode
 	}
-	if code := NormalizeCode(fallback); code != "" {
-		return code
+	if mapping, ok := shortCodeIndex[value]; ok {
+		return mapping.ShortCode
 	}
-	return DefaultCode
+	return ""
 }
 
+// IsShortCode 判断值是否为受支持的精确内部短码。
 func IsShortCode(value string) bool {
-	code := strings.TrimSpace(value)
-	if code == "" || code != strings.ToLower(code) {
-		return false
-	}
-	_, ok := supportedCodeSet[code]
+	_, ok := shortCodeIndex[value]
 	return ok
 }
 
-func NormalizeTextMap(input map[string]string) map[string]string {
-	if len(input) == 0 {
-		return map[string]string{}
-	}
+// NormalizeTextMap 将语言键精确转换为内部短码并拒绝无效或冲突输入。
+func NormalizeTextMap(input map[string]string) (map[string]string, error) {
 	result := make(map[string]string, len(input))
 	for key, value := range input {
 		code := NormalizeCode(key)
+		if code == "" {
+			return nil, fmt.Errorf("unsupported locale key %q", key)
+		}
 		text := strings.TrimSpace(value)
-		if code == "" || text == "" {
-			continue
+		if text == "" {
+			return nil, fmt.Errorf("locale %q has empty text", key)
 		}
 		if _, exists := result[code]; exists {
-			continue
+			return nil, fmt.Errorf("duplicate locale mapping for short code %q", code)
 		}
 		result[code] = text
 	}
-	return result
+	return result, nil
 }
 
-func NormalizeLocaleRootedMap[T any](input map[string]T) map[string]T {
-	if len(input) == 0 {
-		return map[string]T{}
-	}
+// NormalizeLocaleRootedMap 将语言根键精确转换为内部短码并拒绝无效或冲突输入。
+func NormalizeLocaleRootedMap[T any](input map[string]T) (map[string]T, error) {
 	result := make(map[string]T, len(input))
 	for key, value := range input {
 		code := NormalizeCode(key)
 		if code == "" {
-			continue
+			return nil, fmt.Errorf("unsupported locale key %q", key)
 		}
 		if _, exists := result[code]; exists {
-			continue
+			return nil, fmt.Errorf("duplicate locale mapping for short code %q", code)
 		}
 		result[code] = value
 	}
-	return result
+	return result, nil
 }
 
+// NormalizeRawTextMap 将 JSON 文本映射规范化为内部短码键。
 func NormalizeRawTextMap(raw json.RawMessage) (json.RawMessage, error) {
 	if len(raw) == 0 {
 		return json.RawMessage(`{}`), nil
@@ -136,7 +156,13 @@ func NormalizeRawTextMap(raw json.RawMessage) (json.RawMessage, error) {
 	if err := json.Unmarshal(raw, &input); err != nil {
 		return nil, err
 	}
-	normalized := NormalizeTextMap(input)
+	if input == nil {
+		return nil, fmt.Errorf("locale text map must be a JSON object")
+	}
+	normalized, err := NormalizeTextMap(input)
+	if err != nil {
+		return nil, err
+	}
 	payload, err := json.Marshal(normalized)
 	if err != nil {
 		return nil, err

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{}).