权限原子 = (操作类型, 资源范围, 权限字符串, 黑白名单策略)
| 要素 | 定义 | 示例 |
|------|------|------|
| **操作类型** | 用户对资源可执行的动作，通常映射为 HTTP 方法或功能动词 | `CREATE`, `READ`, `UPDATE`, `DELETE`, `EXPORT`, `APPROVE` |
| **资源范围** | 操作所作用的数据对象或数据集合的粒度 | 全部客户、本部门客户、本人创建的客户、单条客户记录 |
| **权限字符串** | 用于在代码或配置中唯一标识该权限点的机器可读字符串 | `customer:read:all`, `order:write:own` |
| **黑白名单** | 针对特定实体（用户、IP、时段）的例外放行或拒绝规则 | 白名单：仅允许运营部在 9:00-18:00 执行批量删除 |
---
#### 3.3 操作类型定义（Action Type）
操作类型应遵循**最小覆盖、无重叠**原则。常见业务操作类型分为三类：
- **基本 CRUD**（必需）：CREATE, READ, UPDATE, DELETE
- **业务操作**（按需）：APPROVE（审批）, REJECT（驳回）, EXPORT（导出）, IMPORT（导入）, PROCESS（处理）, TRANSFER（转交）
- **管理与审计**：CONFIGURE（配置）, AUDIT（审计）, ADMIN（管理）
> **案例提示**：在订单管理模块中，`DELETE` 操作通常只分配给系统管理员，而业务员仅拥有 `READ`、`UPDATE` 和 `PROCESS` 权限。
---
#### 3.4 资源范围定义（Resource Scope）
资源范围决定了同一操作在不同上下文下的可见性。范围从宽到窄可分为四个层级：
| 范围层级 | 标识符 | 含义 | 适用场景 |
|----------|--------|------|----------|
| 全局 | `all` | 不受任何限制，访问系统内所有数据 | 超级管理员、系统配置 |
| 部门 | `dept` | 仅限用户所属组织/部门的数据 | 部门经理查看下属数据 |
| 个人 | `own` | 仅限用户本人创建或分配的数据 | 普通员工查看自己的工单 |
| 实例 | `instance` | 极细粒度，仅限特定一条或几条数据 | 数据密级隔离、特定项目查看 |
---
#### 3.5 权限字符串编码规则（Permission Code）
**编码规则**用于将操作与资源范围组合为一个短、可读、可排序的字符串。推荐格式：
标准格式： [模块]:[操作]:[范围]
示例：
##### 3.5.1 编码模式对比
| 模式 | 格式 | 示例 | 优点 | 缺点 |
|------|------|------|------|------|
| **扁平模式** | `模块_操作_范围` | `order_export_dept` | 简单直观 | 模块多时难以管理 |
| **层次模式** | `模块:操作:范围` | `order:export:dept` | 易于按模块分组 | 需统一分隔符 |
| **命名空间模式** | `命名空间.模块.操作.范围` | `biz.order.export.dept` | 适合多业务域 | 字符串较长 |
##### 3.5.2 编码规则最佳实践
- **强制小写**：避免大小写敏感导致匹配失败。
- **分隔符统一**：推荐使用冒号 `:` 或点号 `.`，避免使用斜杠或空格。
- **动词优先**：先写出操作，再写范围，便于按功能聚合（如 `read:*` 可匹配所有读操作）。
- **通配符支持**：使用 `*` 表示匹配所有子级（如 `order:*:all` 表示对订单的所有操作）。
> **风险提示**：避免在编码中使用数字序号或版本号（如 `v2_customer_view`），否则版本升级将导致大量硬编码字符串需要同步更新。
---
#### 3.6 黑白名单设计（Allow/Deny Strategy）
黑白名单用于在角色授权基础上，对**特定实体**或**特定条件**进行例外处理。
##### 3.6.1 黑白名单模型对比
| 特性 | 白名单（Allowlist） | 黑名单（Denylist） |
|------|---------------------|-------------------|
| **默认行为** | 全部拒绝，仅允许显式声明的实体 | 全部允许，仅拒绝显式声明的实体 |
| **适用场景** | 高安全环境（财务系统、核心配置） | 宽松环境（CRM、工单系统） |
| **维护成本** | 较低（条目少） | 较高（随着异常增多，列表膨胀） |
| **风险倾向** | 倾向于保守（可能阻止合法访问） | 倾向于开放（可能遗漏恶意访问） |
##### 3.6.2 黑白名单设计要素
1. **检查顺序**：黑名单优先于白名单优先于角色权限。
2. **冲突处理**：当同一实体同时出现在白名单和黑名单时，黑名单应优先拒绝（安全优先原则）。
3. **条件表达式**：黑白名单可绑定条件上下文，如：
- `deny IP:192.168.1.* 操作:DELETE`
- `allow 用户:张三 范围:own 时间:outside_working_hours`
---
#### 3.7 权限原子组装与验证流程图
以下 SVG 展示了操作类型、资源范围、编码规则与黑白名单如何组装为一个完整的权限判断流程。
---
#### 3.8 权限原子定义清单（验收标准）
在项目中定义权限原子时，应使用以下表格确认覆盖所有必要维度。
| 模块 | 操作类型 | 资源范围 | 权限字符串 | 黑白名单策略 |
|------|----------|----------|------------|--------------|
| 用户管理 | CREATE | all | `user:create:all` | 黑名单：禁止 IP 段 `10.0.0.0/8` |
| 用户管理 | UPDATE | own | `user:update:own` | 白名单：仅 Admin 角色可修改 |
| 订单管理 | READ | dept | `order:read:dept` | 无条件允许 |
| 订单管理 | DELETE | instance | `order:delete:instance` | 黑名单：禁止非工作时间操作 |
| 报表管理 | EXPORT | all | `report:export:all` | 白名单：仅允许部门经理及以上 |
---
#### 3.9 常见落地风险
1. **字符串硬编码**：权限字符串在代码中硬编码，导致模块重构时需同步修改所有校验点。
2. **范围定义不清**：`own` 与 `dept` 的边界模糊，导致数据泄露或无法访问。
3. **黑白名单冲突无预案**：未定义冲突时优先级，导致系统出现安全漏洞或合法请求被拒绝。
4. **编码规则无通配符**：不支持 `*` 通配符，造成角色授权时需枚举大量权限点。
> **最佳实践**：所有权限字符串统一存储在配置中心或策略库中，代码内仅通过常量引用，避免魔数（magic strings）。
示例：
order:export:dept 表示“导出本部门订单”