#权限管理概览

本文档介绍 DataAgent 的权限模型，以及权限在运行时是如何合并、传播和解析的。

#核心概念

#定义

#权限维度

• 表权限：决定用户是否可以访问某个 Schema。
• 行权限：通过过滤条件限制用户可见的数据行。
• 列权限（含原子指标）：通过字段白名单限制用户可见的字段和原子指标。
• 复合指标权限：限制用户可访问的复合指标范围。

#多角色权限合并

一个用户可以绑定多个角色。系统在计算用户权限时，会先收集所有角色的权限，再合并为最终结果。

#合并规则

#表权限

• 取所有角色中最宽松的结果。
• 可理解为：只要某个角色允许访问，该用户就可访问该 Schema。

#行权限

• 多个角色的行权限按“并集”处理。
• 实现上通常会合并为 $or 条件。
• 可理解为：只要命中任一角色的行权限，该数据行就可见。

#列权限（含原子指标）与复合指标权限

• 两者都按白名单合并。
• 只要某个角色允许访问某个字段、原子指标或复合指标，最终就可访问。

#行权限自动传播

#设计目的

如果 Schema 之间存在引用关系（例如销售事件表引用店铺实体表），系统可以把下游 Schema 上配置的行权限自动传播到上游 Schema，减少重复配置。

典型场景：

• 店铺有行权限
• 订单通过 实体属性 关联店铺
• 那么订单可以自动继承店铺的行权限

#传播规则

系统会基于 Schema 引用关系做传播，满足以下条件时才会自动继承：

#传播示意

#传播示例

假设存在如下 Schema：

地理位置: {
  _id: "location",
  properties: [
    { name: "id", type: "string" },
    { name: "名称", type: "string" },
    { name: "大区", type: "string" }
  ]
}

店铺: {
  _id: "shop",
  properties: [
    { name: "id", type: "string" },
    { name: "名称", type: "string" },
    { name: "位置", type: "object", ref: "location" }
  ]
}

如果在“地理位置”上配置了如下行权限：

地理位置.rowPermissions = {
  "大区": { "$eq": "华东大区" }
}

传播后，店铺的行权限会变为：

店铺.rowPermissions = {
  "位置": {
    "schema": "location",
    "query": {
      "大区": { "$eq": "华东大区" }
    }
  }
}

这表示：查询店铺时，只能看到其“位置”属于华东大区的数据。

#变量模板解析

行权限支持使用变量模板，从当前用户上下文中动态取值。

#支持的变量

#前端配置示例

#使用示例

rowPermissions = {
  "店铺ID": {
    "$eq": "{{$user.store}}"
  }
}

如果当前用户的 store 值为 shop123，运行时会解析为：

rowPermissions = {
  "店铺ID": {
    "$eq": "shop123"
  }
}

#配置建议

#角色设计

1. 按业务职能拆分角色，例如管理员、区域经理、店员。
2. 尽量减少角色职责重叠，避免权限来源过多。
3. 保持角色粒度适中，过细会增加维护成本。

#权限配置

1. 优先在实体 Schema 上配置行权限，可以不需要在事件 Schema 上配置，便于复用传播能力。
2. 优先使用用户字段变量模板，减少为单个用户单独写死权限。
3. 配置完成后，结合真实用户验证最终可见数据是否符合预期。

#常见场景

#术语表