新增忽略公司以及部门数据权限的注解

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

@@ -0,0 +1,42 @@
+# 数据权限忽略与上下文覆盖说明
+
+本文说明新增的公司/部门数据权限忽略能力，以及部门上下文对数据权限的覆盖策略。
+
+## 新增注解
+
+- `@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` 中恢复旧值，嵌套调用安全。
+- 若需要同时忽略公司与部门数据权限，可叠加两个注解或在业务代码中分别设置忽略标记。