zt-dsc/zt-framework/zt-spring-boot-starter-biz-data-permission/docs/数据权限忽略与上下文说明.md

数据权限忽略与上下文覆盖说明

本文说明新增的公司/部门数据权限忽略能力，以及部门上下文对数据权限的覆盖策略。

新增注解

• @CompanyDataPermissionIgnore(enable = "true")
• @DeptDataPermissionIgnore(enable = "true")

用法：

• 可标记在类或方法上。
• enable 支持 Spring EL，计算结果为 true 时生效，默认开启。
• 生效后，在方法执行期间临时设置忽略标记，结束后自动恢复。

忽略生效范围

• 公司数据权限：切面在进入方法时将 CompanyContextHolder.setIgnore(true)，数据权限规则检测到后直接放行。
• 部门数据权限：切面在进入方法时将 DeptContextHolder.setIgnore(true)，部门数据权限规则检测到后直接放行。

部门上下文覆盖策略

当未忽略部门数据权限且上下文存在有效部门 ID 时：

• 优先使用上下文中的单一部门作为过滤条件，避免因默认的 ALL 或“无部门且不可查看自己”导致放行或误判无权。
• 上下文部门不会修改原有的数据权限 DTO，仅在当前计算中使用。
• 若上下文公司与缓存公司不一致，会记录告警日志，但仍按上下文部门过滤。

典型场景

1. 任务/全局调用需要暂时关闭数据权限

   • 在方法上标记 @DeptDataPermissionIgnore 或 @CompanyDataPermissionIgnore。

2. 带部门上下文的接口调用

   • 请求预先设置 DeptContextHolder.setContext(deptId, companyId)。
   • 即便数据权限声明为 all=true，也会按该部门过滤，避免读出全量。

3. 无部门权限但指定了上下文部门

   • 即使 deptIds 为空且 self=false，只要上下文提供部门，也会使用该部门过滤，而非直接判定无权。

注意事项

• 忽略标记只作用于当前线程上下文，切面会在 finally 中恢复旧值，嵌套调用安全。
• 若需要同时忽略公司与部门数据权限，可叠加两个注解或在业务代码中分别设置忽略标记。