@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/enums/registry.go

@@ -0,0 +1,77 @@
+package enums
+
+import (
+	"sort"
+	"sync"
+)
+
+// Registry 枚举元数据注册中心（线程安全）。
+//
+// 写路径：构造函数阶段一次性批量 Register；运行期不再修改，
+// 读路径由 HTTP handler 调用 List。
+type Registry struct {
+	mu     sync.RWMutex
+	byName map[Domain][]EnumItem
+}
+
+// NewRegistry 创建注册中心并装载默认枚举集合。
+//
+// 默认集合在 register.go 的 DefaultEnums 中定义，避免 init() 副作用（A7）。
+func NewRegistry() *Registry {
+	r := &Registry{byName: make(map[Domain][]EnumItem)}
+	DefaultEnums(r)
+	return r
+}
+
+// Register 为指定 domain 追加一组 EnumItem。
+//
+// 重复调用同一 domain 会覆盖上次注册结果，满足部署时的幂等预期。
+func (r *Registry) Register(domain Domain, items []EnumItem) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	// 浅拷贝避免调用方后续修改切片污染注册表
+	copied := make([]EnumItem, len(items))
+	copy(copied, items)
+	r.byName[domain] = copied
+}
+
+// List 返回指定 domain 列表对应的枚举集合。
+//
+// domains 为空时返回所有已注册 domain；调用方得到的是副本，可安全修改。
+func (r *Registry) List(domains ...Domain) map[Domain][]EnumItem {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	result := make(map[Domain][]EnumItem)
+	if len(domains) == 0 {
+		for d, items := range r.byName {
+			result[d] = cloneItems(items)
+		}
+		return result
+	}
+	for _, d := range domains {
+		if items, ok := r.byName[d]; ok {
+			result[d] = cloneItems(items)
+		}
+	}
+	return result
+}
+
+// Domains 返回所有已注册 domain 的有序列表，便于管理端自检。
+func (r *Registry) Domains() []Domain {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	out := make([]Domain, 0, len(r.byName))
+	for d := range r.byName {
+		out = append(out, d)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i] < out[j] })
+	return out
+}
+
+// cloneItems 复制 item 切片，防止调用方篡改注册表内部切片。
+func cloneItems(items []EnumItem) []EnumItem {
+	dup := make([]EnumItem, len(items))
+	copy(dup, items)
+	return dup
+}

package/dist/resources/templates/go-backend/internal/common/httporigin/origin.go

@@ -0,0 +1,62 @@
+package httporigin
+
+import (
+	"fmt"
+	"net"
+	"net/url"
+	"strings"
+
+	"golang.org/x/net/idna"
+)
+
+// Normalize 将 HTTP Origin 归一为可用于精确安全比较的规范表示。
+func Normalize(value string) (string, error) {
+	parsed, err := url.Parse(strings.TrimSpace(value))
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return "", fmt.Errorf("must be an absolute origin")
+	}
+	if parsed.User != nil || parsed.Path != "" || parsed.RawPath != "" || parsed.RawQuery != "" || parsed.Fragment != "" {
+		return "", fmt.Errorf("must not contain credentials, path, query, or fragment")
+	}
+	parsed.Scheme = strings.ToLower(parsed.Scheme)
+	host, err := normalizeHost(parsed.Hostname())
+	if err != nil {
+		return "", err
+	}
+	if parsed.Scheme != "https" && !(parsed.Scheme == "http" && isLoopbackHost(host)) {
+		return "", fmt.Errorf("must use HTTPS outside loopback")
+	}
+	if strings.ContainsAny(parsed.Host, "* ") {
+		return "", fmt.Errorf("must name one exact host")
+	}
+	port := parsed.Port()
+	if (parsed.Scheme == "https" && port == "443") || (parsed.Scheme == "http" && port == "80") {
+		port = ""
+	}
+	return parsed.Scheme + "://" + hostPort(host, port), nil
+}
+
+func normalizeHost(value string) (string, error) {
+	if ip := net.ParseIP(value); ip != nil {
+		return strings.ToLower(ip.String()), nil
+	}
+	host, err := idna.Lookup.ToASCII(strings.ToLower(strings.TrimSpace(value)))
+	if err != nil || host == "" {
+		return "", fmt.Errorf("origin host is invalid")
+	}
+	return host, nil
+}
+
+func hostPort(host string, port string) string {
+	if port != "" {
+		return net.JoinHostPort(host, port)
+	}
+	if strings.Contains(host, ":") {
+		return "[" + host + "]"
+	}
+	return host
+}
+
+func isLoopbackHost(host string) bool {
+	return host == "localhost" || host == "127.0.0.1" || host == "::1"
+}

package/dist/resources/templates/go-backend/internal/common/httporigin/origin_test.go

@@ -0,0 +1,38 @@
+package httporigin
+
+import "testing"
+
+func TestNormalizeCanonicalizesExactOrigins(t *testing.T) {
+	t.Parallel()
+
+	tests := map[string]string{
+		"HTTPS://BÜCHER.Example:443": "https://xn--bcher-kva.example",
+		"http://LOCALHOST:80":        "http://localhost",
+		"http://[::1]:3000":          "http://[::1]:3000",
+	}
+	for input, expected := range tests {
+		actual, err := Normalize(input)
+		if err != nil {
+			t.Fatalf("Normalize(%q) error = %v", input, err)
+		}
+		if actual != expected {
+			t.Fatalf("Normalize(%q) = %q, want %q", input, actual, expected)
+		}
+	}
+}
+
+func TestNormalizeRejectsNonOriginValues(t *testing.T) {
+	t.Parallel()
+
+	for _, input := range []string{
+		"http://example.com",
+		"https://*.example.com",
+		"https://example.com/path",
+		"https://user@example.com",
+		"https://example.com?token=secret",
+	} {
+		if _, err := Normalize(input); err == nil {
+			t.Fatalf("Normalize(%q) error = nil", input)
+		}
+	}
+}

package/dist/resources/templates/go-backend/internal/common/iamcredential/plaintext.go

@@ -0,0 +1,35 @@
+package iamcredential
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+const PlaintextPrefix = "iamk_"
+
+var plaintextPattern = regexp.MustCompile(`^iamk_(ck_[A-Za-z0-9_-]{24})\.([A-Za-z0-9_-]{43})$`)
+
+// Plaintext 表示经过完整语法校验的 IAM 启动凭证。
+type Plaintext struct {
+	CredentialKeyID string
+	Secret          string
+}
+
+// ParsePlaintext 按签发器的固定熵与编码合同解析 IAM 启动凭证。
+func ParsePlaintext(value string) (Plaintext, error) {
+	if strings.TrimSpace(value) != value {
+		return Plaintext{}, fmt.Errorf("IAM credential plaintext is invalid")
+	}
+	matches := plaintextPattern.FindStringSubmatch(value)
+	if len(matches) != 3 {
+		return Plaintext{}, fmt.Errorf("IAM credential plaintext is invalid")
+	}
+	return Plaintext{CredentialKeyID: matches[1], Secret: matches[2]}, nil
+}
+
+// ValidatePlaintext 校验 IAM 启动凭证是否与签发格式完全一致。
+func ValidatePlaintext(value string) error {
+	_, err := ParsePlaintext(value)
+	return err
+}

package/dist/resources/templates/go-backend/internal/common/iamcredential/plaintext_test.go

@@ -0,0 +1,29 @@
+package iamcredential
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestParsePlaintextUsesExactIssuedCredentialContract(t *testing.T) {
+	const value = "iamk_ck_AAAAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
+	parsed, err := ParsePlaintext(value)
+	require.NoError(t, err)
+	require.Equal(t, "ck_AAAAAAAAAAAAAAAAAAAAAAAA", parsed.CredentialKeyID)
+	require.Equal(t, "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", parsed.Secret)
+}
+
+func TestParsePlaintextRejectsNonCanonicalForms(t *testing.T) {
+	for _, value := range []string{
+		"",
+		"iamk_ck_short.secret",
+		" iamk_ck_AAAAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+		"iamk_ck_AAAAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB ",
+		"Bearer iamk_ck_AAAAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+		"iamk_ck_AAAAAAAAAAAAAAAAAAAAAAA!.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+		"iamk_ck_AAAAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+	} {
+		require.Error(t, ValidatePlaintext(value), value)
+	}
+}

package/dist/resources/templates/go-backend/internal/common/iamscope/scope.go

@@ -0,0 +1,212 @@
+package iamscope
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 数据范围约束代数（ScopeConstraint）
+// ═══════════════════════════════════════════════════════════════
+//
+// 这是「列表数据范围」与「单资源授权」语义等价的核心（设计文档 §6.3）。
+// ScopeConstraint 用析取范式（DNF）+ Deny 否定表达：
+//   AllowGroups 组间 OR、组内 AND；DenyGroups 逐组 AND NOT；Unbounded 短路放行。
+// 翻译为 SQL：( (g1) OR (g2) ... ) AND NOT (d1) AND NOT (d2) ...
+// 该结构与单资源 Evaluate 的「多 Allow 取并 / Deny 覆盖 / super 短路」严格同构，
+// 保证一致性不变式：Evaluate(p,a,r).allowed == ( r ∈ translate(ResolveScope(p,a)) )。
+
+// ScopeDimension 可下推到 SQL 列的数据范围维度。
+type ScopeDimension string
+
+const (
+	// ScopeDimensionProduct 产品线
+	ScopeDimensionProduct ScopeDimension = "product"
+	// ScopeDimensionOrganization 跨产品共享组织
+	ScopeDimensionOrganization ScopeDimension = "organization"
+	// ScopeDimensionWorkspace 产品自有工作区
+	ScopeDimensionWorkspace ScopeDimension = "workspace"
+	// ScopeDimensionMerchant 商户（隔离维度，exact-match）
+	ScopeDimensionMerchant ScopeDimension = "merchant"
+	// ScopeDimensionTenant 租户（隔离维度，exact-match）
+	ScopeDimensionTenant ScopeDimension = "tenant"
+	// ScopeDimensionAgent 代理 / 分销
+	ScopeDimensionAgent ScopeDimension = "agent"
+	// ScopeDimensionFacility 设施总维度（store/kitchen/warehouse/zone 的统称，隔离维度）
+	ScopeDimensionFacility ScopeDimension = "facility"
+	// ScopeDimensionStore 门店
+	ScopeDimensionStore ScopeDimension = "store"
+	// ScopeDimensionKitchen 厨房 / 产能点
+	ScopeDimensionKitchen ScopeDimension = "kitchen"
+	// ScopeDimensionWarehouse 仓库
+	ScopeDimensionWarehouse ScopeDimension = "warehouse"
+	// ScopeDimensionZone 配送区
+	ScopeDimensionZone ScopeDimension = "zone"
+	// ScopeDimensionAssignedToSelf 派给当前主体
+	ScopeDimensionAssignedToSelf ScopeDimension = "assigned_to_self"
+	// ScopeDimensionCreatedBySelf 当前主体创建
+	ScopeDimensionCreatedBySelf ScopeDimension = "created_by_self"
+	// ScopeDimensionSameOwner 与当前主体同 owner
+	ScopeDimensionSameOwner ScopeDimension = "same_owner"
+	// ScopeDimensionOwnerTeam 当前主体所属团队拥有
+	ScopeDimensionOwnerTeam ScopeDimension = "owner_team"
+)
+
+// allScopeDimensions 全部可下推维度（与 register_iam.go 注册集合一致）。
+var allScopeDimensions = []ScopeDimension{
+	ScopeDimensionProduct, ScopeDimensionOrganization, ScopeDimensionWorkspace,
+	ScopeDimensionMerchant, ScopeDimensionTenant, ScopeDimensionAgent,
+	ScopeDimensionFacility, ScopeDimensionStore, ScopeDimensionKitchen, ScopeDimensionWarehouse, ScopeDimensionZone,
+	ScopeDimensionAssignedToSelf, ScopeDimensionCreatedBySelf, ScopeDimensionSameOwner, ScopeDimensionOwnerTeam,
+}
+
+// AllScopeDimensions 返回全部可下推维度副本。
+func AllScopeDimensions() []ScopeDimension {
+	out := make([]ScopeDimension, len(allScopeDimensions))
+	copy(out, allScopeDimensions)
+	return out
+}
+
+// IsValid 校验维度是否在可下推集合内。
+func (d ScopeDimension) IsValid() bool {
+	for _, item := range allScopeDimensions {
+		if item == d {
+			return true
+		}
+	}
+	return false
+}
+
+// IsIsolation 隔离维度（无约束=拒绝、禁通配、须 exact-match）。
+func (d ScopeDimension) IsIsolation() bool {
+	switch d {
+	case ScopeDimensionOrganization, ScopeDimensionWorkspace, ScopeDimensionMerchant,
+		ScopeDimensionTenant, ScopeDimensionAgent, ScopeDimensionFacility,
+		ScopeDimensionStore, ScopeDimensionKitchen, ScopeDimensionWarehouse, ScopeDimensionZone:
+		return true
+	default:
+		return false
+	}
+}
+
+// 范围谓词算子（内部代数用，非前端元数据，故不暴露为命名枚举类型）。
+const (
+	// ScopeOpIn 维度值落在给定集合内
+	ScopeOpIn = "in"
+	// ScopeOpEquals 维度值精确相等（隔离维度专用）
+	ScopeOpEquals = "equals"
+	// ScopeOpSelf 维度绑定到当前主体（assigned_to_self/created_by_self/same_owner），Values 为空，由 applier 用 principal 填充
+	ScopeOpSelf = "self"
+)
+
+// DimPredicate 单维度范围谓词。
+type DimPredicate struct {
+	// 维度
+	Dimension ScopeDimension
+	// 算子（ScopeOpIn / ScopeOpEquals / ScopeOpSelf）
+	Operator string
+	// 候选值集合（ScopeOpSelf 时为空）
+	Values []string
+}
+
+// ScopeConstraint 数据范围约束（DNF + Deny 否定 + super 短路）。
+type ScopeConstraint struct {
+	// 允许组：组间 OR、组内 AND
+	AllowGroups [][]DimPredicate
+	// 拒绝组：逐组 AND NOT
+	DenyGroups [][]DimPredicate
+	// 是否全局无约束（super scope，短路放行）
+	Unbounded bool
+}
+
+// NewUnboundedScope 返回 super scope（放行全部）。
+func NewUnboundedScope() ScopeConstraint {
+	return ScopeConstraint{Unbounded: true}
+}
+
+// IsUnbounded 是否全局无约束。
+func (c ScopeConstraint) IsUnbounded() bool {
+	return c.Unbounded
+}
+
+// IsEmpty 既非 unbounded 又无任一允许组 → 拒绝全部（fail-safe 默认，无 Allow 即不可见）。
+func (c ScopeConstraint) IsEmpty() bool {
+	return !c.Unbounded && len(c.AllowGroups) == 0
+}
+
+// AddAllowGroup 追加一条 Allow 语句产出的维度组（组间 OR）。
+//
+// 空组表示该 Allow 无可下推 scope 条件，等价于该 action 上的 super scope，置 Unbounded。
+func (c *ScopeConstraint) AddAllowGroup(group []DimPredicate) {
+	if c.Unbounded {
+		return
+	}
+	if len(group) == 0 {
+		c.Unbounded = true
+		c.AllowGroups = nil
+		return
+	}
+	c.AllowGroups = append(c.AllowGroups, cloneScopeGroup(group))
+}
+
+// AddDenyGroup 追加一条 Deny 语句产出的维度组（AND NOT）。
+//
+// 空组（无可下推条件的 Deny）无法表达为列谓词，交由行级精判处理，此处忽略。
+func (c *ScopeConstraint) AddDenyGroup(group []DimPredicate) {
+	if len(group) == 0 {
+		return
+	}
+	c.DenyGroups = append(c.DenyGroups, cloneScopeGroup(group))
+}
+
+// Narrow 用 boundary / session 约束收紧当前约束（取交）。
+//
+// DNF 取交 = 允许组两两笛卡尔积合并（组内再 AND）；拒绝组取并。
+// boundary unbounded 则不收紧；当前 unbounded 则收紧为 boundary。
+func (c ScopeConstraint) Narrow(boundary ScopeConstraint) ScopeConstraint {
+	if boundary.Unbounded {
+		return c.clone()
+	}
+	if c.Unbounded {
+		return boundary.clone()
+	}
+	result := ScopeConstraint{}
+	for _, ga := range c.AllowGroups {
+		for _, gb := range boundary.AllowGroups {
+			merged := make([]DimPredicate, 0, len(ga)+len(gb))
+			merged = append(merged, cloneScopeGroup(ga)...)
+			merged = append(merged, cloneScopeGroup(gb)...)
+			result.AllowGroups = append(result.AllowGroups, merged)
+		}
+	}
+	for _, d := range c.DenyGroups {
+		result.DenyGroups = append(result.DenyGroups, cloneScopeGroup(d))
+	}
+	for _, d := range boundary.DenyGroups {
+		result.DenyGroups = append(result.DenyGroups, cloneScopeGroup(d))
+	}
+	return result
+}
+
+// clone 深拷贝约束，避免调用方修改污染。
+func (c ScopeConstraint) clone() ScopeConstraint {
+	out := ScopeConstraint{Unbounded: c.Unbounded}
+	for _, g := range c.AllowGroups {
+		out.AllowGroups = append(out.AllowGroups, cloneScopeGroup(g))
+	}
+	for _, g := range c.DenyGroups {
+		out.DenyGroups = append(out.DenyGroups, cloneScopeGroup(g))
+	}
+	return out
+}
+
+// cloneScopeGroup 深拷贝维度组（含 Values 切片）。
+func cloneScopeGroup(group []DimPredicate) []DimPredicate {
+	out := make([]DimPredicate, len(group))
+	for i := range group {
+		out[i] = DimPredicate{
+			Dimension: group[i].Dimension,
+			Operator:  group[i].Operator,
+		}
+		if len(group[i].Values) > 0 {
+			out[i].Values = make([]string, len(group[i].Values))
+			copy(out[i].Values, group[i].Values)
+		}
+	}
+	return out
+}

package/dist/resources/templates/go-backend/internal/common/iamscope/scope_binding.go

@@ -0,0 +1,26 @@
+package iamscope
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 数据范围注入绑定（ScopeBinding，设计文档 §6.5）
+// ═══════════════════════════════════════════════════════════════
+//
+// 依赖方向（A3，消费方定义接口）：ScopeBinding 由 common/iamscope 定义、各业务域实现、
+// common/iamscope 的 applier 消费——common 不 import 任何业务域。各域在自己的 query_service
+// 里构造本域 ScopeBinding（把 scope 维度映射到本域表的 SQL 列），再调 applier.ApplyScope
+// 把 ScopeConstraint 翻译成 GORM WHERE。
+//
+// 维度→列是「域知识」（order 的 facility 在 store_id 列、delivery 在 zone_code 列），故由域提供；
+// 「DNF 代数→SQL」是「iam 知识」，故由 applier 持有。两者经此接口解耦，互不反向依赖。
+
+// ScopeBinding 由各业务域提供：把数据范围维度映射到本域表的 SQL 列。
+//
+// applier 对每个 DimPredicate 调 Column(dim) 取列后，按 Operator（in/equals/self）统一构造谓词。
+// 维度在本域无对应列（如 merchandise 域无 facility 列）时返回 ok=false，applier 据此 fail loudly
+// 返回 error——绝不静默放行（静默=越权可见，§6.5）。
+type ScopeBinding interface {
+	// Column 返回维度对应的本域 SQL 列名。
+	//
+	// 该维度在本域无对应列时 ok=false，applier 据此返回 error（不静默放行）。
+	// 返回的列名是域提供的常量（非用户输入），由 applier 安全拼接进查询。
+	Column(dim ScopeDimension) (column string, ok bool)
+}

package/dist/resources/templates/go-backend/internal/common/iamscope/scope_filter.go

@@ -0,0 +1,173 @@
+package iamscope
+
+import (
+	"fmt"
+
+	"gorm.io/gorm"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 数据范围 SQL 注入器（applier，设计文档 §6.3 翻译 / §6.5 注入机制）
+// ═══════════════════════════════════════════════════════════════
+//
+// 无状态纯函数：把 ResolveScope 产出的 ScopeConstraint（DNF + Deny 否定）翻译成 GORM WHERE。
+// 维度→列由域提供的 ScopeBinding 映射（common 不 import 业务域，A3）；applier 只持有
+// 「DNF 代数 → SQL」翻译规则。
+//
+// 翻译规则（§6.3，与 evaluator_consistency_test.go 的 matchesConstraint 参照实现严格等价）：
+//
+//	WHERE ( (g1d1 AND g1d2) OR (g2d1) OR ... )   -- AllowGroups：组间 OR、组内 AND
+//	  AND NOT (d1...) AND NOT (d2...)            -- DenyGroups：逐组 AND NOT
+//
+//	Unbounded（super scope）→ 不加任何 WHERE，原样返回（§6.6 短路优先，与 matchesConstraint 同）。
+//	IsEmpty（非 unbounded 且无 AllowGroup）→ WHERE 1 = 0（无授权=查不到，fail-safe）。
+//
+// 括号正确性靠「每组用独立 NewDB 会话构建子表达式 + 组间 OR 整体包进一个外层 Where」保证：
+// AllowGroups 全部 OR 进一个子构建器后再 db.Where(orBuilder)，GORM 渲染为 ((g1) OR (g2))；
+// 每个 DenyGroup 经 db.Not(groupBuilder) 渲染为 AND NOT (...)。两者由顶层 AND 连接，
+// 与 Allow 的 OR 优先级不串（已 DryRun 验证：((a AND b) OR c) AND NOT (d AND e)）。
+
+// ApplyScope 把数据范围约束注入 GORM 查询，返回追加 WHERE 后的查询。
+//
+// db 为待过滤的查询（通常已 .Model/.Table）；sc 为 ResolveScope 产出的约束；
+// binding 由调用域提供维度→列映射；principalID 用于填充 ScopeOpSelf 谓词（col = principalID）。
+// 维度无对应列、算子不支持、或谓词取值非法时返回 error（fail loudly，不静默放行=不越权）。
+func ApplyScope(
+	db *gorm.DB,
+	sc ScopeConstraint,
+	binding ScopeBinding,
+	principalID int64,
+) (*gorm.DB, error) {
+	// super scope：短路放行，不加任何过滤（§6.6，与参照实现 matchesConstraint 的 IsUnbounded 短路一致）。
+	if sc.IsUnbounded() {
+		return db, nil
+	}
+	// 无任一 Allow 组：拒绝全部（fail-safe 默认，无授权即不可见）。
+	if sc.IsEmpty() {
+		return db.Where("1 = 0"), nil
+	}
+
+	// AllowGroups：组间 OR。每组构建为独立子表达式后用 .Or 串联，整体再包进一个外层 Where 保证括号。
+	allow, err := buildAllowExpr(db, sc.AllowGroups, binding, principalID)
+	if err != nil {
+		return nil, err
+	}
+	result := db.Where(allow)
+
+	// DenyGroups：逐组 AND NOT（每组组内 AND）。
+	for _, group := range sc.DenyGroups {
+		denyExpr, err := buildGroupExpr(db, group, binding, principalID)
+		if err != nil {
+			return nil, err
+		}
+		if denyExpr == nil {
+			// 空 Deny 组无可下推谓词 → 无法表达为列否定，跳过（与 AddDenyGroup 忽略空组一致）。
+			continue
+		}
+		result = result.Not(denyExpr)
+	}
+	return result, nil
+}
+
+// buildAllowExpr 把全部 AllowGroups 构建为「组间 OR」的子表达式。
+//
+// 每组构建为独立子表达式；首组用 Where、其余用 Or 串联，使 GORM 渲染为 ((g1) OR (g2) ...)。
+// 空组（无可下推谓词）等价于该 OR 分支无约束（恒真），按参照实现 groupMatches 对空组返回 true
+// 处理——一旦出现空 Allow 组即整体放行（不再追加列约束），保持与 matchesConstraint 语义等价。
+func buildAllowExpr(
+	db *gorm.DB,
+	groups [][]DimPredicate,
+	binding ScopeBinding,
+	principalID int64,
+) (*gorm.DB, error) {
+	orBuilder := newScopeSession(db)
+	hasClause := false
+	for _, group := range groups {
+		groupExpr, err := buildGroupExpr(db, group, binding, principalID)
+		if err != nil {
+			return nil, err
+		}
+		if groupExpr == nil {
+			// 空 Allow 组 = 该分支恒真（matchesConstraint 对空组 groupMatches→true）。
+			// 任一 OR 分支恒真 ⇒ 整个 Allow 恒真，注入一个恒真表达式即可，无需追加列约束。
+			return newScopeSession(db).Where("1 = 1"), nil
+		}
+		if hasClause {
+			orBuilder = orBuilder.Or(groupExpr)
+		} else {
+			orBuilder = orBuilder.Where(groupExpr)
+			hasClause = true
+		}
+	}
+	return orBuilder, nil
+}
+
+// buildGroupExpr 把一个维度组构建为「组内 AND」的子表达式；空组返回 nil（无可下推谓词）。
+//
+// 组内每个 DimPredicate 经 binding 映射列、按 Operator 构造列谓词后用 Where 串联（GORM 默认 AND）。
+func buildGroupExpr(
+	db *gorm.DB,
+	group []DimPredicate,
+	binding ScopeBinding,
+	principalID int64,
+) (*gorm.DB, error) {
+	if len(group) == 0 {
+		return nil, nil
+	}
+	groupBuilder := newScopeSession(db)
+	for i := range group {
+		pred := group[i]
+		column, ok := binding.Column(pred.Dimension)
+		if !ok {
+			// 域无此维度对应列 → fail loudly，绝不静默放行（静默=越权可见，§6.5）。
+			return nil, fmt.Errorf("scope dimension %s unsupported by binding", pred.Dimension)
+		}
+		if column == "" {
+			// 防御：绑定返回空列名属域实现错误，同样 fail loudly。
+			return nil, fmt.Errorf("scope dimension %s mapped to empty column by binding", pred.Dimension)
+		}
+		query, args, err := buildPredicate(column, pred, principalID)
+		if err != nil {
+			return nil, err
+		}
+		groupBuilder = groupBuilder.Where(query, args...)
+	}
+	return groupBuilder, nil
+}
+
+// buildPredicate 按算子把单维度谓词构造成 GORM 条件片段与参数。
+//
+// 列名为域提供常量（非用户输入），作占位安全拼接；候选值一律走 ? 占位，无 SQL 注入面。
+//   - ScopeOpIn  → col IN (values)；空候选值 → 1 = 0（fail-closed，与 matchesConstraint 的 valueIn 空集返回 false 一致）
+//   - ScopeOpEquals → col = value（隔离维度专用，恰好单值；非单值 fail loudly）
+//   - ScopeOpSelf  → col = principalID（assignment 维度绑定当前主体）
+//   - 其余算子 → fail loudly（不静默放行）
+func buildPredicate(column string, pred DimPredicate, principalID int64) (string, []any, error) {
+	switch pred.Operator {
+	case ScopeOpIn:
+		if len(pred.Values) == 0 {
+			// 空候选集 = 匹配空集（隔离维度无约束=拒绝，§6.6）；用 1 = 0 显式 fail-closed，
+			// 不依赖 GORM 对空 IN 的渲染（跨驱动/版本不稳定）。
+			return "1 = 0", nil, nil
+		}
+		return column + " IN ?", []any{pred.Values}, nil
+	case ScopeOpEquals:
+		// equals 为隔离维度精确相等，约束恰好携带单值；非单值属构造错误，fail loudly（避免 panic / 误下推）。
+		if len(pred.Values) != 1 {
+			return "", nil, fmt.Errorf("scope dimension %s operator equals requires exactly one value, got %d", pred.Dimension, len(pred.Values))
+		}
+		return column + " = ?", []any{pred.Values[0]}, nil
+	case ScopeOpSelf:
+		// self 维度绑定当前主体：列存主体 ID（assigned_operator_id 等），按 principalID 精确比对。
+		return column + " = ?", []any{principalID}, nil
+	default:
+		return "", nil, fmt.Errorf("scope dimension %s has unsupported operator %q", pred.Dimension, pred.Operator)
+	}
+}
+
+// newScopeSession 返回一个全新的子查询会话，用于构建独立的 WHERE 子表达式。
+//
+// NewDB:true 切断与外层链式条件的共享，使每组子表达式互不串扰，保证 OR/NOT 的括号边界正确。
+func newScopeSession(db *gorm.DB) *gorm.DB {
+	return db.Session(&gorm.Session{NewDB: true})
+}