角色开发

每个业务角色是一个独立的 ROLE 资源。Bundle 负责组合交付多个角色，角色自身独立定义、创建版本和引用， 不再增加角色模板集。本文保留原页面 URL，便于已有链接继续访问。

本文描述单资源契约。CLI 命令和参数以本机逐级 --help 为准；权限、资源归属及内容协议由服务端在执行请求时校验。

角色身份与定义

Bundle 角色的稳定身份是完整 environmentKey/bundleId/ROLE/resourceKey，例如 example-origin/example-crm/ROLE/sales。来源环境及资源身份必须使用 Owner 返回值，不能按显示名称拼接。 精确不可变版本另带 semanticVersion。

下面是单个角色的定义。示例 Locator 仅说明格式，使用前替换为实际已创建权限资源的完整身份：

{
  "roleName": "销售",
  "description": "处理客户资料",
  "grants": ["example-origin/example-crm/PERMISSION/customer-read"]
}

• roleName 和 description 是展示信息，不构成身份。
• grants 直接引用独立 PERMISSION 资源的完整 Locator，不使用 serviceId + permissionCode。
• 定义不包含 templates、templateKey、裸 roleKey 或成员名单。角色身份与版本来自外层资源。
• 空 grants 合法；同一权限不能重复引用。非空引用必须满足资源类型、声明范围和安装态校验。
• 两个 Bundle 的同名角色仍是两个不同资源，不按同名或裸 key 合并权限。

权限定义见权限开发。

创建、编辑、创建版本和纳入 Bundle

将上述定义保存为 role.json，先查询和创建资源：

baijimu bundle resource list <bundle> --workspace-id <workspaceId> --resource-type ROLE
baijimu bundle resource create <bundle> --workspace-id <workspaceId> \
  --resource-type ROLE --resource-key sales --definition @role.json
baijimu bundle resource get <bundle> --workspace-id <workspaceId> \
  --resource-type ROLE --resource-key <ownerReturnedResourceKey>
baijimu bundle resource update <bundle> --workspace-id <workspaceId> \
  --resource-type ROLE --resource-key <ownerReturnedResourceKey> --definition @role.json
baijimu bundle resource version create <bundle> --workspace-id <workspaceId> \
  --resource-type ROLE --resource-key <ownerReturnedResourceKey> --version <exactVersion>
baijimu bundle manifest include-resource <bundle> --workspace-id <workspaceId> \
  --file baijimu.bundle.json --resource-type ROLE \
  --resource-key <ownerReturnedResourceKey> --version <exactVersion>

创建命令必须传 --resource-key；后续命令在同一 Bundle 内沿用这个 key。资源类型大小写敏感。 作者清单使用当前清单协议的 definition.resources，由 CLI 纳入并在线预检；见 Bundle 项目清单。审查文件并提交后创建 Bundle 版本，再安装或升级。 编辑草稿不会改变已创建的不可变版本，也不会自动改变客户 Runtime。

工作区角色与主体分配

业务产品定义角色；用户、部门和用户组到角色的实际分配属于目标工作区，不随 Bundle 打包。 角色管理契约明确区分：

• Bundle 角色：kind: "BUNDLE"，以 resourceLocator 标识。
• 工作区自定义角色：kind: "WORKSPACE"，以 workspaceId + roleKey 标识，不创建虚构的 Bundle Locator。

Bundle 角色定义由其版本管理。客户可创建工作区角色，引用已安装 ROLE 的完整 Locator 并配置直接权限； 引用用于组合权限，不等于把被引用角色直接分配给成员，也不自动赋予某个事项的责任。 人工节点候选仍需按对应工作流合同填写，见人工事项定义。

安装与迁移边界

角色授权依赖的权限必须先有效；由 Runtime 安装编排和权限 Owner 校验引用范围及实际状态。 安装、升级和卸载记录由 Runtime 安装系统维护；权限服务持有资源内容及工作区授权关系。 移除资源前必须处理有效引用，不能用资源目录缓存替代安装事实。

旧 ROLE_TEMPLATE_SET、resourceLocator + templateKey 和裸 Bundle roleKey 属于历史合同。 迁移需要明确每个旧成员对应哪个新 ROLE，同步检查主体绑定、自定义角色引用、人工事项和事件策略等消费者。 不能仅替换类型名、按同名猜测、改写历史不可变版本或假定旧绑定自动迁移。 旧集合的创建、更新和版本发布入口已经关闭。历史定义和不可变版本读取、已安装集合的卸载与恢复在迁移窗口内保留；新资源通过登记的 Owner 目录和执行协议处理。旧表名中的 set 不决定新资源粒度，也不能作为新资源类型。