@stackonward/cli 0.0.1 → 1.0.1

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

@@ -0,0 +1,77 @@
+package domain
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 动作（Action）拼装、解析与模式匹配
+// ═══════════════════════════════════════════════════════════════
+//
+// 动作格式（3 段）：<domain>:<resource>:<verb>，例 order:refund:approve。
+// verb 取值见 enum.go Verb 规范集合。
+// 模式匹配语义：按 ':' 段边界比较，'*' 仅匹配本段，整体 '*' 匹配一切动作。
+//   order:refund:*  命中 order:refund:approve / order:refund:read …
+//   order:*:*       命中 order 域全部动作
+//   *               命中任意动作（管理面 super 语义）
+
+// actionSegments 动作以 ':' 切分后的段数（domain + resource + verb）。
+const actionSegments = 3
+
+// actionWildcardAll 整体通配（匹配任意动作）。
+const actionWildcardAll = "*"
+
+// BuildAction 动作唯一拼装入口（N2 owner helper）。
+//
+// 调用方禁止自行 fmt.Sprintf 拼装动作串，统一经此函数保证三段格式一致。
+func BuildAction(domainCode, resourceType string, verb Verb) string {
+	return fmt.Sprintf("%s:%s:%s", domainCode, resourceType, verb)
+}
+
+// ParseAction 解析规范动作 <domain>:<resource>:<verb>，非法时返回包装 ErrInvalidAction 的错误。
+//
+// 校验项：冒号切分须恰为 3 段且各段非空；verb 须在规范动词集合内（enum.go AllVerbs）。
+func ParseAction(s string) (domainCode, resourceType string, verb Verb, err error) {
+	parts := strings.Split(s, ":")
+	if len(parts) != actionSegments {
+		return "", "", "", fmt.Errorf("%w: expected %d segments, got %d in %q",
+			ErrInvalidAction, actionSegments, len(parts), s)
+	}
+	if parts[0] == "" || parts[1] == "" || parts[2] == "" {
+		return "", "", "", fmt.Errorf("%w: empty segment in %q", ErrInvalidAction, s)
+	}
+	v := Verb(parts[2])
+	if !v.IsValid() {
+		return "", "", "", fmt.Errorf("%w: unknown verb %q in %q", ErrInvalidAction, parts[2], s)
+	}
+	return parts[0], parts[1], v, nil
+}
+
+// MatchesActionPattern 动作模式匹配：pattern 是否匹配具体 action。
+//
+// 规则：
+//   - pattern 为 '*'：匹配任意动作（整体通配）；
+//   - 否则按 ':' 切为 3 段逐段比较，段为 '*' 匹配本段任意值，其余要求字面相等。
+//
+// pattern 与 action 段数须均为 3（'*' 整体通配除外），否则不匹配（fail-safe）。
+// 不在此处强校验 verb 是否规范——模式匹配只做字面段比较，规范性由 catalog 写入时保证。
+func MatchesActionPattern(pattern, action string) bool {
+	if pattern == actionWildcardAll {
+		return true
+	}
+	pa := strings.Split(pattern, ":")
+	ac := strings.Split(action, ":")
+	if len(pa) != actionSegments || len(ac) != actionSegments {
+		return false
+	}
+	for i := range pa {
+		if pa[i] == segWildcard {
+			continue
+		}
+		if pa[i] != ac[i] {
+			return false
+		}
+	}
+	return true
+}

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

@@ -0,0 +1,238 @@
+package domain
+
+import (
+	"errors"
+	"slices"
+	"testing"
+)
+
+// TestBuildParseActionRoundTrip 校验 Build → Parse 往返一致性。
+func TestBuildParseActionRoundTrip(t *testing.T) {
+	cases := []struct {
+		name         string
+		domain       string
+		resourceType string
+		verb         Verb
+		wantAction   string
+	}{
+		{
+			name:         "order refund approve",
+			domain:       "order",
+			resourceType: "refund",
+			verb:         VerbApprove,
+			wantAction:   "order:refund:approve",
+		},
+		{
+			name:         "catalog product read",
+			domain:       "catalog",
+			resourceType: "product",
+			verb:         VerbRead,
+			wantAction:   "catalog:product:read",
+		},
+		{
+			name:         "iam policy publish",
+			domain:       "iam",
+			resourceType: "policy",
+			verb:         VerbPublish,
+			wantAction:   "iam:policy:publish",
+		},
+		{
+			name:         "secret lease replace",
+			domain:       "secret",
+			resourceType: "lease",
+			verb:         VerbReplace,
+			wantAction:   "secret:lease:replace",
+		},
+		{
+			name:         "secret lease redeem",
+			domain:       "secret",
+			resourceType: "lease",
+			verb:         VerbRedeem,
+			wantAction:   "secret:lease:redeem",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			action := BuildAction(tc.domain, tc.resourceType, tc.verb)
+			if action != tc.wantAction {
+				t.Fatalf("BuildAction = %q, want %q", action, tc.wantAction)
+			}
+			gotDomain, gotResource, gotVerb, err := ParseAction(action)
+			if err != nil {
+				t.Fatalf("ParseAction(%q) unexpected error: %v", action, err)
+			}
+			if gotDomain != tc.domain || gotResource != tc.resourceType || gotVerb != tc.verb {
+				t.Fatalf("ParseAction(%q) = (%q, %q, %q), want (%q, %q, %q)",
+					action, gotDomain, gotResource, gotVerb, tc.domain, tc.resourceType, tc.verb)
+			}
+		})
+	}
+}
+
+// TestAllVerbsCanonicalSet 锁定规范动词全集，防止扩展 Secret 动作时丢失既有动作或引入重复值。
+func TestAllVerbsCanonicalSet(t *testing.T) {
+	want := []Verb{
+		VerbList, VerbRead, VerbCreate, VerbUpdate, VerbDelete, VerbManage, VerbExport,
+		VerbApprove, VerbReject, VerbRefund, VerbPublish, VerbRollback, VerbConfigure,
+		VerbImpersonate, VerbRun, VerbRecover, VerbReplay, VerbRotate, VerbRevoke,
+		VerbGrant, VerbAssign, VerbClose, VerbModerate, VerbBind, VerbAdjust,
+		VerbCancel, VerbErase, VerbSuspend, VerbVerify, VerbReplace, VerbRedeem,
+	}
+	got := AllVerbs()
+	if !slices.Equal(got, want) {
+		t.Fatalf("AllVerbs() = %v, want %v", got, want)
+	}
+
+	seen := make(map[Verb]struct{}, len(got))
+	for _, verb := range got {
+		if _, exists := seen[verb]; exists {
+			t.Fatalf("AllVerbs() contains duplicate verb %q", verb)
+		}
+		seen[verb] = struct{}{}
+		if !verb.IsValid() {
+			t.Fatalf("AllVerbs() contains invalid verb %q", verb)
+		}
+	}
+}
+
+// TestParseDesignedSecretActions 校验 SecretBroker 已设计动作全部使用规范三段动作和封闭动词。
+func TestParseDesignedSecretActions(t *testing.T) {
+	testCases := []struct {
+		action       string
+		resourceType string
+		verb         Verb
+	}{
+		{action: "secret:secret:create", resourceType: "secret", verb: VerbCreate},
+		{action: "secret:secret:read", resourceType: "secret", verb: VerbRead},
+		{action: "secret:version:rotate", resourceType: "version", verb: VerbRotate},
+		{action: "secret:secret:revoke", resourceType: "secret", verb: VerbRevoke},
+		{action: "secret:version:revoke", resourceType: "version", verb: VerbRevoke},
+		{action: "secret:secret:delete", resourceType: "secret", verb: VerbDelete},
+		{action: "secret:lease:create", resourceType: "lease", verb: VerbCreate},
+		{action: "secret:lease:replace", resourceType: "lease", verb: VerbReplace},
+		{action: "secret:lease:redeem", resourceType: "lease", verb: VerbRedeem},
+		{action: "secret:access-event:list", resourceType: "access-event", verb: VerbList},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.action, func(t *testing.T) {
+			domainCode, resourceType, verb, err := ParseAction(testCase.action)
+			if err != nil {
+				t.Fatalf("ParseAction(%q) unexpected error: %v", testCase.action, err)
+			}
+			if domainCode != "secret" || resourceType != testCase.resourceType || verb != testCase.verb {
+				t.Fatalf(
+					"ParseAction(%q) = (%q, %q, %q), want (%q, %q, %q)",
+					testCase.action,
+					domainCode,
+					resourceType,
+					verb,
+					"secret",
+					testCase.resourceType,
+					testCase.verb,
+				)
+			}
+		})
+	}
+}
+
+// TestParseActionInvalid 校验非法动作均返回包装 ErrInvalidAction 的错误。
+func TestParseActionInvalid(t *testing.T) {
+	cases := []struct {
+		name   string
+		action string
+	}{
+		{name: "too few segments", action: "order:refund"},
+		{name: "too many segments", action: "order:refund:approve:extra"},
+		{name: "empty domain segment", action: ":refund:approve"},
+		{name: "empty verb segment", action: "order:refund:"},
+		{name: "unknown verb", action: "order:refund:frobnicate"},
+		{name: "unknown secret lease verb", action: "secret:lease:consume"},
+		{name: "access operation is not an IAM verb", action: "secret:lease:issue_lease"},
+		{name: "wildcard is not a concrete verb", action: "secret:lease:*"},
+		{name: "empty string", action: ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, _, _, err := ParseAction(tc.action)
+			if err == nil {
+				t.Fatalf("ParseAction(%q) expected error, got nil", tc.action)
+			}
+			if !errors.Is(err, ErrInvalidAction) {
+				t.Fatalf("ParseAction(%q) error = %v, want errors.Is ErrInvalidAction", tc.action, err)
+			}
+		})
+	}
+}
+
+// TestMatchesActionPattern 校验动作模式匹配各档：精确 / verb 通配 / resource+verb 通配 / 全局 / 不匹配 / 非法段数。
+func TestMatchesActionPattern(t *testing.T) {
+	cases := []struct {
+		name    string
+		pattern string
+		action  string
+		want    bool
+	}{
+		{
+			name:    "exact match",
+			pattern: "order:refund:approve",
+			action:  "order:refund:approve",
+			want:    true,
+		},
+		{
+			name:    "verb wildcard hits same domain resource",
+			pattern: "order:refund:*",
+			action:  "order:refund:read",
+			want:    true,
+		},
+		{
+			name:    "verb wildcard misses different resource",
+			pattern: "order:refund:*",
+			action:  "order:shipment:read",
+			want:    false,
+		},
+		{
+			name:    "resource and verb wildcard hits whole domain",
+			pattern: "order:*:*",
+			action:  "order:refund:approve",
+			want:    true,
+		},
+		{
+			name:    "resource and verb wildcard misses other domain",
+			pattern: "order:*:*",
+			action:  "catalog:product:read",
+			want:    false,
+		},
+		{
+			name:    "global wildcard matches any action",
+			pattern: "*",
+			action:  "iam:policy:publish",
+			want:    true,
+		},
+		{
+			name:    "literal mismatch on domain",
+			pattern: "order:refund:approve",
+			action:  "catalog:refund:approve",
+			want:    false,
+		},
+		{
+			name:    "pattern wrong segment count fails safe",
+			pattern: "order:refund",
+			action:  "order:refund:approve",
+			want:    false,
+		},
+		{
+			name:    "action wrong segment count fails safe",
+			pattern: "order:refund:approve",
+			action:  "order:refund",
+			want:    false,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := MatchesActionPattern(tc.pattern, tc.action); got != tc.want {
+				t.Fatalf("MatchesActionPattern(%q, %q) = %v, want %v", tc.pattern, tc.action, got, tc.want)
+			}
+		})
+	}
+}

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

@@ -0,0 +1,107 @@
+package domain
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 策略条件词汇（13 condition 族）
+// ═══════════════════════════════════════════════════════════════
+//
+// 条件语义（设计文档 §5.5）：同一语句内多个 condition 取 AND；
+// 同一 condition key 多值取 OR；跨条件 OR 须拆成多条 statement（不自创 OR 算子）。
+// 求值（Condition 对 AdminAccessContext 的匹配）在 application 层 evaluator 实现，
+// 本文件只定义条件的词汇与数据结构。
+
+// ConditionFamily 条件族。
+type ConditionFamily string
+
+const (
+	// ConditionFamilyString 字符串（equals/not_equals/in/starts_with）
+	ConditionFamilyString ConditionFamily = "string"
+	// ConditionFamilyBoolean 布尔（is_true/is_false：MFA 在场、break-glass 会话）
+	ConditionFamilyBoolean ConditionFamily = "boolean"
+	// ConditionFamilyNumeric 数值（lt/lte/gt/gte/between：退款金额、导出行数）
+	ConditionFamilyNumeric ConditionFamily = "numeric"
+	// ConditionFamilyTime 时间（before/after/between/business_hours：访问时段）
+	ConditionFamilyTime ConditionFamily = "time"
+	// ConditionFamilyCIDR 网段（ip_in/ip_not_in：办公网允许列表）
+	ConditionFamilyCIDR ConditionFamily = "cidr"
+	// ConditionFamilyOwnership 主体归属（same_product/same_merchant/same_tenant/same_agent）
+	ConditionFamilyOwnership ConditionFamily = "ownership"
+	// ConditionFamilyCapability 能力位（has_capability/lacks_capability）
+	ConditionFamilyCapability ConditionFamily = "capability"
+	// ConditionFamilyState 资源状态（status_in/approval_state_in：已支付订单、草稿陈列）
+	ConditionFamilyState ConditionFamily = "state"
+	// ConditionFamilySensitivity 敏感度（max_sensitivity：PII 与财务字段）
+	ConditionFamilySensitivity ConditionFamily = "sensitivity"
+	// ConditionFamilyFacility 设施（facility_in/store_in/kitchen_in/warehouse_in/zone_in）
+	ConditionFamilyFacility ConditionFamily = "facility"
+	// ConditionFamilyAssignment 归属关系（assigned_to_self/created_by_self/same_owner）
+	ConditionFamilyAssignment ConditionFamily = "assignment"
+	// ConditionFamilyGeo 地理（region_in/country_in/locale_in/area_in）
+	ConditionFamilyGeo ConditionFamily = "geo"
+	// ConditionFamilyChannelEnv 渠道与环境（channel_in/environment_in）
+	ConditionFamilyChannelEnv ConditionFamily = "channel_env"
+)
+
+// allConditionFamilies 全部 14 个条件族（与 register_iam.go 注册集合一致）。
+var allConditionFamilies = []ConditionFamily{
+	ConditionFamilyString, ConditionFamilyBoolean, ConditionFamilyNumeric, ConditionFamilyTime,
+	ConditionFamilyCIDR, ConditionFamilyOwnership, ConditionFamilyCapability, ConditionFamilyState,
+	ConditionFamilySensitivity, ConditionFamilyFacility, ConditionFamilyAssignment, ConditionFamilyGeo,
+	ConditionFamilyChannelEnv,
+}
+
+// AllConditionFamilies 返回全部条件族副本。
+func AllConditionFamilies() []ConditionFamily {
+	out := make([]ConditionFamily, len(allConditionFamilies))
+	copy(out, allConditionFamilies)
+	return out
+}
+
+// IsValid 校验条件族是否合法。
+func (f ConditionFamily) IsValid() bool {
+	for _, item := range allConditionFamilies {
+		if item == f {
+			return true
+		}
+	}
+	return false
+}
+
+// IsScopeDimension 判断条件族是否为「资源行级范围维度」（facility/assignment/ownership）。
+//
+// 这三族表达资源归属（资源属哪个设施 / 派给谁 / 属哪个商户租户代理产品），其求值依赖具体资源行的
+// 属性。两阶段授权（设计 §6.4）下，这类维度由 ResolveScope 下推为 WHERE 列谓词、EvaluateMany 逐行
+// 复判；集合动作（list / 聚合）的 action 级检查无单一资源可判，故延迟这类条件至 ResolveScope。
+// 与 effective_access_service.go 的可下推分类（classifyCondition 仅 facility/assignment/ownership
+// 进 ScopeConstraint）同源，避免两处分类漂移（SH-E6 单一真相源思想）。
+//
+// 非范围维度（time/cidr/boolean/string/numeric/state/sensitivity/...）不依赖资源归属行，集合动作
+// 的 action 级检查仍恒应用（如「仅营业时段」「仅办公网」对 list 同样生效），不予延迟。
+func (f ConditionFamily) IsScopeDimension() bool {
+	switch f {
+	case ConditionFamilyFacility, ConditionFamilyAssignment, ConditionFamilyOwnership:
+		return true
+	default:
+		return false
+	}
+}
+
+// Condition 策略语句中的单条条件。
+//
+// Operator 为族内算子（如 in/starts_with/status_in/facility_in/assigned_to_self），
+// 其完整算子集由 evaluator 在求值时校验与执行；Key 为上下文属性键；
+// Values 为候选值集合（多值取 OR），布尔/self 类算子可为空。
+type Condition struct {
+	// 条件族
+	Family ConditionFamily `json:"family"`
+	// 族内算子
+	Operator string `json:"operator"`
+	// 上下文属性键
+	Key string `json:"key,omitempty"`
+	// 候选值集合（多值取 OR）
+	Values []string `json:"values,omitempty"`
+}
+
+// HasValues 是否携带候选值（布尔 / self 类算子无值）。
+func (c Condition) HasValues() bool {
+	return len(c.Values) > 0
+}

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

@@ -0,0 +1,256 @@
+package domain
+
+import "time"
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 求值上下文与决策值对象（设计文档 §7.2 / §7.4）
+// ═══════════════════════════════════════════════════════════════
+//
+// AdminAccessContext 是单资源求值的完整上下文快照（condition 求值的属性来源，§5.5）；
+// Decision 是求值产出的值对象（不落库，投影到 DecisionLog 时映射，见 model.go）。
+// 这些类型为值对象，不嵌 BaseModel、不持久化。
+
+// PrincipalContext 主体维度上下文（who）。
+//
+// DelegatedBy 非空表示当前为扮演 / 提权会话（assumed_role）。
+type PrincipalContext struct {
+	// 主体 ID
+	PrincipalID int64
+	// 不可变主体公共引用
+	PrincipalRef string
+	// 主体类型（见 enum.go PrincipalType）
+	PrincipalType string
+	// 关联身份 ID（人类主体）
+	IdentityID *int64
+	// 当前请求是否已通过 MFA（boolean condition 输入）
+	MFAPresent bool
+	// 来源 IP（cidr condition 输入）
+	SourceIP string
+	// 登录方式
+	LoginMethod string
+	// 设备信任等级
+	DeviceTrustLevel string
+	// 授权来源主体 ID（扮演 / 提权时的委派人）
+	DelegatedBy *int64
+}
+
+// WorkspaceContext 工作区维度上下文（在哪个产品 / 隔离边界下操作）。
+type WorkspaceContext struct {
+	// 工作区类型
+	WorkspaceType string
+	// 产品编码
+	ProductCode string
+	// 组织公共引用。
+	OrganizationRef string
+	// 工作区公共引用。
+	WorkspaceRef string
+	// 商户编码（隔离维度）
+	MerchantCode string
+	// 租户 ID（隔离维度）
+	TenantID *int64
+	// 代理编码
+	AgentCode string
+	// 设施 ID（门店 / 厨房 / 仓库 / 配送区，隔离维度）
+	FacilityID string
+}
+
+// RequestContext 请求维度上下文（when / how）。
+type RequestContext struct {
+	// 请求 ID
+	RequestID string
+	// 调用方提供的命令幂等键
+	IdempotencyKey string
+	// 客户端 User-Agent
+	UserAgent string
+	// 路由名
+	RouteName string
+	// HTTP 方法
+	Method string
+	// 被求值的规范动作全名
+	Action string
+	// 来源 IP
+	SourceIP string
+	// 请求时刻（time / business_hours condition 输入）
+	RequestedAt time.Time
+}
+
+// ResourceContext 资源维度上下文（被操作资源的属性快照，state / sensitivity / assignment condition 输入）。
+//
+// 业务状态（Status/ApprovalState）仅作为 condition 输入，IAM 不含 state_forbidden（§7.3）；
+// 授权后的状态机校验由域 service 负责（返回 409/422）。
+type ResourceContext struct {
+	// 资源 ARN
+	ARN string
+	// 资源归属作用域值
+	OwnerScope string
+	// 资源业务状态（state 族 status_in 输入）
+	Status string
+	// 资源敏感度（sensitivity 族输入）
+	Sensitivity string
+	// 资源金额（numeric 族输入，金额以字符串承载避免精度丢失）
+	Amount string
+	// 审批状态（state 族 approval_state_in 输入）
+	ApprovalState string
+	// 资源所属设施 ID（facility 族输入）
+	FacilityID string
+	// 资源 owner 主体 ID（assignment same_owner 输入）
+	OwnerPrincipalID *int64
+	// 资源创建者主体 ID（assignment created_by_self 输入）
+	CreatedByPrincipalID *int64
+	// 请求授予的数据范围类型（授权绑定类操作输入）
+	RequestedScopeType string
+	// 请求授予的数据范围值（授权绑定类操作输入）
+	RequestedScopeValue string
+}
+
+// AdminAccessContext 单资源求值的完整上下文快照。
+//
+// 五个维度共同构成 condition 求值的属性来源（§5.5），并供决策日志快照投影。
+type AdminAccessContext struct {
+	// 主体维度
+	Principal PrincipalContext
+	// 工作区维度
+	Workspace WorkspaceContext
+	// 产品维度
+	Product ProductContext
+	// 请求维度
+	Request RequestContext
+	// 资源维度
+	Resource ResourceContext
+}
+
+// AdminAccessContextInput 管理端授权上下文的可信调用输入。
+//
+// Principal 只承载当前会话事实；主体身份由工厂从权威 Principal 记录覆盖。
+// Workspace 必须由认证后的产品边界适配器提供，工厂不从主体生命周期归属推导请求范围。
+type AdminAccessContextInput struct {
+	// 主体会话维度
+	Principal PrincipalContext
+	// 工作区维度
+	Workspace WorkspaceContext
+	// 请求维度
+	Request RequestContext
+	// 资源维度
+	Resource ResourceContext
+}
+
+// Decision 单资源求值决策值对象（不落库）。
+//
+// ReasonKind 区分 authorization（403）与 state（409/422）两类语义（§7.3 / §8.2）；
+// authorization 类 ReasonCode 取值见 enum.go 决策原因码常量。
+type Decision struct {
+	// 是否允许
+	Allowed bool
+	// 被求值的规范动作全名
+	Action string
+	// 被求值的资源 ARN
+	Resource string
+	// 决策原因码（见 enum.go 决策原因码常量）
+	ReasonCode string
+	// 决策原因类别（见 enum.go ReasonKind）
+	ReasonKind ReasonKind
+	// 命中语句 ID 集合
+	MatchedStatementIDs []int64
+	// 触发拒绝的来源标识集合（如命中的 Deny 语句 / boundary / session 标记），用于解释
+	DeniedBy []string
+	// 人类可读的决策解释
+	Explanation string
+}
+
+// NewAllowedDecision 构造允许决策（ReasonAllowed + authorization 类）。
+func NewAllowedDecision(action, resource string, matched []int64) Decision {
+	return Decision{
+		Allowed:             true,
+		Action:              action,
+		Resource:            resource,
+		ReasonCode:          ReasonAllowed,
+		ReasonKind:          ReasonKindAuthorization,
+		MatchedStatementIDs: matched,
+	}
+}
+
+// NewDeniedDecision 构造拒绝决策（authorization 类，携带拒绝来源与解释）。
+//
+// reasonCode 取 enum.go authorization 类决策原因码（如 ReasonExplicitDeny / ReasonNoMatchingAllow）。
+func NewDeniedDecision(action, resource, reasonCode string, deniedBy []string, explanation string) Decision {
+	return Decision{
+		Allowed:     false,
+		Action:      action,
+		Resource:    resource,
+		ReasonCode:  reasonCode,
+		ReasonKind:  ReasonKindAuthorization,
+		DeniedBy:    deniedBy,
+		Explanation: explanation,
+	}
+}
+
+// NewStateDeniedDecision 构造业务状态前置条件拒绝决策。
+func NewStateDeniedDecision(action, resource, reasonCode, explanation string) Decision {
+	return Decision{
+		Allowed:     false,
+		Action:      action,
+		Resource:    resource,
+		ReasonCode:  reasonCode,
+		ReasonKind:  ReasonKindState,
+		Explanation: explanation,
+	}
+}
+
+// EvaluateRequest 单资源求值请求。
+//
+// PrincipalID 与 Context.Principal.PrincipalID 应一致（调用方装配时保证）；
+// Action 为规范动作全名，Resource 为资源 ARN。
+type EvaluateRequest struct {
+	// 主体 ID
+	PrincipalID int64
+	// 被求值的规范动作全名
+	Action string
+	// 被求值的资源 ARN
+	Resource string
+	// 求值上下文快照
+	Context AdminAccessContext
+}
+
+// PageActionDecision 页面动作的逐资源授权决策（EffectiveActions 产出，设计文档 §7.1）。
+//
+// 一个页面动作契约（PageAction）渲染 ResourceTemplate 后对当前操作者求值，
+// 产出本值对象供前端按钮级渲染（allow → 可点；deny → 隐藏 / 置灰 + reason_code 解释）。
+// 携带 Placement / RiskLevel 让前端按位摆放与高危标注，无需二次查动作字典。
+type PageActionDecision struct {
+	// 动作位键（页面内唯一，前端按此定位按钮）
+	ActionKey string
+	// 绑定的规范动作全名（domain:resource:verb）
+	Action string
+	// 渲染后的资源 ARN（模板占位符已填充）
+	Resource string
+	// 是否允许（前端按钮可点 / 隐藏的依据）
+	Allowed bool
+	// 决策原因码（见 enum.go 决策原因码常量，allow=allowed）
+	ReasonCode string
+	// 决策原因类别（授权拒绝为 authorization，状态条件拒绝为 state）
+	ReasonKind ReasonKind
+	// 摆放位置（见 enum.go Placement，前端按位渲染）
+	Placement string
+	// 风险等级（见 enum.go RiskLevel，前端高危动作二次确认）
+	RiskLevel string
+	// 触发拒绝的来源标识集合（命中的 Deny 语句 / boundary / session 标记），用于解释
+	DeniedBy []string
+}
+
+// NewPageActionDecision 由页面动作契约与求值决策构造页面动作决策值对象。
+//
+// ActionKey / Placement / RiskLevel 取自契约（前端渲染元数据）；Allowed / ReasonCode /
+// ReasonKind / Action / Resource / DeniedBy 取自求值决策（授权结论）。两者语义不同不混淆。
+func NewPageActionDecision(actionKey, placement, riskLevel string, decision Decision) PageActionDecision {
+	return PageActionDecision{
+		ActionKey:  actionKey,
+		Action:     decision.Action,
+		Resource:   decision.Resource,
+		Allowed:    decision.Allowed,
+		ReasonCode: decision.ReasonCode,
+		ReasonKind: decision.ReasonKind,
+		Placement:  placement,
+		RiskLevel:  riskLevel,
+		DeniedBy:   decision.DeniedBy,
+	}
+}