角色模板开发

ROLE_TEMPLATE_SET 是 Bundle 内的不可变版本资源。它声明业务角色的稳定 roleKey、展示信息和 Runtime 权限，不保存成员。用户、部门和用户组到角色的分配属于目标工作区。

定义格式

{
  "templates": [
    {
      "templateKey": "sales",
      "roleKey": "crm.sales",
      "roleName": "销售",
      "description": "处理 CRM 线索和客户",
      "adoptExisting": false,
      "grants": [
        {
          "serviceId": "crm-core",
          "permissionCode": "crm.customer.read"
        }
      ]
    }
  ]
}

• templateKey 在一个模板集内唯一，用于追踪模板来源；它不是工作区角色身份。
• roleKey 是跨版本稳定的角色身份，也是工作流人工节点 identityType: "role" 时的 identityId。
• roleName 和 description 是 Bundle 提供的展示元数据。
• grants 不能为空；serviceId + permissionCode 必须指向当前 Runtime 已登记的权限点。
• adoptExisting 默认为 false。目标工作区已有同 roleKey 的人工角色时，安装会失败，避免 Bundle 静默接管。只有所有贡献该 roleKey 的 Bundle 模板都设置为 true，人工角色才能覆盖展示信息和启停状态； Bundle 权限仍按当前安装资源取并集。

多个已安装 Bundle 可以贡献同一个 roleKey，但 roleName 和 description 必须一致，否则角色目录和 安装校验会失败关闭。

创建、发布和引用

把上面的 JSON 保存为 role-templates.json，然后通过统一资源命令创建和发布：

baijimu bundle resource create <workspace> <bundle> ROLE_TEMPLATE_SET crm-roles \
  --definition @role-templates.json --json

baijimu bundle resource publish <workspace> <bundle> ROLE_TEMPLATE_SET crm-roles 1.0.0 --json

baijimu bundle manifest resource add manifest.json \
  --resource-type ROLE_TEMPLATE_SET --resource-key crm-roles --semantic-version 1.0.0
baijimu bundle manifest validate manifest.json

修改模板时先完整更新草稿，再发布新的严格 Semantic Version；已发布版本不可修改。

安装与卸载语义

安装不会向目标工作区复制 workspace_role、角色权限或 Bundle 安装快照。平台按 workspaceId + applicationRuntimeId 读取当前有效 Bundle 安装资源，解析每个精确 ROLE_TEMPLATE_SET 版本，并与工作区人工角色合并成实时目录：

• Bundle-only 角色在角色管理页只读，但可以分配给用户、部门或用户组，也可以作为人工节点候选。
• 同时存在人工角色且允许 adoptExisting 时，管理员只编辑人工部分。
• 卸载后，派生角色及其权限立即从当前 Runtime 目录和鉴权中消失，不需要资源所有者执行删除。
• 主体到 roleKey 的绑定保留为 dormant；以后再次安装提供同一 roleKey 的 Bundle 时自动恢复。
• 已创建 Issue 的角色候选仍按稳定 roleKey 与工作区主体绑定匹配，不保存角色成员快照。

因此，Bundle 作者应把 roleKey 当作长期兼容的公开身份。改变 roleKey 等同于定义一个新角色，旧绑定和 历史人工事项不会自动迁移到新身份。