Aptli

授权

授权定义了用户在身份验证后可以做什么以及不能做什么。Aptli 结合了两个独立的层：宽松的 管理员权限（可以做什么）和严格的 角色限制（不能看到什么）。 二者结合，使管理员能够对功能和数据可见性进行精细化控制。

授权模型概述

Aptli 的完整安全模型包含三个层级：

  1. 身份验证 — 您是谁（详见“身份验证”章节）
  2. 管理员权限 — 您可以修改的内容（宽松的授权）
  3. 角色限制 — 您无法查看的内容（限制性过滤）

所有限制均在服务器端强制执行——无论您通过 UI、API 还是导出功能尝试什么操作，未经授权的数据绝不会发送至您的浏览器。

该模型在保持安全性的同时提供了极大的灵活性。

管理员权限（许可式）

管理员权限授予修改信息或更改状态的权限。 若无这些权限，用户仅能查看数据并编辑自己的个人资料。

管理员权限采用“点菜式”的按用户设置方式（user.admin）。每个条目对应一个权限名称；不进行分组打包。权限直接授予用户，绝不会从角色继承。

常见管理员权限：

  • usersUpdate - 编辑其他用户的个人资料（姓名、职位、部门——不包括邮箱/密码）
  • usersLogout - 强制注销或锁定用户
  • usersDelete - 删除用户账户
  • usersCreate - 创建新用户或恢复已删除的账户
  • featureCreate、featureUpdate、featureDelete - 修改地图要素（点、线、多边形）
  • allowCommits - 将地图版本实时提交 （否则“提交”操作将作为请求提交给管理员审核）
  • jobsCreate、jobsUpdate、jobsDelete - 管理任务（计划中的工作单元）
  • workOrdersCreate、workOrdersUpdate、workOrdersDelete - 管理工作订单
  • reportsCreate、reportsUpdate、reportsDelete - 提交和管理工作报告
  • validationsCreate、validationsUpdate、validationsDelete - 报告的质量保证（QA）签核
  • activitiesCreate、activitiesUpdate、activitiesDelete - 维护活动（工作类型）目录
  • projectsCreate、projectsUpdate、projectsDelete - 管理项目
  • transactionsCreate - 创建库存交易（总账仅支持插入操作——无更新或删除权限）
  • canFacilitatePickups - 通过二维码代领方式向人员发放物料
  • canTransferStock - 在不同站点之间转移库存（站点代表转移，人员代表提货）

提交帮助请求无需任何权限——任何经过身份验证的用户均可发起请求。AI 助手是否可用取决于全系统范围的设置，而非用户级权限。

超级权限（优先于所有其他权限）：

  • appSettingSchemasModify - 修改应用程序级设置（域名、超时、安全设置）
  • adminRightsModify - 向其他用户授予管理员权限
  • viewDeleted - 查看已删除的记录（几乎通用，部分受角色限制覆盖）

检查用户的管理员权限：

  1. 导航至“管理”→“用户”
  2. 打开用户个人资料
  3. “管理员权限”部分列出了所有已授予的权限

角色限制（限制性）

角色是一组限制规则的集合，用于阻止查看和修改具有特定特征的记录。一个角色仅包含一个 名称 和一组 限制 —— 除此之外别无其他。角色不包含成员、所有者或管理权限。 成员资格与用户相关联：每个用户都有一个 roles 列表，这些角色中的每项限制都会应用于该用户。

要分配角色，请通过用户个人资料将其添加给用户（或将其设置为新用户的默认角色）。要列出角色的成员，请搜索 roles 中包含该角色的用户。

角色组件：

  • 名称 - 易于理解的标签
  • 角色限制 - 用于隐藏特定数据的字段级过滤器

角色仅控制可见范围和限制。它们绝不会授予任何操作权限——这正是管理员权限的作用所在。

角色限制结构

每条限制定义：

  • 模型（target_model） - 数据类型（用户、特征、角色等）
  • 字段 - 用于筛选的属性（所有者、状态、类别、自定义字段）
  • 比较条件 - 匹配方式。可选之一：eq、ne、gt、gte、lt、lte、in、nin
  • 筛选值 - 匹配的值（单个值，或用于 in/nin 的数组）
  • 权限 - 记录匹配时被拒绝的操作数组。每个条目为 read、edit、create 或 delete 之一。 在此列出的操作将被阻止；未列出的操作则被允许。

角色管理界面将这些内容显示为“模型”、“操作”和“路径”列。

示例用例：承包商隔离

场景： 防止承包商 A 查看承包商 B 的工作

设置：

  1. 创建角色：“承包商 A”
  2. 添加角色限制：
    • 模型：feature
    • 字段：owner
    • 比较条件：eq
    • 过滤值：承包商 B
    • 权限（拒绝）：read、edit、create、delete（全部四项均被阻止）
  3. 将“承包商 A”角色添加到承包商 A 的用户中（通过各用户的个人资料）

结果：

  • 承包商 A 的成员无法查看任何所有者 = “承包商 B”的要素
  • 不仅在 UI 中隐藏——API 返回的数据也仿佛这些记录不存在一样
  • 无法通过截图、API 调用或导出意外查看
  • 完全在服务器端强制执行

其他用例

按工作阶段： 防止现场工作人员查看质量控制验证报告：

Role: "Field Workers"
Restriction:
  Model: validation
  Field: status
  Comparison: ne
  Filter Value: "" (any value)
  Permissions (denied): read

现场工作人员完全无法查看验证结果。

按资产类型： 区分基础设施团队（电杆/管道与在用设备）：

Role: "Civil Team"
Restriction:
  Model: feature
  Field: category
  Comparison: eq
  Filter Value: "Active Equipment"
  Permissions (denied): read, edit, create, delete

土木团队无法查看或修改有源设备要素。

按物理/逻辑划分： 区分办公数据访问权限（容量关系与办公地点）：

Role: "Capacity Analysts"
Restriction:
  Model: feature
  Field: layer
  Comparison: eq
  Filter Value: "Office Locations"
  Permissions (denied): edit, create, delete

分析师可以查看办公地点，但无法修改位置（只读——读取权限未被拒绝）。

结合管理员权限与角色限制

默认行为： 所有用户均可查看所有内容，但无法进行任何修改（除非拥有管理员权限）。

添加受限的写入权限：

示例： 现场工作人员可以编辑自己的工作内容，但不能编辑他人的

Admin Rights:
  - reportsCreate: true
  - reportsUpdate: true

Role Restrictions:
  Model: report
  Field: submittedBy
  Comparison: ne
  Filter Value: [current user ID]
  Permissions (denied): edit

结果：

  • 工作人员可以创建报告（已授予管理员权限）
  • 工作人员仅能编辑自己的报告（角色限制会过滤掉其他人的报告）
  • 无法查看或修改其他工作人员的报告

服务器端强制执行

工作原理：

  • 所有查询在返回数据前均经过过滤
  • 角色限制在服务器端生效（不仅是界面隐藏）
  • 用户无法通过直接调用 API、浏览器工具或导出功能绕过限制
  • 对无权限用户而言，数据确实不存在

安全影响：

  • 截取他人屏幕的截图无济于事（数据不会为你加载）
  • 无法导出受限数据（服务器强制执行过滤）
  • 无法“猜测”记录 ID（在 ID 查询前已进行过滤）
  • 超出您权限范围的记录将返回“未找到”，即使您知道 ID 也是如此

角色管理

创建角色：

  1. 导航至“管理”→“角色”
  2. 点击“创建角色”
  3. 输入角色名称
  4. 添加角色限制（可设置多个）
  5. 保存

创建角色需要 rolesCreate 管理员权限。

编辑角色：

  • 需要 rolesUpdate 管理员权限
  • 可修改限制条件
  • 可通过 rolesDelete 删除角色（解除成员受该角色限制的约束）

此处无法编辑角色的成员列表——成员身份设置在用户端，而非角色端。

角色成员身份：

  • 成员身份存储在用户端（user.roles）；可在用户个人资料中添加或移除角色
  • 用户可同时属于多个角色（限制条件将合并适用）
  • 离开组织：在删除账户前，请先移除该用户的所有角色

为新用户自定义授权

应用设置配置（需要 appSettingSchemasModify）：

  1. 导航至“应用设置”
  2. “默认角色”——自动分配给新账户的角色
  3. 保存

没有“默认管理员权限”设置——新用户初始时不具备管理员权限。 请在账户创建后，通过用户个人资料为每位用户单独授予权限。

典型配置：

现场工作人员：

  • 默认角色：["Field Workers"]
  • 创建后授予用户的管理员权限：reportsCreate

办公室协调员：

  • 默认角色：无
  • 创建后授予用户的管理权限：workOrdersCreate、stockItemsCreate、stockItemsUpdate

不自动授予（人工审核）：

  • 默认角色：无
  • 管理员在审核账户后手动分配角色和权限。

查看实际权限

针对特定用户：

  1. 进入用户个人资料
  2. “管理员权限”部分——用户“可以”执行的操作
  3. “角色”部分——用户“无法”查看的内容（通过限制设置）
  4. 综合视图显示实际权限

测试权限：

  1. 以用户身份登录（或使用管理员权限模拟登录）
  2. 正常浏览
  3. 受限数据将不会显示
  4. 无管理员权限的操作将被禁用/隐藏

最佳实践

从严格限制开始，按需授予：

  • 新用户初始权限最低
  • 根据角色需求逐步授予管理员权限
  • 授予权限比撤销权限更容易（避免“权限蔓延”）

利用角色控制数据可见性：

  • 隔离承包商（防止竞争情报泄露）
  • 区分工作阶段（将质量控制与现场工作人员分离）
  • 区分资产类型（将基础设施与在用设备分离）

利用管理员权限管理功能：

  • 谁可以创建任务
  • 谁可以修改库存
  • 谁可以授予权限

记录角色用途：

  • 角色名称应清晰（“承包商 A”优于“角色 1”）
  • 描述中应说明限制条件
  • 帮助未来的管理员理解设计意图

定期进行权限审计：

  • 每季度审查用户的管理权限
  • 移除未使用的权限（用户角色已变更）
  • 核查角色成员资格（用户已离开组织）

监控访问尝试：

  • 记录授权失败的尝试
  • 拒绝访问的模式 = 用户试图进行未经授权的访问
  • 调查并调整权限或对用户进行培训

最小权限原则：

  • 仅授予履行工作职能所需的最低权限
  • 项目期间可临时提升访问权限（结束后撤销）
  • 超级权限（adminRightsModify）仅授予可信管理员