openxiangda-skill-kit 2.0.0-alpha.124 → 2.0.0-alpha.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.124",
+  "version": "2.0.0-alpha.126",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.102"
+    "openxiangda-devkit-core": "2.0.0-alpha.104"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "Use when researching, designing, building, testing, or delivering an OpenXiangda 2.0 application, including anonymous public forms and other no-account external-user pages.",
-      "sha256": "1f5bfa9cd4c29a971b9f77dbaf4023a339ddeaef6feb3bf5dcc8f8a90b261d8b"
+      "sha256": "99c39264c2159b1236db8b61a58825433b3083fd996ed63e29be4298f8b8f45f"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -27,6 +27,7 @@ Use this order:
 3. If the workspace contains `appspec/`, the user asks to maintain requirements, or the task changes observable behavior, read [AppSpec](references/appspec.md), load the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID. AppSpec is optional and never a release gate; L0 changes create no record.
 4. Read [Architecture](references/architecture.md), assign one owner to each capability and keep ordinary CRUD on platform Data API.
 5. For every resource or permission change, read [Data and authorization](references/data-authz.md) before editing `openxiangda.config.ts`.
+   When a custom authenticated page lets business users maintain application-role memberships or delegate that maintenance authority, also read [Frontend](references/frontend.md). Use the current-user role-management browser SDK documented there; never add actor selection, an application-owned grant table, or a proxy authorization service.
 6. If the request mentions external users without platform accounts, anonymous or guest access, a public form/page, resumable submission, duplicate checks, public uploads, or letting a visitor read their own submissions, read [Anonymous public access](references/public-access.md). Use the declared platform contract; do not invent a guest role, public Native Data API, fingerprint identity or application-owned token.
 7. Read [Frontend](references/frontend.md) for pages or fields and [Backend actions](references/backend.md) only for a real business action.
 8. When the application explicitly enables standard approval, application events or notifications, read [Workflow, Events and Notification Hub](references/workflow-events.md). Keep them optional and out of ordinary CRUD.

package/skills/openxiangda-v2/references/data-authz.md

@@ -61,8 +61,13 @@ const visitorReservations = {
 ```
 
 Put it in `data: { resources: [visitorReservations] }`. Resource CRUD
-capabilities are derived by `resourceCapabilityCodes`; grant the needed values
-to roles. Directory-backed roles also require
+capabilities are derived by `resourceCapabilityCodes`. For a Native resource,
+grant `read` to each role that may enter its generated page; the compiler also
+grants that role every enabled generated create/update/delete operation. Remove
+an operation only when the role must be restricted, using the corresponding
+code in `deniedCapabilities`. The compiler validates the denial and seals only
+the resulting allow list, so runtime authorization has no second deny model.
+Non-Native mutation owners never receive this expansion. Directory-backed roles also require
 `app:<app-code>:directory:read`. Explicit field `access` capability codes are
 also granted only to the intended roles. They are owned and exported by the
 generated field policy, so do not repeat them in `authz.capabilities`.
@@ -301,4 +306,100 @@ rows or recover a dead-letter job. Rebuild/recovery are idempotent and accept an
 input. Do not write `sourceCode`, canonical membership rows or relationship
 grant rows yourself.
 
+## Custom role-management pages
+
+Use the current-user browser SDK when a custom desktop or mobile page must
+maintain this application's role members. Do not create an application role
+table, call the platform `role` controller, forward a developer token, or add a
+NestJS endpoint that accepts a user/tenant/role from the browser.
+
+An application or platform super administrator initializes delegation by
+attaching one role-management grant to a business role. `manageAllRoles: true`
+means every current application role and therefore requires
+`managedRoleCodes: []`; otherwise list the exact role codes. Every grant must
+include `membership.read` and may add `membership.assign`,
+`membership.update`, `membership.revoke`, and `management.delegate`:
+
+```ts
+import {
+  createRoleManagementGrant,
+  loadRoleManagementCatalog,
+} from 'openxiangda/core';
+
+const catalog = await loadRoleManagementCatalog();
+const managerAuthority = catalog.roleManagement.roles.find(
+  item => item.roleCode === 'business_manager',
+);
+
+await createRoleManagementGrant({
+  operationId: crypto.randomUUID(),
+  reason: '允许业务管理员维护场馆操作员',
+  subjectRoleCode: 'business_manager',
+  manageAllRoles: false,
+  managedRoleCodes: ['venue_operator'],
+  actions: [
+    'membership.read',
+    'membership.assign',
+    'membership.update',
+    'membership.revoke',
+    'management.delegate',
+  ],
+});
+```
+
+The platform always evaluates the current logged-in user's complete
+application-role union. A delegated manager can pass on only role/action pairs
+already present in that union and needs `management.delegate` for both the
+recipient role and every managed role. It cannot manufacture an all-role grant
+from several selected-role grants.
+
+Build the member page only from these SDK calls:
+
+```ts
+import {
+  createRoleMembership,
+  listRoleMemberships,
+  searchRoleManagementUsers,
+  updateRoleMembership,
+  revokeRoleMembership,
+} from 'openxiangda/core';
+
+const users = await searchRoleManagementUsers({ keyword: '张' });
+const page = await listRoleMemberships({
+  roleCode: 'venue_operator',
+  status: 'active',
+  limit: 20,
+  offset: 0,
+});
+
+await createRoleMembership({
+  operationId: crypto.randomUUID(),
+  reason: '张老师负责场馆日常运营',
+  userId: users.items[0]!.id,
+  roleCode: 'venue_operator',
+  scopeGrants: [],
+});
+
+const membership = page.items[0]!;
+if (membership.maintainable) {
+  await updateRoleMembership(membership.id, {
+    operationId: crypto.randomUUID(),
+    reason: '调整角色有效期',
+    expectedRevision: membership.revision,
+    scopeGrants: membership.scopeGrants,
+    validFrom: null,
+    validTo: '2027-01-01T00:00:00.000Z',
+  });
+}
+```
+
+Use `listRoleManagementGrants`, `updateRoleManagementGrant` and
+`revokeRoleManagementGrant` for the delegation page. All updates/revocations
+require the row's latest `revision`. On HTTP 409, reload catalog and rows; never
+retry with a guessed revision. Every successful mutation returns an immutable
+`receipt`; `loadAuthorizationMutationReceipt(operationId)` reads it again for
+the same actor. Show `immutableReason` for an authenticated-user or projection
+membership and never try to mutate it. A hidden button is only UX—the server
+returns 403 for every undelegated role/action.
+
 Run `pnpm openxiangda check` after every declaration or permission change.

package/skills/openxiangda-v2/references/frontend.md

@@ -28,6 +28,15 @@ union. Never fetch identity for the header, display role codes, add a second
 identity selector, or copy Shell and
 directory-client implementations into application source.
 
+For a custom application role-management page, use only the typed functions in
+`openxiangda/core`: `loadRoleManagementCatalog`, `listRoleMemberships`,
+`searchRoleManagementUsers`, the membership mutations, and the
+role-management-grant mutations. The catalog's `roleManagement` projection
+drives button visibility, while the platform repeats the check for every
+request. The “Custom role-management pages” section in
+[Data and authorization](data-authz.md) defines the delegation and CAS
+contract. Do not use the developer control-plane client in browser code.
+
 The application owns the editable admin information architecture through the
 typed `defineAdminNavigation`, `adminNavigationGroup`, `adminResourcePage`,
 and `adminOperationPage` helpers in `openxiangda/config`. The compiler emits

package/skills/openxiangda-v2/references/workspace.md

@@ -40,7 +40,7 @@
 - Visitor duplicate protection uses `createVisitorReservation({ duplicateMatch: { fieldCode: submittedValue }, ... })`. `duplicateMatch` is a non-empty value map, never a field-name array, and no mutable pre-read is allowed.
 - Desktop and mobile pages share values, validation and authorization, but use separate renderers. Options, members and departments store display snapshots; resource references store direct JSON display values; attachments, images and signatures use platform-managed file references.
 - `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled object and multiple values store object arrays. `resource-ref.*` JSON is not a foreign key, trusted target snapshot or automatically refreshed copy; current target state is read by `resourceCode` plus `value`. A resource source `labelField` must be `text.short` or `text.long`; `serial-number` is allowed in source search, description and snapshot fields, but not as the label. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
-- Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
+- Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Grant a Native resource's `read` capability to every role allowed to enter its generated page; the compiler adds enabled generated create/update/delete capabilities by default. Tighten only exceptional roles with `deniedCapabilities`, which is compile-time authoring input and is removed from the sealed role. Non-Native mutation owners never receive this expansion. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
 - Do not add compatibility aliases, migration branches or silent fallbacks for an earlier 2.0 alpha contract. Replace an incorrect contract and regenerate the application.
 - Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through canonical `openxiangda.config.ts` declarations and generated clients. `standalone`/`hidden-handoff` default to the compiler-owned process operation; action-owned submission must instead declare `launch.submission.kind: 'named-operation'` with sealed create/existing input and output bindings so the standard PC/mobile page calls the original Named Action and accepts an explicit no-Workflow result. Never add a browser save callback or call Workflow prepare/start directly. Custom pages launch only through a verified Named Action using `OpenXiangdaBusinessProcessService`. PC and mobile render the same `ProcessCommandSurface` independently and recover only by `commandId`. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`. Add the current-user todo page only with `frontend.user.applicationTodoCenter: true`; never query Notification Hub management APIs from a user page.
 - Run `pnpm openxiangda check --json` after contract changes and read `data.sealedArtifact`; check never seals, and an older `.openxiangda/build/app-package.json` is not the current check result. Use `pnpm openxiangda accept --plan <file>` only for optional real preproduction identity acceptance; it never blocks delivery. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.