openxiangda 1.0.136 → 1.0.138

package/lib/design-gates.js

@@ -113,23 +113,31 @@ 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 供表单权限条件匹配',
-      '页面/菜单/路由、表单 submit/view/manage/fieldAccessPolicy/dataScope 的权限矩阵如何落到 resources',
+      '每个角色的 action matrix 是什么：view/create/edit/delete/export/import/change_records/workflow 是否分别授权',
+      '导出/导入是否独立授权；导出范围是否与 view 范围不同，导入是否还需要逐行 create 范围校验',
+      'create 是否需要 scope_policy 校验提交数据，防止新增到未授权业务范围',
+      '页面/菜单/路由、表单 actions/fieldAccessPolicy/dataPermission/scope_policy 的权限矩阵如何落到 resources',
       '查询参数是否参与授权；如果参与，只能做上下文、筛选或 ticket 输入，敏感数据必须由 public-access grant、角色、表单权限组或 App Function 校验',
       '验收时需要模拟哪些角色、账号状态、业务范围、查询参数篡改和拒绝场景',
     ],
     recommendedDefaults: [
       '正式后台优先选择 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',
+      '角色写 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',
+      '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',
       '由校区管理员等委托管理员创建的新角色，如果还具备继续管理账号/角色/权限的能力，也必须同步声明并发布对应 apiPermissionCodes',
       '账号治理闭环使用 organization_unit、system_account、role_assignment 等业务表，加 roles、page groups、form groups、sync App Functions 和 PermissionBoundary',
@@ -140,7 +148,11 @@ const DESIGN_GATE_TOPICS = [
       '不能只做前端权限隐藏，必须有后端角色、表单权限组、public-access grant 或 App Function 校验',
       '查询参数不能作为敏感授权依据，只能作为上下文、筛选或 ticket 输入',
       '只配菜单可见，不配后端数据权限',
+      '只隐藏按钮但没有表单权限组 actions 或 App Function 服务端校验',
       '为了省事授予全部数据再在前端过滤',
+      '为每个客户/项目/区域/学院/班级/门店创建一个角色或一个权限组',
+      '把应用表单里的业务范围强行同步成平台部门、平台角色或大量权限组',
+      '用数据冗余字段 + 成百上千个权限组表达动态业务授权',
       '在页面里硬编码角色、账号、部门或权限范围',
       '只给用户挂业务角色但没有给该角色绑定角色设置接口权限，导致后续新增账号/角色时运行时报无权限',
       '让普通管理员创建带管理能力的新角色，但没有同时发布新角色的 apiPermissionCodes',
@@ -150,6 +162,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/component-guide.md

@@ -64,7 +64,7 @@ AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
 | 富文本编辑 | `EditorField` | 含图片上传集成 | 完整工具栏、平台图床、粘贴清洗 |
 | 数字签名 | `DigitalSignatureField` | 平台级签名 | 签名采集、验证、归档 |
 | 地理位置 | `LocationField` | 接入地图服务 | 定位、地图选点、地址解析 |
-| 数据管理列表 | `DataManagementList` | 接入数据查询 API | 分页、筛选、导出、批量操作、字段权限 |
+| 数据管理列表 | `DataManagementList` | 接入数据查询 API | 分页、筛选、导出、批量操作、字段权限、后端 action summary 按钮控制 |
 
 ### 示例
 
@@ -89,6 +89,12 @@ OSS 浏览器直传所需的 CORS 规则在 `src/resources/storage/<code>.json`
 
 业务应用只能从 `openxiangda`、`openxiangda/runtime`、`openxiangda/runtime/react` 等公开入口导入组件和 SDK。不要为了减小包体积去引用 `openxiangda/packages/sdk/dist/...` 内部文件；React SPA 模板已提供 vendor chunk 分组，SDK 会把 `antd-mobile`、`dayjs` 等大型 UI 依赖交给应用构建器按路由拆分。
 
+`DataManagementList` 默认 `permissionMode="auto"`，进入页面会读取表单 action
+summary，并用 `can.create/export/import/delete/workflow/change_records` 隐藏新增、
+导入、导出、删除、流程等按钮。`readonly=true` 仍会强制关闭新增、编辑、删除和
+导入。`actionOverrides` 只能关闭按钮，不能扩大后端权限；敏感授权必须依赖后端
+form actions、`scope_policy` 或 App Function 服务端校验。
+
 > ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
 
 ---

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

@@ -27,8 +27,8 @@ Required design:
   scalar scope keys, platform role member sync state.
 - `src/resources/roles/*.json`: stable app role codes.
 - `src/resources/permissions/page-groups/*.json`: menu, route, and page access.
-- `src/resources/permissions/form-groups/*.json`: submit/view/manage, data
-  scope, operations, and `fieldAccessPolicy`.
+- `src/resources/permissions/form-groups/*.json`: `actions`, data scope or
+  `dataPermission.type=scope_policy`, and `fieldAccessPolicy`.
 - `apiPermissionCodes` on roles that are allowed to manage roles, role members,
   permission groups, or organization accounts.
 - Sync App Functions or trusted JS_CODE: sync organization units, accounts, and
@@ -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,81 @@ 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.
+- Form `actions` decide what a role can do: `view`, `create`, `edit`, `delete`,
+  `export`, `import`, `change_records`, and `workflow`.
+- Data View `actions` decide query capabilities: `query`, `stats`, `export`,
+  and `refresh`.
+- Field access remains `fieldAccessPolicy`.
+- Business scope policies decide which rows or submitted scope values a matched
+  role/user can access for the current action.
+- 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.
+- `DataManagementList` can hide buttons from the backend action summary, but it
+  is not the authority. Sensitive actions must be represented by form actions or
+  App Function server checks.
+
+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.
+
+Recommended action pattern:
+
+```json
+{
+  "code": "campus_profile_manage",
+  "formCode": "student_profile",
+  "name": "校区管理员档案权限",
+  "type": "view",
+  "roles": ["campus_admin"],
+  "actions": ["view", "edit", "export"],
+  "dataPermission": {
+    "type": "scope_policy",
+    "policyCode": "campus_row_scope"
+  },
+  "fieldAccessPolicy": {
+    "defaultAccess": "readonly",
+    "fields": [{ "fieldId": "remark", "access": "edit" }]
+  }
+}
+```
+
 ## Role Setting Delegation
 
 Setting application roles is itself permission controlled. A user can be a
@@ -179,6 +261,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 +280,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 +295,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,171 @@ 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"],
+  "actions": ["view", "edit", "export"],
+  "dataPermission": {
+    "type": "scope_policy",
+    "policyCode": "college_data"
+  }
+}
+```
+
+Unified permission model:
+
+- `scope_policy` means data range: which rows this user/current app role can
+  access.
+- `actions` means operation ability: what the role can do to rows in that
+  range. Form actions are `view`, `create`, `edit`, `delete`, `export`,
+  `import`, `change_records`, and `workflow`.
+- The platform still stores actions in the legacy `operations` field. Manifests
+  may use either `actions` or `operations`; prefer `actions` in new resources.
+- `type: "submit"` is the legacy create group and maps to `actions:["create"]`.
+- `export` is independent from `view` for new apps. Old apps may temporarily
+  rely on view-to-export compatibility, but `permission audit` should be used to
+  migrate to explicit `export`.
+- `create` with `scope_policy` validates submitted scope fields; a campus admin
+  cannot create a row for another campus just because the create button is
+  visible.
+- Frontend button hiding is UX only. The backend action check and action-specific
+  data range are authoritative.
+
+Create permission with business scope:
+
+```json
+{
+  "code": "college_student_create",
+  "formCode": "student",
+  "name": "学院管理员新增本学院学生",
+  "type": "submit",
+  "roles": ["college_admin"],
+  "actions": ["create"],
+  "dataPermission": {
+    "type": "scope_policy",
+    "policyCode": "college_data"
+  }
+}
+```
+
+For Data View permission groups, use the same `dataPermission` shape inside the
+view's `permissionGroups`. Data View actions are `query`, `stats`, `export`,
+and `refresh`.
+
+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.138",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {

package/packages/sdk/dist/{ProcessPreview-Ci8_UsbN.d.mts → ProcessPreview-CZJP8n3e.d.mts}

@@ -1021,6 +1021,12 @@ interface ProcessDefinition {
 interface ViewPermissionSummary {
     fieldPermissions: Record<string, 'FORM_FILED_HIDDEN' | 'FORM_FILED_VIEW' | 'FORM_FILED_EDIT'>;
     operations: string[];
+    actions?: string[];
+    can?: Record<string, boolean>;
+    fieldAccessPolicy?: any;
+    hasFullAccess?: boolean;
+    resourceType?: string;
+    matchedGroupCodes?: string[];
 }
 /** 表单实例数据 */
 interface FormInstanceData {

package/packages/sdk/dist/{ProcessPreview-Ci8_UsbN.d.ts → ProcessPreview-CZJP8n3e.d.ts}

@@ -1021,6 +1021,12 @@ interface ProcessDefinition {
 interface ViewPermissionSummary {
     fieldPermissions: Record<string, 'FORM_FILED_HIDDEN' | 'FORM_FILED_VIEW' | 'FORM_FILED_EDIT'>;
     operations: string[];
+    actions?: string[];
+    can?: Record<string, boolean>;
+    fieldAccessPolicy?: any;
+    hasFullAccess?: boolean;
+    resourceType?: string;
+    matchedGroupCodes?: string[];
 }
 /** 表单实例数据 */
 interface FormInstanceData {