角色模板开发

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 已登记的权限点。
• Bundle 自己提供权限点时，应先发布并在同一 Bundle 或依赖闭包中引用 PERMISSION_DEFINITION_SET。Runtime 安装时先应用权限定义，再校验和应用角色模板。
• adoptExisting 默认为 false。目标工作区已有同 roleKey 的人工角色时，安装会失败，避免 Bundle 静默接管。只有所有贡献该 roleKey 的 Bundle 模板都设置为 true，人工角色才能覆盖展示信息和启停状态； Bundle 权限仍按当前安装资源取并集。

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

创建、发布和引用

把上面的 JSON 保存为 role-templates.json，然后通过领域对象命令创建和发布：

创建命令不传身份；使用返回的领域对象身份进行后续冻结和选择：

baijimu bundle object create <bundle> role-template-set --workspace-id <workspaceId> \
  --definition @role-templates.json --json
baijimu bundle object publish <bundle> role-template-set --workspace-id <workspaceId> \
  --object-id <ownerReturnedId> --version 1.0.0 --json
baijimu bundle manifest include <bundle> role-template-set --workspace-id <workspaceId> \
  --file baijimu.bundle.json --object-id <ownerReturnedId> --version 1.0.0
baijimu bundle manifest validate @baijimu.bundle.json

include 在线预检全部选择后原子更新文件。审查 Git 差异并提交，再从该提交发布 Bundle。 修改定义时使用 bundle object update，冻结新版本后重新纳入；已发布版本不可修改。

安装与卸载语义

安装不会把模板复制成工作区人工角色或人工角色权限。Runtime 安装编排器按 Bundle Operation 调用权限资源 Owner；权限资源 Owner 以 workspaceId + applicationRuntimeId + ResourceLocator 保存当前精确 ROLE_TEMPLATE_SET 的 Runtime 投影，并由这些有效投影与工作区人工角色合并成实时目录：

• Bundle-only 角色在角色管理页只读，但可以分配给用户、部门或用户组，也可以作为人工节点候选。
• 同时存在人工角色且允许 adoptExisting 时，管理员只编辑人工部分。
• 卸载时 Runtime 安装编排器先向权限资源 Owner 下发 Role Template Set 的 REMOVE 动作；Owner 停用对应 Runtime 投影后，派生角色及其权限从当前 Runtime 目录和鉴权中消失，不删除人工角色数据。
• 主体到 roleKey 的绑定保留为 dormant；以后再次安装提供同一 roleKey 的 Bundle 时自动恢复。
• 已创建 Issue 的角色候选仍按稳定 roleKey 与工作区主体绑定匹配，不保存角色成员快照。

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