openxiangda 1.0.136 → 1.0.137

package/lib/cli.js

@@ -93,6 +93,7 @@ async function main(argv) {
   if (command === 'workflow') return workflow(rest);
   if (command === 'automation') return automation(rest);
   if (command === 'data-view') return dataView(rest);
+  if (command === 'scope') return scope(rest);
   if (command === 'route') return route(rest);
   if (command === 'public-access') return publicAccess(rest);
   if (command === 'auth-config') return authConfig(rest);
@@ -162,6 +163,7 @@ Usage:
   openxiangda automation diagnose <automationCode|automationId> [--redact] [--json]
   openxiangda automation publish|enable|disable <automationCode|automationId>
   openxiangda data-view list|get|create|update|upsert|delete|status|refresh|query|stats <dataViewCode> [--profile name] [--json]
+  openxiangda scope dimension-list|dimension-upsert|grant-source-list|grant-source-upsert|policy-list|policy-upsert|sync|explain [code] [--json-file file]
   openxiangda route list|get|create|update|upsert|delete [--json-file file] [--dry-run] [--write-manifest]
   openxiangda public-access list|get|create|update|upsert|delete|ticket-create|session-test|grant-check [--json-file file]
   openxiangda auth-config list|get|create|update|upsert|delete|methods [--json-file file]
@@ -1860,6 +1862,9 @@ async function workspace(args) {
         connectors: {},
         dataViews: {},
         storageConfigs: {},
+        scopeDimensions: {},
+        scopeGrantSources: {},
+        dataScopePolicies: {},
         pagePermissionGroups: {},
         formPermissionGroups: {},
         formSettings: {},
@@ -3101,6 +3106,112 @@ async function dataView(args) {
   fail('用法: openxiangda data-view list|get|create|update|upsert|delete|status|refresh|query|stats');
 }
 
+async function scope(args) {
+  const { subcommand, rest } = parseSubcommandArgs(args);
+  const { flags, positional } = parseArgs(rest);
+  if (wantsSubcommandHelp(subcommand, flags)) {
+    print('用法: openxiangda scope dimension-list|dimension-upsert|grant-source-list|grant-source-upsert|policy-list|policy-upsert|sync|explain [code] [--json-file file] [--dry-run] [--write-manifest]');
+    return;
+  }
+  const config = loadConfig();
+  const target = getWorkspaceTarget(config, flags.profile || config.currentProfile, flags);
+  const basePath = `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope`;
+
+  if (subcommand === 'dimension-list') {
+    return runDirectRequest(config, target, flags, {
+      method: 'GET',
+      path: `${basePath}/dimensions`,
+    });
+  }
+
+  if (subcommand === 'dimension-upsert') {
+    return upsertScopeResource(config, target, flags, positional, {
+      commandName: 'scope dimension-upsert',
+      resourceType: 'scope-dimension',
+      path: `${basePath}/dimensions`,
+      normalizeBody: body => normalizeScopeDimensionManifest(body, target.bound),
+    });
+  }
+
+  if (subcommand === 'grant-source-list') {
+    return runDirectRequest(config, target, flags, {
+      method: 'GET',
+      path: `${basePath}/grant-sources`,
+    });
+  }
+
+  if (subcommand === 'grant-source-upsert') {
+    return upsertScopeResource(config, target, flags, positional, {
+      commandName: 'scope grant-source-upsert',
+      resourceType: 'scope-grant-source',
+      path: `${basePath}/grant-sources`,
+      normalizeBody: body => normalizeScopeGrantSourceManifest(body, target.bound),
+    });
+  }
+
+  if (subcommand === 'policy-list') {
+    return runDirectRequest(config, target, flags, {
+      method: 'GET',
+      path: `${basePath}/policies`,
+    });
+  }
+
+  if (subcommand === 'policy-upsert') {
+    return upsertScopeResource(config, target, flags, positional, {
+      commandName: 'scope policy-upsert',
+      resourceType: 'data-scope-policy',
+      path: `${basePath}/policies`,
+      normalizeBody: normalizeDataScopePolicyManifest,
+    });
+  }
+
+  if (subcommand === 'sync') {
+    const [code] = positional;
+    if (!code) fail('用法: openxiangda scope sync <grantSourceCode> [--dry-run] [--json]');
+    const body = {
+      ...readDirectJsonBody(flags, 'scope sync', { optional: true }),
+      ...(flags['dry-run'] ? { dryRun: true } : {}),
+    };
+    return runDirectRequest(config, target, flags, {
+      method: 'POST',
+      path: `${basePath}/grant-sources/${encodeURIComponent(code)}/sync`,
+      body,
+    });
+  }
+
+  if (subcommand === 'explain') {
+    const [code] = positional;
+    if (!code) fail('用法: openxiangda scope explain <policyCode> [--json-file file] [--json]');
+    const body = readDirectJsonBody(flags, 'scope explain', { optional: true });
+    return runDirectRequest(config, target, flags, {
+      method: 'POST',
+      path: `${basePath}/policies/${encodeURIComponent(code)}/explain`,
+      body,
+    });
+  }
+
+  fail('用法: openxiangda scope dimension-list|dimension-upsert|grant-source-list|grant-source-upsert|policy-list|policy-upsert|sync|explain');
+}
+
+async function upsertScopeResource(config, target, flags, positional, spec) {
+  const rawBody = readDirectJsonBody(flags, spec.commandName);
+  const explicitCode = positional[0] || flags.code;
+  if (explicitCode && !rawBody.code && !rawBody.resourceCode) rawBody.code = explicitCode;
+  const code = explicitCode || rawBody.code || rawBody.resourceCode;
+  if (!code) fail(`openxiangda ${spec.commandName} 缺少资源 code`);
+  const body = spec.normalizeBody(rawBody);
+  const data = await runDirectRequest(config, target, flags, {
+    method: 'POST',
+    path: `${spec.path}/${encodeURIComponent(code)}`,
+    body,
+  }, { returnData: true });
+  if (!flags['dry-run']) {
+    saveScopeResource(target, resourceTypeToBucket(spec.resourceType), code, data);
+    if (flags['write-manifest']) writeDirectManifest(spec.resourceType, code, { ...rawBody, code });
+  }
+  return outputDirectResult({ action: 'upsert', data }, flags);
+}
+
 async function route(args) {
   const { subcommand, rest } = parseSubcommandArgs(args);
   const { flags, positional } = parseArgs(rest);
@@ -5579,6 +5690,9 @@ function directManifestDir(resourceType) {
     role: path.join('src', 'resources', 'roles'),
     'page-permission-group': path.join('src', 'resources', 'permissions', 'page-groups'),
     'form-permission-group': path.join('src', 'resources', 'permissions', 'form-groups'),
+    'scope-dimension': path.join('src', 'resources', 'permissions', 'scope-dimensions'),
+    'scope-grant-source': path.join('src', 'resources', 'permissions', 'scope-grant-sources'),
+    'data-scope-policy': path.join('src', 'resources', 'permissions', 'data-scope-policies'),
   };
   return dirs[resourceType];
 }
@@ -5738,6 +5852,8 @@ async function buildPermissionAudit(config, target, flags = {}) {
   const manifest = loadWorkspaceResources();
   const validation = validateWorkspaceResources(manifest);
   const roleCodes = new Set((manifest.roles || []).map(item => item.code || item.resourceCode).filter(Boolean));
+  const policyCodes = new Set((manifest.dataScopePolicies || []).map(item => item.code || item.resourceCode).filter(Boolean));
+  const scopePolicyRefs = [];
   const warnings = [...validation.warnings];
   const errors = [...validation.errors];
   for (const group of manifest.pagePermissionGroups || []) {
@@ -5751,6 +5867,31 @@ async function buildPermissionAudit(config, target, flags = {}) {
     }
     const formUuid = resolveManifestFormUuid(target.bound, group);
     if (!formUuid) errors.push(`form permission group ${group.code} 缺少 formCode/formUuid`);
+    if (group.dataPermission?.type === 'scope_policy') {
+      const policyCode = getScopePolicyCode(group.dataPermission);
+      if (policyCode) scopePolicyRefs.push(policyCode);
+      if (policyCode && policyCodes.size > 0 && !policyCodes.has(policyCode)) {
+        warnings.push(`form permission group ${group.code} 引用未声明 data-scope-policy: ${policyCode}`);
+      }
+    }
+  }
+  for (const dataView of manifest.dataViews || []) {
+    for (const group of dataView.permissionGroups || []) {
+      for (const roleCode of group.roles || []) {
+        if (roleCodes.size > 0 && !roleCodes.has(roleCode)) {
+          warnings.push(`data view ${dataView.code} permission group ${group.code || group.name || '?'} 引用未声明角色: ${roleCode}`);
+        }
+      }
+      if (group.dataPermission?.type !== 'scope_policy') continue;
+      const policyCode = getScopePolicyCode(group.dataPermission);
+      if (policyCode) scopePolicyRefs.push(policyCode);
+      if (policyCode && policyCodes.size > 0 && !policyCodes.has(policyCode)) {
+        warnings.push(`data view ${dataView.code} permission group ${group.code || group.name || '?'} 引用未声明 data-scope-policy: ${policyCode}`);
+      }
+    }
+  }
+  if (scopePolicyRefs.length > 0 && (manifest.scopeGrantSources || []).length === 0) {
+    warnings.push('权限组已引用 scope_policy，但本工作区未声明 scopeGrantSources；请确认授权来源由其他工作区或平台后台维护');
   }
   for (const policy of manifest.publicAccessPolicies || []) {
     const grants = normalizePublicAccessPolicyManifest(target.bound, policy).grants || {};
@@ -5770,6 +5911,12 @@ async function buildPermissionAudit(config, target, flags = {}) {
     ),
     errors,
     warnings,
+    scope: {
+      dimensions: (manifest.scopeDimensions || []).length,
+      grantSources: (manifest.scopeGrantSources || []).length,
+      policies: (manifest.dataScopePolicies || []).length,
+      referencedPolicies: unique(scopePolicyRefs),
+    },
   };
   if (flags.live) {
     result.live = await requestWithAuth(
@@ -5806,6 +5953,9 @@ function ensureResourceBuckets(bound) {
   bound.resources.authConfigs = bound.resources.authConfigs || {};
   bound.resources.routes = bound.resources.routes || {};
   bound.resources.publicAccessPolicies = bound.resources.publicAccessPolicies || {};
+  bound.resources.scopeDimensions = bound.resources.scopeDimensions || {};
+  bound.resources.scopeGrantSources = bound.resources.scopeGrantSources || {};
+  bound.resources.dataScopePolicies = bound.resources.dataScopePolicies || {};
   bound.resources.notifications = bound.resources.notifications || {};
   bound.resources.notifications.templates = bound.resources.notifications.templates || {};
   bound.resources.notifications.typeConfigs = bound.resources.notifications.typeConfigs || {};
@@ -6056,6 +6206,24 @@ function saveStorageConfigResource(target, storageCode, storageConfigId, extra =
   }, keys);
 }
 
+function saveScopeResource(target, bucket, code, data = {}) {
+  if (!bucket || !code) return;
+  const keys = ['id', 'resourceCode', 'name', 'updatedAt'];
+  saveStateResource(target, bucket, code, {
+    id: data?.id,
+    resourceCode: data?.resourceCode || data?.code || code,
+    name: data?.name,
+  }, keys);
+}
+
+function resourceTypeToBucket(resourceType) {
+  return {
+    'scope-dimension': 'scopeDimensions',
+    'scope-grant-source': 'scopeGrantSources',
+    'data-scope-policy': 'dataScopePolicies',
+  }[resourceType];
+}
+
 function saveRouteResource(target, routeCode, routeId, extra = {}) {
   const keys = ['routeId', 'pathPattern', 'publicAccess', 'publicPolicyCode'];
   saveStateResource(target, 'routes', routeCode, {
@@ -6208,6 +6376,24 @@ const RESOURCE_SPECS = [
     topFiles: [path.join('permissions', 'form-groups.json')],
     pluralKeys: ['formPermissionGroups', 'formGroups'],
   },
+  {
+    key: 'scopeDimensions',
+    dir: path.join('permissions', 'scope-dimensions'),
+    topFiles: [path.join('permissions', 'scope-dimensions.json')],
+    pluralKeys: ['scopeDimensions', 'dimensions'],
+  },
+  {
+    key: 'scopeGrantSources',
+    dir: path.join('permissions', 'scope-grant-sources'),
+    topFiles: [path.join('permissions', 'scope-grant-sources.json')],
+    pluralKeys: ['scopeGrantSources', 'grantSources', 'sources'],
+  },
+  {
+    key: 'dataScopePolicies',
+    dir: path.join('permissions', 'data-scope-policies'),
+    topFiles: [path.join('permissions', 'data-scope-policies.json')],
+    pluralKeys: ['dataScopePolicies', 'scopePolicies', 'policies'],
+  },
   {
     key: 'formSettings',
     dir: path.join('settings', 'forms'),
@@ -6274,6 +6460,20 @@ const RESOURCE_TYPE_ALIASES = new Map([
   ['form-groups', 'formPermissionGroups'],
   ['formpermissiongroup', 'formPermissionGroups'],
   ['formpermissiongroups', 'formPermissionGroups'],
+  ['scope-dimension', 'scopeDimensions'],
+  ['scope-dimensions', 'scopeDimensions'],
+  ['scopedimension', 'scopeDimensions'],
+  ['scopedimensions', 'scopeDimensions'],
+  ['scope-grant-source', 'scopeGrantSources'],
+  ['scope-grant-sources', 'scopeGrantSources'],
+  ['scopegrantsource', 'scopeGrantSources'],
+  ['scopegrantsources', 'scopeGrantSources'],
+  ['data-scope-policy', 'dataScopePolicies'],
+  ['data-scope-policies', 'dataScopePolicies'],
+  ['scope-policy', 'dataScopePolicies'],
+  ['scope-policies', 'dataScopePolicies'],
+  ['datascopepolicy', 'dataScopePolicies'],
+  ['datascopepolicies', 'dataScopePolicies'],
   ['form-setting', 'formSettings'],
   ['form-settings', 'formSettings'],
   ['settings-form', 'formSettings'],
@@ -6283,8 +6483,8 @@ const RESOURCE_TYPE_ALIASES = new Map([
 ]);
 
 const RESOURCE_TYPE_ALIAS_GROUPS = new Map([
-  ['permission', ['pagePermissionGroups', 'formPermissionGroups']],
-  ['permissions', ['pagePermissionGroups', 'formPermissionGroups']],
+  ['permission', ['pagePermissionGroups', 'formPermissionGroups', 'scopeDimensions', 'scopeGrantSources', 'dataScopePolicies']],
+  ['permissions', ['pagePermissionGroups', 'formPermissionGroups', 'scopeDimensions', 'scopeGrantSources', 'dataScopePolicies']],
 ]);
 
 function getResourceTypeFilters(positional = [], flags = {}) {
@@ -6313,7 +6513,7 @@ function getResourceTypeFilters(positional = [], flags = {}) {
     if (!key) {
       fail(
         `未知资源类型: ${rawType}。常用类型包括 workflow, notification, route, menu, role, ` +
-          `storage, page-permission-group, form-permission-group, public-access。`
+          `storage, page-permission-group, form-permission-group, scope-policy, public-access。`
       );
     }
     filters.add(key);
@@ -6523,6 +6723,7 @@ function validateWorkspaceResources(manifest) {
     }
   }
   validateNotificationReferences(manifest.notifications || [], errors);
+  validateScopePermissionResources(manifest, errors, warnings);
   return {
     valid: errors.length === 0,
     errors,
@@ -6610,6 +6811,9 @@ function generateResourceTypes(manifest, outputFile) {
   const storageConfigCodes = unique((manifest.storageConfigs || []).map(item => item.code).filter(Boolean));
   const authConfigCodes = unique((manifest.authConfigs || []).map(item => item.code).filter(Boolean));
   const publicAccessPolicyCodes = unique((manifest.publicAccessPolicies || []).map(item => item.code).filter(Boolean));
+  const scopeDimensionCodes = unique((manifest.scopeDimensions || []).map(item => item.code).filter(Boolean));
+  const scopeGrantSourceCodes = unique((manifest.scopeGrantSources || []).map(item => item.code).filter(Boolean));
+  const dataScopePolicyCodes = unique((manifest.dataScopePolicies || []).map(item => item.code).filter(Boolean));
   const content = [
     '/* eslint-disable */',
     '// Generated by openxiangda resource typegen. Do not edit manually.',
@@ -6638,6 +6842,15 @@ function generateResourceTypes(manifest, outputFile) {
     `export const publicAccessPolicyCodes = ${JSON.stringify(publicAccessPolicyCodes, null, 2)} as const`,
     'export type PublicAccessPolicyCode = typeof publicAccessPolicyCodes[number]',
     '',
+    `export const scopeDimensionCodes = ${JSON.stringify(scopeDimensionCodes, null, 2)} as const`,
+    'export type ScopeDimensionCode = typeof scopeDimensionCodes[number]',
+    '',
+    `export const scopeGrantSourceCodes = ${JSON.stringify(scopeGrantSourceCodes, null, 2)} as const`,
+    'export type ScopeGrantSourceCode = typeof scopeGrantSourceCodes[number]',
+    '',
+    `export const dataScopePolicyCodes = ${JSON.stringify(dataScopePolicyCodes, null, 2)} as const`,
+    'export type DataScopePolicyCode = typeof dataScopePolicyCodes[number]',
+    '',
     `export const runtimeMenus = ${JSON.stringify(menus, null, 2)} as const`,
     '',
     `export const runtimeRoutes = ${JSON.stringify(routes, null, 2)} as const`,
@@ -6657,6 +6870,9 @@ function generateResourceTypes(manifest, outputFile) {
     functions: functionCodes.length,
     authConfigs: authConfigCodes.length,
     publicAccessPolicies: publicAccessPolicyCodes.length,
+    scopeDimensions: scopeDimensionCodes.length,
+    scopeGrantSources: scopeGrantSourceCodes.length,
+    dataScopePolicies: dataScopePolicyCodes.length,
   };
 }
 
@@ -6836,10 +7052,61 @@ function validateResourceItem(kind, item, errors, warnings) {
       errors.push(`${label}: externalRoleCodes 必须是数组`);
     }
   }
+  if (kind === 'scopeDimensions') {
+    if (!item.name) warnings.push(`${label}: 未声明 name，将使用 code`);
+    if (item.hierarchyMode && !['flat', 'self_parent'].includes(String(item.hierarchyMode))) {
+      errors.push(`${label}: hierarchyMode 只能是 flat 或 self_parent`);
+    }
+    if ((item.sourceFormUuid || item.formUuid) && !item.sourceValueField && !item.valueField) {
+      errors.push(`${label}: 使用表单维护维度时缺少 sourceValueField`);
+    }
+  }
+  if (kind === 'scopeGrantSources') {
+    if (!item.name) warnings.push(`${label}: 未声明 name，将使用 code`);
+    if (!item.sourceFormUuid && !item.formUuid) errors.push(`${label}: 缺少 sourceFormUuid`);
+    const subjectMappings = item.subjectMappings || item.subjects;
+    const dimensionMappings = item.dimensionMappings || item.dimensions;
+    if (!Array.isArray(subjectMappings) || subjectMappings.length === 0) {
+      errors.push(`${label}: 缺少 subjectMappings`);
+    }
+    if (!Array.isArray(dimensionMappings) || dimensionMappings.length === 0) {
+      errors.push(`${label}: 缺少 dimensionMappings`);
+    }
+  }
+  if (kind === 'dataScopePolicies') {
+    if (!item.name) warnings.push(`${label}: 未声明 name，将使用 code`);
+    const rules = item.rules || item.dimensions;
+    if (!Array.isArray(rules) || rules.length === 0) {
+      errors.push(`${label}: 缺少 rules`);
+    } else {
+      rules.forEach((rule, index) => {
+        const ruleLabel = `${label}.rules[${index}]`;
+        const dimensionCode = rule.dimensionCode || rule.dimension;
+        const targetField = rule.field || rule.targetField;
+        if (!dimensionCode) errors.push(`${ruleLabel}: 缺少 dimensionCode`);
+        if (!targetField) errors.push(`${ruleLabel}: 缺少 field/targetField`);
+        if (rule.valuePath && !isSafeScopePolicyValuePath(rule.valuePath)) {
+          errors.push(`${ruleLabel}: valuePath 只能包含字母、数字、下划线、中划线、点或 >`);
+        }
+        if (isScopePolicyMultiValueComponent(rule.componentType)) {
+          warnings.push(`${ruleLabel}: 多值选择/人员/部门字段不适合直接作为 scope_policy 目标字段，建议派生隐藏 scalar key 字段`);
+        } else if (
+          !rule.valuePath &&
+          !rule.componentType &&
+          looksLikeJsonScopeTargetField(targetField)
+        ) {
+          warnings.push(`${ruleLabel}: 目标字段看起来可能是选择/人员/部门类字段；若底层是 JSONB，请声明 valuePath:"value" 或 componentType，优先使用隐藏 scalar key`);
+        }
+      });
+    }
+  }
   if (kind === 'pagePermissionGroups' && !item.name) errors.push(`${label}: 缺少 name`);
   if (kind === 'formPermissionGroups') {
     if (!item.name) errors.push(`${label}: 缺少 name`);
     if (!item.formCode && !item.formUuid) errors.push(`${label}: 缺少 formCode 或 formUuid`);
+    if (item.dataPermission?.type === 'scope_policy' && !getScopePolicyCode(item.dataPermission)) {
+      errors.push(`${label}: dataPermission.type=scope_policy 时必须声明 policyCode`);
+    }
   }
   if (kind === 'formSettings') {
     if (!item.formCode && !item.formUuid && !item.code) {
@@ -6856,6 +7123,105 @@ function validateResourceItem(kind, item, errors, warnings) {
   }
 }
 
+function validateScopePermissionResources(manifest, errors, warnings) {
+  const policyCodes = new Set(
+    (manifest.dataScopePolicies || [])
+      .map(item => item.code || item.resourceCode)
+      .filter(Boolean)
+      .map(String)
+  );
+  const scopePolicyRefs = [];
+  const inspectPermissionGroup = (kind, item) => {
+    const groups = kind === 'dataViews'
+      ? (Array.isArray(item.permissionGroups) ? item.permissionGroups : [])
+      : [item];
+    for (const group of groups) {
+      const dataPermission = group?.dataPermission;
+      if (!dataPermission) continue;
+      if (dataPermission.type === 'scope_policy') {
+        const policyCode = getScopePolicyCode(dataPermission);
+        if (!policyCode) {
+          errors.push(`${resourceLabel(kind, item)}: scope_policy 缺少 policyCode`);
+          continue;
+        }
+        scopePolicyRefs.push(policyCode);
+        if (policyCodes.size > 0 && !policyCodes.has(policyCode)) {
+          warnings.push(`${resourceLabel(kind, item)}: scope_policy 引用 ${policyCode}，但 src/resources 中未声明同名 data-scope-policy`);
+        }
+      } else if (containsBusinessScopeLikeField(dataPermission)) {
+        warnings.push(`${resourceLabel(kind, item)}: 检测到疑似业务范围字段条件，业务对象数量超过少量枚举时优先改为 dataPermission.type=scope_policy`);
+      }
+    }
+  };
+  for (const group of manifest.formPermissionGroups || []) {
+    inspectPermissionGroup('formPermissionGroups', group);
+  }
+  for (const view of manifest.dataViews || []) {
+    inspectPermissionGroup('dataViews', view);
+  }
+  const formGroupCount = (manifest.formPermissionGroups || []).length;
+  const pageGroupCount = (manifest.pagePermissionGroups || []).length;
+  if (formGroupCount >= 30) {
+    warnings.push(`formPermissionGroups 当前 ${formGroupCount} 个；如这些组按客户/项目/区域/学院/班级/门店拆分，建议收敛为业务授权表 + scope_policy`);
+  }
+  if (pageGroupCount >= 30) {
+    warnings.push(`pagePermissionGroups 当前 ${pageGroupCount} 个；如这些组按业务对象拆分，建议只保留入口角色，数据范围交给 scope_policy`);
+  }
+  if (scopePolicyRefs.length > 0 && (manifest.scopeGrantSources || []).length === 0) {
+    warnings.push('已引用 scope_policy，但未声明 scopeGrantSources；请确认授权来源由平台后台或其他工作区维护');
+  }
+}
+
+function getScopePolicyCode(dataPermission = {}) {
+  return String(
+    dataPermission.policyCode ||
+      dataPermission.scopePolicyCode ||
+      dataPermission.code ||
+      ''
+  ).trim();
+}
+
+function isSafeScopePolicyValuePath(value) {
+  return /^[A-Za-z0-9_.>-]+$/.test(String(value || ''));
+}
+
+function isScopePolicyMultiValueComponent(componentType) {
+  const normalized = String(componentType || '').trim().toLowerCase();
+  return [
+    'multiselect',
+    'multiselectfield',
+    'checkbox',
+    'checkboxfield',
+    'cascadeselect',
+    'cascadeselectfield',
+  ].includes(normalized);
+}
+
+function looksLikeJsonScopeTargetField(field) {
+  return /(select|option|user|employee|member|dept|department|linked|association|人员|用户|部门|选择)/i.test(String(field || ''));
+}
+
+function containsBusinessScopeLikeField(value) {
+  const fields = [];
+  const visit = item => {
+    if (!item || typeof item !== 'object') return;
+    if (Array.isArray(item)) {
+      item.forEach(visit);
+      return;
+    }
+    if (item.field || item.key || item.targetField) {
+      fields.push(String(item.field || item.key || item.targetField));
+    }
+    visit(item.condition);
+    visit(item.conditions);
+    visit(item.rules);
+  };
+  visit(value);
+  return fields.some(field =>
+    /(scope|customer|client|project|region|area|store|shop|campus|college|school|class|班级|学院|校区|区域|门店|客户|项目)/i.test(field)
+  );
+}
+
 function validateDataViewPerformance(label, definition, errors, warnings, storageMode = 'materialized') {
   const viewType = String(definition.viewType || 'row').toLowerCase();
   if (viewType !== 'row' && viewType !== 'aggregate') return;
@@ -7306,6 +7672,9 @@ async function buildResourcePlan(config, target, manifest) {
   await addAutomationPlanActions(config, target, actions, manifest.automations, existing.automations);
   addPlanActions(actions, 'dataView', manifest.dataViews, existing.dataViews, (item, current) => dataViewEquals(target.bound, item, current));
   addPlanActions(actions, 'storageConfig', manifest.storageConfigs, existing.storageConfigs, (item, current) => storageConfigEquals(item, current));
+  addPlanActions(actions, 'scopeDimension', manifest.scopeDimensions, existing.scopeDimensions, (item, current) => scopeDimensionEquals(target.bound, item, current));
+  addPlanActions(actions, 'scopeGrantSource', manifest.scopeGrantSources, existing.scopeGrantSources, (item, current) => scopeGrantSourceEquals(target.bound, item, current));
+  addPlanActions(actions, 'dataScopePolicy', manifest.dataScopePolicies, existing.dataScopePolicies, dataScopePolicyEquals);
   addPlanActions(actions, 'pagePermissionGroup', manifest.pagePermissionGroups, existing.pagePermissionGroups, (item, current) => pagePermissionGroupEquals(target.bound, item, current));
   addPlanActions(actions, 'formPermissionGroup', manifest.formPermissionGroups, existing.formPermissionGroups, (item, current) => formPermissionGroupEquals(target.bound, item, current));
   for (const item of manifest.formSettings || []) {
@@ -7378,6 +7747,9 @@ async function publishResourceManifest(config, target, manifest, options = {}) {
   await publishAuthConfigResources(config, target, manifest.authConfigs || [], result, publishOptions);
   await publishRouteResources(config, target, manifest.routes || [], result, publishOptions);
   await publishAutomationResources(config, target, manifest.automations || [], result, publishOptions);
+  await publishScopeDimensionResources(config, target, manifest.scopeDimensions || [], result, publishOptions);
+  await publishScopeGrantSourceResources(config, target, manifest.scopeGrantSources || [], result, publishOptions);
+  await publishDataScopePolicyResources(config, target, manifest.dataScopePolicies || [], result, publishOptions);
   await publishDataViewResources(config, target, manifest.dataViews || [], result, publishOptions);
   await publishStorageConfigResources(config, target, manifest.storageConfigs || [], result, publishOptions);
   await publishPublicAccessPolicyResources(config, target, manifest.publicAccessPolicies || [], result, publishOptions);
@@ -7408,6 +7780,9 @@ async function fetchExistingResourceMaps(config, target, manifest) {
     automations: new Map(),
     dataViews: new Map(),
     storageConfigs: new Map(),
+    scopeDimensions: new Map(),
+    scopeGrantSources: new Map(),
+    dataScopePolicies: new Map(),
     pagePermissionGroups: new Map(),
     formPermissionGroups: new Map(),
   };
@@ -7620,6 +7995,30 @@ async function fetchExistingResourceMaps(config, target, manifest) {
       });
     }
   }
+  if ((manifest.scopeDimensions || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/dimensions`
+    );
+    indexByCode(maps.scopeDimensions, normalizeItems(data), item => item.code || item.resourceCode);
+  }
+  if ((manifest.scopeGrantSources || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/grant-sources`
+    );
+    indexByCode(maps.scopeGrantSources, normalizeItems(data), item => item.code || item.resourceCode);
+  }
+  if ((manifest.dataScopePolicies || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/policies`
+    );
+    indexByCode(maps.dataScopePolicies, normalizeItems(data), item => item.code || item.resourceCode);
+  }
   if ((manifest.pagePermissionGroups || []).length > 0) {
     const data = await requestWithAuth(
       config,
@@ -8454,6 +8853,102 @@ async function publishAuthConfigResources(config, target, authConfigs, result, o
   }
 }
 
+async function publishScopeDimensionResources(config, target, dimensions, result, options = {}) {
+  for (const item of dimensions) {
+    const code = item.code || item.resourceCode;
+    if (shouldSkipNoopResource(options, 'scopeDimension', code)) {
+      recordNoopResource(result, 'scopeDimension', code, options);
+      continue;
+    }
+    const existing = await findExistingScopeResource(config, target, 'dimensions', code);
+    const body = normalizeScopeDimensionManifest(item, target.bound);
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/dimensions/${encodeURIComponent(code)}`,
+      { method: 'POST', body }
+    );
+    saveScopeResource(target, 'scopeDimensions', code, data);
+    result.published.push({
+      kind: 'scopeDimension',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+    });
+  }
+}
+
+async function publishScopeGrantSourceResources(config, target, sources, result, options = {}) {
+  for (const item of sources) {
+    const code = item.code || item.resourceCode;
+    if (shouldSkipNoopResource(options, 'scopeGrantSource', code)) {
+      recordNoopResource(result, 'scopeGrantSource', code, options);
+      continue;
+    }
+    const existing = await findExistingScopeResource(config, target, 'grant-sources', code);
+    const body = normalizeScopeGrantSourceManifest(item, target.bound);
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/grant-sources/${encodeURIComponent(code)}`,
+      { method: 'POST', body }
+    );
+    saveScopeResource(target, 'scopeGrantSources', code, data);
+    const published = {
+      kind: 'scopeGrantSource',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+    };
+    if (item.sync === true) {
+      published.sync = await requestWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/grant-sources/${encodeURIComponent(code)}/sync`,
+        { method: 'POST', body: { dryRun: false } }
+      );
+    }
+    result.published.push(published);
+  }
+}
+
+async function publishDataScopePolicyResources(config, target, policies, result, options = {}) {
+  for (const item of policies) {
+    const code = item.code || item.resourceCode;
+    if (shouldSkipNoopResource(options, 'dataScopePolicy', code)) {
+      recordNoopResource(result, 'dataScopePolicy', code, options);
+      continue;
+    }
+    const existing = await findExistingScopeResource(config, target, 'policies', code);
+    const body = normalizeDataScopePolicyManifest(item);
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/policies/${encodeURIComponent(code)}`,
+      { method: 'POST', body }
+    );
+    saveScopeResource(target, 'dataScopePolicies', code, data);
+    result.published.push({
+      kind: 'dataScopePolicy',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+    });
+  }
+}
+
+async function findExistingScopeResource(config, target, segment, code) {
+  if (!code) return null;
+  const data = await requestWithAuth(
+    config,
+    target.profileName,
+    `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/scope/${segment}`
+  );
+  return normalizeItems(data).find(item =>
+    String(item.code || item.resourceCode || '') === String(code)
+  );
+}
+
 async function publishDataViewResources(config, target, dataViews, result, options = {}) {
   for (const dataViewItem of dataViews) {
     if (shouldSkipNoopResource(options, 'dataView', dataViewItem.code)) {
@@ -10016,6 +10511,60 @@ function normalizePublicAccessPolicyManifest(bound, policy) {
   });
 }
 
+function normalizeScopeDimensionManifest(dimension, bound) {
+  const code = dimension.code || dimension.resourceCode;
+  const sourceFormUuid =
+    dimension.sourceFormUuid ||
+    dimension.formUuid ||
+    resolveOptionalFormUuid(bound, dimension.sourceFormCode || dimension.formCode);
+  return stripUndefinedValues({
+    code,
+    name: dimension.name || dimension.title || code,
+    valueType: dimension.valueType || 'string',
+    hierarchyMode: dimension.hierarchyMode || 'flat',
+    sourceFormUuid,
+    sourceValueField: dimension.sourceValueField || dimension.valueField,
+    sourceLabelField: dimension.sourceLabelField || dimension.labelField,
+    sourceParentField: dimension.sourceParentField || dimension.parentField,
+    enabledField: dimension.enabledField,
+    enabled: dimension.enabled !== false,
+    configJson: dimension.configJson || dimension.config,
+  });
+}
+
+function normalizeScopeGrantSourceManifest(source, bound) {
+  const code = source.code || source.resourceCode;
+  const sourceFormUuid =
+    source.sourceFormUuid ||
+    source.formUuid ||
+    resolveOptionalFormUuid(bound, source.sourceFormCode || source.formCode);
+  return stripUndefinedValues({
+    code,
+    name: source.name || source.title || code,
+    sourceFormUuid,
+    subjectMappings: source.subjectMappings || source.subjects || [],
+    dimensionMappings: source.dimensionMappings || source.dimensions || [],
+    operationField: source.operationField,
+    enabledField: source.enabledField,
+    effectiveFromField: source.effectiveFromField,
+    effectiveToField: source.effectiveToField,
+    filterJson: source.filterJson || source.filter,
+    enabled: source.enabled !== false,
+  });
+}
+
+function normalizeDataScopePolicyManifest(policy) {
+  const code = policy.code || policy.resourceCode;
+  return stripUndefinedValues({
+    code,
+    name: policy.name || policy.title || code,
+    matchMode: policy.matchMode === 'OR' ? 'OR' : 'AND',
+    rules: policy.rules || policy.dimensions || [],
+    configJson: policy.configJson || policy.config,
+    enabled: policy.enabled !== false,
+  });
+}
+
 function normalizePublicAccessGrants(bound, grants = {}) {
   const formEntries = [
     ...normalizePermissionCodeArray(grants.forms),
@@ -10579,6 +11128,30 @@ function formPermissionGroupEquals(bound, desired, existing) {
   return stableStringifyForPlan(current, process.cwd()) === stableStringifyForPlan(expected, desired.__dir || process.cwd());
 }
 
+function scopeDimensionEquals(bound, desired, existing) {
+  if (!existing) return false;
+  const expected = normalizeScopeDimensionManifest(desired, bound);
+  return scopeResourceEquals(expected, existing, desired.__dir);
+}
+
+function scopeGrantSourceEquals(bound, desired, existing) {
+  if (!existing) return false;
+  const expected = normalizeScopeGrantSourceManifest(desired, bound);
+  return scopeResourceEquals(expected, existing, desired.__dir);
+}
+
+function dataScopePolicyEquals(desired, existing) {
+  if (!existing) return false;
+  const expected = normalizeDataScopePolicyManifest(desired);
+  return scopeResourceEquals(expected, existing, desired.__dir);
+}
+
+function scopeResourceEquals(expected, existing, baseDir) {
+  const current = pickObjectKeys(existing, Object.keys(expected));
+  return stableStringifyForPlan(current, process.cwd()) ===
+    stableStringifyForPlan(expected, baseDir || process.cwd());
+}
+
 function normalizeFormPermissionGroupManifest(bound, group) {
   const formUuid = resolveManifestFormUuid(bound, group);
   const body = {

package/lib/design-gates.js

@@ -113,12 +113,14 @@ const DESIGN_GATE_TOPICS = [
   {
     code: 'permissions',
     title: '账号 / 角色 / 页面权限 / 表单数据范围',
-    triggers: ['权限', '角色', 'RBAC', '账号权限', '平台账号', '组织账号', '角色治理', '数据范围', '只看自己', '部门数据', '页面权限', '字段权限', '查询参数权限'],
+    triggers: ['权限', '角色', 'RBAC', '账号权限', '平台账号', '组织账号', '角色治理', '数据范围', '业务范围', 'scope_policy', '只看自己', '部门数据', '页面权限', '字段权限', '查询参数权限'],
     mustAsk: [
       '权限模式选择：managed-platform-account、existing-platform-user-assignment、static-role-permission、query-param-context 中哪一种，为什么',
       '账号来源是什么：应用创建平台账号/部门、选择已有平台用户、固定角色成员，还是仅使用低风险查询参数上下文',
       '是否创建或维护平台账号/部门；如果是，哪些 App Function/organization SDK 负责创建、更新、重置密码和同步审计',
       '角色成员如何维护：角色分配表、平台角色手工维护、静态 roles manifest、还是公开访问 externalRoleCodes',
+      '业务范围是否来自应用表单：用户/角色到客户、项目、区域、门店、学院、班级等授权关系是否需要 scopeDimensions、scopeGrantSources、dataScopePolicies',
+      '业务范围数量是否超过少量固定枚举；如果会增长到几十/上百个对象，是否采用 scope_policy 而不是为每个对象建角色/权限组',
       '哪些角色可以设置应用角色、分配角色成员、给角色分配接口权限；这些角色是否需要 `app:role:manage`',
       '哪些角色可以维护页面权限组、表单权限组、组织账号；是否需要 `app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`',
       '业务范围字段是什么，哪些可见字段需要派生隐藏 scalar key 供表单权限条件匹配',
@@ -130,6 +132,8 @@ const DESIGN_GATE_TOPICS = [
       '正式后台优先选择 managed-platform-account；如果平台账号已存在，选择 existing-platform-user-assignment；固定内部门户选择 static-role-permission',
       'query-param-context 仅用于低风险页面上下文、筛选条件或公开 ticket 输入，不作为敏感数据授权依据',
       '角色写 src/resources/roles，页面组写 permissions/page-groups，表单组写 permissions/form-groups，显式声明 dataScope/operations/fieldAccessPolicy',
+      '复杂业务范围优先写 permissions/scope-dimensions、permissions/scope-grant-sources、permissions/data-scope-policies，并在表单权限组或 data-view 权限组使用 dataPermission.type=scope_policy',
+      'scope_policy 默认语义是个人授权 + 当前应用角色授权；多维 rules 显式 AND；空授权集合拒绝；管理员绕过但可审计',
       '能管理角色或给别人分配角色的应用角色必须在 roles manifest 声明 apiPermissionCodes；至少包含 app:role:manage，按需加入 app:page-permission-group:manage、app:form-permission-group:manage、app:organization:manage',
       '由校区管理员等委托管理员创建的新角色，如果还具备继续管理账号/角色/权限的能力，也必须同步声明并发布对应 apiPermissionCodes',
       '账号治理闭环使用 organization_unit、system_account、role_assignment 等业务表，加 roles、page groups、form groups、sync App Functions 和 PermissionBoundary',
@@ -141,6 +145,9 @@ const DESIGN_GATE_TOPICS = [
       '查询参数不能作为敏感授权依据，只能作为上下文、筛选或 ticket 输入',
       '只配菜单可见，不配后端数据权限',
       '为了省事授予全部数据再在前端过滤',
+      '为每个客户/项目/区域/学院/班级/门店创建一个角色或一个权限组',
+      '把应用表单里的业务范围强行同步成平台部门、平台角色或大量权限组',
+      '用数据冗余字段 + 成百上千个权限组表达动态业务授权',
       '在页面里硬编码角色、账号、部门或权限范围',
       '只给用户挂业务角色但没有给该角色绑定角色设置接口权限，导致后续新增账号/角色时运行时报无权限',
       '让普通管理员创建带管理能力的新角色，但没有同时发布新角色的 apiPermissionCodes',
@@ -150,6 +157,7 @@ const DESIGN_GATE_TOPICS = [
     ],
     acceptance: [
       'permission audit 输出无高危缺口',
+      '业务范围超过少量枚举时，resource validate/permission audit 不再出现权限组爆炸 warning，scope explain 能说明用户、当前角色、命中授权、缓存状态和最终策略',
       '设计文档写明权限模式、账号来源、角色成员来源和权限矩阵',
       '角色资源中声明了管理型角色的 apiPermissionCodes，并说明由谁首次授予',
       '内部角色允许项可用，未授权项拒绝',

package/openxiangda-skills/references/best-practices.md

@@ -47,8 +47,9 @@ Use a normal form plus:
 - a `status` field
 - user-facing responsibility fields such as personnel, department, enum, or
   SDK-backed select fields
-- hidden permission scope keys, when form permission groups require scalar
-  matching
+- hidden permission scope keys only for small fixed data-permission conditions;
+  for dynamic customer/project/region/store/college/class-like scopes, use
+  business authorization forms plus `scope_policy`
 - an action log form
 - a pure state machine in `domain/<feature>/state-machine.ts`
 - a service method that changes status and writes the log in one path
@@ -133,24 +134,34 @@ For apps with managed accounts or dynamic roles:
      `searchFieldId`, and a reasonable `pageSize` so typing in the dropdown
      triggers remote search
 4. Add hidden derived scope keys only when platform form permission conditions
-   require scalar matching, for example:
+   require scalar matching in a small fixed app, for example:
    - `collegeScopeKey`
    - `classScopeKey`
    - `ownerDeptScopeKey`
    - `ownerUserScopeKey`
 5. Create page permission groups for entry visibility.
-6. Create form permission groups with condition-based data permissions for real
-   data isolation.
-7. For delegated administrators, add role API permissions in
+6. For dynamic business ranges, declare
+   `permissions/scope-dimensions`, `permissions/scope-grant-sources`, and
+   `permissions/data-scope-policies`, then reference the policy from form
+   permission groups or Data View permission groups with
+   `dataPermission.type = "scope_policy"`.
+7. Use condition-based data permissions only when the scope values are a small,
+   fixed set or map cleanly to platform organization/departments.
+8. For delegated administrators, add role API permissions in
    `src/resources/roles/<code>.json` with `apiPermissionCodes`, for example
    `app:role:manage`, `app:page-permission-group:manage`,
    `app:form-permission-group:manage`, and `app:organization:manage`.
-8. Put sensitive writes behind App Functions with server-side role/scope checks.
+9. Put sensitive writes behind App Functions with server-side role/scope checks.
 
 Frontend button hiding is only user experience. It is not permission control.
 Every sensitive action must still be protected by platform role/form permission
 groups or backend-side JS_CODE checks.
 
+Do not generate one role or one permission group per customer, project, region,
+store, college, class, or other maintained business object. That configuration
+will not scale and should be replaced with a form-maintained authorization
+relationship and `scope_policy`.
+
 Query parameters are not permission control either. They may prefill context,
 select filters, or carry a signed/expiring ticket, but tampering with a query
 parameter must not expand sensitive data access.

package/openxiangda-skills/references/permission-design-patterns.md

@@ -49,11 +49,15 @@ Required design:
 
 - Role assignment form with `UserSelectField` / department fields for members.
 - Business scope fields such as region, department, project, customer, class, or
-  college; derive hidden scalar keys with `valueSync` when permission
-  conditions need scalar matching.
+  college. When the scope object count can grow past a few fixed values, model
+  the authorization as `scopeDimensions`, `scopeGrantSources`, and
+  `dataScopePolicies` instead of creating one role or permission group per
+  object.
 - Role sync App Function or automation only updates app role members, not
   account records.
-- Roles, page groups, and form groups remain the backend enforcement layer.
+- Roles, page groups, and form groups remain the RBAC enforcement layer.
+  `scope_policy` becomes the data-range enforcement layer for dynamic business
+  objects.
 
 Use this when HR/IT or the platform admin owns account lifecycle.
 
@@ -109,6 +113,9 @@ organization_unit
   -> src/resources/roles
   -> permissions/page-groups
   -> permissions/form-groups
+  -> permissions/scope-dimensions
+  -> permissions/scope-grant-sources
+  -> permissions/data-scope-policies
   -> sync App Functions / JS_CODE
   -> PermissionBoundary for display
   -> backend role/scope checks for sensitive writes
@@ -119,6 +126,52 @@ Pages may show or hide navigation with `useAppMenus`, `useCanAccessRoute`, and
 platform permission group, public-access grant, or App Function role/scope
 check.
 
+## Business Scope Authorization
+
+Use this layer for application-maintained authorization relationships:
+
+```text
+authorization form rows
+  -> scope grant source sync
+  -> materialized effective grants
+  -> Redis summary cache
+  -> form/data-view dataPermission.type=scope_policy
+```
+
+The platform keeps RBAC and data range separate:
+
+- Roles decide who can enter pages, submit/view forms, use operations, and
+  maintain permissions.
+- Field access remains `fieldAccessPolicy`.
+- Business scope policies decide which rows a matched role/user can read.
+- App Functions must still check role/scope server-side before sensitive
+  writes.
+
+Default semantics:
+
+- Effective grants are personal grants plus current app role grants.
+- Multi-dimension policies are `AND` by default.
+- Empty grants deny.
+- Admin bypass remains available, but use `openxiangda scope explain` and audit
+  logs to make bypass behavior visible.
+- Authorization source rows should include an explicit status/enabled field and
+  grant sources should use `filterJson` or `enabledField` so drafts, disabled
+  rows, or rejected assignments are not materialized.
+- Source forms must have a sync path. `sync: true` on the manifest runs during
+  publish; runtime changes need an automation/App Function or platform API call
+  that resyncs the affected grant source after create/update/delete.
+- Policy target fields should normally be hidden scalar keys. If targeting a
+  JSONB option/person/department field directly, declare `valuePath: "value"` or
+  `componentType`; multi-value fields should be normalized into a scalar key or
+  a separate authorization row.
+- App Function form read helpers enforce view permission for real callers. Do
+  not grant broad form read permission and then filter in function/page code.
+
+Do not model a dynamic business object set by generating dozens or hundreds of
+roles or permission groups. Use a business authorization form and `scope_policy`
+when the object set is maintained by users, imported from another system, or
+expected to grow.
+
 ## Role Setting Delegation
 
 Setting application roles is itself permission controlled. A user can be a
@@ -179,6 +232,7 @@ Before implementation, write a matrix with at least these columns:
 | Role source | role assignment form / platform role admin / roles manifest / public external role |
 | Role setting delegation | which roles need `apiPermissionCodes`, who grants them first, and whether delegation can continue |
 | Business scope fields | visible fields and hidden scalar keys |
+| Business scope policy | dimensions, grant sources, policy code, sync trigger, empty-grant behavior |
 | Page access | menu codes, route codes, path patterns, role codes |
 | Form access | submit/view/manage operations, data scope, field access policy |
 | Backend checks | App Functions that validate role/scope and deny bad input |
@@ -197,6 +251,10 @@ Before implementation, write a matrix with at least these columns:
 - Mock role context, fake account IDs, fake form instance IDs, or empty-array
   fallback displays.
 - Giving users all form data and filtering in the browser.
+- One platform role or one permission group per customer, project, region,
+  store, college, class, or other maintained object.
+- Syncing application-maintained business scope into platform departments just
+  to reuse department data scope.
 - Direct platform account API calls that bypass OpenXiangda organization SDK.
 - Reusing public visitor roles as internal admin roles.
 
@@ -208,6 +266,9 @@ Before implementation, write a matrix with at least these columns:
 - Admin roles that can manage roles, members, permission groups, or accounts
   declare `apiPermissionCodes`.
 - `openxiangda permission audit --json` has no high-risk gaps.
+- `openxiangda scope explain <policyCode> --json` explains user, current role,
+  matched grants, cache state, and final policy for at least one allow and one
+  deny case.
 - Allowed role paths and denied role paths are both tested.
 - Query parameter tampering does not expand sensitive access.
 - App Functions that mutate sensitive data verify `ctx.operator.roleCodes`,

package/openxiangda-skills/references/permissions-settings.md

@@ -209,6 +209,134 @@ Condition-style data permission:
 }
 ```
 
+## Business Scope Policy
+
+Use `scope_policy` when data access follows application-maintained business
+relationships such as user/role -> customer, project, region, store, campus,
+college, class, merchant, or any other maintained object set.
+
+Recommended boundary:
+
+- Small fixed app: static roles + a few page/form permission groups.
+- Platform organization fits the business: department data scope.
+- Common complex business scope: authorization form + `scope_policy`.
+- Public access: public-access grant + external role + permission groups.
+- Sensitive writes: App Function service-side role/scope checks.
+
+Do not create one platform role or one permission group per business object.
+Do not force form-maintained business scope into platform departments. Frontend
+hiding, query parameters, and page role checks are not sensitive authorization.
+
+Declare scope resources:
+
+```json
+// src/resources/permissions/scope-dimensions/college.json
+{
+  "code": "college",
+  "name": "学院",
+  "sourceFormCode": "college",
+  "sourceValueField": "collegeCode",
+  "sourceLabelField": "collegeName",
+  "hierarchyMode": "flat"
+}
+```
+
+```json
+// src/resources/permissions/scope-grant-sources/college_grants.json
+{
+  "code": "college_grants",
+  "name": "学院授权",
+  "sourceFormCode": "college_grant",
+  "subjectMappings": [
+    { "subjectType": "user", "field": "userId" },
+    { "subjectType": "role", "field": "roleCode" }
+  ],
+  "dimensionMappings": [
+    { "dimensionCode": "college", "field": "collegeCode" }
+  ],
+  "filterJson": {
+    "logic": "AND",
+    "rules": [
+      { "field": "status", "op": "eq", "value": "enabled" }
+    ]
+  },
+  "sync": true
+}
+```
+
+```json
+// src/resources/permissions/data-scope-policies/college_data.json
+{
+  "code": "college_data",
+  "name": "学院数据",
+  "matchMode": "AND",
+  "rules": [
+    {
+      "dimensionCode": "college",
+      "field": "collegeCode",
+      "operation": "view"
+    }
+  ]
+}
+```
+
+Reference the policy from a form permission group:
+
+```json
+{
+  "code": "college_view",
+  "formCode": "student",
+  "name": "学院查看学生",
+  "type": "view",
+  "roles": ["college_admin"],
+  "operations": ["view"],
+  "dataPermission": {
+    "type": "scope_policy",
+    "policyCode": "college_data"
+  }
+}
+```
+
+For Data View permission groups, use the same `dataPermission` shape inside the
+view's `permissionGroups`.
+
+Default runtime semantics:
+
+- Effective scope = personal grants + current app role grants.
+- Multiple policy rules are explicit `AND` unless `matchMode: "OR"` is set.
+- Empty grant sets deny data.
+- App administrators still bypass data filtering, but audit/explain should make
+  the bypass visible.
+- Redis caches per user/current-role/policy summaries with a scope version key;
+  large grant sets fall back to DB `EXISTS` checks instead of huge SQL `IN`
+  lists.
+- Prefer hidden scalar target fields such as `collegeCode` or `projectId`.
+  If a policy directly targets a JSONB option/person/department field, declare
+  `valuePath: "value"` or a supported `componentType` so the runtime compares
+  the stored option value instead of the whole JSON object.
+- `filterJson` filters authorization source rows before materializing grants.
+  Use it for enabled/approved/effective authorization rows; unsupported filter
+  operations do not match.
+- Source authorization forms must be synced after changes. For formal apps,
+  create an automation/App Function that runs `openxiangda scope sync` or the
+  equivalent platform API after authorization rows are created, updated, or
+  deleted. Publishing with `"sync": true` only syncs during resource publish.
+- App Function `ctx.form.queryOne/queryMany/getById` enforces the caller's view
+  permission when there is a real current user. No matching view permission
+  group means deny; backend system automations can still use trusted internal
+  paths and should add explicit role/scope checks for sensitive logic.
+
+Useful commands:
+
+```bash
+openxiangda scope dimension-upsert college --json-file src/resources/permissions/scope-dimensions/college.json --write-manifest
+openxiangda scope grant-source-upsert college_grants --json-file src/resources/permissions/scope-grant-sources/college_grants.json --write-manifest
+openxiangda scope policy-upsert college_data --json-file src/resources/permissions/data-scope-policies/college_data.json --write-manifest
+openxiangda scope sync college_grants --json
+openxiangda scope explain college_data --json
+openxiangda permission audit --json
+```
+
 ## Settings
 
 Form settings are deep-merged:

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -52,6 +52,11 @@ openxiangda notification preview public_register_notice --body-json '{"payload":
 
 openxiangda resource plan storage --profile <name>
 openxiangda data-view upsert --json-file src/resources/data-views/public_lookup.json
+openxiangda scope dimension-upsert college --json-file src/resources/permissions/scope-dimensions/college.json --write-manifest
+openxiangda scope grant-source-upsert college_grants --json-file src/resources/permissions/scope-grant-sources/college_grants.json --write-manifest
+openxiangda scope policy-upsert college_data --json-file src/resources/permissions/data-scope-policies/college_data.json --write-manifest
+openxiangda scope sync college_grants --json
+openxiangda scope explain college_data --json
 openxiangda menu update public_register --json-file src/resources/menus/public_register.json --write-manifest
 openxiangda permission audit --json
 openxiangda permission role-update external_visitor --json-file src/resources/roles/external_visitor.json --write-manifest
@@ -290,6 +295,88 @@ Ticket 默认单次使用，首次换取 public session 后立即失效；只有
 
 `grants.forms` 可以写本地 `formCode`，CLI 发布时会解析为真实 `formUuid`。
 
+## Business Scope Permission — `src/resources/permissions/scope-*`
+
+Use this when a form-maintained business authorization relationship controls
+row visibility. The pattern replaces "one role / one permission group per
+college, class, project, customer, region, store, etc."
+
+Dimension:
+
+```json
+{
+  "code": "college",
+  "name": "学院",
+  "sourceFormCode": "college",
+  "sourceValueField": "collegeCode",
+  "sourceLabelField": "collegeName",
+  "hierarchyMode": "flat"
+}
+```
+
+Grant source:
+
+```json
+{
+  "code": "college_grants",
+  "name": "学院授权",
+  "sourceFormCode": "college_grant",
+  "subjectMappings": [
+    { "subjectType": "user", "field": "userId" },
+    { "subjectType": "role", "field": "roleCode" }
+  ],
+  "dimensionMappings": [
+    { "dimensionCode": "college", "field": "collegeCode" }
+  ],
+  "filterJson": {
+    "logic": "AND",
+    "rules": [
+      { "field": "status", "op": "eq", "value": "enabled" }
+    ]
+  },
+  "sync": true
+}
+```
+
+Policy:
+
+```json
+{
+  "code": "college_data",
+  "name": "学院数据",
+  "matchMode": "AND",
+  "rules": [
+    { "dimensionCode": "college", "field": "collegeCode", "operation": "view" }
+  ]
+}
+```
+
+Form permission group reference:
+
+```json
+{
+  "code": "college_view",
+  "formCode": "student",
+  "name": "学院查看学生",
+  "type": "view",
+  "roles": ["college_admin"],
+  "operations": ["view"],
+  "dataPermission": {
+    "type": "scope_policy",
+    "policyCode": "college_data"
+  }
+}
+```
+
+Data View permission groups use the same `dataPermission` object inside
+`permissionGroups`. Empty grant sets deny; multiple policy rules are AND by
+default; large grant sets use DB `EXISTS` instead of huge `IN` SQL. Prefer
+hidden scalar target fields such as `collegeCode`; if the target is a JSONB
+option/person/department field, set `valuePath: "value"` or `componentType`.
+Runtime changes to the authorization source form need an automation/App
+Function or explicit platform API call to resync the grant source; manifest
+`sync: true` only runs during resource publish.
+
 ## 3. Connector — `src/resources/connectors/<code>.json`
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.136",
+  "version": "1.0.137",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {

package/packages/sdk/dist/runtime/react.d.mts

@@ -33,11 +33,13 @@ interface DataPermissionConditionDto {
     conditions?: DataPermissionConditionDto[];
 }
 interface DataPermissionDto {
-    type: "condition" | "sql";
+    type: "condition" | "sql" | "scope_policy";
     condition?: DataPermissionConditionDto;
     logic?: "AND" | "OR";
     rules?: DataPermissionRuleDto[];
     expression?: string;
+    policyCode?: string;
+    scopePolicyCode?: string;
 }
 type SearchLogic = "AND" | "OR";
 type SearchOperator = "EQ" | "NEQ" | "LIKE" | "ILIKE" | "MATCH" | "CONTAINS" | "NOT_CONTAINS" | "IN" | "IS_NULL" | "IS_NOT_NULL" | "GT" | "GTE" | "GE" | "LT" | "LTE" | "LE" | "BETWEEN" | "EXISTS" | "NOT_EXISTS" | "PATH_EQ" | string;

package/packages/sdk/dist/runtime/react.d.ts

@@ -33,11 +33,13 @@ interface DataPermissionConditionDto {
     conditions?: DataPermissionConditionDto[];
 }
 interface DataPermissionDto {
-    type: "condition" | "sql";
+    type: "condition" | "sql" | "scope_policy";
     condition?: DataPermissionConditionDto;
     logic?: "AND" | "OR";
     rules?: DataPermissionRuleDto[];
     expression?: string;
+    policyCode?: string;
+    scopePolicyCode?: string;
 }
 type SearchLogic = "AND" | "OR";
 type SearchOperator = "EQ" | "NEQ" | "LIKE" | "ILIKE" | "MATCH" | "CONTAINS" | "NOT_CONTAINS" | "IN" | "IS_NULL" | "IS_NOT_NULL" | "GT" | "GTE" | "GE" | "LT" | "LTE" | "LE" | "BETWEEN" | "EXISTS" | "NOT_EXISTS" | "PATH_EQ" | string;