openxiangda-skill-kit 2.0.0-alpha.123 → 2.0.0-alpha.125

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.123",
+  "version": "2.0.0-alpha.125",
   "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.101"
+    "openxiangda-devkit-core": "2.0.0-alpha.103"
   },
   "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

@@ -301,4 +301,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