@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/integrations/onex/iam/resource.go

@@ -0,0 +1,215 @@
+package domain
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — Resource ARN 与段边界匹配（设计文档 §11① / §5.3）
+// ═══════════════════════════════════════════════════════════════
+//
+// ARN 格式（5 段，scope_type 与 scope_id 为独立段，SH-I1 不混标识符类）：
+//
+//	onex:<scope_type>:<scope_id>:<domain>:<resource_type>/<resource_id>
+//
+// 前 4 段以 ':' 分隔；末段为 '<resource_type>/<resource_id>'，按首个 '/' 切分。
+// 例：onex:product:catalog_app:catalog:product/SKU-1
+//
+// 匹配语义（INFO-14 段边界前缀匹配，非裸字符串前缀）：
+//   - IsUnder：prefix 每段须等于对应段或为 '*'（本段通配）。
+//     onex:product:catalog_app:catalog:product/* 命中 .../product/SKU-1，
+//     但不误命中 .../product-archive/*（product 段 ≠ product-archive 段）。
+//   - MatchesARNPattern：pattern 段额外支持 '**'（跨段任意，吞掉剩余全部逻辑段）。
+
+// arnScheme ARN 固定前缀（首段）。
+const arnScheme = "onex"
+
+// arnColonSegments ARN 以 ':' 切分后的段数（onex + scope_type + scope_id + domain + type/id）。
+const arnColonSegments = 5
+
+// segWildcard 单段通配符（匹配任意单个逻辑段）。
+const segWildcard = "*"
+
+// segGlobstar 跨段通配符（匹配剩余任意数量逻辑段，仅模式串可用）。
+const segGlobstar = "**"
+
+// ResourceARN 解析后的资源 ARN。
+//
+// 五个语义字段对应 ARN 的可变部分；Raw 保留原始串用于日志与回显。
+type ResourceARN struct {
+	// 作用域类型（global/product/merchant/tenant/agent/facility）
+	ScopeType string
+	// 作用域值（global 时通常为空串占位）
+	ScopeID string
+	// 域编码
+	Domain string
+	// 资源类型
+	ResourceType string
+	// 资源实例 ID（可含通配 '*'）
+	ResourceID string
+	// 原始 ARN 串
+	Raw string
+}
+
+// BuildResourceARN 资源 ARN 唯一拼装入口（N2 owner helper）。
+//
+// 调用方禁止自行 fmt.Sprintf 拼装 ARN，统一经此函数保证分段格式一致。
+func BuildResourceARN(scopeType, scopeID, domainCode, resourceType, resourceID string) string {
+	return fmt.Sprintf("%s:%s:%s:%s:%s/%s",
+		arnScheme, scopeType, scopeID, domainCode, resourceType, resourceID)
+}
+
+// ParseResourceARN 解析资源 ARN，非法时返回包装 ErrInvalidResourceARN 的错误。
+//
+// 校验项：首段须为 onex；冒号切分须恰为 5 段；末段须含 '/' 切出非空 resource_type。
+func ParseResourceARN(s string) (ResourceARN, error) {
+	parts := strings.Split(s, ":")
+	if len(parts) != arnColonSegments {
+		return ResourceARN{}, fmt.Errorf("%w: expected %d colon-segments, got %d in %q",
+			ErrInvalidResourceARN, arnColonSegments, len(parts), s)
+	}
+	if parts[0] != arnScheme {
+		return ResourceARN{}, fmt.Errorf("%w: scheme must be %q in %q", ErrInvalidResourceARN, arnScheme, s)
+	}
+	// 末段 <resource_type>/<resource_id>，按首个 '/' 切分（resource_id 可再含 '/' 由实现自由约定，此处取首个）
+	tail := parts[4]
+	slash := strings.IndexByte(tail, '/')
+	if slash < 0 {
+		return ResourceARN{}, fmt.Errorf("%w: last segment %q must contain '/'", ErrInvalidResourceARN, tail)
+	}
+	resourceType := tail[:slash]
+	resourceID := tail[slash+1:]
+	if resourceType == "" {
+		return ResourceARN{}, fmt.Errorf("%w: empty resource_type in %q", ErrInvalidResourceARN, s)
+	}
+	return ResourceARN{
+		ScopeType:    parts[1],
+		ScopeID:      parts[2],
+		Domain:       parts[3],
+		ResourceType: resourceType,
+		ResourceID:   resourceID,
+		Raw:          s,
+	}, nil
+}
+
+// segments 返回参与匹配的 5 个逻辑段（去掉固定前缀 onex）：
+// [scope_type, scope_id, domain, resource_type, resource_id]。
+func (a ResourceARN) segments() []string {
+	return []string{a.ScopeType, a.ScopeID, a.Domain, a.ResourceType, a.ResourceID}
+}
+
+// IsCollection 判断 ARN 是否指向「资源集合」而非单个资源实例（resource_id 为空或单段通配 `*`）。
+//
+// 集合 ARN 由 list / 聚合端点的资源模板产出（如 onex:product:catalog_app:order:order/*），请求期无单一
+// 资源实例可加载，故资源行级维度（facility/assignment/ownership）此时无属性可判——这类动作的 action
+// 级检查只判「主体是否被授予此动作」，行级范围交由 ResolveScope → ApplyScope 下推为 WHERE 过滤
+// （两阶段授权，设计 §6.4）。单资源实例 ARN（resource_id 为具体值）不在此列，仍完整求值。
+func (a ResourceARN) IsCollection() bool {
+	return a.ResourceID == "" || a.ResourceID == segWildcard
+}
+
+// IsCollectionResource 解析 ARN 串后判断其是否指向资源集合（无法解析的 ARN 保守视为非集合）。
+//
+// 求值器据此区分集合动作（list / 聚合）与单资源动作：解析失败时返回 false，使非法 ARN 走完整求值
+// 路径并由 §7.2 步骤 6 的 ARN fail-safe 兜底拒绝，绝不因解析失败而误判为集合放宽条件。
+func IsCollectionResource(arn string) bool {
+	parsed, err := ParseResourceARN(arn)
+	if err != nil {
+		return false
+	}
+	return parsed.IsCollection()
+}
+
+// IsUnder 段边界前缀匹配：判断当前 ARN 是否落在 prefix 之下（父子资源继承）。
+//
+// 规则：逐段比较，prefix 的每段须等于当前 ARN 对应段，或为 '*'（本段通配）。
+// '*' 只在单个逻辑段内展开，不跨段；故 product/* 不命中 product-archive/* 段。
+// 不支持 '**'（跨段继承语义不明确，跨段匹配请用 MatchesARNPattern）。
+func (a ResourceARN) IsUnder(prefix ResourceARN) bool {
+	self := a.segments()
+	pre := prefix.segments()
+	for i := range pre {
+		if pre[i] == segWildcard {
+			continue
+		}
+		if pre[i] != self[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// MatchesARNPattern 模式段边界匹配：pattern 是否匹配具体 arn。
+//
+// 具体 arn 切为固定 5 个逻辑段；pattern 段对齐后逐段比较：
+//   - 段为 '*'：匹配任意单个逻辑段；
+//   - 段为 '**'：匹配该位置起剩余任意数量逻辑段（含 0 个），并终止模式（其后段无意义）；
+//   - 其余：要求字面相等。
+//
+// 模式可比具体值"更松"（glob/gitignore 惯例）：以 '**' 收尾的模式无需携带末段 '/'，
+// 例 onex:product:catalog_app:catalog:** 命中 catalog 域下任意 resource_type/resource_id。
+// 非法 arn 或非法 pattern 一律不匹配（fail-safe）。
+func MatchesARNPattern(pattern, arn string) bool {
+	patternSegs, ok := patternSegments(pattern)
+	if !ok {
+		return false
+	}
+	ar, err := ParseResourceARN(arn)
+	if err != nil {
+		return false
+	}
+	return matchSegments(patternSegs, ar.segments())
+}
+
+// patternSegments 把 ARN 模式切为逻辑段（去掉固定前缀 onex）。
+//
+// 与具体 ARN 解析的区别：允许末个冒号段为裸 '**'（无 '/'），此时它作为单个跨段
+// 通配逻辑段，省略其后的 resource_id 逻辑段（模式比具体值更松）；
+// 否则按具体 ARN 同规则解析（首段 onex、共 5 冒号段、末段含 '/' 切出非空 type）。
+// 返回 ok=false 表示模式结构非法。
+func patternSegments(pattern string) ([]string, bool) {
+	parts := strings.Split(pattern, ":")
+	if len(parts) != arnColonSegments || parts[0] != arnScheme {
+		return nil, false
+	}
+	// 形如 onex:scope_type:scope_id:domain:**（末段为裸跨段通配，省略 type/id）
+	if parts[4] == segGlobstar {
+		return []string{parts[1], parts[2], parts[3], segGlobstar}, true
+	}
+	// 其余末段须为合法 type/id 形态（含 '/' 且 type 非空）
+	tail := parts[4]
+	slash := strings.IndexByte(tail, '/')
+	if slash < 0 {
+		return nil, false
+	}
+	resourceType := tail[:slash]
+	if resourceType == "" {
+		return nil, false
+	}
+	return []string{parts[1], parts[2], parts[3], resourceType, tail[slash+1:]}, true
+}
+
+// matchSegments 段序列匹配，支持 '*'（单段）与 '**'（跨段，吞掉剩余并终止）。
+//
+// pattern 段数可少于 target（当 pattern 以 '**' 收尾时）；'**' 一命中即匹配 target
+// 剩余全部段并短路返回 true。非 '**' 情形下 pattern 段数必须与 target 相等。
+func matchSegments(pattern, target []string) bool {
+	for i := range pattern {
+		if pattern[i] == segGlobstar {
+			// 跨段通配：匹配 target 此位置起的全部剩余段，终止比较
+			return true
+		}
+		if i >= len(target) {
+			return false
+		}
+		if pattern[i] == segWildcard {
+			continue
+		}
+		if pattern[i] != target[i] {
+			return false
+		}
+	}
+	// 无 '**' 终止：要求段数完全对齐
+	return len(pattern) == len(target)
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/iam/resource_test.go

@@ -0,0 +1,242 @@
+package domain
+
+import (
+	"errors"
+	"testing"
+)
+
+// TestBuildParseResourceARNRoundTrip 校验 Build → Parse 往返一致性。
+func TestBuildParseResourceARNRoundTrip(t *testing.T) {
+	cases := []struct {
+		name         string
+		scopeType    string
+		scopeID      string
+		domain       string
+		resourceType string
+		resourceID   string
+		wantRaw      string
+	}{
+		{
+			name:         "product catalog SKU",
+			scopeType:    "product",
+			scopeID:      "catalog",
+			domain:       "catalog",
+			resourceType: "product",
+			resourceID:   "SKU-1",
+			wantRaw:      "onex:product:catalog:catalog:product/SKU-1",
+		},
+		{
+			name:         "global scope empty scope_id",
+			scopeType:    "global",
+			scopeID:      "",
+			domain:       "iam",
+			resourceType: "policy",
+			resourceID:   "P-001",
+			wantRaw:      "onex:global::iam:policy/P-001",
+		},
+		{
+			name:         "wildcard resource id",
+			scopeType:    "product",
+			scopeID:      "catalog",
+			domain:       "catalog",
+			resourceType: "product",
+			resourceID:   "*",
+			wantRaw:      "onex:product:catalog:catalog:product/*",
+		},
+		{
+			name:         "hierarchical resource id",
+			scopeType:    "product",
+			scopeID:      "product_beta",
+			domain:       "user_ops",
+			resourceType: "credit-account",
+			resourceID:   "reservation/88",
+			wantRaw:      "onex:product:product_beta:user_ops:credit-account/reservation/88",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			raw := BuildResourceARN(tc.scopeType, tc.scopeID, tc.domain, tc.resourceType, tc.resourceID)
+			if raw != tc.wantRaw {
+				t.Fatalf("BuildResourceARN = %q, want %q", raw, tc.wantRaw)
+			}
+			got, err := ParseResourceARN(raw)
+			if err != nil {
+				t.Fatalf("ParseResourceARN(%q) unexpected error: %v", raw, err)
+			}
+			if got.ScopeType != tc.scopeType || got.ScopeID != tc.scopeID || got.Domain != tc.domain ||
+				got.ResourceType != tc.resourceType || got.ResourceID != tc.resourceID {
+				t.Fatalf("ParseResourceARN(%q) = %+v, fields mismatch", raw, got)
+			}
+			if got.Raw != raw {
+				t.Fatalf("ParseResourceARN(%q).Raw = %q, want %q", raw, got.Raw, raw)
+			}
+		})
+	}
+}
+
+// TestParseResourceARNInvalid 校验非法 ARN 均返回包装 ErrInvalidResourceARN 的错误。
+func TestParseResourceARNInvalid(t *testing.T) {
+	cases := []struct {
+		name string
+		raw  string
+	}{
+		{name: "too few colon segments", raw: "onex:product:catalog:catalog"},
+		{name: "too many colon segments", raw: "onex:product:catalog:catalog:product/SKU:extra"},
+		{name: "wrong scheme", raw: "aws:product:catalog:catalog:product/SKU-1"},
+		{name: "last segment missing slash", raw: "onex:product:catalog:catalog:product"},
+		{name: "empty resource type before slash", raw: "onex:product:catalog:catalog:/SKU-1"},
+		{name: "empty string", raw: ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := ParseResourceARN(tc.raw)
+			if err == nil {
+				t.Fatalf("ParseResourceARN(%q) expected error, got nil", tc.raw)
+			}
+			if !errors.Is(err, ErrInvalidResourceARN) {
+				t.Fatalf("ParseResourceARN(%q) error = %v, want errors.Is ErrInvalidResourceARN", tc.raw, err)
+			}
+		})
+	}
+}
+
+// TestResourceARNIsUnder 校验段边界前缀匹配，重点覆盖 product 与 product-archive 段边界反例。
+func TestResourceARNIsUnder(t *testing.T) {
+	cases := []struct {
+		name   string
+		arn    string
+		prefix string
+		want   bool
+	}{
+		{
+			name:   "exact match self under self",
+			arn:    "onex:product:catalog:catalog:product/SKU-1",
+			prefix: "onex:product:catalog:catalog:product/SKU-1",
+			want:   true,
+		},
+		{
+			name:   "wildcard resource id hits concrete sku",
+			arn:    "onex:product:catalog:catalog:product/SKU-1",
+			prefix: "onex:product:catalog:catalog:product/*",
+			want:   true,
+		},
+		{
+			name:   "segment boundary blocks product-archive",
+			arn:    "onex:product:catalog:catalog:product-archive/SKU-9",
+			prefix: "onex:product:catalog:catalog:product/*",
+			want:   false,
+		},
+		{
+			name:   "wildcard scope_id matches any scope_id",
+			arn:    "onex:product:product_beta:catalog:product/SKU-2",
+			prefix: "onex:product:*:catalog:product/*",
+			want:   true,
+		},
+		{
+			name:   "different domain not under",
+			arn:    "onex:product:catalog:order:product/SKU-1",
+			prefix: "onex:product:catalog:catalog:product/*",
+			want:   false,
+		},
+		{
+			name:   "different resource id not under exact prefix",
+			arn:    "onex:product:catalog:catalog:product/SKU-2",
+			prefix: "onex:product:catalog:catalog:product/SKU-1",
+			want:   false,
+		},
+		{
+			name:   "all wildcard prefix matches everything",
+			arn:    "onex:merchant:M-1:order:refund/RF-1",
+			prefix: "onex:*:*:*:*/*",
+			want:   true,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			arn, err := ParseResourceARN(tc.arn)
+			if err != nil {
+				t.Fatalf("ParseResourceARN(arn=%q) error: %v", tc.arn, err)
+			}
+			prefix, err := ParseResourceARN(tc.prefix)
+			if err != nil {
+				t.Fatalf("ParseResourceARN(prefix=%q) error: %v", tc.prefix, err)
+			}
+			if got := arn.IsUnder(prefix); got != tc.want {
+				t.Fatalf("%q.IsUnder(%q) = %v, want %v", tc.arn, tc.prefix, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestMatchesARNPattern 校验模式匹配：'*' 单段、'**' 跨段、字面相等与非法输入。
+func TestMatchesARNPattern(t *testing.T) {
+	cases := []struct {
+		name    string
+		pattern string
+		arn     string
+		want    bool
+	}{
+		{
+			name:    "exact literal match",
+			pattern: "onex:product:catalog:catalog:product/SKU-1",
+			arn:     "onex:product:catalog:catalog:product/SKU-1",
+			want:    true,
+		},
+		{
+			name:    "single-segment wildcard on resource id",
+			pattern: "onex:product:catalog:catalog:product/*",
+			arn:     "onex:product:catalog:catalog:product/SKU-7",
+			want:    true,
+		},
+		{
+			name:    "resource wildcard covers hierarchical identity",
+			pattern: "onex:product:product_beta:user_ops:credit-account/*",
+			arn:     "onex:product:product_beta:user_ops:credit-account/grant/77",
+			want:    true,
+		},
+		{
+			name:    "single-segment wildcard does not cross segment boundary",
+			pattern: "onex:product:catalog:catalog:product/*",
+			arn:     "onex:product:catalog:catalog:product-archive/SKU-7",
+			want:    false,
+		},
+		{
+			name:    "globstar swallows trailing segments from resource_type",
+			pattern: "onex:product:catalog:catalog:**",
+			arn:     "onex:product:catalog:catalog:product/SKU-1",
+			want:    true,
+		},
+		{
+			// '**' 终止模式：其后的冒号段即使与目标不符也被忽略（证明跨段通配吞掉剩余）
+			name:    "globstar mid-pattern swallows and ignores trailing mismatch",
+			pattern: "onex:product:**:order:refund/RF-9",
+			arn:     "onex:product:catalog:catalog:product/SKU-1",
+			want:    true,
+		},
+		{
+			name:    "literal mismatch on domain",
+			pattern: "onex:product:catalog:catalog:product/*",
+			arn:     "onex:product:catalog:order:product/SKU-1",
+			want:    false,
+		},
+		{
+			name:    "invalid pattern fails safe",
+			pattern: "not-an-arn",
+			arn:     "onex:product:catalog:catalog:product/SKU-1",
+			want:    false,
+		},
+		{
+			name:    "invalid arn fails safe",
+			pattern: "onex:product:catalog:catalog:product/*",
+			arn:     "garbage",
+			want:    false,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := MatchesARNPattern(tc.pattern, tc.arn); got != tc.want {
+				t.Fatalf("MatchesARNPattern(%q, %q) = %v, want %v", tc.pattern, tc.arn, got, tc.want)
+			}
+		})
+	}
+}

package/dist/resources/templates/go-backend/internal/products/README.md

@@ -0,0 +1,5 @@
+# Product modules
+
+Each module owns product use cases, models and persistence. Select Full DDD, Simplified DDD or Flat using [module standards](../../.claude/docs/module-standards.md); the directory name describes its business responsibility.
+
+Compose modules through Wire in `cmd/`. Depend on generic infrastructure and consumer-defined integration ports. Platform authentication, asset execution and payment services remain upstream owners; access their published contracts without querying their internal tables.

package/dist/resources/templates/go-backend/internal/sharedevents/README.md

@@ -0,0 +1,5 @@
+# Shared event contracts
+
+Declare cross-module event names and typed payloads here. Producers and consumers use the same pointer payload contract, with resource identity and audit metadata in the event envelope.
+
+Register persisted payload factories and explicit event schema versions when adding durable delivery. Domain state transitions remain in the owning product module. See [event runtime boundaries](../../.claude/docs/event-runtime-boundary.md) and [backend standards](../../CLAUDE.md).

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

@@ -0,0 +1,13 @@
+BEGIN;
+DROP TABLE public.sys_command_replay_records CASCADE;
+DROP TABLE public.sys_outbox_event_deliveries CASCADE;
+DROP TABLE public.sys_outbox_events CASCADE;
+DROP TABLE public.sys_audit_event_inbox CASCADE;
+DROP TABLE public.sys_operation_logs CASCADE;
+DROP TABLE public.sys_audit_logs CASCADE;
+DROP TABLE public.sys_login_logs CASCADE;
+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();
+COMMIT;