openxiangda 1.0.134 → 1.0.136

package/lib/workspace-init.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { getProfile, loadConfig, saveProjectState } = require('./config');
+const { initSddWorkspace } = require('./sdd');
 
 const ROOT_DIR = path.join(__dirname, '..');
 const LEGACY_TEMPLATE_DIR = path.join(ROOT_DIR, 'templates', 'sy-lowcode-app-workspace');
@@ -37,6 +38,7 @@ function initWorkspace(options = {}) {
   copyTemplate(templateDir, targetDir, {
     __WORKSPACE_PACKAGE_NAME__: packageName,
   });
+  const sdd = initSddWorkspace({ cwd: targetDir });
 
   let bound = null;
   if (profileName && appType) {
@@ -88,6 +90,7 @@ function initWorkspace(options = {}) {
     templateDir,
     installedDependencies: install,
     bound,
+    sdd,
     nextSteps: buildNextSteps(targetDir, install, bound),
   };
 }

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`                                                                                             |
@@ -40,6 +40,9 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 ### Hard rules — always
 
 - ✅ Publish classic workspaces through `openxiangda workspace publish --profile <name>`; publish React SPA forms first with `openxiangda workspace publish --form <formCode>`, then resources/runtime through `openxiangda resource validate` → `openxiangda resource publish --dry-run` → `openxiangda resource publish` → `openxiangda runtime deploy`.
+- ✅ High-risk changes must be attached to SDD records before implementation/publish. Run `openxiangda sdd context --json`; for forms/pages/resources/functions/automations/workflows/JS_CODE/runtime/config changes create or continue `openxiangda sdd propose <change>`, wait for user confirmation, run `openxiangda sdd approve <change>`, then verify with `openxiangda sdd verify <change> --changed`.
+- ✅ Before publishing AI-authored changes, run `openxiangda workspace plan --changed --json` and `openxiangda workspace check --changed`. Fix reported fake IDs, fallback data, direct `/openxiangda-api` page calls, missing schema, or resource/runtime omissions before publish.
+- ✅ When unsure about runtime response shape, run `openxiangda contract explain <contract-name> --json`. `sdk.form.create` returns identifiers and generated serial number values only; fetch detail explicitly for full row data, formula results, or other server-generated fields.
 - ✅ Architecture-class requests are plan-gated by default. For 新应用、复杂页面、登录注册、公开访问、权限数据范围、流程自动化、连接器/通知、外部集成, first run `openxiangda doctor --json` when a workspace exists and `openxiangda design gates --topic <code> --json`; then ask the user to confirm the design. Before confirmation, only read files, inspect/snapshot, dry-run, ask questions, and write/output design docs. Do not edit source files, write platform resources, send notifications, publish, or deploy.
 - ✅ `runtime deploy` defaults to staged multipart `dist/` uploads plus a final manifest. Use `--upload-mode legacy-json` only for old platform servers.
 - ✅ User token lives in `~/.openxiangda/profiles.json`; project state in `.openxiangda/state.json` (IDs only).
@@ -48,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.
@@ -65,6 +69,8 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ❌ Using `openxiangda form create` / `form publish` / `page publish` as the normal page generation path. They are low-level repair commands.
 - ❌ 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.
@@ -157,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.
@@ -204,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:
 
@@ -222,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/pages/page-sdk.md

@@ -18,6 +18,9 @@ Guidelines:
 - Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
 - Use `sdk.organization.departments.*` and `sdk.organization.accounts.*` only for admin-style app pages that intentionally manage platform departments/accounts. The current user needs `app:organization:manage` on the app. Do not call legacy `/user` or `/department` write endpoints from pages.
 - Use `sdk.workCenter.listItems({ boxType })` and `sdk.workCenter.getStats()` for current-user work center lists and counts. `boxType` is one of `todo`, `done`, `cc`, or `initiated`. This is the end-user task/handled/cc/initiated surface; do not build todo pages by reading workflow operation logs, automation logs, or raw process-task tables.
+- `sdk.form.create` returns identifiers and generated serial number values only. Treat `formInstId` / `formInstanceId` as the required success contract; `serialNumber` / `serialNumbers` are present only when the form has `SerialNumberField`. Do not expect the save response to contain the full row, formula results, or other server-generated field values. Call `sdk.form.getDetail` explicitly after create when those values are needed.
+- Missing `formInstId` / `formInstanceId` is a real error in strict mode. Do not create fake IDs, mock rows, or fallback display data to hide it.
+- `lookupAfterCreate` is legacy compatibility only. New pages should save, read the returned instance ID, then explicitly query detail if needed.
 - Use `createAuthClient` from `openxiangda/runtime` or `LoginPage` / `useAuth` from `openxiangda/runtime/react` for application login pages. Auth provider App Functions return identity assertions only; platform auth owns create/bind/reject/token decisions.
 - Use `PublicAccessGate` from `openxiangda/runtime/react` or `createPublicAccessClient` from `openxiangda/runtime` for React SPA public pages under `/view/:appType/public/*`. Do not append old `?publicAccess=guest` links in new apps.
 - In React SPA apps, wrap route children with `OpenXiangdaPageProvider` inside `OpenXiangdaProvider` before using `usePageSdk()`, `usePageContext()`, `useDataSource()`, or `useFormViewPermissions()`. `OpenXiangdaProvider` alone is not enough and missing the page provider causes `usePageSdkStore 必须在 PageProvider 内使用`.

package/openxiangda-skills/references/pages/publish-flow.md

@@ -16,6 +16,10 @@ activate. Use `openxiangda workspace publish ...` as the external entry.
 For day-to-day AI edits, prefer a targeted publish:
 
 ```bash
+# First ask OpenXiangda for the release plan and reliability checks.
+openxiangda workspace plan --changed --json
+openxiangda workspace check --changed
+
 # Preview what git-touched forms/pages would publish.
 openxiangda workspace publish --profile <name> --changed --dry-run
 
@@ -39,6 +43,18 @@ Targeted publish skips `src/resources` by default. Add `--resources` if resource
 manifests changed too, or run `openxiangda resource plan|publish` separately.
 Use `--skip-resources` when you explicitly want forms/pages only.
 
+React SPA workspaces use a fixed release order:
+
+```bash
+openxiangda workspace plan --changed --json
+openxiangda workspace publish --profile <name> --form <formCode>
+openxiangda resource publish --profile <name>
+openxiangda runtime deploy --profile <name>
+```
+
+If `workspace check --changed` reports risky AI fallback code, missing schema,
+or direct platform API calls, fix those issues before publishing.
+
 The CLI injects:
 
 - `OPENXIANGDA_PROFILE`

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/platform-data-model.md

@@ -19,9 +19,16 @@
 - **写入端**：前端/Agent 提交什么格式，数据库就存什么格式。
 - **读取端**：API 查询返回的就是原始 JSON 结构，**不会**额外执行字典翻译、用户名补全或部门名拼接。
 - **展示端**：选择类字段的中文名（label）已经随数据写入，前端直接取 `item.label` 即可，**禁止**再次基于 `value` 去查字典。
-- **操作端**：业务逻辑、过滤、查询条件统一以 `item.value` 为准（稳定、不随显示文案变化）。
-
-> 这意味着：label 是"快照"，value 是"语义键"。一旦字段值落库，label 与 value 一起被冻结，后续即便选项字典改名也不会影响历史数据展示。
+- **操作端**：业务逻辑、过滤、查询条件统一以 `item.value` 为准（稳定、不随显示文案变化）。
+
+> 这意味着：label 是"快照"，value 是"语义键"。一旦字段值落库，label 与 value 一起被冻结，后续即便选项字典改名也不会影响历史数据展示。
+
+### 1.3 保存接口响应契约
+
+- `sdk.form.create` / `saveFormData` / `submitFormData` 只承诺返回实例标识和保存时已生成的流水号字段，例如 `formInstId`、`formInstanceId`、`processInstanceId`、`serialNumber`、`serialNumbers`。
+- 保存接口**不返回完整业务数据**，也不承诺返回公式回填或其他服务端格式化后的字段值。
+- 需要读取完整行数据、公式回填或非流水号服务端字段时，必须在拿到 `formInstId` 后显式调用 `sdk.form.getDetail({ formUuid, formInstId })`。
+- 禁止生成假 ID（例如 `inst_${Date.now()}`），禁止在业务代码中手写 `response.data || response.result` 猜返回结构。
 
 ---
 
@@ -64,7 +71,15 @@ type MultiSelectValue = Option[];
 ```
 
 - **单选/多选的判定**取决于字段配置 `multiple: boolean`，而非字段类型本身。
-- **多选字段始终为数组**，即使用户只勾选了一项，也是 `[{label, value}]`，**不要降级为对象**。
+- **多选字段始终为数组**，即使用户只勾选了一项，也是 `[{label, value}]`，**不要降级为对象**。
+
+### 2.2 字段类型变更
+
+- 字段创建后对应数据库列类型已经固定。`TextField` 是 `TEXT`，`SelectField` / `RadioField` / 附件 / 子表等复杂字段是 `JSONB`。
+- 把 `TextField` 改成 `SelectField` 不是纯 UI 改动，而是 `TEXT -> JSONB` 的破坏性存储类型变更。
+- 平台会阻断已有列的破坏性类型变更。需要迁移时采用显式 shadow migration：旧列重命名为 `fieldId__legacy_yyyymmdd`，再创建原 `fieldId` 的新类型列。
+- 回填必须提供明确转换规则，例如文本 `"待处理"` 转 `{ "label": "待处理", "value": "pending" }`；平台和 AI 都不能自动猜。
+- 发布前可用 `openxiangda form schema-plan <formCode> --schema-json <file> --json` 检查 `safeAdd`、`compatibleNoop`、`breakingTypeChanges`。
 
 ---
 

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