1378 lines
64 KiB
Markdown
1378 lines
64 KiB
Markdown
> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.
|
||
# Fonrey — 权限管理数据模型（DATA_MODEL_PERMISSION）
|
||
|
||
> **所属系统**: Fonrey 房产经纪管理系统
|
||
> **版本**: v1.0
|
||
> **日期**: 2026-04-24
|
||
> **关联模块**: `apps/permissions/`
|
||
> **PRD 来源**: `PRD/权限管理/权限管理模块PRD.md`
|
||
> **技术方案**: `TECH_STACK/权限管理系统技术方案.md`（本文档为其最终固化版，修正了 12 处设计问题）
|
||
|
||
---
|
||
|
||
## 变更历史
|
||
|
||
| 日期 | 变更人 | 变更内容 |
|
||
|---|---|---|
|
||
| 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |
|
||
|
||
## 一、领域概览（Domain Overview）
|
||
|
||
### 1.1 核心概念
|
||
|
||
| 概念 | 表 | 业务说明 |
|
||
|------|-----|---------|
|
||
| **PermissionDef（权限定义）** | `permission_defs` | 系统所有权限项的元数据目录（约 300+ 条），开发者维护、运营不可编辑。定义权限的 code/名称/值类型/可选范围/默认值 |
|
||
| **Role（角色）** | `roles` | 权限模板，管理员创建，如「高级业务员」「分行经理」。绑定角色类别，类别决定可配置权限项的上限 |
|
||
| **RolePermission（角色权限值）** | `role_permissions` | 某角色在某权限项上的具体配置值（稀疏存储：只存非默认值）|
|
||
| **StaffRole（员工-角色关联）** | `staff_roles` | 员工与角色的多对多关系，支持一人多角色（PRD Story 8），含主角色标识 |
|
||
| **StaffPermissionOverride（个人覆盖）** | `staff_permission_overrides` | 员工个人权限定制（稀疏存储：只存与角色合并结果不同的项） |
|
||
| **StaffDataScope（员工管理范围）** | `staff_data_scopes` | 员工的**数据可见边界**（PRD 5.6），独立于权限项的 SCOPE 值，支持跨层级叠加（如"本组 ∪ 门店B"） |
|
||
| **PermissionChangeLog（权限变更日志）** | `permission_change_logs` | 所有角色/个人权限/范围的变更流水（append-only，不可删除，对齐 `staff_transfer_logs` 范式）|
|
||
|
||
### 1.2 权限模型（Hybrid RBAC + Override）
|
||
|
||
```
|
||
员工最终权限 = 多角色值合并（最宽松） + 个人 Override（覆盖/收窄/扩展）
|
||
员工最终数据范围 = staff_data_scopes 的并集（跨层级可叠加）
|
||
AND 业务级 attribute/protection 规则（如保护客过滤）
|
||
```
|
||
|
||
**优先级**：`PermissionOverride > Merged(RolePermissions) > PermissionDef.default_value`
|
||
|
||
**SCOPE 与 DataScope 的职责分离**（关键设计决策）：
|
||
- `PermissionDef.value_type = SCOPE` 的权限项值（本人/本组/本门店/全公司）→ **权限项自身的范围维度**，如"查看私客范围=本门店"
|
||
- `StaffDataScope` → **员工整体的数据边界**，与权限项正交组合。例：员工权限"查看私客=本门店"，但 DataScope 额外授予"门店B"，则员工可见"所属门店 ∪ 门店B"下的私客
|
||
|
||
### 1.3 与其他模型的关系
|
||
|
||
```
|
||
OrgUnit (组织树) ─────────────┐
|
||
│ │ path 用于 SCOPE 子树查询
|
||
│ ▼
|
||
Staff ──N:M── StaffRole ──N:1── Role ──N:M── RolePermission ──N:1── PermissionDef
|
||
│ │ category: 置业顾问/店管/总经
|
||
│ │
|
||
├──1:N── StaffPermissionOverride ──N:1── PermissionDef
|
||
│
|
||
├──1:N── StaffDataScope ──N:1── OrgUnit (范围节点)
|
||
│
|
||
└── staff.role (系统角色) ──── 与 Role 表双轨并行
|
||
（系统角色决定顶层权限上限）
|
||
|
||
PermissionChangeLog (append-only) ← 所有变更流水
|
||
```
|
||
|
||
### 1.4 与现有 DATA_MODEL 的对接
|
||
|
||
| 现有模型 | 对接方式 |
|
||
|---------|---------|
|
||
| `staff.role`（系统角色枚举） | 保留，作为**系统角色**（决定是否能登录、是否系统管理员）。**Role 表是业务角色**（决定业务权限）。两者正交 |
|
||
| `staff.is_system_admin` | **权限检查短路**：`is_system_admin=TRUE` 时 `PermissionChecker` 全部返回 True，绕过所有检查 |
|
||
| `org_units.path` | `ScopeQueryBuilder` 的核心依赖，用于 "本组/本门店/本区域" 的子树查询（`path LIKE '/{root}/{scope_root}/%'`） |
|
||
| `properties.attribute`（公盘/私盘/特盘/封盘） | 业务属性，权限系统 **不干预**。权限决定"能否访问房源列表"，attribute 决定"列表内按业务规则过滤" |
|
||
| `clients.is_protected`（保护客） | 保护客在 ScopeQueryBuilder 中**额外 AND 保护规则**：非 owner/合保人即使有「本门店」权限也不可见 |
|
||
| `property_protections` / 保护房 | 同上，业务状态由 ScopeQueryBuilder 额外过滤 |
|
||
|
||
---
|
||
|
||
## 二、实体关系 ER
|
||
|
||
```
|
||
┌──────────────────┐ ┌──────────────────┐ ┌────────────────────┐
|
||
│ permission_defs │───N:1─│ role_permissions │───N:1─│ roles │
|
||
│ (权限目录, 租户级)│ │ (角色×权限→值) │ │ (业务角色模板) │
|
||
└──────────────────┘ └──────────────────┘ └────────────────────┘
|
||
│ │
|
||
│ │ N:M via
|
||
│ │
|
||
│ ┌─────▼──────┐
|
||
│ N:1 │ staff_roles│
|
||
│ │ is_primary│
|
||
│ └─────┬──────┘
|
||
│ │ N:1
|
||
│ │
|
||
│ ┌───────────────────────────┐ ┌────────▼────────┐
|
||
└──N:1│ staff_permission_overrides│──N:1────│ staff │
|
||
│ (个人差异化权限) │ └────────┬────────┘
|
||
└───────────────────────────┘ │
|
||
│ 1:N
|
||
┌──────────────────────────────────────┤
|
||
▼ ▼
|
||
┌──────────────────────┐ ┌──────────────────────────┐
|
||
│ staff_data_scopes │──N:1────►│ org_units (物化路径树) │
|
||
│ (管理范围,可跨层叠加)│ └──────────────────────────┘
|
||
└──────────────────────┘
|
||
|
||
┌────────────────────────────────┐
|
||
│ permission_change_logs │ (不可删除流水)
|
||
│ -> target (role/staff/scope) │
|
||
└────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Schema 定义
|
||
|
||
### 3.1 permission_defs — 权限定义表（权限目录）
|
||
|
||
> **归属 schema**：`tenant_apps`（非 shared），每个租户独立一份初始化数据。
|
||
> **理由**：避免 `django-tenants` 跨 schema 外键限制；为未来"企业版自定义权限项"留空间；通过 data migration 在租户创建时批量 seed 约 300 条默认记录。
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| code | VARCHAR(150) | UNIQUE, NOT NULL | 权限编码，规则：`{module}.{sub_module}.{action}[.{qualifier}]`，如 `client.private.view.scope` |
|
||
| module | VARCHAR(50) | NOT NULL | 一级模块枚举（见 §4.1） |
|
||
| sub_module | VARCHAR(50) | | 二级模块（如 `二手&租赁`、`商圈精耕`） |
|
||
| group_name | VARCHAR(100) | NOT NULL | 分组标题（如「私客基础权限」「联系人基础权限」） |
|
||
| name | VARCHAR(200) | NOT NULL | 显示名称 |
|
||
| description | TEXT | | 权限作用描述（PRD 5.4.3 每项均有） |
|
||
| value_type | VARCHAR(20) | NOT NULL, CHECK | `BOOLEAN` / `SCOPE` / `INTEGER`（见 §4.2） |
|
||
| scope_choices | JSONB | DEFAULT `'[]'` | 仅 `SCOPE` 类型有效，可选枚举值的 code 列表，如 `["none","self","store","company"]` |
|
||
| integer_min | INTEGER | | 仅 `INTEGER` 有效，最小值 |
|
||
| integer_max | INTEGER | | 仅 `INTEGER` 有效，最大值；`NULL`=无上限（业务语义：0 通常代表"不限制"） |
|
||
| default_value | JSONB | NOT NULL DEFAULT `'{"v":false}'` | 系统最小默认值 |
|
||
| max_allowed_categories | VARCHAR(50)[] | DEFAULT `'{}'` | 允许配置此权限的角色类别列表，空数组=所有类别均可（对应 Issue #11）|
|
||
| sort_order | INTEGER | NOT NULL DEFAULT 0 | 分组内排序 |
|
||
| is_active | BOOLEAN | NOT NULL DEFAULT TRUE | 下线权限项置 FALSE，历史记录保留 |
|
||
| is_deprecated | BOOLEAN | NOT NULL DEFAULT FALSE | 废弃标记（不再推荐使用但保持兼容） |
|
||
| version | INTEGER | NOT NULL DEFAULT 1 | 权限项定义版本，变更时递增，用于缓存失效 |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
|
||
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录最后更新时间（系统自动） |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE UNIQUE INDEX idx_permission_defs_code ON permission_defs(code);
|
||
CREATE INDEX idx_permission_defs_module ON permission_defs(module, sub_module, sort_order) WHERE is_active = TRUE;
|
||
CREATE INDEX idx_permission_defs_active ON permission_defs(is_active) WHERE is_active = TRUE;
|
||
```
|
||
|
||
**校验规则**（Django model `clean()`）：
|
||
- `code` 必须匹配 `^[a-z_]+\.[a-z_]+(\.[a-z_]+){1,2}$`
|
||
- `value_type='SCOPE'` 时 `scope_choices` 非空
|
||
- `default_value` 必须包含 `"v"` 键且值与 `value_type` 兼容
|
||
|
||
---
|
||
|
||
### 3.2 roles — 角色表
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| name | VARCHAR(100) | NOT NULL | 角色名称 |
|
||
| category | VARCHAR(30) | NOT NULL, CHECK | `agent`(置业顾问) / `store_manager`(店管) / `director`(总经) / `operator`(运营) / `custom`（见 §4.3） |
|
||
| description | TEXT | | 角色描述 |
|
||
| template_role_id | UUID | FK→roles, SET NULL | 权限模板来源角色（PRD「引用该角色配置」列） |
|
||
| is_system_builtin | BOOLEAN | NOT NULL DEFAULT FALSE | 系统内置角色（如"最大权限角色"），不可删除、不可改名 |
|
||
| is_active | BOOLEAN | NOT NULL DEFAULT TRUE | 角色是否启用；FALSE=禁用（员工无法继承该角色权限） |
|
||
| created_by | UUID | FK→staff, SET NULL | 创建人（PRD: 角色类别只能由创建者修改） |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
|
||
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录最后更新时间（系统自动） |
|
||
| updated_by | UUID | FK→staff, SET NULL | 最后修改人（权限管理审计用） |
|
||
| deleted_at | TIMESTAMPTZ | | 软删除时间戳；NULL=未删除，非NULL=已软删除 |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
-- 软删除友好的唯一索引：同名角色只要有一个未删除即冲突
|
||
CREATE UNIQUE INDEX idx_roles_name_active ON roles(name) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_roles_category ON roles(category) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_roles_template ON roles(template_role_id);
|
||
```
|
||
|
||
**禁止操作**：
|
||
- ❌ 角色被 `staff_roles` 引用时禁止删除（DB 层 `PROTECT`，Application 层给出"请先迁移 N 位员工"提示）
|
||
- ❌ `is_system_builtin = TRUE` 的角色禁止删除/改名
|
||
- ❌ `category` 在创建后仅 `created_by` 本人可修改（Application 层校验）
|
||
|
||
---
|
||
|
||
### 3.3 role_permissions — 角色权限值表
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| role_id | UUID | NOT NULL, FK→roles, CASCADE | 所属角色（稀疏存储：角色删除时级联清理权限值） |
|
||
| permission_def_id | UUID | NOT NULL, FK→permission_defs, RESTRICT | 权限定义（RESTRICT防止删除仍被引用的权限项） |
|
||
| value | JSONB | NOT NULL | 统一格式 `{"v": <value>}`，如 `{"v": true}` / `{"v": "store"}` / `{"v": 50}` |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
|
||
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录最后更新时间（系统自动） |
|
||
| updated_by | UUID | FK→staff, SET NULL | 最后修改人（权限审计用） |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE UNIQUE INDEX idx_role_permissions_uniq ON role_permissions(role_id, permission_def_id);
|
||
CREATE INDEX idx_role_permissions_role ON role_permissions(role_id);
|
||
CREATE INDEX idx_role_permissions_def ON role_permissions(permission_def_id);
|
||
```
|
||
|
||
**稀疏存储原则**：**只存储非 `default_value` 的项**。保存时若 `value == permission_def.default_value`，执行 DELETE 而非 UPSERT。优化存储与合并性能。
|
||
|
||
---
|
||
|
||
### 3.4 staff_roles — 员工角色关联
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| staff_id | UUID | NOT NULL, FK→staff, CASCADE | 所属员工（员工删除时级联删除角色关联） |
|
||
| role_id | UUID | NOT NULL, FK→roles, PROTECT | 角色被员工引用时禁止删除 |
|
||
| is_primary | BOOLEAN | NOT NULL DEFAULT FALSE | 主角色标识，每个员工有且仅有一个主角色（Issue #5） |
|
||
| assigned_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 角色分配时间（系统自动） |
|
||
| assigned_by | UUID | FK→staff, SET NULL | 分配操作人（管理员） |
|
||
| valid_from | DATE | | 生效日（预留未来"定时生效"功能） |
|
||
| valid_until | DATE | | 失效日 |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE UNIQUE INDEX idx_staff_roles_uniq ON staff_roles(staff_id, role_id);
|
||
CREATE UNIQUE INDEX idx_staff_roles_primary ON staff_roles(staff_id) WHERE is_primary = TRUE;
|
||
CREATE INDEX idx_staff_roles_role ON staff_roles(role_id);
|
||
```
|
||
|
||
**约束触发器**：每次 UPDATE `is_primary=TRUE` 时，自动将该 staff 其他行 `is_primary=FALSE`（Django signal 实现，避免 DB 级递归触发器）
|
||
|
||
---
|
||
|
||
### 3.5 staff_permission_overrides — 个人权限覆盖
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| staff_id | UUID | NOT NULL, FK→staff, CASCADE | 所属员工（员工删除时级联删除覆盖记录） |
|
||
| permission_def_id | UUID | NOT NULL, FK→permission_defs, RESTRICT | 被覆盖的权限项 |
|
||
| value | JSONB | NOT NULL | 个人权限值，同 `{"v": ...}` 格式 |
|
||
| override_mode | VARCHAR(10) | NOT NULL DEFAULT 'REPLACE' | `REPLACE`(覆盖角色合并值，PRD 默认) / `RESTRICT`(限制上限) / `GRANT`(仅扩展) — Issue #6 |
|
||
| reason | TEXT | | 管理员备注（建议强制，为后续审计） |
|
||
| modified_by | UUID | FK→staff, SET NULL | 执行个人权限修改的管理员 |
|
||
| modified_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 最近修改时间（系统自动） |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE UNIQUE INDEX idx_staff_overrides_uniq ON staff_permission_overrides(staff_id, permission_def_id);
|
||
CREATE INDEX idx_staff_overrides_staff ON staff_permission_overrides(staff_id);
|
||
```
|
||
|
||
**稀疏存储**：只存与角色合并值不同的项。批量设置角色（PRD Story 2）会清除员工所有 Override；个人编辑（Story 3）按需 UPSERT/DELETE。
|
||
|
||
---
|
||
|
||
### 3.6 staff_data_scopes — 员工数据管理范围（⭐ 新增，Issue #1）
|
||
|
||
> PRD 5.6「管理范围」的实体化。与权限项的 `SCOPE` 值互为补充：权限项决定"访问什么数据"，DataScope 决定"数据的组织边界"。
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| staff_id | UUID | NOT NULL, FK→staff, CASCADE | 所属员工（员工删除时级联删除范围记录） |
|
||
| scope_type | VARCHAR(20) | NOT NULL, CHECK | `self` / `group` / `store` / `area` / `region` / `company` / `custom_unit` |
|
||
| org_unit_id | UUID | FK→org_units, RESTRICT | `scope_type='custom_unit'` 时必填，指向具体的组织节点；其他类型时 NULL（由 `staff.org_unit_id` 动态推导） |
|
||
| is_readable | BOOLEAN | NOT NULL DEFAULT TRUE | 可读 |
|
||
| is_writable | BOOLEAN | NOT NULL DEFAULT FALSE | 可写（默认只读） |
|
||
| granted_by | UUID | FK→staff, SET NULL | 授权操作人（管理员） |
|
||
| granted_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 授权时间（系统自动） |
|
||
| expires_at | TIMESTAMPTZ | | 临时授权失效时间 |
|
||
| reason | TEXT | | 授予原因 |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE INDEX idx_data_scopes_staff ON staff_data_scopes(staff_id);
|
||
CREATE INDEX idx_data_scopes_org ON staff_data_scopes(org_unit_id);
|
||
CREATE INDEX idx_data_scopes_expires ON staff_data_scopes(expires_at) WHERE expires_at IS NOT NULL;
|
||
```
|
||
|
||
**业务语义**：
|
||
- 员工的「管理范围」= 所有 `staff_data_scopes` 记录对应的 `org_units.path` 子树**并集**
|
||
- 支持"扩充范围"（PRD 5.3.3）：新增一条 `scope_type='custom_unit', org_unit_id=门店B` 记录
|
||
- 保底规则：员工至少有一条 `scope_type='self'` 的记录（入职时自动创建）
|
||
|
||
---
|
||
|
||
### 3.7 permission_change_logs — 权限变更流水（⭐ 新增，Issue #4）
|
||
|
||
> append-only，**不可删除**，对齐 `staff_transfer_logs` 范式。
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|---------|
|
||
| id | UUID | PK | 主键（系统生成，业务无关） |
|
||
| target_type | VARCHAR(30) | NOT NULL, CHECK | `role` / `role_permission` / `staff_role` / `staff_override` / `staff_scope` |
|
||
| target_id | UUID | NOT NULL | 被变更对象的 ID（上述各表的主键） |
|
||
| staff_id | UUID | FK→staff, SET NULL | 被影响员工（target 是 `staff_role/staff_override/staff_scope` 时必填，便于按员工查询） |
|
||
| role_id | UUID | FK→roles, SET NULL | 被影响角色（便于按角色查询） |
|
||
| permission_code | VARCHAR(150) | | 被变更的权限 code（用 code 而非 FK，避免 PermissionDef 删除后日志丢失） |
|
||
| action | VARCHAR(20) | NOT NULL, CHECK | `create` / `update` / `delete` / `assign` / `revoke` |
|
||
| old_value | JSONB | | 变更前快照 |
|
||
| new_value | JSONB | | 变更后快照 |
|
||
| operator_id | UUID | NOT NULL, FK→staff, RESTRICT | 操作人 |
|
||
| operator_ip | INET | | 操作来源 IP |
|
||
| user_agent | TEXT | | 操作终端 UA |
|
||
| reason | TEXT | | 操作原因（批量设置角色等场景强制填写） |
|
||
| operated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 操作时间（append-only流水，系统自动） |
|
||
| ⚠️ 无 deleted_at | — | — | 审计日志**不可删除** |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE INDEX idx_perm_log_staff ON permission_change_logs(staff_id, operated_at DESC) WHERE staff_id IS NOT NULL;
|
||
CREATE INDEX idx_perm_log_role ON permission_change_logs(role_id, operated_at DESC) WHERE role_id IS NOT NULL;
|
||
CREATE INDEX idx_perm_log_target ON permission_change_logs(target_type, target_id, operated_at DESC);
|
||
CREATE INDEX idx_perm_log_operator ON permission_change_logs(operator_id, operated_at DESC);
|
||
CREATE INDEX idx_perm_log_time ON permission_change_logs(operated_at DESC);
|
||
```
|
||
|
||
**分区建议**：数据量大（每次批量角色变更产生 N 条记录）时按 `operated_at` 月度 RANGE 分区。
|
||
|
||
---
|
||
|
||
## 四、枚举常量
|
||
|
||
### 4.1 PermissionModule — 一级模块（与 PRD 8.2 导航完全对齐）
|
||
|
||
```
|
||
home = 首页
|
||
property = 房源
|
||
new_house = 新房
|
||
client = 客源
|
||
transaction = 交易
|
||
data = 数据
|
||
marketing = 营销
|
||
hr = 人事OA
|
||
contract = 合同
|
||
trinet = 三网
|
||
system = 系统
|
||
mobile = 移动端
|
||
smart_store = 智能门店
|
||
recharge = 在线充值
|
||
```
|
||
|
||
### 4.2 ValueType — 权限值类型
|
||
|
||
| 值 | 存储格式 | UI 控件 | 示例 |
|
||
|----|---------|---------|------|
|
||
| `BOOLEAN` | `{"v": true}` | Toggle | 今日新上房源是否显示 |
|
||
| `SCOPE` | `{"v": "store"}` | 下拉选择 | 查看私客范围（本人/本组/本门店/本区域/全公司）|
|
||
| `INTEGER` | `{"v": 50}` | 数字输入 | 每日最多查看联系人数（0=不限制）|
|
||
|
||
### 4.3 RoleCategory — 角色类别
|
||
|
||
```
|
||
agent = 置业顾问（一线经纪人）
|
||
store_manager = 店管（店长/区域经理）
|
||
director = 总经（公司级管理）
|
||
operator = 运营/行政
|
||
custom = 自定义（不继承预设上限）
|
||
```
|
||
|
||
### 4.4 ScopeLevel — SCOPE 枚举有序值（用于多角色合并）
|
||
|
||
```
|
||
none = 0 无
|
||
self = 1 本人
|
||
group = 2 本组
|
||
store = 3 本门店
|
||
area = 4 本区域
|
||
region = 5 本大区
|
||
company = 6 全公司
|
||
```
|
||
|
||
---
|
||
|
||
## 五、权限解析与查询模式
|
||
|
||
### 5.1 员工权限解析流程（resolver）
|
||
|
||
```
|
||
输入: staff_id
|
||
Step 1: 若 staff.is_system_admin = TRUE → 返回 "全部权限=true，全部 SCOPE=company"（短路）
|
||
Step 2: 加载所有 staff_roles → role_ids
|
||
Step 3: 加载所有 role_permissions (role_id IN role_ids) 按 permission_def 分组
|
||
Step 4: 合并多角色值:
|
||
BOOLEAN → OR
|
||
SCOPE → MAX by ScopeLevel
|
||
INTEGER → MAX (0 视为 +∞)
|
||
Step 5: 填入未配置权限项的 default_value
|
||
Step 6: 叠加 staff_permission_overrides（按 override_mode 规则）:
|
||
REPLACE → 直接替换合并值
|
||
RESTRICT → min(override_value, merged_value)
|
||
GRANT → max(override_value, merged_value)
|
||
输出: { permission_code: {"v": value}, ... }
|
||
缓存: perm:v{CACHE_VERSION}:{schema}:{staff_id} (TTL=3600)
|
||
```
|
||
|
||
### 5.2 数据范围查询（ScopeQueryBuilder）
|
||
|
||
核心工具类，职责：将"SCOPE 权限值 + StaffDataScope"转为 Django ORM `Q` 对象。
|
||
|
||
```python
|
||
# apps/permissions/services/scope_query.py
|
||
|
||
from django.db.models import Q
|
||
|
||
class ScopeQueryBuilder:
|
||
"""
|
||
用法:
|
||
qs = Property.objects.all()
|
||
qs = ScopeQueryBuilder(staff, "property.list.view.scope", field_prefix="seller_agent")\
|
||
.apply_to(qs)
|
||
"""
|
||
def __init__(self, staff, permission_code: str, field_prefix: str):
|
||
self.staff = staff
|
||
self.perm_code = permission_code
|
||
self.field_prefix = field_prefix # e.g. "seller_agent" or "owner"
|
||
|
||
def build_q(self) -> Q:
|
||
# 1. 系统管理员短路
|
||
if self.staff.is_system_admin:
|
||
return Q() # no filter
|
||
|
||
# 2. 读取权限值
|
||
checker = PermissionChecker(self.staff)
|
||
scope = checker.get_scope(self.perm_code) # e.g. "store"
|
||
|
||
# 3. 构建 base Q（基于 SCOPE 值 + staff.org_unit.path 子树）
|
||
base_q = self._scope_to_q(scope)
|
||
|
||
# 4. 叠加 StaffDataScope 并集
|
||
for ds in StaffDataScope.objects.filter(staff=self.staff, is_readable=True):
|
||
base_q |= self._datascope_to_q(ds)
|
||
|
||
return base_q
|
||
|
||
def _scope_to_q(self, scope: str) -> Q:
|
||
"""将 SCOPE 枚举转为 Q，基于当前 staff 的 org_unit.path"""
|
||
prefix = self.field_prefix
|
||
if scope == "none":
|
||
return Q(pk__in=[]) # 永远为空
|
||
if scope == "self":
|
||
return Q(**{f"{prefix}_id": self.staff.id})
|
||
if scope == "group":
|
||
return Q(**{f"{prefix}__org_unit__path__startswith": self.staff.org_unit.path})
|
||
if scope in ("store", "area", "region"):
|
||
# 向上定位到对应层级节点
|
||
target_unit = self.staff.org_unit.ancestor_of_type(scope) # "store" → Store 节点
|
||
return Q(**{f"{prefix}__org_unit__path__startswith": target_unit.path})
|
||
if scope == "company":
|
||
return Q()
|
||
return Q(pk__in=[])
|
||
|
||
def apply_to(self, queryset):
|
||
q = self.build_q()
|
||
# 业务规则叠加：保护客过滤（客源场景）
|
||
if hasattr(queryset.model, "is_protected"):
|
||
q &= (Q(is_protected=False) | Q(owner_id=self.staff.id))
|
||
return queryset.filter(q)
|
||
```
|
||
|
||
### 5.3 「权限与角色不一致」标记
|
||
|
||
```sql
|
||
-- 批量标记逻辑（SQL 层，用于人员列表高频查询）
|
||
-- 某员工若存在任一 override 行，其 value != (其角色合并值)，则标记不一致
|
||
SELECT DISTINCT o.staff_id
|
||
FROM staff_permission_overrides o
|
||
JOIN permission_defs pd ON pd.id = o.permission_def_id
|
||
WHERE NOT EXISTS (
|
||
-- 简化示例：实际需在应用层对比合并结果
|
||
SELECT 1 FROM role_permissions rp
|
||
JOIN staff_roles sr ON sr.role_id = rp.role_id
|
||
WHERE sr.staff_id = o.staff_id
|
||
AND rp.permission_def_id = o.permission_def_id
|
||
AND rp.value = o.value
|
||
);
|
||
```
|
||
|
||
**实现建议**：查询时应用层计算，结果缓存到 `perm:inconsistent:{schema}:{staff_id}` (TTL=300)，变更时失效。
|
||
|
||
### 5.4 查询某角色的应用人数（PRD 5.5.1）
|
||
|
||
```sql
|
||
SELECT COUNT(DISTINCT staff_id) AS applied_count
|
||
FROM staff_roles
|
||
WHERE role_id = :role_id
|
||
AND (valid_until IS NULL OR valid_until >= CURRENT_DATE);
|
||
```
|
||
|
||
### 5.5 按模块懒加载权限面板（PRD 性能考量）
|
||
|
||
```sql
|
||
-- 一次只加载单模块的权限定义与当前角色/员工的值
|
||
SELECT pd.*, rp.value AS role_value, spo.value AS override_value
|
||
FROM permission_defs pd
|
||
LEFT JOIN role_permissions rp
|
||
ON rp.permission_def_id = pd.id AND rp.role_id = :role_id
|
||
LEFT JOIN staff_permission_overrides spo
|
||
ON spo.permission_def_id = pd.id AND spo.staff_id = :staff_id
|
||
WHERE pd.module = :module AND pd.is_active = TRUE
|
||
ORDER BY pd.sub_module, pd.group_name, pd.sort_order;
|
||
```
|
||
|
||
---
|
||
|
||
## 六、Redis 缓存策略
|
||
|
||
| Cache Key | TTL | 失效触发 |
|
||
|-----------|-----|---------|
|
||
| `perm:v{VER}:{schema}:{staff_id}` | 3600s | `invalidate_staff_cache()`：Override/StaffRole 变更 |
|
||
| `perm:v{VER}:{schema}:role:{role_id}:staff_ids` | 3600s | 角色权限变更时用 Pipeline 批量失效该 role 下所有 staff 缓存（Issue #8） |
|
||
| `perm:inconsistent:{schema}:{staff_id}` | 300s | 同上 |
|
||
| `perm:defs:{schema}` | 86400s | PermissionDef 变更（低频） |
|
||
| `perm:role_applied_count:{schema}:{role_id}` | 600s | StaffRole 变更 |
|
||
|
||
**版本号机制**（Issue #7）：`CACHE_VERSION` 在 Django settings 中，升级 PermissionDef 结构时 bump，一键全局失效。
|
||
|
||
**批量失效优化**：
|
||
```python
|
||
def invalidate_role_cache(role_id: int, tenant_schema: str):
|
||
staff_ids = StaffRole.objects.filter(role_id=role_id).values_list("staff_id", flat=True)
|
||
pipe = _redis.pipeline()
|
||
for sid in staff_ids:
|
||
pipe.delete(f"perm:v{CACHE_VERSION}:{tenant_schema}:{sid}")
|
||
pipe.delete(f"perm:inconsistent:{tenant_schema}:{sid}")
|
||
pipe.execute() # 单次往返
|
||
```
|
||
|
||
---
|
||
|
||
## 七、Django Model 要点
|
||
|
||
```python
|
||
# apps/permissions/models.py (精简示例，完整代码见 TECH_STACK/权限管理系统技术方案.md)
|
||
|
||
from django.db import models
|
||
from django.contrib.postgres.fields import ArrayField
|
||
from apps.core.models.base import TimeStampedModel, SoftDeleteModel
|
||
|
||
class ValueType(models.TextChoices):
|
||
BOOLEAN = "BOOLEAN", "开关型"
|
||
SCOPE = "SCOPE", "范围型"
|
||
INTEGER = "INTEGER", "数值型"
|
||
|
||
class ScopeLevel(models.IntegerChoices):
|
||
NONE = 0, "无"
|
||
SELF = 1, "本人"
|
||
GROUP = 2, "本组"
|
||
STORE = 3, "本门店"
|
||
AREA = 4, "本区域"
|
||
REGION = 5, "本大区"
|
||
COMPANY = 6, "全公司"
|
||
|
||
class PermissionDef(TimeStampedModel):
|
||
code = models.CharField(max_length=150, unique=True)
|
||
module = models.CharField(max_length=50)
|
||
sub_module = models.CharField(max_length=50, blank=True)
|
||
group_name = models.CharField(max_length=100)
|
||
name = models.CharField(max_length=200)
|
||
description = models.TextField(blank=True)
|
||
value_type = models.CharField(max_length=20, choices=ValueType.choices)
|
||
scope_choices = models.JSONField(default=list, blank=True)
|
||
integer_min = models.IntegerField(null=True, blank=True)
|
||
integer_max = models.IntegerField(null=True, blank=True)
|
||
default_value = models.JSONField(default=dict)
|
||
max_allowed_categories = ArrayField(models.CharField(max_length=50), default=list, blank=True)
|
||
sort_order = models.PositiveIntegerField(default=0)
|
||
is_active = models.BooleanField(default=True)
|
||
is_deprecated = models.BooleanField(default=False)
|
||
version = models.IntegerField(default=1)
|
||
|
||
class Meta:
|
||
db_table = "permission_defs"
|
||
indexes = [
|
||
models.Index(fields=["module", "sub_module", "sort_order"]),
|
||
]
|
||
|
||
# ... Role / RolePermission / StaffRole / StaffPermissionOverride / StaffDataScope
|
||
# ... PermissionChangeLog（append-only，override save() 禁止 update/delete）
|
||
```
|
||
|
||
---
|
||
|
||
## 八、关键业务规则与约束
|
||
|
||
### 8.1 批量设置角色（PRD Story 2）
|
||
|
||
```python
|
||
def bulk_assign_role(staff_ids: list, role_id: UUID, operator, override_individual=False):
|
||
"""
|
||
override_individual=True 时清除员工所有个人 Override（PRD 提示"将覆盖个人自定义权限"）
|
||
"""
|
||
with transaction.atomic():
|
||
# 1. 清除旧主角色
|
||
StaffRole.objects.filter(staff_id__in=staff_ids, is_primary=True).update(is_primary=False)
|
||
# 2. 批量 UPSERT 新主角色
|
||
for sid in staff_ids:
|
||
sr, _ = StaffRole.objects.update_or_create(
|
||
staff_id=sid, role_id=role_id,
|
||
defaults={"is_primary": True, "assigned_by": operator}
|
||
)
|
||
PermissionChangeLog.objects.create(
|
||
target_type="staff_role", target_id=sr.id,
|
||
staff_id=sid, role_id=role_id, action="assign",
|
||
operator_id=operator.id
|
||
)
|
||
# 3. 可选清除个人 Override
|
||
if override_individual:
|
||
StaffPermissionOverride.objects.filter(staff_id__in=staff_ids).delete()
|
||
# 4. 批量失效缓存
|
||
invalidate_staff_cache_batch(staff_ids, tenant_schema)
|
||
```
|
||
|
||
### 8.2 角色删除前置校验
|
||
|
||
```python
|
||
def delete_role(role: Role, operator):
|
||
applied_count = StaffRole.objects.filter(role=role).count()
|
||
if applied_count > 0:
|
||
raise ValidationError(f"无法删除：仍有 {applied_count} 位员工使用此角色，请先迁移")
|
||
if role.is_system_builtin:
|
||
raise ValidationError("系统内置角色不可删除")
|
||
role.deleted_at = timezone.now()
|
||
role.save()
|
||
PermissionChangeLog.objects.create(
|
||
target_type="role", target_id=role.id, role_id=role.id,
|
||
action="delete", operator_id=operator.id,
|
||
old_value={"name": role.name, "category": role.category}
|
||
)
|
||
```
|
||
|
||
### 8.3 角色类别与权限项的可配置约束（Issue #11）
|
||
|
||
```python
|
||
def get_editable_permissions_for_role(role: Role):
|
||
"""编辑角色权限时，只返回该角色类别允许配置的权限项"""
|
||
return PermissionDef.objects.filter(
|
||
is_active=True
|
||
).filter(
|
||
# max_allowed_categories 为空 或 包含当前角色类别
|
||
models.Q(max_allowed_categories=[]) |
|
||
models.Q(max_allowed_categories__contains=[role.category])
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 九、与现有 DATA_MODEL 的集成契约
|
||
|
||
| 接入点 | 契约 |
|
||
|--------|------|
|
||
| `Staff` | 新增 method `get_permission_checker()` 返回 `PermissionChecker` 实例 |
|
||
| `OrgUnit` | 新增 method `ancestor_of_type(type: str)` 返回指定类型的祖先节点（供 SCOPE → store/area 定位） |
|
||
| `Property.objects` | Manager 新增 `visible_to(staff)` 方法，内部用 `ScopeQueryBuilder` |
|
||
| `Client.objects` | 同上，额外 AND 保护客规则 |
|
||
| `apps/core/middleware` | Request 级注入 `request.permission_checker`，供 View/template 使用 |
|
||
|
||
---
|
||
|
||
## 十、禁止操作
|
||
|
||
- ❌ **严禁直接 INSERT/UPDATE `permission_change_logs` 跳过业务逻辑** — 所有权限变更必须通过 service 层触发日志写入
|
||
- ❌ **严禁 DELETE `permission_change_logs`** — 审计要求不可删除
|
||
- ❌ **严禁绕过 `ScopeQueryBuilder` 在 View 直接构造 Q** — 会导致越权漏洞，且无法统一审计
|
||
- ❌ **严禁在 Application 层假设 `default_value` 的具体值** — 所有判断必须经 `PermissionChecker`
|
||
- ❌ **严禁 `StaffPermissionOverride` 与 `RolePermission` 值完全相同的冗余记录** — 保存时必须先做差异对比（稀疏存储）
|
||
- ❌ **严禁硬删除 `PermissionDef`** — 设置 `is_active=FALSE`，历史数据依赖 `code` 保留
|
||
- ❌ **严禁修改 `PermissionDef.code`** — code 是业务代码的硬依赖，变更需走新建 code + 下线旧 code 流程
|
||
- ❌ **严禁修改 `StaffRole.is_primary`** 绕过唯一约束（必须通过 signal 维护）
|
||
- ❌ **严禁跨租户查询权限数据** — 所有查询必须通过 `django-tenants` 的 connection schema 路由
|
||
|
||
---
|
||
|
||
## 十一、数据量与性能预测
|
||
|
||
| 表 | 预估行数 | 增长 | 优化策略 |
|
||
|----|---------|------|---------|
|
||
| `permission_defs` | 300-500 | 低 | 全表缓存 |
|
||
| `roles` | 10-50 per tenant | 低 | 无需优化 |
|
||
| `role_permissions` | 50-150 per role | 低 | 按 role_id 聚合缓存 |
|
||
| `staff_roles` | 1-3 per staff | 低 | 主键即可 |
|
||
| `staff_permission_overrides` | 5-50 per staff（稀疏）| 中 | 按 staff_id 缓存 |
|
||
| `staff_data_scopes` | 1-5 per staff | 低 | 结合 org_units.path 查询 |
|
||
| `permission_change_logs` | 10万-100万+ | **高** | 月度 RANGE 分区，6个月前数据归档冷存储 |
|
||
|
||
---
|
||
|
||
## 十二、迁移与初始化清单
|
||
|
||
1. **Migration 001** — 创建 7 张核心表 + 索引 + 触发器
|
||
2. **Data Migration 002** — 从 `fixtures/permission_defs.json` 加载 300 条 PermissionDef 初始数据
|
||
3. **Data Migration 003** — 创建系统内置角色：`最大权限角色`（`is_system_builtin=TRUE`, category=`director`）
|
||
4. **Data Migration 004** — 为所有现有员工创建 `scope_type='self'` 的默认 DataScope
|
||
5. **Hook** — `Tenant.create` 后钩子自动执行 002/003/004
|
||
6. **信号注册** — Staff 创建时自动 DataScope=self；Role 权限变更 → 缓存失效；Override 保存 → 日志
|
||
7. **权限定义版本管理** — 新增 CLI：`python manage.py sync_permission_defs --fixture-version=1.2`
|
||
|
||
---
|
||
|
||
## 十三、开放问题与后续迭代
|
||
|
||
| 问题 | 建议方向 |
|
||
|------|---------|
|
||
| 权限申请工作流（PRD 非目标） | v2 引入 `permission_requests` 表 + 审批流引擎 |
|
||
| 行级权限（如指定小区的房源） | v2 基于 PostgreSQL RLS（Row-Level Security）或 Guardian |
|
||
| 权限变更日志看板（PRD 非目标） | v1.5 基于 `permission_change_logs` + Grafana |
|
||
| IP 白名单/登录时段 | v2 独立的"安全策略"模块 |
|
||
| 跨租户权限（加盟商/联合门店） | v3，需引入联邦身份方案 |
|
||
|
||
---
|
||
|
||
_本文档版本 v1.1 | 作者: Backend Architect | 更新时间 2026-04-24_
|
||
|
||
---
|
||
|
||
## 附录 A — 决策确认记录（v1.1 追加）
|
||
|
||
| 议题 | 决策 | 日期 | 说明 |
|
||
|------|------|------|------|
|
||
| **Issue #3**：`permission_defs` 归属 schema | ✅ **`tenant_apps`（每租户独立）** | 2026-04-24 | 避免 django-tenants 跨 schema FK 限制；预留"企业版自定义权限项"能力；通过 `Tenant.create` 后钩子 seed 初始 300 条 |
|
||
| **Issue #6**：`staff_permission_overrides.override_mode` 默认值 | ✅ **`REPLACE`** | 2026-04-24 | 契合 PRD "个人特殊授权" 语义；管理员若需限制/扩展可显式选择 RESTRICT/GRANT |
|
||
|
||
---
|
||
|
||
## 附录 B — PermissionDef 种子数据样例
|
||
|
||
> 完整 fixture（约 300 条）待 Django 项目 bootstrap 后落地至 `apps/permissions/fixtures/permission_defs.json`。
|
||
> 本附录仅给出**代表性条目**（覆盖 BOOLEAN/SCOPE/INTEGER 三种 value_type + 主要模块）作为结构模板与 code 命名规范参考。
|
||
|
||
```json
|
||
[
|
||
{
|
||
"code": "home.today_new_property.show",
|
||
"module": "home",
|
||
"sub_module": "",
|
||
"group_name": "首页基础权限",
|
||
"name": "今日新上房源是否显示",
|
||
"description": "控制首页小组件「今日新上」房源是否对该用户可见",
|
||
"value_type": "BOOLEAN",
|
||
"default_value": {"v": true},
|
||
"max_allowed_categories": [],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "property.list.view.scope",
|
||
"module": "property",
|
||
"sub_module": "二手&租赁",
|
||
"group_name": "房源列表权限",
|
||
"name": "查看房源范围",
|
||
"description": "控制房源列表页可见的数据范围；与保护房业务规则叠加生效",
|
||
"value_type": "SCOPE",
|
||
"scope_choices": ["none", "self", "group", "store", "area", "region", "company"],
|
||
"default_value": {"v": "self"},
|
||
"max_allowed_categories": [],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "property.list.export.scope",
|
||
"module": "property",
|
||
"sub_module": "二手&租赁",
|
||
"group_name": "房源列表权限",
|
||
"name": "导出房源范围",
|
||
"value_type": "SCOPE",
|
||
"scope_choices": ["none", "self", "store", "company"],
|
||
"default_value": {"v": "none"},
|
||
"max_allowed_categories": ["store_manager", "director"],
|
||
"sort_order": 20
|
||
},
|
||
{
|
||
"code": "property.owner_phone.view.daily_limit",
|
||
"module": "property",
|
||
"sub_module": "二手&租赁",
|
||
"group_name": "房源隐私权限",
|
||
"name": "每日查看业主电话次数上限",
|
||
"description": "0 表示不限制；达到上限后次日自然恢复",
|
||
"value_type": "INTEGER",
|
||
"integer_min": 0,
|
||
"integer_max": 999,
|
||
"default_value": {"v": 20},
|
||
"max_allowed_categories": [],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "client.private.view.scope",
|
||
"module": "client",
|
||
"sub_module": "私客",
|
||
"group_name": "私客基础权限",
|
||
"name": "查看私客范围",
|
||
"description": "与保护客规则叠加：非 owner/合保人即使有 store 权限也不可见保护客",
|
||
"value_type": "SCOPE",
|
||
"scope_choices": ["none", "self", "group", "store", "area", "region", "company"],
|
||
"default_value": {"v": "self"},
|
||
"max_allowed_categories": [],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "client.private.transfer.allow",
|
||
"module": "client",
|
||
"sub_module": "私客",
|
||
"group_name": "私客操作权限",
|
||
"name": "是否允许转移私客",
|
||
"value_type": "BOOLEAN",
|
||
"default_value": {"v": false},
|
||
"max_allowed_categories": ["store_manager", "director"],
|
||
"sort_order": 20
|
||
},
|
||
{
|
||
"code": "transaction.contract.approve.allow",
|
||
"module": "transaction",
|
||
"sub_module": "合同",
|
||
"group_name": "合同审批权限",
|
||
"name": "是否可审批合同",
|
||
"value_type": "BOOLEAN",
|
||
"default_value": {"v": false},
|
||
"max_allowed_categories": ["store_manager", "director"],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "data.report.performance.view.scope",
|
||
"module": "data",
|
||
"sub_module": "业绩报表",
|
||
"group_name": "业绩数据权限",
|
||
"name": "业绩报表可见范围",
|
||
"value_type": "SCOPE",
|
||
"scope_choices": ["none", "self", "group", "store", "area", "company"],
|
||
"default_value": {"v": "self"},
|
||
"max_allowed_categories": [],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "hr.staff.create.allow",
|
||
"module": "hr",
|
||
"sub_module": "员工管理",
|
||
"group_name": "员工操作权限",
|
||
"name": "是否可新建员工",
|
||
"value_type": "BOOLEAN",
|
||
"default_value": {"v": false},
|
||
"max_allowed_categories": ["store_manager", "director", "operator"],
|
||
"sort_order": 10
|
||
},
|
||
{
|
||
"code": "system.role.manage.allow",
|
||
"module": "system",
|
||
"sub_module": "权限管理",
|
||
"group_name": "角色管理权限",
|
||
"name": "是否可管理角色与权限",
|
||
"description": "授予此权限者可进入角色管理页；系统管理员 is_system_admin=TRUE 自动拥有",
|
||
"value_type": "BOOLEAN",
|
||
"default_value": {"v": false},
|
||
"max_allowed_categories": ["director", "operator"],
|
||
"sort_order": 10
|
||
}
|
||
]
|
||
```
|
||
|
||
**Seed 覆盖清单**（Django 项目落地时需补齐）：
|
||
|
||
| 模块 | 预计条目数 | 典型权限项 |
|
||
|------|-----------|-----------|
|
||
| home | ~15 | 小组件显示/隐藏开关 |
|
||
| property | ~60 | 列表/详情/导出/隐私/分享/操作 × SCOPE/BOOLEAN |
|
||
| new_house | ~30 | 楼盘/房型/佣金/报备 |
|
||
| client | ~50 | 私客/公客/保护客 × 查看/转移/释放/导出 |
|
||
| transaction | ~40 | 合同/审批/佣金/收付款 |
|
||
| data | ~30 | 业绩/排行/漏斗/业务报表 |
|
||
| marketing | ~20 | 营销活动/素材/投放 |
|
||
| hr | ~25 | 员工/组织/考勤/调整 |
|
||
| contract/trinet/system/mobile/smart_store/recharge | ~30 | 模块特定 |
|
||
| **合计** | **~300** | |
|
||
|
||
---
|
||
|
||
## 附录 C — Migration DDL 草图
|
||
|
||
> 以下为 Django migration 的 **等价 DDL**，用于评审与 DBA 沟通。实际实现以 `apps/permissions/migrations/000X_*.py` 为准。
|
||
|
||
### C.1 Migration 0001 — 核心 7 张表
|
||
|
||
```sql
|
||
-- permission_defs
|
||
CREATE TABLE permission_defs (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||
code VARCHAR(150) NOT NULL UNIQUE, -- 权限码，格式 {module}.{sub_module}.{action}[.{qualifier}]，全局唯一，创建后不可修改
|
||
module VARCHAR(50) NOT NULL, -- 一级模块标识，如 property / client / org
|
||
sub_module VARCHAR(50) NOT NULL DEFAULT '', -- 二级子模块标识；无子模块时为空字符串
|
||
group_name VARCHAR(100) NOT NULL, -- 权限分组显示名称（管理界面分组展示用）
|
||
name VARCHAR(200) NOT NULL, -- 权限项中文名称（管理界面展示）
|
||
description TEXT NOT NULL DEFAULT '', -- 权限项说明（管理界面 tooltip 文案）
|
||
value_type VARCHAR(20) NOT NULL CHECK (value_type IN ('BOOLEAN','SCOPE','INTEGER')), -- 权限值类型：BOOLEAN=开关 / SCOPE=数据范围 / INTEGER=数量上限
|
||
scope_choices JSONB NOT NULL DEFAULT '[]'::jsonb, -- SCOPE 类型可选范围列表（JSON 数组）；非 SCOPE 类型为空数组
|
||
integer_min INTEGER, -- INTEGER 类型最小允许值；其他类型为 NULL
|
||
integer_max INTEGER, -- INTEGER 类型最大允许值；其他类型为 NULL
|
||
default_value JSONB NOT NULL DEFAULT '{"v":false}'::jsonb, -- 权限默认值，格式 {"v": false/scope_str/int}
|
||
max_allowed_categories VARCHAR(50)[] NOT NULL DEFAULT ARRAY[]::VARCHAR[], -- 可配置此权限的角色分类白名单；空数组=无限制
|
||
sort_order INTEGER NOT NULL DEFAULT 0, -- 同分组内排序权重（数值越小越靠前）
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE, -- 是否启用；FALSE=已下线，前端配置页隐藏
|
||
is_deprecated BOOLEAN NOT NULL DEFAULT FALSE, -- 是否已废弃；废弃后不可被新角色引用
|
||
version INTEGER NOT NULL DEFAULT 1, -- 乐观锁版本号（每次更新+1）
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||
CONSTRAINT chk_code_format CHECK (code ~ '^[a-z_]+\.[a-z_]+(\.[a-z_]+){1,2}$')
|
||
);
|
||
CREATE INDEX idx_permission_defs_module ON permission_defs(module, sub_module, sort_order) WHERE is_active = TRUE;
|
||
CREATE INDEX idx_permission_defs_active ON permission_defs(is_active) WHERE is_active = TRUE;
|
||
|
||
-- roles
|
||
CREATE TABLE roles (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||
name VARCHAR(100) NOT NULL, -- 角色显示名称（同租户内唯一，软删除后不参与唯一性校验）
|
||
category VARCHAR(30) NOT NULL CHECK (category IN ('agent','store_manager','director','operator','custom')), -- 角色分类：agent=经纪人 / store_manager=门店管理 / director=区域管理 / operator=运营职能 / custom=自定义
|
||
description TEXT NOT NULL DEFAULT '', -- 角色说明文案
|
||
template_role_id UUID REFERENCES roles(id) ON DELETE SET NULL, -- 模板来源（自引用）；从某内置角色克隆时记录；NULL=无模板
|
||
is_system_builtin BOOLEAN NOT NULL DEFAULT FALSE, -- 是否系统内置角色；TRUE=不可删除、不可改名
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE, -- 是否启用；FALSE=角色已停用，员工不可再分配此角色
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 创建人（关联 staff 表）；系统内置角色为 NULL
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 最后修改人（关联 staff 表）
|
||
deleted_at TIMESTAMPTZ -- 软删除时间戳，NULL=未删除，非NULL=已软删除
|
||
);
|
||
CREATE UNIQUE INDEX idx_roles_name_active ON roles(name) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_roles_category ON roles(category) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_roles_template ON roles(template_role_id);
|
||
|
||
-- role_permissions
|
||
CREATE TABLE role_permissions (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||
role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE, -- 关联角色（角色删除则权限配置同步级联清除）
|
||
permission_def_id UUID NOT NULL REFERENCES permission_defs(id) ON DELETE RESTRICT, -- 关联权限定义（有角色引用时权限项不可删除）
|
||
value JSONB NOT NULL, -- 权限配置值，格式 {"v": false/scope_str/int}，与 permission_defs.value_type 对应
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 最后修改人（关联 staff 表）
|
||
);
|
||
CREATE UNIQUE INDEX idx_role_permissions_uniq ON role_permissions(role_id, permission_def_id);
|
||
CREATE INDEX idx_role_permissions_role ON role_permissions(role_id);
|
||
CREATE INDEX idx_role_permissions_def ON role_permissions(permission_def_id);
|
||
|
||
-- staff_roles
|
||
CREATE TABLE staff_roles (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE, -- 员工 ID（员工删除则角色分配同步级联删除）
|
||
role_id UUID NOT NULL REFERENCES roles(id) ON DELETE RESTRICT, -- 角色 ID（有员工使用的角色不可删除）
|
||
is_primary BOOLEAN NOT NULL DEFAULT FALSE, -- 是否主角色；每员工同时仅可有 1 个主角色（唯一索引保障）
|
||
assigned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 角色分配时间（系统自动）
|
||
assigned_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 分配操作人（关联 staff 表）；NULL=系统自动分配
|
||
valid_from DATE, -- 角色有效期开始日期；NULL=立即生效
|
||
valid_until DATE -- 角色有效期结束日期；NULL=永久有效
|
||
);
|
||
CREATE UNIQUE INDEX idx_staff_roles_uniq ON staff_roles(staff_id, role_id);
|
||
CREATE UNIQUE INDEX idx_staff_roles_primary ON staff_roles(staff_id) WHERE is_primary = TRUE;
|
||
CREATE INDEX idx_staff_roles_role ON staff_roles(role_id);
|
||
|
||
-- staff_permission_overrides
|
||
CREATE TABLE staff_permission_overrides (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE, -- 员工 ID（员工删除则个人覆盖配置同步级联删除）
|
||
permission_def_id UUID NOT NULL REFERENCES permission_defs(id) ON DELETE RESTRICT, -- 关联权限定义
|
||
value JSONB NOT NULL, -- 覆盖配置值，格式与 role_permissions.value 一致
|
||
override_mode VARCHAR(10) NOT NULL DEFAULT 'REPLACE'
|
||
CHECK (override_mode IN ('REPLACE','RESTRICT','GRANT')), -- 覆盖模式：REPLACE=完全替换角色权限 / RESTRICT=向下收紧 / GRANT=向上提升
|
||
reason TEXT NOT NULL DEFAULT '', -- 覆盖理由（操作审计留存）
|
||
modified_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 修改操作人（关联 staff 表）
|
||
modified_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 修改时间（系统自动）
|
||
);
|
||
CREATE UNIQUE INDEX idx_staff_overrides_uniq ON staff_permission_overrides(staff_id, permission_def_id);
|
||
CREATE INDEX idx_staff_overrides_staff ON staff_permission_overrides(staff_id);
|
||
|
||
-- staff_data_scopes
|
||
CREATE TABLE staff_data_scopes (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE, -- 员工 ID
|
||
scope_type VARCHAR(20) NOT NULL -- 数据范围类型：self=本人 / group=小组 / store=门店 / area=大区 / region=区域 / company=全公司 / custom_unit=自定义单元
|
||
CHECK (scope_type IN ('self','group','store','area','region','company','custom_unit')),
|
||
org_unit_id UUID REFERENCES org_units(id) ON DELETE RESTRICT, -- 自定义组织单元；scope_type=custom_unit 时必填，其他为 NULL
|
||
is_readable BOOLEAN NOT NULL DEFAULT TRUE, -- 是否有读权限
|
||
is_writable BOOLEAN NOT NULL DEFAULT FALSE, -- 是否有写权限
|
||
granted_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 授权操作人（关联 staff 表）
|
||
granted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 授权时间（系统自动）
|
||
expires_at TIMESTAMPTZ, -- 到期时间；NULL=永久有效
|
||
reason TEXT NOT NULL DEFAULT '', -- 数据范围授权理由（操作审计留存）
|
||
CONSTRAINT chk_custom_unit_has_org CHECK (
|
||
(scope_type = 'custom_unit' AND org_unit_id IS NOT NULL) OR
|
||
(scope_type <> 'custom_unit')
|
||
)
|
||
);
|
||
CREATE INDEX idx_data_scopes_staff ON staff_data_scopes(staff_id);
|
||
CREATE INDEX idx_data_scopes_org ON staff_data_scopes(org_unit_id);
|
||
CREATE INDEX idx_data_scopes_expires ON staff_data_scopes(expires_at) WHERE expires_at IS NOT NULL;
|
||
|
||
-- permission_change_logs (append-only, no deleted_at)
|
||
CREATE TABLE permission_change_logs (
|
||
id UUID NOT NULL DEFAULT gen_random_uuid(), -- 主键（与 operated_at 组成复合主键，分区表要求）
|
||
operated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 分区键（原 operated_at 前置）
|
||
target_type VARCHAR(30) NOT NULL -- 操作对象类型：role / role_permission / staff_role / staff_override / staff_scope
|
||
CHECK (target_type IN ('role','role_permission','staff_role','staff_override','staff_scope')),
|
||
target_id UUID NOT NULL, -- 操作对象 ID
|
||
staff_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 被操作员工 ID（如分配/撤销角色时的目标员工）
|
||
role_id UUID REFERENCES roles(id) ON DELETE SET NULL, -- 被操作角色 ID
|
||
permission_code VARCHAR(150), -- 操作涉及的权限码（冗余存储，避免关联查询）
|
||
action VARCHAR(20) NOT NULL -- 操作类型：create=新建 / update=修改 / delete=删除 / assign=分配 / revoke=撤销
|
||
CHECK (action IN ('create','update','delete','assign','revoke')),
|
||
old_value JSONB, -- 变更前值；create 时为 NULL
|
||
new_value JSONB, -- 变更后值；delete 时为 NULL
|
||
operator_id UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT, -- 操作人员工 ID（RESTRICT：操作记录保留，操作人不可删除）
|
||
operator_ip INET, -- 操作人来源 IP
|
||
user_agent TEXT, -- 操作人客户端 UA
|
||
reason TEXT NOT NULL DEFAULT '', -- 操作理由（可选，审计留存）
|
||
|
||
PRIMARY KEY (id, operated_at) -- 分区表主键必须包含分区键
|
||
) PARTITION BY RANGE (operated_at);
|
||
|
||
CREATE TABLE permission_change_logs_2026_04 PARTITION OF permission_change_logs
|
||
FOR VALUES FROM ('2026-04-01') TO ('2026-05-01');
|
||
CREATE TABLE permission_change_logs_2026_05 PARTITION OF permission_change_logs
|
||
FOR VALUES FROM ('2026-05-01') TO ('2026-06-01');
|
||
CREATE TABLE permission_change_logs_default PARTITION OF permission_change_logs DEFAULT;
|
||
CREATE INDEX idx_perm_log_staff ON permission_change_logs(staff_id, operated_at DESC) WHERE staff_id IS NOT NULL;
|
||
CREATE INDEX idx_perm_log_role ON permission_change_logs(role_id, operated_at DESC) WHERE role_id IS NOT NULL;
|
||
CREATE INDEX idx_perm_log_target ON permission_change_logs(target_type, target_id, operated_at DESC);
|
||
CREATE INDEX idx_perm_log_operator ON permission_change_logs(operator_id, operated_at DESC);
|
||
CREATE INDEX idx_perm_log_time ON permission_change_logs(operated_at DESC);
|
||
|
||
-- 拒绝 UPDATE/DELETE 的 rule（兜底，应用层已禁止）
|
||
CREATE RULE no_update_perm_log AS ON UPDATE TO permission_change_logs DO INSTEAD NOTHING;
|
||
CREATE RULE no_delete_perm_log AS ON DELETE TO permission_change_logs DO INSTEAD NOTHING;
|
||
```
|
||
|
||
### C.2 Migration 0002 — Seed PermissionDef（data migration）
|
||
|
||
```python
|
||
# 伪代码
|
||
def forwards(apps, schema_editor):
|
||
PermissionDef = apps.get_model("permissions", "PermissionDef")
|
||
data = json.load(open("apps/permissions/fixtures/permission_defs.json"))
|
||
PermissionDef.objects.bulk_create([PermissionDef(**row) for row in data])
|
||
```
|
||
|
||
### C.3 Migration 0003 — Seed 系统内置角色
|
||
|
||
```python
|
||
def forwards(apps, schema_editor):
|
||
Role = apps.get_model("permissions", "Role")
|
||
RolePermission = apps.get_model("permissions", "RolePermission")
|
||
PermissionDef = apps.get_model("permissions", "PermissionDef")
|
||
|
||
super_role = Role.objects.create(
|
||
name="最大权限角色",
|
||
category="director",
|
||
is_system_builtin=True,
|
||
description="系统内置，拥有所有权限项的最高值"
|
||
)
|
||
# 将所有 SCOPE 权限设为 company，所有 BOOLEAN 设为 true，所有 INTEGER 设为 0(不限)
|
||
rows = []
|
||
for pd in PermissionDef.objects.filter(is_active=True):
|
||
if pd.value_type == "BOOLEAN":
|
||
v = {"v": True}
|
||
elif pd.value_type == "SCOPE":
|
||
v = {"v": "company"}
|
||
else:
|
||
v = {"v": 0}
|
||
if v == pd.default_value:
|
||
continue # 稀疏存储
|
||
rows.append(RolePermission(role=super_role, permission_def=pd, value=v))
|
||
RolePermission.objects.bulk_create(rows)
|
||
```
|
||
|
||
### C.4 Migration 0004 — 为现有员工创建默认 DataScope(self)
|
||
|
||
```python
|
||
def forwards(apps, schema_editor):
|
||
Staff = apps.get_model("org", "Staff")
|
||
StaffDataScope = apps.get_model("permissions", "StaffDataScope")
|
||
rows = [
|
||
StaffDataScope(staff_id=sid, scope_type="self", is_readable=True, is_writable=True, reason="初始化")
|
||
for sid in Staff.objects.values_list("id", flat=True)
|
||
]
|
||
StaffDataScope.objects.bulk_create(rows, ignore_conflicts=True)
|
||
```
|
||
|
||
### C.5 Tenant.create 后钩子
|
||
|
||
```python
|
||
# apps/tenants/signals.py
|
||
from django_tenants.utils import tenant_context
|
||
|
||
@receiver(post_save, sender=Tenant)
|
||
def init_tenant_permissions(sender, instance, created, **kwargs):
|
||
if not created:
|
||
return
|
||
with tenant_context(instance):
|
||
call_command("migrate", "permissions") # 0001
|
||
call_command("loaddata", "permission_defs") # 等价于 0002
|
||
seed_builtin_roles() # 0003 逻辑
|
||
seed_default_data_scopes() # 0004 逻辑
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 D — PermissionChecker 伪代码
|
||
|
||
```python
|
||
# apps/permissions/services/checker.py
|
||
|
||
from dataclasses import dataclass
|
||
from django.core.cache import cache
|
||
from django.conf import settings
|
||
|
||
CACHE_VERSION = getattr(settings, "PERMISSION_CACHE_VERSION", 1)
|
||
|
||
@dataclass
|
||
class ResolvedValue:
|
||
code: str
|
||
value_type: str # BOOLEAN / SCOPE / INTEGER
|
||
value: object # bool / str / int
|
||
source: str # "admin_shortcircuit" / "override" / "role_merge" / "default"
|
||
|
||
class PermissionChecker:
|
||
def __init__(self, staff):
|
||
self.staff = staff
|
||
self._resolved: dict[str, ResolvedValue] | None = None
|
||
|
||
# ---------- 公共 API ----------
|
||
def has(self, code: str) -> bool:
|
||
r = self._get(code)
|
||
if r.value_type == "BOOLEAN":
|
||
return bool(r.value)
|
||
if r.value_type == "SCOPE":
|
||
return r.value != "none"
|
||
if r.value_type == "INTEGER":
|
||
return r.value != 0 and r.value is not None
|
||
return False
|
||
|
||
def get_scope(self, code: str) -> str:
|
||
r = self._get(code)
|
||
assert r.value_type == "SCOPE"
|
||
return r.value
|
||
|
||
def get_int(self, code: str) -> int:
|
||
r = self._get(code)
|
||
assert r.value_type == "INTEGER"
|
||
return r.value
|
||
|
||
# ---------- 解析核心 ----------
|
||
def _get(self, code: str) -> ResolvedValue:
|
||
if self._resolved is None:
|
||
self._resolved = self._resolve_all()
|
||
if code not in self._resolved:
|
||
raise KeyError(f"Unknown permission code: {code}")
|
||
return self._resolved[code]
|
||
|
||
def _resolve_all(self) -> dict[str, ResolvedValue]:
|
||
# 1) 系统管理员短路
|
||
if self.staff.is_system_admin:
|
||
return self._build_admin_values()
|
||
|
||
# 2) Redis cache
|
||
schema = connection.schema_name
|
||
key = f"perm:v{CACHE_VERSION}:{schema}:{self.staff.id}"
|
||
cached = cache.get(key)
|
||
if cached:
|
||
return cached
|
||
|
||
# 3) 加载所有 PermissionDef
|
||
defs = {pd.code: pd for pd in PermissionDef.objects.filter(is_active=True)}
|
||
|
||
# 4) 加载员工所有角色权限值
|
||
role_ids = list(StaffRole.objects.filter(staff=self.staff).values_list("role_id", flat=True))
|
||
role_values: dict[str, list] = {} # code -> [value, value, ...]
|
||
qs = RolePermission.objects.filter(role_id__in=role_ids).select_related("permission_def")
|
||
for rp in qs:
|
||
role_values.setdefault(rp.permission_def.code, []).append(rp.value["v"])
|
||
|
||
# 5) 合并多角色值
|
||
resolved: dict[str, ResolvedValue] = {}
|
||
for code, pd in defs.items():
|
||
values = role_values.get(code, [])
|
||
if not values:
|
||
merged = pd.default_value["v"]
|
||
source = "default"
|
||
else:
|
||
merged = self._merge(pd.value_type, values)
|
||
source = "role_merge"
|
||
resolved[code] = ResolvedValue(code, pd.value_type, merged, source)
|
||
|
||
# 6) 叠加 Override
|
||
overrides = StaffPermissionOverride.objects.filter(staff=self.staff).select_related("permission_def")
|
||
for o in overrides:
|
||
code = o.permission_def.code
|
||
current = resolved[code]
|
||
new_val = self._apply_override(current, o.value["v"], o.override_mode)
|
||
resolved[code] = ResolvedValue(code, current.value_type, new_val, "override")
|
||
|
||
# 7) 缓存
|
||
cache.set(key, resolved, timeout=3600)
|
||
return resolved
|
||
|
||
@staticmethod
|
||
def _merge(value_type: str, values: list):
|
||
if value_type == "BOOLEAN":
|
||
return any(values)
|
||
if value_type == "SCOPE":
|
||
return max(values, key=lambda s: SCOPE_LEVEL[s])
|
||
if value_type == "INTEGER":
|
||
# 0 视为 +∞
|
||
if 0 in values:
|
||
return 0
|
||
return max(values)
|
||
|
||
@staticmethod
|
||
def _apply_override(current: ResolvedValue, ov: object, mode: str):
|
||
if mode == "REPLACE":
|
||
return ov
|
||
if mode == "RESTRICT":
|
||
if current.value_type == "BOOLEAN":
|
||
return current.value and ov
|
||
if current.value_type == "SCOPE":
|
||
return min([current.value, ov], key=lambda s: SCOPE_LEVEL[s])
|
||
if current.value_type == "INTEGER":
|
||
# 0=+∞，RESTRICT 取最小正值
|
||
a, b = current.value, ov
|
||
if a == 0: return b
|
||
if b == 0: return a
|
||
return min(a, b)
|
||
if mode == "GRANT":
|
||
if current.value_type == "BOOLEAN":
|
||
return current.value or ov
|
||
if current.value_type == "SCOPE":
|
||
return max([current.value, ov], key=lambda s: SCOPE_LEVEL[s])
|
||
if current.value_type == "INTEGER":
|
||
if 0 in (current.value, ov): return 0
|
||
return max(current.value, ov)
|
||
|
||
def _build_admin_values(self) -> dict[str, ResolvedValue]:
|
||
defs = PermissionDef.objects.filter(is_active=True)
|
||
out = {}
|
||
for pd in defs:
|
||
if pd.value_type == "BOOLEAN":
|
||
v = True
|
||
elif pd.value_type == "SCOPE":
|
||
v = "company"
|
||
else:
|
||
v = 0
|
||
out[pd.code] = ResolvedValue(pd.code, pd.value_type, v, "admin_shortcircuit")
|
||
return out
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 E — 缓存失效服务
|
||
|
||
```python
|
||
# apps/permissions/services/cache.py
|
||
|
||
from django.db import connection
|
||
from django.core.cache import cache
|
||
from django.conf import settings
|
||
|
||
CACHE_VERSION = getattr(settings, "PERMISSION_CACHE_VERSION", 1)
|
||
|
||
def _schema() -> str:
|
||
return connection.schema_name
|
||
|
||
def invalidate_staff(staff_id) -> None:
|
||
s = _schema()
|
||
cache.delete_many([
|
||
f"perm:v{CACHE_VERSION}:{s}:{staff_id}",
|
||
f"perm:inconsistent:{s}:{staff_id}",
|
||
])
|
||
|
||
def invalidate_staff_batch(staff_ids) -> None:
|
||
s = _schema()
|
||
keys = []
|
||
for sid in staff_ids:
|
||
keys.append(f"perm:v{CACHE_VERSION}:{s}:{sid}")
|
||
keys.append(f"perm:inconsistent:{s}:{sid}")
|
||
cache.delete_many(keys)
|
||
|
||
def invalidate_role(role_id) -> None:
|
||
"""角色权限变更 → 该角色下所有员工缓存失效"""
|
||
from apps.permissions.models import StaffRole
|
||
staff_ids = list(
|
||
StaffRole.objects.filter(role_id=role_id).values_list("staff_id", flat=True)
|
||
)
|
||
invalidate_staff_batch(staff_ids)
|
||
s = _schema()
|
||
cache.delete(f"perm:v{CACHE_VERSION}:{s}:role:{role_id}:staff_ids")
|
||
cache.delete(f"perm:role_applied_count:{s}:{role_id}")
|
||
|
||
def invalidate_all_tenant() -> None:
|
||
"""极端情况（PermissionDef 批量变更）— 走版本号 bump 更高效"""
|
||
cache.delete(f"perm:defs:{_schema()}")
|
||
# 不推荐遍历删除；生产上应 bump settings.PERMISSION_CACHE_VERSION
|
||
```
|
||
|
||
**信号连接**（在 `apps.py` ready() 中注册）：
|
||
|
||
| 信号 | 触发失效 |
|
||
|------|---------|
|
||
| `post_save` / `post_delete` on `RolePermission` | `invalidate_role(instance.role_id)` |
|
||
| `post_save` / `post_delete` on `StaffRole` | `invalidate_staff(instance.staff_id)` + 角色应用数缓存 |
|
||
| `post_save` / `post_delete` on `StaffPermissionOverride` | `invalidate_staff(instance.staff_id)` |
|
||
| `post_save` / `post_delete` on `StaffDataScope` | `invalidate_staff(instance.staff_id)` |
|
||
| `post_save` on `PermissionDef` (version bump) | `invalidate_all_tenant()` + 建议 bump `CACHE_VERSION` |
|
||
|
||
---
|
||
|
||
## 附录 F — Manager 扩展（Property / Client）
|
||
|
||
> 契合 §九集成契约，提供对外统一的 `visible_to(staff)` 入口，**禁止业务代码直接写过滤 Q**。
|
||
|
||
```python
|
||
# apps/property/managers.py
|
||
from django.db import models
|
||
from apps.permissions.services.scope_query import ScopeQueryBuilder
|
||
|
||
class PropertyQuerySet(models.QuerySet):
|
||
def visible_to(self, staff):
|
||
return ScopeQueryBuilder(
|
||
staff=staff,
|
||
permission_code="property.list.view.scope",
|
||
field_prefix="seller_agent",
|
||
).apply_to(self)
|
||
|
||
def writable_by(self, staff):
|
||
# 编辑权限：基于同一 scope 字段 + property.list.edit.allow BOOLEAN
|
||
checker = staff.get_permission_checker()
|
||
if not checker.has("property.list.edit.allow"):
|
||
return self.none()
|
||
return self.visible_to(staff)
|
||
|
||
class PropertyManager(models.Manager.from_queryset(PropertyQuerySet)):
|
||
pass
|
||
|
||
|
||
# apps/client/managers.py
|
||
class ClientQuerySet(models.QuerySet):
|
||
def visible_to(self, staff):
|
||
# ScopeQueryBuilder.apply_to() 内部已处理 is_protected 过滤
|
||
return ScopeQueryBuilder(
|
||
staff=staff,
|
||
permission_code="client.private.view.scope",
|
||
field_prefix="owner",
|
||
).apply_to(self)
|
||
```
|
||
|
||
**使用示例**：
|
||
|
||
```python
|
||
# views.py
|
||
def property_list(request):
|
||
qs = Property.objects.visible_to(request.staff)
|
||
# ... 继续其他业务过滤 ...
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 G — 验收 Checklist（开发启动前）
|
||
|
||
- [x] Issue #3 决策：`permission_defs` 归属 `tenant_apps`
|
||
- [x] Issue #6 决策：override 默认 `REPLACE`
|
||
- [ ] 完整 `permission_defs.json` fixture（~300 条）落地
|
||
- [ ] Migration 0001-0004 实现并 dry-run 通过
|
||
- [ ] `Tenant.create` post_save signal 接入 seed 逻辑
|
||
- [ ] `PermissionChecker` / `ScopeQueryBuilder` / 缓存失效服务单测覆盖 ≥ 80%
|
||
- [ ] `Property` / `Client` Manager 接入 `visible_to`
|
||
- [ ] `staff.is_system_admin=TRUE` 短路逻辑 e2e 测试
|
||
- [ ] 保护客/保护房过滤规则 e2e 测试
|
||
- [ ] `permission_change_logs` 禁止 UPDATE/DELETE 的数据库级 RULE 验证
|
||
|
||
---
|
||
|
||
_v1.1 追加: 附录 A-G | 2026-04-24_
|