openxiangda 1.0.138 → 1.0.139

package/lib/cli.js

@@ -7079,6 +7079,12 @@ function validateResourceItem(kind, item, errors, warnings) {
   if (kind === 'scopeGrantSources') {
     if (!item.name) warnings.push(`${label}: 未声明 name，将使用 code`);
     if (!item.sourceFormUuid && !item.formUuid) errors.push(`${label}: 缺少 sourceFormUuid`);
+    if (
+      item.syncMode !== undefined &&
+      !['on_write', 'manual'].includes(String(item.syncMode))
+    ) {
+      errors.push(`${label}: syncMode 只能是 on_write 或 manual`);
+    }
     const subjectMappings = item.subjectMappings || item.subjects;
     const dimensionMappings = item.dimensionMappings || item.dimensions;
     if (!Array.isArray(subjectMappings) || subjectMappings.length === 0) {
@@ -7159,6 +7165,11 @@ function validateScopePermissionResources(manifest, errors, warnings) {
       .map(String)
   );
   const scopePolicyRefs = [];
+  for (const source of manifest.scopeGrantSources || []) {
+    if (String(source.syncMode || '').trim() === 'manual') {
+      warnings.push(`${resourceLabel('scopeGrantSources', source)}: syncMode=manual，运行时来源表单变更不会自动物化；请确认有显式 scope sync 作业`);
+    }
+  }
   const inspectPermissionGroup = (kind, item) => {
     const groups = kind === 'dataViews'
       ? (Array.isArray(item.permissionGroups) ? item.permissionGroups : [])
@@ -10610,10 +10621,20 @@ function normalizeScopeGrantSourceManifest(source, bound) {
     effectiveFromField: source.effectiveFromField,
     effectiveToField: source.effectiveToField,
     filterJson: source.filterJson || source.filter,
+    syncMode: normalizeScopeGrantSourceSyncMode(source.syncMode, source.sync),
     enabled: source.enabled !== false,
   });
 }
 
+function normalizeScopeGrantSourceSyncMode(value, legacySync) {
+  const raw = String(value || '').trim().toLowerCase();
+  if (['manual', 'off', 'none', 'disabled', 'false'].includes(raw)) {
+    return 'manual';
+  }
+  if (legacySync === false) return 'manual';
+  return 'on_write';
+}
+
 function normalizeDataScopePolicyManifest(policy) {
   const code = policy.code || policy.resourceCode;
   return stripUndefinedValues({

package/lib/design-gates.js

@@ -135,7 +135,7 @@ 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，显式声明 actions/dataPermission/fieldAccessPolicy；平台内部仍兼容存储为 operations',
-      '复杂业务范围优先写 permissions/scope-dimensions、permissions/scope-grant-sources、permissions/data-scope-policies，并在表单权限组或 data-view 权限组使用 dataPermission.type=scope_policy',
+      '复杂业务范围优先写 permissions/scope-dimensions、permissions/scope-grant-sources、permissions/data-scope-policies，并在表单权限组或 data-view 权限组使用 dataPermission.type=scope_policy；授权来源默认 syncMode=on_write，由平台在来源表单写入后自动物化',
       'scope_policy 只表达数据范围，actions 表达操作能力；按钮隐藏只是 UX，后端 action check 才是权威',
       'scope_policy 默认语义是个人授权 + 当前应用角色授权；多维 rules 显式 AND；空授权集合拒绝；管理员绕过但可审计',
       '能管理角色或给别人分配角色的应用角色必须在 roles manifest 声明 apiPermissionCodes；至少包含 app:role:manage，按需加入 app:page-permission-group:manage、app:form-permission-group:manage、app:organization:manage',

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

@@ -162,9 +162,11 @@ Default semantics:
 - 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.
+- Source authorization forms are synced by the platform after form
+  create/update/delete/import when the grant source uses the default
+  `syncMode: "on_write"`. Use `syncMode: "manual"` only for externally
+  maintained sources or unusual bulk jobs; `sync: true` still performs an
+  immediate full sync during resource publish.
 - 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

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

@@ -260,6 +260,7 @@ Declare scope resources:
       { "field": "status", "op": "eq", "value": "enabled" }
     ]
   },
+  "syncMode": "on_write",
   "sync": true
 }
 ```
@@ -354,10 +355,11 @@ Default runtime semantics:
 - `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.
+- Source authorization forms are synced by the platform after create/update/
+  delete/import when the grant source uses the default `syncMode: "on_write"`.
+  Use `syncMode: "manual"` only for externally maintained sources or unusual
+  bulk jobs that explicitly call `openxiangda scope sync`. Publishing with
+  `"sync": true` still performs an immediate full sync 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

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

@@ -334,6 +334,7 @@ Grant source:
       { "field": "status", "op": "eq", "value": "enabled" }
     ]
   },
+  "syncMode": "on_write",
   "sync": true
 }
 ```
@@ -373,9 +374,12 @@ Data View permission groups use the same `dataPermission` object inside
 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.
+Authorization source form changes are synced by the platform after
+create/update/delete/import when the grant source uses the default
+`syncMode: "on_write"`. Use `syncMode: "manual"` only for externally maintained
+sources or special bulk jobs that explicitly call `openxiangda scope sync`.
+Manifest `sync: true` still performs an immediate full sync during resource
+publish.
 
 ## 3. Connector — `src/resources/connectors/<code>.json`
 

package/package.json

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