权限定义开发

PERMISSION_DEFINITION_SET 是 Bundle 内的不可变版本资源。它登记当前 Application Runtime 可使用的 权限点和展示分类，不创建角色、不分配主体，也不等同于 baijimu.bundle.json 顶层的 requestedPermissions 或 providedPermissions。

权限点的稳定身份是 serviceId + permissionCode。ROLE_TEMPLATE_SET、工作区人工角色和主体直接授权都 只能引用已登记的权限点，不能通过 grant 临时创建权限。

定义格式

把下面的 JSON 保存为 permission-definitions.json：

{
  "categories": [
    {
      "categoryKey": "crm",
      "displayName": "CRM",
      "sortOrder": 10
    },
    {
      "categoryKey": "crm.customer",
      "displayName": "客户",
      "parentKey": "crm",
      "sortOrder": 20
    }
  ],
  "permissions": [
    {
      "serviceId": "crm-core",
      "permissionCode": "crm.customer.read",
      "displayName": "查看客户",
      "description": "查看当前 Runtime 中的 CRM 客户",
      "categoryKey": "crm.customer",
      "sortOrder": 10
    }
  ]
}

• permissions 必须是非空数组；同一集合内的 serviceId + permissionCode 不能重复。
• categories 可省略或为空；categoryKey 在集合内唯一。
• parentKey 必须引用同一集合中存在的分类，不能引用自身，也不能形成循环。
• categoryKey、serviceId 和 permissionCode 是稳定身份字段；展示名称、描述和排序字段属于元数据。
• 权限点填写 categoryKey 时，该分类必须存在于同一 Permission Definition Set。
• 多个已安装资源可以提供相同权限点或分类，但相同稳定身份的元数据必须完全一致；定义冲突会使安装或升级失败。
• 如果同一 Runtime 已存在人工登记的相同权限点，Bundle 定义的展示名称、描述、分类和排序也必须一致。

创建、发布和加入 Manifest

baijimu bundle resource create --workspace-id <workspaceId> \
  <bundle> PERMISSION_DEFINITION_SET crm-permissions \
  --definition @permission-definitions.json --json

baijimu bundle resource publish --workspace-id <workspaceId> \
  <bundle> PERMISSION_DEFINITION_SET crm-permissions 1.0.0 --json

baijimu bundle manifest resource add @baijimu.bundle.json \
  --resource-type PERMISSION_DEFINITION_SET --resource-key crm-permissions \
  --semantic-version 1.0.0 --json > baijimu.bundle.next.json
baijimu bundle manifest validate @baijimu.bundle.next.json --json
mv baijimu.bundle.next.json baijimu.bundle.json

Manifest 子命令返回修改后的完整 JSON，不会原地写文件。必须先验证新文件，再替换 baijimu.bundle.json 并提交 Git。修改权限定义时完整更新草稿、发布新的严格 Semantic Version，再更新 Manifest 中的精确版本引用；已发布版本不可修改。

与角色模板的关系

角色模板通过完全相同的 serviceId + permissionCode 引用权限点：

{
  "templates": [
    {
      "templateKey": "sales",
      "roleKey": "crm.sales",
      "roleName": "销售",
      "grants": [
        {
          "serviceId": "crm-core",
          "permissionCode": "crm.customer.read"
        }
      ]
    }
  ]
}

Bundle 同时包含两种资源时，Runtime 固定先安装 PERMISSION_DEFINITION_SET，再安装 ROLE_TEMPLATE_SET；这样角色应用前可以校验每个 grant。卸载顺序相反，先移除角色模板，再移除权限定义。

安装、升级和卸载语义

Runtime 安装编排器是 Bundle 安装和 Operation 状态的 Owner。它把类型化资源动作发送给权限资源 Owner：

• 安装或升级时，权限 Owner 读取精确不可变版本，校验全部已安装权限定义及人工权限目录没有冲突，再保存当前 Runtime 投影。
• KEEP 要求当前投影的精确版本一致；投影缺失时重新收敛。
• 卸载时，权限 Owner 对对应 ResourceLocator 执行 REMOVE 并停用 Runtime 投影。
• 生效目录按当前 Runtime 的有效 Permission Definition Set 投影实时合并；资源移除后，其中独有的权限点不再可用于新授权或鉴权。

权限定义不保存用户、部门、用户组、角色或主体绑定。主体和角色管理属于目标工作区，Bundle 资源只提供可 引用的权限目录。