权限与角色

Canopy 使用三层权限模型，将应用程序范围内基于角色的访问控制与卡片特定的利益相关者角色结合起来。本页解释其设计、何时使用各层，以及各层如何组合成有效权限。

为何需要三层？

企业架构本质上是跨职能的。一张给定的卡片——例如一个 Application——可能：

• 对大多数用户只读（查看者可以看到库存但无法编辑）
• 由 EA 团队可编辑（成员可以更新任何卡片）
• 由负责该应用程序的特定人员管理（技术应用程序负责人可以编辑和审批状态，即使他们没有组织范围内的编辑权限）
• 由管理员完全控制（管理员可以做任何事情）

扁平角色系统可以处理前三种情况，但在第四种情况下失效：您要么给某人组织范围内的编辑权限（范围太广），要么什么都不给（太过限制）。利益相关者层通过向指定个人授予每张卡片的权限来解决这个问题。

第一层——应用角色

应用角色分配给用户，并在整个平台范围内生效。它们在管理 → 用户与角色中定义和管理。

每个角色携带一组 JSON 权限。内置角色为：

角色	键	范围
管理员	admin	通配符 {"*": true}——无限制
BPM 管理员	bpm_admin	完整 BPM + 完整库存，无 admin.*
成员	member	完整库存 + BPM 编辑，无 admin.*
查看者	viewer	所有域的只读访问

自定义角色可以使用可用权限键的任意组合创建，按域分组，如 inventory.*、reports.*、bpm.*、ppm.*、grc.*、todos.*、admin.*。

使用应用角色来控制某类用户在整个平台上可以执行的操作。

第二层——利益相关者角色

利益相关者角色分配给特定卡片上的用户。每种卡片类型定义自己的一组利益相关者角色定义（例如，Application 卡片有「技术应用程序负责人」、「业务应用程序负责人」、「数据管理员」）。这些在管理 → 元模型 → [类型] → 利益相关者角色中配置。

每个利益相关者角色定义携带一组卡片级权限——例如 card.edit、card.approve、card.manage_relations。当用户被添加为卡片上的利益相关者时，他们只在该卡片上获得这些权限。

使用利益相关者角色来处理所有权或责任特定于卡片的情况：特定应用程序的负责人应该能够管理它，而无需获得其他 500 个应用程序的编辑权限。

第三层——有效权限

当用户尝试对卡片执行操作时，系统通过组合以下内容计算其有效权限：

1. 其应用角色权限（从平台级键映射到卡片级键）
2. 其在该特定卡片上持有的所有利益相关者角色权限

结果是两个集合的并集。一个在平台范围内是查看者，但在某张卡片上是技术应用程序负责人的用户可以编辑该卡片，因为利益相关者角色授予 card.edit，即使查看者角色不授予。

当前用户在给定卡片上的有效权限通过 GET /cards/{id}/effective-permissions 暴露，并驱动界面中所有编辑/审批/删除控件。

管理员通配符

管理员角色使用 {"*": true} 作为其权限集。这被评估为「允许一切」——包括创建角色时不存在的权限。这意味着新模块和新权限键无需任何角色更新即可自动供管理员使用。

没有其他内置角色使用通配符。创建自定义角色时，请使用明确的权限键而非通配符——这使角色的范围可审计，并防止意外过度授权。

权限键结构

所有权限键遵循 域.操作 模式：

• inventory.view — 读取卡片
• inventory.edit — 更新卡片
• inventory.create — 创建卡片
• admin.metamodel — 管理卡片类型和关系类型
• admin.impersonate — 临时以不同角色行事（参见角色模拟）
• bpm.approve — 审批 BPMN 流程版本
• todos.view / todos.create / todos.manage — 访问和管理待办事项
• risks.manage — 创建和更新风险登记条目

有效键的完整列表在 backend/app/core/permissions.py 中，这是唯一的可信来源。新权限键必须在那里添加，才能授予任何角色。

常见模式

将某个模块限制给特定团队： 创建一个仅具有 ppm.* 和 inventory.view 权限的自定义角色，将其分配给项目组合团队。他们可以在 PPM 中工作，但无法编辑主库存。

授予审批权但不授予编辑权： 在特定 Application 卡片上给业务利益相关者分配「业务应用程序负责人」利益相关者角色。将该角色配置为包含 card.approval_status 但不包含 card.edit。他们可以审批 EA 团队填写的卡片，但无法更改数据。

为管理员提供紧急访问： 管理员通配符意味着任何未来权限——包括扩展或未来版本添加的权限——都会自动授予。仅对真正需要无限制访问权限的用户使用管理员角色。

以特定角色测试： 具有 admin.impersonate 权限的用户可以从用户菜单（以角色查看…）切换到任何非管理员角色，以准确验证该角色可以看到和做什么——无需创建单独的测试账户。模拟会话仅基于 JWT，不会在底层账户上留下任何痕迹。完整工作流程请参见角色模拟。

另请参阅

• 用户与角色 — 创建和编辑应用角色
• 元模型管理 — 按卡片类型配置利益相关者角色
• 卡片详情：利益相关者标签页 — 向卡片分配利益相关者