openxiangda 1.0.135 → 1.0.136

package/lib/design-gates.js

@@ -112,28 +112,51 @@ const DESIGN_GATE_TOPICS = [
   },
   {
     code: 'permissions',
-    title: '角色 / 页面权限 / 表单数据范围',
-    triggers: ['权限', '角色', '数据范围', '只看自己', '部门数据', '页面权限', '字段权限'],
+    title: '账号 / 角色 / 页面权限 / 表单数据范围',
+    triggers: ['权限', '角色', 'RBAC', '账号权限', '平台账号', '组织账号', '角色治理', '数据范围', '只看自己', '部门数据', '页面权限', '字段权限', '查询参数权限'],
     mustAsk: [
-      '角色清单及成员来源：固定成员、组织部门、外部角色',
-      '页面、菜单、公开路由分别开放给哪些角色',
-      '每个表单的 submit/view/manage 操作和字段权限',
-      '数据范围是全部、本人、部门、自定义条件还是公开 grant',
-      '验收时需要模拟哪些角色和拒绝场景',
+      '权限模式选择：managed-platform-account、existing-platform-user-assignment、static-role-permission、query-param-context 中哪一种，为什么',
+      '账号来源是什么：应用创建平台账号/部门、选择已有平台用户、固定角色成员，还是仅使用低风险查询参数上下文',
+      '是否创建或维护平台账号/部门；如果是，哪些 App Function/organization SDK 负责创建、更新、重置密码和同步审计',
+      '角色成员如何维护：角色分配表、平台角色手工维护、静态 roles manifest、还是公开访问 externalRoleCodes',
+      '哪些角色可以设置应用角色、分配角色成员、给角色分配接口权限；这些角色是否需要 `app:role:manage`',
+      '哪些角色可以维护页面权限组、表单权限组、组织账号；是否需要 `app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`',
+      '业务范围字段是什么，哪些可见字段需要派生隐藏 scalar key 供表单权限条件匹配',
+      '页面/菜单/路由、表单 submit/view/manage/fieldAccessPolicy/dataScope 的权限矩阵如何落到 resources',
+      '查询参数是否参与授权；如果参与，只能做上下文、筛选或 ticket 输入，敏感数据必须由 public-access grant、角色、表单权限组或 App Function 校验',
+      '验收时需要模拟哪些角色、账号状态、业务范围、查询参数篡改和拒绝场景',
     ],
     recommendedDefaults: [
-      '角色写 src/resources/roles，页面组写 permissions/page-groups',
-      '表单权限组写 permissions/form-groups，显式声明 dataScope/operations',
-      '公开访问不要复用内部管理员权限组',
+      '正式后台优先选择 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',
+      '能管理角色或给别人分配角色的应用角色必须在 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',
+      '平台账号创建、更新、重置密码只走 sdk.organization/ctx.organization；操作者必须具备 app:organization:manage',
+      '公开访问不要复用内部管理员权限组；公开数据仍需 public-access grants 与外部角色权限组双重覆盖',
     ],
     antiPatterns: [
+      '不能只做前端权限隐藏，必须有后端角色、表单权限组、public-access grant 或 App Function 校验',
+      '查询参数不能作为敏感授权依据，只能作为上下文、筛选或 ticket 输入',
       '只配菜单可见，不配后端数据权限',
       '为了省事授予全部数据再在前端过滤',
+      '在页面里硬编码角色、账号、部门或权限范围',
+      '只给用户挂业务角色但没有给该角色绑定角色设置接口权限，导致后续新增账号/角色时运行时报无权限',
+      '让普通管理员创建带管理能力的新角色，但没有同时发布新角色的 apiPermissionCodes',
+      '前端模拟权限通过、mock role、假账号、假 ID 或空数组兜底',
+      '直接绕过 SDK 调平台账号/组织写接口，或用旧 /user、/department 接口写账号',
       '公开角色和内部角色混用',
     ],
     acceptance: [
       'permission audit 输出无高危缺口',
+      '设计文档写明权限模式、账号来源、角色成员来源和权限矩阵',
+      '角色资源中声明了管理型角色的 apiPermissionCodes，并说明由谁首次授予',
       '内部角色允许项可用，未授权项拒绝',
+      '用非授权角色验证角色创建/成员分配/权限组维护会被拒绝，用授权角色验证可成功',
+      '敏感 App Function 包含服务端 role/scope checks，且不信任页面传入的 roleCodes',
+      '平台账号治理路径验证当前操作者拥有 app:organization:manage',
+      '查询参数篡改不会扩大敏感数据访问范围',
       '公开访问受 public-access grant 和权限组双重约束',
     ],
   },
@@ -236,6 +259,13 @@ const DESIGN_GATE_TOPIC_ALIASES = {
   permission: 'permissions',
   role: 'permissions',
   roles: 'permissions',
+  rbac: 'permissions',
+  'role-governance': 'permissions',
+  'account-permission': 'permissions',
+  'organization-account': 'permissions',
+  'org-account': 'permissions',
+  'account-role': 'permissions',
+  'query-param-permission': 'permissions',
   workflow: 'workflow-automation',
   automation: 'workflow-automation',
   function: 'workflow-automation',

package/openxiangda-skills/SKILL.md

@@ -29,7 +29,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 | 自动化 / 定时任务 / 提交触发 / cron                      | `openxiangda-workflow-automation`                                                          | `openxiangda automation validate / create / publish / enable`                                                                                            |
 | App Function / function_call / 可复用后端逻辑            | `openxiangda-workflow-automation`                                                          | declare `src/resources/functions/<code>.json` + `src/functions/<code>/index.ts`                                                                          |
 | 应用登录 / Auth SDK / 手机号验证码 / CAS / 钉钉免登      | `openxiangda-architecture-design` + `openxiangda-page`                                     | design security gate first, then declare `src/resources/auth/<code>.json` and use `createAuthClient` / `LoginPage`                                       |
-| 角色 / 权限组 / 字段权限 / 数据范围                      | `openxiangda-permission-settings`                                                          | `openxiangda permission ...` / `openxiangda settings ...`                                                                                                |
+| 账号权限 / 角色 / 权限组 / 字段权限 / 数据范围 / RBAC   | `openxiangda-permission-settings`                                                          | `openxiangda design gates --topic permissions --json` → choose permission mode → `openxiangda permission ...` / `openxiangda settings ...`              |
 | 平台部门 / 平台账号 / 重置密码 / 组织账号管理            | `openxiangda-architecture-design` + `openxiangda-page`                                     | check `openxiangda organization capabilities --json`; use `sdk.organization` / `ctx.organization` only after `app:organization:manage` is granted         |
 | 外部人员无需登录访问 / 公开报名 / 公开查询 / public page | `openxiangda-architecture-design` + `openxiangda-permission-settings` + `openxiangda-page` | 先确认公开范围、外部角色、ticket、grants；再声明 `routes` + `public-access`，并用 `OpenXiangdaProvider` + `OpenXiangdaPageProvider` + `PublicAccessGate` |
 | 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错            | `openxiangda-inspect`                                                                      | `openxiangda app snapshot <APP_XXX> --profile <name> --json`                                                                                             |
@@ -51,6 +51,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ✅ For non-trivial app requirements, run the architecture design gate first: forms, fields, pages, permissions, data views, status/workflow, automation, notifications, and development tasks must be decided before coding.
 - ✅ For app login/auth requirements, run the auth security gate before coding: enabled methods, registration policy, identity matching keys, provider boundary, default roles, rate limits, audit fields, and third-party ownership must be confirmed.
 - ✅ For public/no-login access requirements, run the public access design gate before coding: public routes, external role codes, guest vs ticket, form/dataView/function/connector grants, backend permission groups, and visible loading/error fallback states must be confirmed. New React SPA apps use `/view/:appType/public/*`, `src/resources/routes/`, `src/resources/public-access/`, and `PublicAccessGate`; route children that use Page SDK hooks must be inside `OpenXiangdaProvider` + `OpenXiangdaPageProvider`.
+- ✅ For account/role/permission/data-scope/query-param authorization requirements, run `openxiangda design gates --topic permissions --json` before coding. Pick one mode from `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`, write the permission matrix, and use roles/page-groups/form-groups/App Functions for real enforcement.
 - ✅ Public/no-login validation must inspect the JSON envelope, not only HTTP status. HTTP 200 with `code: "PUBLIC_GRANT_DENIED"` is a denied request; success requires `code` `200`, `"200"`, or compatible `0`, and no `success: false`.
 - ✅ Use first-class resource CLI commands for discovery, diagnosis, and small live fixes: `route`, `public-access`, `auth-config`, `function`, `connector`, `notification`, `organization`, `data-view`, `menu`, and `permission`. For multi-resource formal development, still prefer `src/resources/**` + `openxiangda resource validate|plan|publish`. If a direct CLI write is intentionally used, add `--write-manifest` when the repository should stay the source of truth.
 - ✅ For form-entry UX, pick components in this order: OpenXiangda platform form components → `antd` / `antd-mobile` wrappers → custom component only when neither exists.
@@ -69,6 +70,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ❌ Implementing an architecture-class request before the user confirms the design. This includes creating files, mutating platform resources, publishing runtime, sending notifications, or calling live write/delete endpoints.
 - ❌ Running a full publish after editing one file. Default to `--changed --dry-run` → `--changed`, or targeted `--page` / `--form`.
 - ❌ Generating fake form instance IDs, mock rows, fallback schemas, or fallback display data to make a broken API path look successful.
+- ❌ Treating query parameters, frontend button hiding, hardcoded roles, mock role context, or `PermissionBoundary` alone as sensitive authorization. Query parameters may provide context or ticket input only; sensitive data still needs public-access grants, platform roles, form permission groups, or App Function checks.
 - ❌ Storing tokens, AK, SK, or third-party API secrets in project files. Shared env (`APP_OSS_*`, feedback robot) goes to `~/.openxiangda/.env`.
 - ❌ Raw native HTML form controls in AI-authored workspace code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, hand-written upload controls). They are allowed only inside OpenXiangda SDK/platform component internals.
 - ❌ Using `?publicAccess=guest` or form `publicAccess` settings for new React SPA apps. Those are legacy `sy-lowcode-view` compatibility only.
@@ -161,6 +163,8 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
 - For reusable backend logic shared by pages, automations, and workflows, create an App Function in `src/resources/functions/<functionCode>.json` plus `src/functions/<functionCode>/index.ts`. Call it from pages with `sdk.function.invoke`, from automation/workflow graphs with `function_call`, or from the runtime endpoint when the caller has app automation management permission. Current App Function MVP exposes controlled helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, and `ctx.platform.api`; it does not expose raw SQL or Redis. Runtime functions also receive trusted role context on `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; use these for server-side business authorization. Do not trust role codes sent in page input for sensitive actions. App Function form writes are trusted backend writes governed by declared `resources.forms` and function invocation authorization; do not grant normal users raw submit permission to internal forms just to let `ctx.form.createOne/updateOne/updateById` run.
 - For app-managed platform departments/accounts, use `sdk.organization.departments.*`, `sdk.organization.accounts.*`, `ctx.organization.departments.*`, or `ctx.organization.accounts.*`. The real current user/audit actor must hold `app:organization:manage` on the app; runtime service principals do not bypass this permission. Do not call legacy `/user` or `/department` write endpoints from apps. Do not include `password` in account updates; reset target accounts with `resetPassword`, and change the current user's password with `changeMyPassword({ oldPassword, newPassword })`.
+- For account, role, data-scope, organization-account, RBAC, or query-param authorization designs, read `references/permission-design-patterns.md` and choose a permission mode before writing forms/pages/resources. Formal backends should use platform roles, page permission groups, form permission groups, public-access grants, and App Function role/scope checks; frontend hiding is display only.
+- When a role such as 校区管理员 will create app roles, assign role members, grant role permissions, maintain permission groups, or manage organization accounts, its role manifest must declare the needed `apiPermissionCodes` such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`. If that administrator creates another administrator role, the new role must also declare its own `apiPermissionCodes`; permissions are not inherited from the creator.
 - For application login, declare auth resources in `src/resources/auth/<code>.json` and publish them with `openxiangda resource publish`. App Function auth providers may validate external credentials and return only an identity assertion; they must never issue tokens, set cookies, or write platform user/binding tables directly. The platform auth service decides create/bind/reject and issues tokens.
 - For external/no-login pages in React SPA apps, declare `src/resources/routes/<code>.json` and `src/resources/public-access/<code>.json`, put the page under `/view/:appType/public/*`, and use `PublicAccessGate` or `createPublicAccessClient`. The route tree must also include `OpenXiangdaPageProvider` inside `OpenXiangdaProvider` before any `usePageSdk()` / `usePageContext()` / `useDataSource()` call; otherwise pages throw `usePageSdkStore 必须在 PageProvider 内使用`. Always provide `fallback` and `errorFallback` for public routes so slow networks, missing tickets, or expired tickets do not render blank pages. Public guest access to forms, dataViews, functions, and connectors is denied unless policy `grants` explicitly names the resource; backend permission groups still apply.
 - When verifying public access, parse the response body and reject string business errors such as `PUBLIC_GRANT_DENIED` even if the HTTP status is 200. Do not use `response.ok` alone as the success condition.
@@ -208,6 +212,7 @@ Core CLI / state:
 - `references/data-views.md` — `src/resources/data-views` materialized/live data view resources, DSL, permissions, refresh, CLI commands, and runtime SDK usage.
 - `references/notifications.md` — `src/resources/notifications`, notification templates/type bindings, and `sdk.notification` / `ctx.notification`.
 - `references/best-practices.md` — initialized examples for modular pages, state lifecycles, role governance, permission isolation, high-performance queries, portal shells, workflow boundaries, and automation patterns.
+- `references/permission-design-patterns.md` — account/role/permission design modes: managed platform account, existing user assignment, static role permission, query-param context, and the required resource/permission matrix.
 
 Form authoring:
 
@@ -226,6 +231,7 @@ Workflow / automation / permissions:
 - `references/workflow-v3.md` — workflow v3 definitions, JS_CODE nodes, App Function `function_call`, and trusted_node mode.
 - `references/automation-v3.md` — automation triggers, conditions, App Function `function_call`, and publishing.
 - `references/permissions-settings.md` — roles, page/form permission groups, settings.
+- `references/permission-design-patterns.md` — required when designing accounts, roles, RBAC, organization-account governance, data scope, or query-param authorization.
 
 Platform domain knowledge (read these first when generating forms or pages so the output matches the live platform behavior):
 

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

@@ -27,7 +27,7 @@ form codes, field names, permissions, and page route names.
    - business status lifecycle
    - real approval workflow
    - automation / JS_CODE
-   - role governance / permissions
+   - access governance / role governance / permissions
    - optional admin UI template:
      `glass-home-dashboard`, `mint-analytics-dashboard`,
      `ops-monitor-dashboard`, or `work-order-list-drawer`
@@ -104,10 +104,25 @@ same `domain/` and `shared/services/` when the business behavior is the same.
 
 ## Permission And Data Isolation
 
-For apps with dynamic roles:
-
-1. Create an app role maintenance form, such as `app-role`.
-2. Use automation / JS_CODE to sync role records to platform roles.
+For account, role, RBAC, data-scope, or query-parameter authorization
+requirements, read `permission-design-patterns.md` and choose one mode before
+writing code:
+
+- `managed-platform-account`: the app owns platform account/department lifecycle
+  and role synchronization.
+- `existing-platform-user-assignment`: the app assigns existing platform users
+  to app roles and business scopes.
+- `static-role-permission`: roles and permission groups are fixed resources.
+- `query-param-context`: query parameters are context, filters, or ticket input
+  only; sensitive access still needs real authorization.
+
+For apps with managed accounts or dynamic roles:
+
+1. Create the minimum governance forms required by the chosen mode:
+   `organization_unit`, `system_account`, `role_assignment`, or a smaller app
+   role maintenance form such as `app-role`.
+2. Use App Functions, automation, or JS_CODE to sync organization units,
+   platform accounts, and role records to platform departments/accounts/roles.
 3. Model visible scope fields with maintainable controls:
    - personnel and departments use platform personnel/department fields
    - enum scopes use `SelectField` / `RadioField` with `options`
@@ -126,11 +141,20 @@ For apps with dynamic roles:
 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
+   `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.
 
 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.
 
+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.
+
 ## Form Copy And Field Visibility
 
 - Every visible form field should have a short, user-facing placeholder.
@@ -220,6 +244,9 @@ groups or backend-side JS_CODE checks.
 - `service-ticket-ops`: custom data management page based on
   `DataManagementList`, split into page, components, hook, query builder, and
   detail drawer.
+- `access-governance`: account/role permission mode decision, organization,
+  account, role assignment, sync function, roles, page-group, and form-group
+  skeletons.
 - `role-governance`: role maintenance form, role sync JS_CODE, maintainable
   scope fields, hidden permission keys, and permission-group resource examples.
 - `pc-portal-shell`: app-shell PC portal with routes, modules, components, and

package/openxiangda-skills/references/openxiangda-api.md

@@ -636,11 +636,13 @@ Requires Bearer token. Returns one execution record with raw `nodeExecutionLogs`
 
 ### GET `/apps/:appType/roles`
 
-Requires Bearer token. Lists app roles visible to the current user.
+Requires Bearer token and app role management permission for role-setting
+operations. Lists app roles visible to the current user.
 
 ### POST `/apps/:appType/roles`
 
-Requires Bearer token. Creates an app-scoped role.
+Requires Bearer token with `app:role:manage` on the app. Creates an app-scoped
+role.
 
 Body:
 
@@ -658,11 +660,13 @@ Requires Bearer token. Returns app role detail.
 
 ### PUT `/apps/:appType/roles/:roleId`
 
-Requires Bearer token. Updates app role metadata.
+Requires Bearer token with `app:role:manage` on the app. Updates app role
+metadata.
 
 ### DELETE `/apps/:appType/roles/:roleId`
 
-Requires Bearer token. Deletes a non-system app role.
+Requires Bearer token with `app:role:manage` on the app. Deletes a non-system
+app role.
 
 ### GET `/apps/:appType/roles/:roleId/users`
 
@@ -670,11 +674,33 @@ Requires Bearer token. Lists users under an app role.
 
 ### POST `/apps/:appType/roles/:roleId/users`
 
-Requires Bearer token. Adds users to an app role.
+Requires Bearer token with `app:role:manage` on the app. Adds users to an app
+role.
 
 ### DELETE `/apps/:appType/roles/:roleId/users/:userId`
 
-Requires Bearer token. Removes one user from an app role.
+Requires Bearer token with `app:role:manage` on the app. Removes one user from
+an app role.
+
+When publishing role resources, OpenXiangda can also assign app-scoped API
+permissions to the role:
+
+```json
+{
+  "code": "campus_admin",
+  "name": "校区管理员",
+  "apiPermissionMode": "merge",
+  "apiPermissionCodes": [
+    "app:role:manage",
+    "app:page-permission-group:manage",
+    "app:form-permission-group:manage"
+  ]
+}
+```
+
+This is required when the role itself should create roles, assign role members,
+or maintain permission groups. The first grant is normally done by a platform
+administrator or an existing app role that already has `app:role:manage`.
 
 ### GET `/apps/:appType/page-permission-groups`
 

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

@@ -0,0 +1,216 @@
+# Permission Design Patterns
+
+Use this reference before implementing OpenXiangda requirements that mention
+accounts, roles, permission groups, organization scope, data scope, or query
+parameter based access.
+
+The rule is simple: choose the permission mode first, then design forms,
+resources, App Functions, pages, and publish order. Do not start by hiding
+buttons in the frontend.
+
+## Mode Selection
+
+### `managed-platform-account`
+
+The app owns account governance. Use this for formal admin systems, external
+account lifecycle, school/company tenant management, or any workflow where the
+app must create, update, disable, reset, or place platform accounts into
+departments and roles.
+
+Required design:
+
+- `organization_unit` form: business organization tree, parent key, manager,
+  platform department ID, sync status, sync message, last synced time.
+- `system_account` form: login name, display name, phone/email, organization
+  unit, enabled state, platform user ID, sync status, last synced time.
+- `role_assignment` form: account, role codes, business scope fields, hidden
+  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`.
+- `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
+  role assignments to the platform.
+- Page `PermissionBoundary` and runtime menus for display control only.
+- Backend role/scope checks in App Functions for sensitive writes.
+
+Platform account writes must use `sdk.organization.*` or `ctx.organization.*`.
+The real current operator must have `app:organization:manage`. Do not call
+legacy `/user` or `/department` write endpoints from app code.
+
+### `existing-platform-user-assignment`
+
+The platform already has users and departments. The app only assigns existing
+users to app roles and business scopes.
+
+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.
+- 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.
+
+Use this when HR/IT or the platform admin owns account lifecycle.
+
+### `static-role-permission`
+
+Roles are fixed and membership is maintained by platform admins or resource
+manifests. Use this for small internal apps, stable admin roles, and apps where
+no in-app role maintenance screen is required.
+
+Required design:
+
+- `roles` resources.
+- Page permission groups for menus/routes.
+- Form permission groups for submit/view/manage/data scope/field access.
+- Optional `PermissionBoundary` for UI display.
+
+Do not create role/account governance forms just because a page has two static
+roles.
+
+### `query-param-context`
+
+Query parameters provide context only. Use this for low-risk links, prefilled
+filters, external ticket input, public lookup keys, or deep links.
+
+Allowed:
+
+- select an initial tab, filter, date range, organization code, or public ticket
+  code
+- prefill a form field before the user submits
+- carry a signed/expiring ticket that is validated by public-access policy or an
+  App Function
+
+Not allowed:
+
+- granting sensitive data access only because `?role=admin` or `?dept=...` is
+  present
+- deciding form data scope only in the frontend
+- bypassing roles, form permission groups, public-access grants, or App
+  Function checks
+
+If the page reads sensitive data, performs writes, or exposes internal records,
+combine query parameters with real authorization: public-access grants, roles,
+form permission groups, or server-side App Function checks.
+
+## Standard Resource Closure
+
+A complete high-governance permission design usually has this closure:
+
+```text
+organization_unit
+  -> system_account
+  -> role_assignment
+  -> src/resources/roles
+  -> permissions/page-groups
+  -> permissions/form-groups
+  -> sync App Functions / JS_CODE
+  -> PermissionBoundary for display
+  -> backend role/scope checks for sensitive writes
+```
+
+Pages may show or hide navigation with `useAppMenus`, `useCanAccessRoute`, and
+`PermissionBoundary`, but these are not the authority. Real authority is the
+platform permission group, public-access grant, or App Function role/scope
+check.
+
+## Role Setting Delegation
+
+Setting application roles is itself permission controlled. A user can be a
+business administrator in the app and still fail to create roles, assign role
+members, or grant role permissions unless that user's current app role has the
+matching API permission.
+
+Use role `apiPermissionCodes` in `src/resources/roles/<code>.json` for delegated
+administrators:
+
+```json
+{
+  "code": "campus_admin",
+  "name": "校区管理员",
+  "description": "维护本校区账号、角色和权限",
+  "apiPermissionMode": "merge",
+  "apiPermissionCodes": [
+    "app:role:manage",
+    "app:page-permission-group:manage",
+    "app:form-permission-group:manage",
+    "app:organization:manage"
+  ]
+}
+```
+
+Platform behavior to design against:
+
+- `app:role:manage` is required to create/update/delete app roles, assign app
+  roles to users, and assign app-scoped API permissions to roles.
+- `app:page-permission-group:manage` is required to create/update/delete page
+  permission groups.
+- `app:form-permission-group:manage` is required to create/update/delete form
+  permission groups.
+- `app:organization:manage` is required for platform account/department writes.
+- Platform roles still require platform-admin authority; delegated app admins
+  can only manage app-scoped roles and app-scoped API permissions.
+
+When a platform administrator first grants a role such as `campus_admin`, that
+role must include the API permissions needed for its future work. If
+`campus_admin` later creates another role that also manages accounts, roles, or
+permission groups, the new role must also be published with its own
+`apiPermissionCodes`. Do not rely on inherited privilege from the creator.
+
+`apiPermissionMode` defaults to `merge`. Use `replace` only when you explicitly
+want the manifest to become the full API permission list for the role.
+`openxiangda resource publish` fails if a declared permission code is missing
+from the platform seed data, which is preferable to silently creating an
+administrator role that cannot administer.
+
+## Design Matrix
+
+Before implementation, write a matrix with at least these columns:
+
+| Area | Decision |
+| ---- | -------- |
+| Permission mode | `managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context` |
+| Account source | app-created platform account / existing platform user / static member / public context |
+| 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 |
+| 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 |
+| Query parameters | context only, ticket validation, tamper-deny test |
+| Publish order | forms -> resources -> functions/runtime |
+
+## Anti-Patterns
+
+- Query parameters as sensitive authorization.
+- Frontend-only button hiding or route hiding.
+- Hardcoded role strings scattered through pages.
+- Delegated administrators without `app:role:manage` or required permission
+  group management API permissions.
+- New roles created by delegated administrators without their own
+  `apiPermissionCodes` when they are expected to administer accounts or roles.
+- 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.
+- Direct platform account API calls that bypass OpenXiangda organization SDK.
+- Reusing public visitor roles as internal admin roles.
+
+## Acceptance
+
+- `openxiangda design gates --topic permissions --json` was run and its open
+  questions are answered.
+- Permission mode and matrix are recorded in SDD/design docs.
+- Admin roles that can manage roles, members, permission groups, or accounts
+  declare `apiPermissionCodes`.
+- `openxiangda permission audit --json` has no high-risk gaps.
+- 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`,
+  `ctx.operator.currentRoleCode`, business scope, or explicit public ticket.
+- Managed account flows verify `app:organization:manage` before account or
+  department writes.

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

@@ -2,6 +2,41 @@
 
 OpenXiangda permission APIs use ordinary user Bearer tokens. The effective permissions are the same as the current frontend user.
 
+Before implementing account, role, RBAC, organization-account, data-scope, or
+query-parameter authorization requirements, run:
+
+```bash
+openxiangda design gates --topic permissions --json
+```
+
+Then choose one permission mode from
+`references/permission-design-patterns.md`:
+
+- `managed-platform-account`: the app creates/maintains platform accounts,
+  departments, and role members.
+- `existing-platform-user-assignment`: the app selects existing platform users
+  and assigns app roles/business scopes.
+- `static-role-permission`: fixed roles and permission groups, no account
+  governance screens.
+- `query-param-context`: query parameters are context, filters, or ticket input
+  only; they are not sensitive authorization.
+
+Frontend hiding, `PermissionBoundary`, route guards, and query parameters are
+display or context tools. Sensitive data access must be enforced by platform
+roles, page permission groups, form permission groups, public-access grants, or
+backend App Function role/scope checks.
+
+Role management is permission controlled too. A role such as "校区管理员" that
+will create app roles, assign role members, or grant role permissions must be
+published with API permissions on the role resource. Use `apiPermissionCodes`
+in `src/resources/roles/<code>.json`; otherwise the user may have the business
+role but still fail when calling role-setting APIs.
+
+For app-managed platform accounts or departments, use `sdk.organization.*` or
+`ctx.organization.*`. The real current operator must have
+`app:organization:manage`; do not bypass OpenXiangda with legacy user or
+department write APIs.
+
 ## Role Codes
 
 Use stable local role codes:
@@ -16,6 +51,29 @@ Use stable local role codes:
 
 Role IDs are platform-specific. Store them only in `.openxiangda/state.json` under the active profile.
 
+For delegated role administrators, include API permission codes on the role:
+
+```json
+{
+  "code": "campus_admin",
+  "name": "校区管理员",
+  "description": "维护本校区账号、角色和权限",
+  "apiPermissionMode": "merge",
+  "apiPermissionCodes": [
+    "app:role:manage",
+    "app:page-permission-group:manage",
+    "app:form-permission-group:manage",
+    "app:organization:manage"
+  ]
+}
+```
+
+`app:role:manage` covers app role creation, role member assignment, and assigning
+app-scoped API permissions to roles. Page/form permission group maintenance use
+their own permission codes. If a delegated administrator creates another role
+that should also administer accounts or roles, that new role also needs its own
+`apiPermissionCodes`; permissions are not inherited from the creator.
+
 ## Page Permission Groups
 
 Page permission groups map role codes to visible menu targets. Form menus use their `FORM_...`

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

@@ -656,13 +656,44 @@ export default async function (ctx) {
 
 ## 8. Role — `src/resources/roles/<code>.json`
 
+Before creating roles or permission groups for account/role/data-scope work,
+run `openxiangda design gates --topic permissions --json` and choose a
+permission mode: `managed-platform-account`,
+`existing-platform-user-assignment`, `static-role-permission`, or
+`query-param-context`. Query parameters and `PermissionBoundary` are never
+sensitive authorization by themselves.
+
 ```json
 {
   "code": "sales",
-  "name": "销售"
+  "name": "销售",
+  "description": "销售人员"
 }
 ```
 
+Delegated admin roles that manage roles, role members, permission groups, or
+organization accounts must also declare API permissions:
+
+```json
+{
+  "code": "campus_admin",
+  "name": "校区管理员",
+  "description": "维护本校区账号、角色和权限",
+  "apiPermissionMode": "merge",
+  "apiPermissionCodes": [
+    "app:role:manage",
+    "app:page-permission-group:manage",
+    "app:form-permission-group:manage",
+    "app:organization:manage"
+  ]
+}
+```
+
+`apiPermissionMode` is `merge` by default. Use `replace` only when the manifest
+should become the full API permission list for that role. Platform role setup
+requires platform-admin authority; app roles can only receive app-scoped API
+permission codes.
+
 ## 9. Page Permission Group — `src/resources/permissions/page-groups/<code>.json`
 
 ```json

package/openxiangda-skills/skills/openxiangda-architecture-design/SKILL.md

@@ -21,6 +21,7 @@ Read these supporting references when the design touches the topic:
 - `references/architecture-patterns.md`
 - `references/data-views.md`
 - `references/permissions-settings.md`
+- `references/permission-design-patterns.md`
 - `references/workflow-v3.md`
 - `references/automation-v3.md`
 - `references/notifications.md`
@@ -66,6 +67,8 @@ Once the user confirms, hand execution to the relevant implementation skill and
 - Do not default to `searchKeyWord` for broad fuzzy search. Prefer explicit searchable fields and structured `filterGroup` conditions.
 - Do not use workflow forms for ordinary business lifecycles. Use normal forms, status fields, state machines, responsibility fields, action logs, permissions, and automations. Use workflow only for real approval semantics.
 - Do not put sensitive authorization in page conditions only. Use page permission groups, form permission groups, backend data scope, and field access policy when data is sensitive.
+- Do not design account/role/permission requirements without choosing a permission mode first: `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`.
+- Do not treat query parameters as sensitive authorization. They may provide context, filters, or ticket input only; sensitive reads/writes still need public-access grants, roles, form permission groups, or App Function checks.
 - Do not put repeated multi-form joins or fixed dashboard metrics into page-side loops. Use Data View when the query is reusable and read-only; choose `live` or `materialized` deliberately.
 - Do not scatter reusable backend logic in pages or JS_CODE nodes. Use App Functions for logic shared by pages, automations, and workflows. Use JS_CODE V2 for node-local backend trigger logic.
 - Do not design raw native form controls for AI-authored workspace code. Use OpenXiangda platform form components first, then Ant Design / antd-mobile wrappers.
@@ -103,6 +106,9 @@ Resolve these before finalizing:
 
 - Data volume, pagination, searchable fields, sort fields, and expected indexes.
 - Role model, data sensitivity, backend-enforced data scope, and field visibility.
+- Account source, role membership source, permission design mode, and whether platform accounts/departments are created by the app.
+- Which roles can manage roles, assign role members, grant role API permissions, maintain permission groups, or manage organization accounts; list the required `apiPermissionCodes`.
+- Permission matrix for pages/routes, form submit/view/manage, data scope, field access policy, backend App Function checks, and query parameter tamper-deny tests.
 - Which flows are status machines and which are real approvals.
 - Report freshness: real-time live view, materialized refresh cadence, or manual snapshot.
 - Whether dashboards and joins are bounded enough for Data View.
@@ -118,6 +124,8 @@ The final design must be decision-complete. Include:
 - Architecture overview and OpenXiangda resource map.
 - Form and field design with storage shape, hidden scope keys, searchable fields, and pagination strategy.
 - Permission design with page groups, form groups, data scope, and field access policy.
+- Permission mode decision with account source, role assignment source, business scope fields, hidden scalar keys, query-parameter boundary, and backend role/scope checks.
+- Delegated role-setting design: which administrator role is first granted by a platform/app admin, which `apiPermissionCodes` it receives, and whether roles it creates can further delegate management.
 - Page/menu/UX design, including PC/mobile and design mockup decisions.
 - Data access and Data View plan with `live` / `materialized`, refresh, indexes, and runtime SDK calls.
 - Status machine, workflow, automation, JS_CODE V2, and App Function plan.

package/openxiangda-skills/skills/openxiangda-permission-settings/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openxiangda-permission-settings
-description: Manage OpenXiangda app **roles** (角色), **page permission groups** (页面权限组 / 菜单可见), **form permission groups** (表单权限组 / 提交 / 查看 / 字段权限 / 数据范围 / 数据隔离), and **form settings** (表单设置 / 索引 / 数据管理页 / 公开访问 / public access / 分享) with profile-isolated IDs and ordinary user token permissions. Trigger on 角色 / role / 权限 / permission / 数据范围 / data scope / 字段权限 / field permission / 菜单可见 / menu visibility / 公开访问 / public access / 分享 / share, or any work touching `permission ...` / `settings ...` CLI commands or `src/resources/{roles,pagePermissionGroups,formPermissionGroups,formSettings}/`.
+description: Manage OpenXiangda app **roles** (角色), **page permission groups** (页面权限组 / 菜单可见), **form permission groups** (表单权限组 / 提交 / 查看 / 字段权限 / 数据范围 / 数据隔离), account/role governance patterns, query-parameter authorization boundaries, and **form settings** (表单设置 / 索引 / 数据管理页 / 公开访问 / public access / 分享) with profile-isolated IDs and ordinary user token permissions. Trigger on 角色 / role / 权限 / permission / RBAC / 账号权限 / account permission / 组织账号 / organization account / 平台账号 / 数据范围 / data scope / 字段权限 / field permission / 菜单可见 / menu visibility / 公开访问 / public access / 分享 / share, or any work touching `permission ...` / `settings ...` CLI commands or `src/resources/{roles,pagePermissionGroups,formPermissionGroups,formSettings}/`.
 ---
 
 # OpenXiangda Permission And Settings
@@ -12,14 +12,25 @@ description: Manage OpenXiangda app **roles** (角色), **page permission groups
 - User wants to **gate form submit / view / edit / data scope / field permissions** (form permission groups).
 - User wants to **publish a form publicly** or change form runtime settings, indexes, data-management page config.
 - User asks about **dynamic role governance** (role maintenance form synced to platform via automation).
+- User asks about **platform accounts, organization accounts, account-role assignment, RBAC, or query-parameter access**.
 
 ## DO / DO NOT
 
+- ✅ Before account/role/permission design, run `openxiangda design gates --topic permissions --json` and choose one mode: `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`.
+- ✅ Write a permission matrix before implementation: account source, role member source, page groups, form groups, data scope, field access policy, backend checks, query parameter boundary, and publish order.
 - ✅ Use logical role / group codes locally; live IDs go under the active profile in `.openxiangda/state.json`.
 - ✅ For dynamic multi-role apps, build a role maintenance form + automation/JS_CODE sync, not hardcoded role logic in page code.
 - ✅ For permission scope keys, derive hidden scalars (`collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, `roleCode`) via `valueSync` from visible select/person/department fields.
 - ✅ Use page permission groups for entry visibility, form permission groups for real data isolation with condition-based data permissions.
+- ✅ For app-managed platform accounts/departments, use `sdk.organization.*` / `ctx.organization.*` and require the current operator to have `app:organization:manage`.
+- ✅ For delegated administrators such as 校区管理员, put role-setting API permissions in the role manifest with `apiPermissionCodes`; use `app:role:manage` for app role creation/member assignment/API-permission assignment, and add page/form/organization management permission codes only when needed.
+- ✅ If a delegated administrator creates another role that can also manage accounts, roles, or permission groups, publish that new role with its own `apiPermissionCodes`.
 - ❌ Expose raw ID text fields to users for permission scopes.
+- ❌ Treat query parameters as sensitive authorization. They may carry context, filters, or ticket input only.
+- ❌ Treat `PermissionBoundary`, button hiding, route hiding, or frontend role checks as the authority for sensitive data.
+- ❌ Hardcode role strings in pages without backing roles/page groups/form groups or App Function checks.
+- ❌ Give a user a business admin role but forget to bind `app:role:manage`, then expect role creation or role-member assignment to work.
+- ❌ Bypass OpenXiangda SDK and call platform account/organization write APIs directly.
 - ❌ Store platform-specific public-access IDs locally; CLI resolves by `appType + formUuid` per profile.
 - ❌ Reuse role / permission-group IDs across profiles.
 - ❌ Use AK/SK or legacy `/dingtalk-api/v1.0` — the logged-in user must have the matching app permission.
@@ -36,6 +47,24 @@ openxiangda workspace bind --profile dev --app-type APP_XXX
 
 The logged-in user must have the matching app permission. Do not use AK/SK or legacy `/dingtalk-api/v1.0`.
 
+For design work, also run:
+
+```bash
+openxiangda design gates --topic permissions --json
+```
+
+Resolve the permission mode before writing resources:
+
+- `managed-platform-account`: the app creates/maintains platform accounts,
+  departments, and role members.
+- `existing-platform-user-assignment`: the app selects existing platform users
+  and assigns app roles/business scopes.
+- `static-role-permission`: fixed app roles and permission groups, no in-app
+  account governance.
+- `query-param-context`: query parameters are only context, filters, or ticket
+  input; sensitive authorization still comes from roles, grants, form groups,
+  or App Function checks.
+
 ## Roles
 
 Create app roles first:
@@ -53,6 +82,13 @@ openxiangda permission role-bind sales --role-id <id> --profile dev
 
 For dynamic multi-role apps, do not hardcode role behavior only in page code. Create a role maintenance form and sync it to platform roles with automation / JS_CODE. Visible scope fields should be maintainable controls: personnel/department fields for people and orgs, `SelectField` / `RadioField` for enums, and `SelectField` with `optionSource.type: "linkedForm"` for records maintained by other forms. When the source form can have many records, set `remoteSearch: true` and `searchFieldId` so typing in the dropdown triggers an SDK query instead of loading every record. If form permission groups need scalar matching, derive hidden keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, and `roleCode`; do not expose raw ID text fields to users. Use page permission groups for entry visibility and form permission groups with condition-based data permissions for real data isolation.
 
+For managed platform account governance, use organization/account forms and sync
+functions as a closed loop: organization units, system accounts, role
+assignments, roles resources, page groups, form groups, sync App Functions, and
+backend role/scope checks. Platform account writes must go through
+`sdk.organization` or `ctx.organization`; the current operator must have
+`app:organization:manage`.
+
 ## Page Permission Groups
 
 Page permission groups control menu/page visibility:
@@ -153,6 +189,7 @@ Do not store platform-specific public access IDs locally. The CLI resolves by `a
 ## References
 
 - Permission model and examples: `references/permissions-settings.md`
+- Account/role design modes: `references/permission-design-patterns.md`
 - Dynamic role governance and data-isolation pattern: `references/best-practices.md`
 - Profile-isolated IDs: `references/workspace-state.md`
 - API fields: `references/openxiangda-api.md`

package/package.json

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

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda.mdc

@@ -22,13 +22,19 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 - Writes and deploys must pass `--profile <name>` explicitly.
 - Architecture-class work is plan-gated: run `openxiangda design gates --topic <code> --json` and wait for confirmation.
 - High-risk changes must start with `openxiangda sdd context --json`, use an approved change, and run `openxiangda sdd verify <change> --changed` before release.
+- Account/role/permission/RBAC/organization-account/query-param authorization work must run `openxiangda design gates --topic permissions --json`, choose `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`, and write the permission matrix.
+- Roles that create roles, assign members, grant API permissions, maintain permission groups, or manage organization accounts must declare `apiPermissionCodes`, such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`.
 - `src/resources/**` is the resource source of truth; use `validate -> plan -> publish`.
 - React routes live in `src/app/router.tsx`; frontend artifacts are deployed with `openxiangda runtime deploy`.
-- Backend permissions and public-access grants are authoritative.
+- Backend permissions, public-access grants, and App Function role/scope checks are authoritative.
+- Query parameters are context, filters, or ticket input only; they are not sensitive authorization.
 
 ## Never
 
 - Do not run `lowcode-workspace publish-all`, `pnpm publish:all`, or `pnpm openxiangda:publish` directly.
 - Do not deploy without `--profile`.
 - Do not use legacy `?publicAccess=guest`, `isRenderNav`, or workbench page parameters for new React SPA routes.
+- Do not rely on frontend-only button hiding, query-param checks, hardcoded roles, mock permissions, fake account IDs, or `PermissionBoundary` alone for real authorization.
+- Do not assign a business admin role without the role-setting API permissions needed for role/member management.
+- Do not bypass `sdk.organization` / `ctx.organization` for platform account/department writes.
 - Do not commit tokens, AK/SK, or third-party secrets.

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda.md

@@ -22,13 +22,19 @@ This is an OpenXiangda React SPA workspace. Read [AGENTS.md](AGENTS.md) for full
 - 发布和写平台资源必须显式传 `--profile <name>`。
 - 架构类需求先跑 `openxiangda design gates --topic <code> --json` 并等用户确认。
 - 高风险变更先跑 `openxiangda sdd context --json`，创建/继续 change，并在用户确认后 `openxiangda sdd approve <change>`；发布前 `openxiangda sdd verify <change> --changed`。
+- 账号/角色/权限/RBAC/组织账号/查询参数授权需求先跑 `openxiangda design gates --topic permissions --json`，选择 `managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context` 并输出权限矩阵。
+- 角色能新增角色、分配成员、授接口权限、维护权限组或管理组织账号时，角色资源必须声明 `apiPermissionCodes`，例如 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`。
 - `src/resources/**` 是工程化资源来源，正式多资源变更走 `validate -> plan -> publish`。
 - React SPA 路由由 `src/app/router.tsx` 管理，前端包通过 `openxiangda runtime deploy` 发布。
-- 页面权限、表单权限、公开访问 grants 以后端资源为准；前端只做展示保护。
+- 页面权限、表单权限、公开访问 grants、App Function 后端检查是授权依据；前端只做展示保护。
+- 查询参数只能做上下文、筛选或 ticket 输入，不能作为敏感数据授权依据。
 
 ## Never
 
 - 不要直接运行 `lowcode-workspace publish-all`、`pnpm publish:all` 或 `pnpm openxiangda:publish`。
 - 不要省略 `--profile` 发布。
 - 不要使用旧 `?publicAccess=guest`、`isRenderNav` 或 workbench 参数模型开发新 React SPA。
+- 不要只隐藏按钮、只判断 query 参数、硬编码角色、前端模拟权限、假账号/假 ID、或用 `PermissionBoundary` 代替真实授权。
+- 不要给用户挂“管理员”业务角色但不给该角色绑定 `app:role:manage` 等角色设置接口权限。
+- 不要绕过 `sdk.organization` / `ctx.organization` 直接写平台账号/部门。
 - 不要把 token、AK、SK、第三方密钥写入项目文件。

package/templates/openxiangda-react-spa/AGENTS.md

@@ -6,12 +6,17 @@
 
 - 架构类需求默认只规划、不实现。新应用、复杂页面、登录注册、公开访问、权限数据范围、流程自动化、连接器/通知等需求，先运行 `openxiangda doctor --json` 和 `openxiangda design gates --topic <code> --json`，输出设计并等用户确认；确认前只允许读取、快照、dry-run、提问和写设计文档，不允许改源码、写平台、发布或发送通知。
 - 高风险变更必须挂到 SDD change。修改 `src/forms/**`、`src/pages/**`、`src/resources/**`、`src/functions/**`、`src/automations/**`、`src/workflows/**`、`src/js-code-nodes/**`、`src/runtime/**` 或 `app-workspace.config.ts` 前，先运行 `openxiangda sdd context --json`，没有合适 change 就 `openxiangda sdd propose <change>`，等用户确认后运行 `openxiangda sdd approve <change>` 再实现。发布前运行 `openxiangda sdd verify <change> --changed`、`openxiangda workspace check --changed`、`openxiangda resource plan --profile <name>`。
+- 账号、角色、权限、数据范围、组织账号、RBAC、查询参数授权需求必须先运行 `openxiangda design gates --topic permissions --json`，选择 `managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context`，输出权限矩阵后再实现。
+- 应用角色如果要创建角色、分配角色成员、给角色授接口权限、维护页面/表单权限组或管理组织账号，必须在角色资源声明 `apiPermissionCodes`，例如 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`。
 - 默认用户界面保持克制：左侧应用导航、顶部账号信息、首页内容区域。
 - 不在默认可见页面展示 SDK、Runtime、Cookie、Proxy、Playwright、AI 验证、调试上下文、构建号等开发语言。
 - 使用 React Router 管理路由，路由定义在 `src/app/router.tsx`。
 - 使用 Tailwind CSS 表达样式，不依赖平台 theme tokens。
 - 菜单和首页文案优先改 `src/app/navigation.ts`、`src/app/starter-content.ts` 与 `src/pages/admin/AdminDashboardPage.tsx`。
 - 页面、表单、字段、数据范围、流程动作、文件、连接器权限以后端接口为准；前端只做展示保护和清晰状态页。
+- 查询参数只能作为上下文、筛选或 ticket 输入，不能作为敏感数据授权依据；敏感读写必须由 public-access grants、平台角色、页面/表单权限组或 App Function 后端校验保护。
+- 应用管理平台账号/部门时，必须走 `sdk.organization` / `ctx.organization`，并要求当前操作者具备 `app:organization:manage`。
+- 只给用户分配“管理员”业务角色不等于授权其设置角色；缺少 `app:role:manage` 时角色创建、成员分配和角色接口权限授予会被后端拒绝。
 - 本地开发通过 Vite `/service` 代理远端平台，保持 HttpOnly Cookie 同域访问。
 - 新公开访问页使用 `/view/:appType/public/*`、`src/resources/routes/`、`src/resources/public-access/` 和 `PublicAccessGate`。不要使用旧 `?publicAccess=guest`。
 
@@ -78,7 +83,7 @@ React SPA 页面需要声明菜单 code、route code 和 path pattern。默认
 import { PermissionBoundary, useAppMenus, useRuntimeBootstrap } from "openxiangda/runtime/react";
 ```
 
-`PermissionBoundary` 只能做展示保护，不能替代后端权限。后端返回 401 时跳登录，403 时展示无权限状态。
+`PermissionBoundary` 只能做展示保护，不能替代后端权限。不要硬编码角色、前端模拟权限、只判断 query 参数或用空数组兜底伪装成功。后端返回 401 时跳登录，403 时展示无权限状态。
 
 公开页面需要同时声明 route 和 public access policy：
 

package/templates/sy-lowcode-app-workspace/.cursor/rules/openxiangda-resources.mdc

@@ -25,4 +25,8 @@ See `references/resource-manifest-cheatsheet.md` for copy-paste skeletons.
 
 Commands: `openxiangda resource validate|plan|publish|pull --profile <name>`.
 
-Forbidden: 把 `formUuid` / `pageId` / `workflowId` 等平台 ID 写进 manifest；把 API key / token / secret / authorization 写进 manifest；data view 用作单表 CRUD / linkedForm / 写回 / 强实时；page 源里 hardcode 通知或 connector URL。
+Before editing `roles`, `permissions/page-groups`, or `permissions/form-groups` for account/role/data-scope/RBAC/query-param authorization work, run `openxiangda design gates --topic permissions --json`, choose the permission mode, and write the permission matrix.
+
+If a `roles/<code>.json` role can create roles, assign members, grant API permissions, maintain permission groups, or manage organization accounts, it must declare `apiPermissionCodes`; a business role name alone does not grant backend API permission.
+
+Forbidden: 把 `formUuid` / `pageId` / `workflowId` 等平台 ID 写进 manifest；把 API key / token / secret / authorization 写进 manifest；data view 用作单表 CRUD / linkedForm / 写回 / 强实时；只靠 query 参数、前端隐藏按钮、硬编码角色、mock 权限或 `PermissionBoundary` 作为敏感授权；管理型角色缺少 `app:role:manage` / `app:page-permission-group:manage` / `app:form-permission-group:manage` / `app:organization:manage`；page 源里 hardcode 通知或 connector URL。

package/templates/sy-lowcode-app-workspace/.cursor/rules/openxiangda.mdc

@@ -18,7 +18,7 @@ This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. See [AGEN
 | edit code page / portal / dashboard / 代码页 | `openxiangda-page` | edit `src/pages/<code>/` → `workspace publish --page <code>` |
 | approval workflow / 审批流程 / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow ...` |
 | automation / cron / 自动化 / 定时 | `openxiangda-workflow-automation` | `openxiangda automation ...` |
-| role / permission / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| account / role / permission / data scope / query-param authorization | `openxiangda-permission-settings` | run `openxiangda design gates --topic permissions --json` first, then `openxiangda permission ...` / `openxiangda settings ...` |
 | diagnose / snapshot / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot APP_XXX --profile <name> --json` |
 | login / token / switch profile | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
 
@@ -26,6 +26,8 @@ This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. See [AGEN
 
 - For routine edits, default to incremental publish: `workspace publish --profile <name> --changed --dry-run` then `--changed` or targeted `--page <code>` / `--form <code>`.
 - High-risk changes must use SDD first: `openxiangda sdd context --json` -> `openxiangda sdd propose <change>` -> user confirmation -> `openxiangda sdd approve <change>`; before release run `openxiangda sdd verify <change> --changed`.
+- Account/role/permission/RBAC/organization-account/query-param authorization work must choose a mode first: `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`, then write the permission matrix.
+- Roles that create roles, assign members, grant API permissions, maintain permission groups, or manage organization accounts must declare `apiPermissionCodes` in `src/resources/roles/<code>.json`, such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`.
 - Confirm current profile before any write: `openxiangda env --profile <name>`.
 - `.openxiangda/state.json` is the authoritative profile → appType → resource-ID map; CLI maintains it, do not hand-edit.
 - User tokens live in `~/.openxiangda/profiles.json`; shared env in `~/.openxiangda/.env`.
@@ -41,6 +43,9 @@ This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. See [AGEN
 - ❌ Search the platform for similar app names when `.openxiangda/state.json` has no binding.
 - ❌ Copy `formUuid` / `pageId` / `workflowId` / `automationId` across profiles.
 - ❌ Run a full publish for a single-file edit.
+- ❌ Frontend-only button hiding, query-param checks, hardcoded roles, mock permissions, fake account IDs, or `PermissionBoundary` alone as real authorization.
+- ❌ Business admin roles without `app:role:manage` or required role-setting API permissions when they are expected to manage roles or members.
+- ❌ Direct platform account/department writes that bypass `sdk.organization` / `ctx.organization`.
 - ❌ Use `openxiangda form create` / `form publish` / `page publish` as the normal page generation path.
 - ❌ Store tokens / AK / SK / third-party secrets in project files.
 - ❌ `npm publish` — this workspace is `"private": true`, not an npm package.

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda-resources.md

@@ -12,6 +12,10 @@ You are editing engineering-managed resource manifests under `src/resources/`. *
 
 `references/resource-manifest-cheatsheet.md`（installed at `~/.qoder/skills/openxiangda/references/resource-manifest-cheatsheet.md`）— connector / data-view / notification / workflow / automation / JS_CODE / role / page-group / form-group / settings / menu 骨架。
 
+编辑 `roles`、`permissions/page-groups`、`permissions/form-groups` 前，如果需求涉及账号、角色、数据范围、组织账号、RBAC 或查询参数授权，先运行 `openxiangda design gates --topic permissions --json`，选择权限模式并输出权限矩阵。
+
+如果 `roles/<code>.json` 代表的角色需要新增角色、分配成员、授接口权限、维护权限组或管理组织账号，必须声明 `apiPermissionCodes`；只写业务角色名不会获得这些后端接口权限。
+
 ## 文件夹与对应 skill
 
 | 路径 | 用途 | 主导 skill |
@@ -42,5 +46,7 @@ openxiangda resource pull     --profile <name>          # 平台 → 本地
 - ❌ 把 `formUuid` / `pageId` / `workflowId` 等平台 ID 直接写进 manifest（CLI 解析逻辑 code）。
 - ❌ 把 API key / token / secret / password / authorization / headers / credential 写进 manifest（平台后台配置）。
 - ❌ data view 用作单表 CRUD、`linkedForm` 下拉、写回、强实时数据源。
+- ❌ 只靠 query 参数、前端隐藏按钮、硬编码角色、mock 权限或 `PermissionBoundary` 作为敏感授权。
+- ❌ 管理型角色缺少 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage` 或 `app:organization:manage`。
 - ❌ 在 page 源里 hardcode `/api/notification-config/*` 或 `/connectors/actions/invoke`（用 `sdk.notification` / `sdk.connector`）。
 - ❌ 同时在 manifest 与平台后台编辑同一个资源（漂移源）。

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda.md

@@ -18,7 +18,7 @@ This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. Read [AGE
 | 改代码页 / portal / dashboard | `openxiangda-page` | 编辑 `src/pages/<code>/` → `workspace publish --page <code>` |
 | 审批流程 / workflow / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow ...` |
 | 自动化 / 定时 / 提交触发 | `openxiangda-workflow-automation` | `openxiangda automation ...` |
-| 角色 / 权限 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 账号 / 角色 / 权限 / 数据范围 / 查询参数授权 | `openxiangda-permission-settings` | 先 `openxiangda design gates --topic permissions --json`，再 `openxiangda permission ...` / `openxiangda settings ...` |
 | 排查 / 快照 / 对比 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot APP_XXX --profile <name> --json` |
 | 登录 / token / 切平台 | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
 
@@ -26,6 +26,8 @@ This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. Read [AGE
 
 - 单文件改动默认增量发布：先 `workspace publish --profile <name> --changed --dry-run`，再 `--changed` 或 `--page <code>` / `--form <code>`。
 - 高风险变更先走 SDD：`openxiangda sdd context --json` → `openxiangda sdd propose <change>` → 用户确认 → `openxiangda sdd approve <change>`；发布前 `openxiangda sdd verify <change> --changed`。
+- 账号/角色/权限/RBAC/组织账号/查询参数授权需求先选权限模式：`managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context`，并输出权限矩阵。
+- 角色能新增角色、分配成员、授接口权限、维护权限组或管理组织账号时，`src/resources/roles/<code>.json` 必须声明 `apiPermissionCodes`，例如 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`。
 - 任何写操作前确认当前 profile：`openxiangda env --profile <name>`。
 - `.openxiangda/state.json` 是 profile 到 appType / 资源 ID 的权威映射，由 CLI 维护，不要手改。
 - 用户 token 在 `~/.openxiangda/profiles.json`；共享 env 在 `~/.openxiangda/.env`。
@@ -41,6 +43,9 @@ This is a `sy-lowcode-app-workspace` managed by the `openxiangda` CLI. Read [AGE
 - ❌ 在没有本地 `.openxiangda/state.json` 绑定时，去平台搜索同名应用"复用"。
 - ❌ 把 `formUuid` / `pageId` / `workflowId` / `automationId` 从 dev 复制到 prod。
 - ❌ 改一处就全量发布。
+- ❌ 只隐藏按钮、只判断 query 参数、硬编码角色、前端模拟权限、假账号/假 ID、或用 `PermissionBoundary` 代替真实授权。
+- ❌ 给用户挂“管理员”业务角色但不给该角色绑定 `app:role:manage` 等角色设置接口权限。
+- ❌ 绕过 `sdk.organization` / `ctx.organization` 直接写平台账号/部门。
 - ❌ `openxiangda form create` / `form publish` / `page publish` 当作页面生成方式（仅底层修复）。
 - ❌ 把 token / AK / SK / 第三方密钥写进项目文件。
 - ❌ `npm publish` — 本工作区 `"private": true`，不发 npm 包。

package/templates/sy-lowcode-app-workspace/AGENTS.md

@@ -25,7 +25,7 @@
 | 创建 / 改自定义代码页、portal、看板 | `openxiangda-page` | 编辑 `src/pages/<code>/` → `workspace publish --page <code>` |
 | 审批流程 / 流程节点 / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow validate / create / publish` |
 | 自动化 / 定时任务 / 提交触发 / cron | `openxiangda-workflow-automation` | `openxiangda automation validate / create / publish / enable` |
-| 角色 / 权限组 / 字段权限 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 账号 / 角色 / 权限组 / 字段权限 / 数据范围 / 查询参数授权 | `openxiangda-permission-settings` | 先 `openxiangda design gates --topic permissions --json`，再 `openxiangda permission ...` / `openxiangda settings ...` |
 | 查应用结构 / 快照 / 对比 / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot <APP_XXX> --profile <name> --json` |
 | 登录 / 切平台 / token / whoami | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
 | 多表只读联表查询 / 报表数据源 | `openxiangda-form`（data view） | 在 `src/resources/data-views/<code>.json` 声明 → `resource publish` |
@@ -37,6 +37,8 @@
 - ✅ 先 preflight：`openxiangda env --profile <name>` + `openxiangda auth status --profile <name>` + `openxiangda update check --json`。
 - ✅ 架构类需求先 plan gate：`openxiangda doctor --profile <name> --json` + `openxiangda design gates --topic <code> --json`，用户确认后再实现。
 - ✅ 高风险变更先 SDD gate：`openxiangda sdd context --json` → `openxiangda sdd propose <change>` → 用户确认 → `openxiangda sdd approve <change>`。
+- ✅ 涉及账号、角色、权限、数据范围、组织账号、RBAC、查询参数授权时，先跑 `openxiangda design gates --topic permissions --json`，选择 `managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context`，并输出权限矩阵后再改资源。
+- ✅ 某个应用角色如果要创建角色、分配角色成员、给角色授接口权限、维护页面/表单权限组或管理组织账号，必须在 `src/resources/roles/<code>.json` 声明 `apiPermissionCodes`，例如 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`。
 - ✅ 单文件改动默认增量发布：`workspace publish --profile <name> --changed --dry-run` → `--changed` / `--page` / `--form`。
 - ✅ 用户 token 在 `~/.openxiangda/profiles.json`；项目 state 在 `.openxiangda/state.json`（只存 ID）。
 - ✅ 共享环境（`APP_OSS_*`、反馈机器人等）在 `~/.openxiangda/.env`，项目 `.env` 仅做 per-workspace override。
@@ -54,6 +56,9 @@
 - ❌ 把 `openxiangda form create` / `form publish` / `page publish` 当作日常页面生成方式。它们仅作底层修复 / 诊断。
 - ❌ 改一个文件就 `workspace publish` 全量。
 - ❌ 用户确认架构设计前就实现、写平台资源、发布、部署或发送通知。
+- ❌ 只隐藏按钮、只判断 query 参数、硬编码角色、前端模拟权限、假账号/假 ID、或用 `PermissionBoundary` 代替真实授权。敏感数据必须由角色、页面/表单权限组、public-access grants 或 App Function 后端校验保护。
+- ❌ 只给用户分配“管理员”业务角色，却不给该角色绑定 `app:role:manage` 等角色设置接口权限，然后期望他能新增账号、角色或权限组。
+- ❌ 直接绕过 SDK 调平台账号/组织写接口；应用管理平台账号/部门必须使用 `sdk.organization` / `ctx.organization`，且当前操作者具备 `app:organization:manage`。
 - ❌ 把 token、AK、SK、第三方密钥写进项目文件。
 - ❌ `npm publish` —— 这个工作区是 `"private": true` 的应用工作区，不是要发到 npm 的 package。
 - ❌ 在 AI 生成的 `src/forms/**` / `src/pages/**` 里直接写原生 `<input>` / `<select>` / `<textarea>` / `<input type="file">`、手写 picker、手写 uploader、手写人员/部门选择器。原生控件只允许出现在 OpenXiangda SDK / 平台组件内部。

package/templates/sy-lowcode-app-workspace/examples/best-practices/README.md

@@ -27,6 +27,9 @@ Run `pnpm examples:check` after editing examples, and run the normal
   `shared/components/`.
 - Use state fields and operation logs for business lifecycle flows.
 - Use workflow only for real approval tasks.
+- For account, role, data scope, organization-account, RBAC, or query-param
+  authorization work, run `openxiangda design gates --topic permissions --json`
+  and choose an access governance mode before copying examples.
 - Query with pagination and structured conditions. Avoid large page sizes,
   client-side filtering, and broad `searchKeyWord` queries.
 - For admin UI, choose one optional default from `glass-home-dashboard`,

package/templates/sy-lowcode-app-workspace/examples/best-practices/access-governance.md

@@ -0,0 +1,239 @@
+# Access Governance Pattern
+
+This example is a generic account and permission governance skeleton. Copy only
+the parts required by the selected permission mode. Do not publish this example
+directly without changing codes, names, roles, and data scopes.
+
+Start with:
+
+```bash
+openxiangda design gates --topic permissions --json
+```
+
+Choose one mode:
+
+- `managed-platform-account`: app creates/maintains platform departments,
+  accounts, and role members.
+- `existing-platform-user-assignment`: app assigns existing platform users to
+  app roles and business scopes.
+- `static-role-permission`: fixed roles and permission groups only.
+- `query-param-context`: query parameters are only context, filters, or ticket
+  input; they do not grant sensitive data access.
+
+## Resource Closure
+
+```text
+src/forms/organization_unit/schema.ts
+src/forms/system_account/schema.ts
+src/forms/role_assignment/schema.ts
+src/functions/sync_access_governance/index.ts
+src/resources/roles/access-roles.json
+src/resources/permissions/page-groups/access-admin-pages.json
+src/resources/permissions/form-groups/role_assignment/access-admin.json
+```
+
+## Form Skeletons
+
+`organization_unit` stores business organization units and the platform
+department sync result:
+
+```ts
+export const organizationUnitFields = [
+  { fieldId: "unitName", label: "组织名称", componentName: "TextField", placeholder: "请输入组织名称" },
+  { fieldId: "unitCode", label: "组织编码", componentName: "TextField", placeholder: "请输入稳定组织编码" },
+  { fieldId: "parentUnit", label: "上级组织", componentName: "SelectField", placeholder: "请选择上级组织", options: [] },
+  { fieldId: "manager", label: "负责人", componentName: "UserSelectField", placeholder: "请选择负责人" },
+  { fieldId: "platformDeptId", label: "平台部门ID", componentName: "TextField", behavior: "HIDDEN" },
+  {
+    fieldId: "syncStatus",
+    label: "同步状态",
+    componentName: "SelectField",
+    behavior: "HIDDEN",
+    options: [
+      { label: "待同步", value: "pending" },
+      { label: "已同步", value: "synced" },
+      { label: "同步失败", value: "failed" },
+    ],
+  },
+  { fieldId: "syncMessage", label: "同步说明", componentName: "TextAreaField", behavior: "HIDDEN" },
+  { fieldId: "lastSyncedAt", label: "最后同步时间", componentName: "DateField", behavior: "HIDDEN" },
+];
+```
+
+`system_account` stores the app-owned account record and the platform user sync
+result:
+
+```ts
+export const systemAccountFields = [
+  { fieldId: "displayName", label: "姓名", componentName: "TextField", placeholder: "请输入姓名" },
+  { fieldId: "loginName", label: "登录名", componentName: "TextField", placeholder: "请输入登录名" },
+  { fieldId: "phone", label: "手机号", componentName: "TextField", placeholder: "请输入手机号" },
+  { fieldId: "unitCode", label: "所属组织", componentName: "SelectField", placeholder: "请选择所属组织", options: [] },
+  {
+    fieldId: "enabled",
+    label: "账号状态",
+    componentName: "RadioField",
+    placeholder: "请选择账号状态",
+    options: [
+      { label: "启用", value: "enabled" },
+      { label: "停用", value: "disabled" },
+    ],
+  },
+  { fieldId: "platformUserId", label: "平台用户ID", componentName: "TextField", behavior: "HIDDEN" },
+  { fieldId: "platformDeptId", label: "平台部门ID", componentName: "TextField", behavior: "HIDDEN" },
+  {
+    fieldId: "syncStatus",
+    label: "同步状态",
+    componentName: "SelectField",
+    behavior: "HIDDEN",
+    options: [
+      { label: "待同步", value: "pending" },
+      { label: "已同步", value: "synced" },
+      { label: "同步失败", value: "failed" },
+    ],
+  },
+  { fieldId: "lastSyncedAt", label: "最后同步时间", componentName: "DateField", behavior: "HIDDEN" },
+];
+```
+
+`role_assignment` maps accounts or existing platform users to roles and business
+scope keys:
+
+```ts
+export const roleAssignmentFields = [
+  { fieldId: "account", label: "账号", componentName: "SelectField", placeholder: "请选择账号", options: [] },
+  { fieldId: "platformUser", label: "平台用户", componentName: "UserSelectField", placeholder: "请选择平台用户" },
+  {
+    fieldId: "roleCodes",
+    label: "角色",
+    componentName: "CheckboxField",
+    placeholder: "请选择角色",
+    options: [
+      { label: "权限管理员", value: "access_admin" },
+      { label: "范围内经办人", value: "scope_operator" },
+    ],
+  },
+  { fieldId: "businessUnit", label: "业务组织", componentName: "SelectField", placeholder: "请选择业务组织", options: [] },
+  { fieldId: "businessScopeKey", label: "业务范围键", componentName: "TextField", behavior: "HIDDEN" },
+  {
+    fieldId: "syncStatus",
+    label: "同步状态",
+    componentName: "SelectField",
+    behavior: "HIDDEN",
+    options: [
+      { label: "待同步", value: "pending" },
+      { label: "已同步", value: "synced" },
+      { label: "同步失败", value: "failed" },
+    ],
+  },
+  { fieldId: "syncMessage", label: "同步说明", componentName: "TextAreaField", behavior: "HIDDEN" },
+];
+```
+
+## Sync App Function Skeleton
+
+```ts
+export default async function syncAccessGovernance(ctx, input) {
+  const roleCodes = ctx.operator?.roleCodes || [];
+  if (!roleCodes.includes("access_admin") && !ctx.operator?.hasFullAccess) {
+    throw new Error("ACCESS_DENIED");
+  }
+
+  if (input.action === "syncAccount") {
+    if (!ctx.organization?.accounts) throw new Error("ORGANIZATION_API_UNAVAILABLE");
+    // Current operator must have app:organization:manage.
+    return ctx.organization.accounts.create({
+      name: input.displayName,
+      loginName: input.loginName,
+      phone: input.phone,
+      departmentId: input.platformDeptId,
+    });
+  }
+
+  if (input.action === "syncRoleMembers") {
+    // Read role_assignment records, resolve platformUserId values, and update
+    // app role members through the platform role API exposed by OpenXiangda.
+    return { ok: true };
+  }
+
+  throw new Error("UNKNOWN_ACTION");
+}
+```
+
+## Role Resource
+
+```json
+[
+  {
+    "code": "access_admin",
+    "name": "权限管理员",
+    "description": "维护组织、账号、角色和权限资源",
+    "apiPermissionMode": "merge",
+    "apiPermissionCodes": [
+      "app:role:manage",
+      "app:page-permission-group:manage",
+      "app:form-permission-group:manage",
+      "app:organization:manage"
+    ]
+  },
+  {
+    "code": "scope_operator",
+    "name": "范围内经办人",
+    "description": "只能访问授权业务范围内的数据"
+  }
+]
+```
+
+The initial grant of `access_admin` is normally done by a platform administrator
+or an existing app administrator. If `access_admin` creates another role that
+also manages accounts, roles, or permission groups, publish that new role with
+its own `apiPermissionCodes`; management power is not inherited from the
+creator.
+
+## Page Permission Group
+
+```json
+{
+  "code": "access_admin_pages",
+  "name": "权限管理员页面",
+  "roles": ["access_admin"],
+  "menuCodes": ["access_governance"],
+  "routeCodes": ["access.governance"],
+  "pathPatterns": ["/view/:appType/admin/access/*"]
+}
+```
+
+## Form Permission Group
+
+```json
+{
+  "code": "role_assignment_admin",
+  "formCode": "role_assignment",
+  "name": "角色分配管理员",
+  "type": "view",
+  "roles": ["access_admin"],
+  "operations": ["view", "edit", "delete"],
+  "dataScope": [{ "type": "all" }],
+  "fieldAccessPolicy": {
+    "defaultAccess": "edit",
+    "fields": [
+      { "fieldId": "syncMessage", "access": "readonly" }
+    ]
+  }
+}
+```
+
+For `scope_operator`, use condition data permission against hidden scalar keys,
+for example `businessScopeKey = ${CURRENT_USER_SCOPE}`. Do not fetch all rows
+and filter them in the page.
+
+## Acceptance
+
+- Permission mode and matrix are written in the SDD change or design document.
+- `openxiangda permission audit --json` has no high-risk gaps.
+- Allowed and denied role paths are both tested.
+- Query parameter tampering does not expand sensitive access.
+- Managed account writes are executed only by a user with
+  `app:organization:manage`.
+- Roles that create roles, assign members, or maintain permission groups include
+  `apiPermissionCodes` such as `app:role:manage`.

package/templates/sy-lowcode-app-workspace/examples/best-practices/catalog.json

@@ -53,6 +53,12 @@
       "path": "src/pages/service-ticket-ops",
       "description": "DataManagementList-based ops page with modular actions, drawer, timeline, hook, and service."
     },
+    {
+      "code": "access-governance",
+      "type": "permissions",
+      "path": "access-governance.md",
+      "description": "Generic account/role permission mode decision with organization, account, role assignment, sync function, role resource, page group, and form group skeletons."
+    },
     {
       "code": "role-governance",
       "type": "permissions",

package/templates/sy-lowcode-app-workspace/examples/best-practices/decision-guide.md

@@ -59,6 +59,21 @@ Frontend code must not be responsible for data isolation or background jobs.
 
 ## Permissions
 
+Run `openxiangda design gates --topic permissions --json` before implementing
+account, role, RBAC, organization-account, data-scope, or query-param
+authorization requirements.
+
+Choose one pattern:
+
+- `managed-platform-account`: app creates and maintains platform departments,
+  accounts, and role members. Start from `access-governance.md`.
+- `existing-platform-user-assignment`: app selects existing platform users and
+  assigns roles/business scopes. Use a role assignment form with
+  `UserSelectField`.
+- `static-role-permission`: fixed roles and permission groups only.
+- `query-param-context`: query parameters are context, filters, or ticket input
+  only; they cannot grant sensitive access.
+
 For dynamic multi-role apps, create a business role table and synchronize it to
 platform app roles. User-facing scope fields should be maintainable controls:
 personnel/department fields for people and orgs, enum fields for fixed option
@@ -67,4 +82,13 @@ customers, and other records maintained by forms. Use `remoteSearch: true` when
 the source form can have many records. If the platform permission condition
 needs a scalar value, derive a hidden scope key such as `collegeScopeKey` or
 `ownerDeptScopeKey`. Use form permission groups with condition-style data
-permissions to enforce data isolation.
+permissions and App Function role/scope checks to enforce data isolation.
+
+When an app role is expected to create roles, assign role members, grant role
+API permissions, maintain permission groups, or manage organization accounts,
+declare the matching `apiPermissionCodes` on that role. `app:role:manage` is
+required for app role creation and member assignment; page/form permission group
+maintenance and organization account management use their own permission codes.
+
+Frontend hiding and query parameters are not authorization. They must not be the
+only barrier for sensitive data or write actions.