openxiangda 1.0.246 → 1.0.247

package/README.md

@@ -54,6 +54,8 @@ openxiangda automation list --profile dev
 openxiangda automation executions daily_ticket_digest --profile dev
 openxiangda automation diagnose daily_ticket_digest --profile dev
 openxiangda permission role-list --profile dev
+openxiangda permission role-users sales --profile dev
+openxiangda permission role-add-users sales --user-ids <user-id> --change <change-id> --profile dev
 openxiangda settings get customer --profile dev
 openxiangda data-view list --profile dev
 openxiangda data-view status ticket_with_customer --profile dev

package/lib/cli.js

@@ -207,6 +207,7 @@ const {
   writeJson,
 } = require('./utils');
 const { version: CURRENT_VERSION } = require('../package.json');
+const { resolveRoleMembershipId } = require('./role-resolution');
 
 const NPM_PACKAGE_NAME = 'openxiangda';
 const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
@@ -390,7 +391,7 @@ Usage:
   openxiangda connector list|get|create|update|upsert|delete|invoke|download-test [--json-file file]
   openxiangda notification template-list|template-get|template-upsert|template-delete|type-list|type-get|type-upsert|type-delete|preview|send|batch-send
   openxiangda organization capabilities|department-list|department-get|department-create|department-update|account-list|account-get|account-create|account-update|account-reset-password
-  openxiangda permission role-list|role-create|role-update|role-delete|role-bind|snapshot|audit
+  openxiangda permission role-list|role-create|role-update|role-delete|role-bind|role-users|role-add-users|snapshot|audit
   openxiangda permission page-group-list|page-group-create|page-group-update|page-group-delete|page-group-bind
   openxiangda permission form-group-list|form-group-create|form-group-update|form-group-delete|form-group-bind
   openxiangda settings get|save|indexes|indexes-save|data-management|data-management-save|public-access
@@ -14105,7 +14106,10 @@ async function permission(args) {
   const { flags, positional } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
     print(
-      '用法: openxiangda permission role-list|role-create|role-update|role-delete|role-bind|role-users|role-add-users|page-group-list|page-group-create|page-group-update|page-group-delete|page-group-bind|form-group-list|form-group-create|form-group-update|form-group-delete|form-group-bind|form-summary|menu-permissions|snapshot|audit'
+      [
+        '用法: openxiangda permission role-list|role-create|role-update|role-delete|role-bind|role-users|role-add-users|page-group-list|page-group-create|page-group-update|page-group-delete|page-group-bind|form-group-list|form-group-create|form-group-update|form-group-delete|form-group-bind|form-summary|menu-permissions|snapshot|audit',
+        'role-users/role-add-users 接受角色 code 或 UUID；本地未绑定的 code 会从当前应用角色列表精确解析，找不到或不唯一时显式失败。',
+      ].join('\n')
     );
     return;
   }
@@ -14218,7 +14222,12 @@ async function permission(args) {
     const [roleKey] = positional;
     if (!roleKey) fail('用法: openxiangda permission role-users <roleCode|roleId>');
     const target = getWorkspaceTarget(config, profileName, flags);
-    const roleId = resolveRoleId(target.bound, roleKey, flags);
+    const roleId = await resolveRoleMembershipIdForCommand(
+      config,
+      target,
+      roleKey,
+      flags
+    );
     const data = await requestWithAuth(
       config,
       target.profileName,
@@ -14243,7 +14252,12 @@ async function permission(args) {
       fail('用法: openxiangda permission role-add-users <roleCode|roleId> --user-ids <id1,id2>');
     }
     const target = getWorkspaceTarget(config, profileName, flags);
-    const roleId = resolveRoleId(target.bound, roleKey, flags);
+    const roleId = await resolveRoleMembershipIdForCommand(
+      config,
+      target,
+      roleKey,
+      flags
+    );
     await ensureDirectMutationPublishContext(config, target, flags, 'permission role-add-users');
     const data = await requestWithAuth(
       config,
@@ -17471,6 +17485,34 @@ function resolveRoleId(bound, roleKey, flags = {}) {
   return mapped || roleKey;
 }
 
+async function resolveRoleMembershipIdForCommand(
+  config,
+  target,
+  roleKey,
+  flags = {}
+) {
+  return resolveRoleMembershipId({
+    roleKey,
+    explicitRoleId: flags['role-id'],
+    localRoleId: target.bound.resources?.roles?.[roleKey]?.roleId,
+    listRoles: async roleCode => {
+      const data = await requestWithAuth(
+        config,
+        target.profileName,
+        apiPathWithQuery(
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/roles`,
+          {
+            code: roleCode,
+            page: 1,
+            limit: 200,
+          }
+        )
+      );
+      return normalizeItems(data);
+    },
+  });
+}
+
 function resolvePagePermissionMenuTargets(bound, flags = {}) {
   const direct = [
     ...splitList(flags['menu-form-uuids']),

package/lib/role-resolution.js

@@ -0,0 +1,57 @@
+const ROLE_UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function isRoleUuid(value) {
+  return ROLE_UUID_PATTERN.test(String(value || '').trim());
+}
+
+async function resolveRoleMembershipId(options = {}) {
+  const roleKey = String(options.roleKey || '').trim();
+  const explicitRoleId = String(options.explicitRoleId || '').trim();
+  const localRoleId = String(options.localRoleId || '').trim();
+
+  if (explicitRoleId) return explicitRoleId;
+  if (isRoleUuid(roleKey)) return roleKey;
+  if (localRoleId) return localRoleId;
+  if (!roleKey) throw roleResolutionError('ROLE_KEY_REQUIRED', '角色代码或 UUID 不能为空');
+  if (typeof options.listRoles !== 'function') {
+    throw roleResolutionError('ROLE_LIST_UNAVAILABLE', '无法查询应用角色列表');
+  }
+
+  const roles = await options.listRoles(roleKey);
+  const matches = (Array.isArray(roles) ? roles : []).filter(
+    role => String(role?.code || role?.roleCode || '').trim() === roleKey
+  );
+  if (matches.length === 0) {
+    throw roleResolutionError(
+      'ROLE_CODE_NOT_FOUND',
+      `应用角色代码 ${roleKey} 不存在；请先创建角色或使用 role-bind/角色 UUID`
+    );
+  }
+  if (matches.length > 1) {
+    throw roleResolutionError(
+      'ROLE_CODE_AMBIGUOUS',
+      `应用角色代码 ${roleKey} 匹配到 ${matches.length} 个角色，无法安全确定 role UUID`
+    );
+  }
+
+  const roleId = String(matches[0]?.id || matches[0]?.roleId || '').trim();
+  if (!roleId) {
+    throw roleResolutionError(
+      'ROLE_ID_MISSING',
+      `应用角色代码 ${roleKey} 的查询结果缺少 role UUID`
+    );
+  }
+  return roleId;
+}
+
+function roleResolutionError(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+module.exports = {
+  isRoleUuid,
+  resolveRoleMembershipId,
+};

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

@@ -80,6 +80,11 @@ Use role codes in permission group JSON. Bind existing role IDs only inside the
 openxiangda permission role-bind sales --role-id <id> --profile dev
 ```
 
+`role-users` and `role-add-users` accept either a role UUID or a logical role
+code. When a code has no profile-local binding, the CLI resolves it from the
+current application's role list and requires exactly one matching code; missing
+or ambiguous matches fail explicitly instead of sending the code as a role ID.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.246",
+  "version": "1.0.247",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -90,6 +90,7 @@
     "test:design-gates": "node scripts/design-gates-smoke.mjs",
     "test:resource-cli": "node scripts/resource-cli-smoke.mjs",
     "test:permission-snapshot": "node scripts/permission-snapshot-smoke.mjs",
+    "test:permission-role-users": "node scripts/permission-role-users-smoke.mjs",
     "test:sdk-bundle": "node scripts/sdk-browser-bundle-smoke.mjs",
     "test:sdk-list-response": "vitest run packages/sdk/src/runtime/react/admin-list/dataSources.test.ts packages/sdk/src/components/core/dataManagementApi.test.ts",
     "test:api-contract": "node scripts/openxiangda-api-contract-smoke.mjs",