feat: add tenant-scoped rule and permission management

docs/权限与地区隔离/权限文档补充清单与编写建议.md

@@ -0,0 +1,436 @@
+# 权限文档补充清单与编写建议
+
+> 适用范围：`docs/权限与地区隔离/` 当前文档体系  
+> 目标：明确“现有文档已经覆盖了什么”“还缺哪些关键文档”“每份补充文档应该写什么”。
+
+---
+
+## 1. 当前文档覆盖情况
+
+目前这个目录下已经有：
+
+- `权限与地区隔离文档导航.md`
+- `用户与地区权限完整设计方案.md`
+- `用户权限与权限点清单.md`
+- `用户权限初始化SQL.sql`
+- `权限架构全面优化改造方案.md`
+- `角色硬编码与接口影响专项补充分析.md`
+
+这批文档已经覆盖了 3 个层面：
+
+1. **现行设计层**
+   - 系统最终采用什么权限模型
+2. **权限点与初始化层**
+   - 角色、菜单、权限点、SQL
+3. **改造策略层**
+   - 架构问题、改造方向、硬编码角色、接口影响面
+
+所以当前并不是“文档太少”，而是**还缺少落地执行层文档**。
+
+换句话说：
+
+- “为什么这么改”已经基本够了
+- “具体怎么一批批改、怎么验收、怎么防回归”还不够
+
+---
+
+## 2. 当前最缺的文档类型
+
+当前最缺的不是再写一份大而全方案，而是补下面 5 类文档：
+
+1. **统一执行器设计文档**
+2. **实施任务拆解文档**
+3. **接口权限矩阵文档**
+4. **测试验收文档**
+5. **迁移灰度与回滚文档**
+
+这 5 类文档补齐后，权限体系文档才会从“设计完整”进入“可实施、可协作、可验收”状态。
+
+---
+
+## 3. 建议优先补充的文档
+
+下面按优先级给出建议。
+
+## 3.1 P0：统一数据范围执行器设计.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/统一数据范围执行器设计.md`
+
+为什么必须补：
+
+- 当前最大缺口就是 `data_scope` 已建模但没有统一执行层
+- 主方案已经讲了方向，但还没有到“类设计/接口设计/接入方式”的粒度
+
+建议文档内容：
+
+1. 背景与目标
+2. 当前问题
+3. 核心对象设计
+   - `PermissionDecision`
+   - `ScopeContext`
+   - `DataScopeResolver`
+   - `QueryScopeBuilder`
+   - `ModulePolicy`
+4. scope 计算规则
+5. 多角色合并规则
+6. `DENY` 与 `GRANT` 优先级
+7. 通用字段映射规范
+   - `region`
+   - `created_by`
+   - `owner_id`
+8. 模块接入方式
+9. 代码落点建议
+10. 第一批接入模块
+
+这份文档的作用：
+
+- 把“方案级描述”变成“研发可直接开工的设计稿”
+
+## 3.2 P0：权限改造实施任务拆解与排期.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/权限改造实施任务拆解与排期.md`
+
+为什么必须补：
+
+- 当前总方案里有阶段建议，但还不够任务化
+- 真正落地时需要明确每阶段交付、负责人边界、依赖顺序
+
+建议文档内容：
+
+1. 总目标
+2. Phase 划分
+3. 每阶段任务清单
+4. 每阶段输入输出
+5. 依赖关系
+6. 关键风险
+7. 验收门槛
+8. 建议排期
+
+建议拆成：
+
+- Phase 1：统一能力层
+- Phase 2：RAG 去双轨
+- Phase 3：文档/公文/统计统一 scope
+- Phase 4：RBAC 管理域与首页入口
+- Phase 5：前端去角色化与 fallback 收口
+
+## 3.3 P0：权限测试验收与回归用例清单.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/权限测试验收与回归用例清单.md`
+
+为什么必须补：
+
+- 权限改造最怕“改对了一处，放大了另一处”
+- 现在还缺一份真正可执行的验收清单
+
+建议文档内容：
+
+1. 测试目标
+2. 用户角色矩阵
+3. 数据边界矩阵
+4. 模块覆盖矩阵
+5. 接口级用例
+6. 越权回归用例
+7. 菜单/页面/按钮一致性用例
+8. 下载/详情/导出接口专项用例
+9. 灰度观察指标
+
+重点必须覆盖：
+
+- 文档
+- 公文
+- 统计
+- RAG
+- RBAC 管理
+- 交叉评查
+
+## 3.4 P0：权限接口矩阵与数据边界清单.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/权限接口矩阵与数据边界清单.md`
+
+为什么必须补：
+
+- 目前有“权限点清单”，但还缺“接口到数据边界”的完整矩阵
+- 这个文档是联调、测试、排查越权最直接的依据
+
+建议文档内容：
+
+每个接口至少写清：
+
+- 接口路径
+- 对应 permission_key
+- 是否需要 data_scope
+- scope 类型
+- 是否有模块 policy
+- 允许哪些角色/能力访问
+- 是否有下载/详情/导出子资源
+
+建议按模块分章节：
+
+- 认证
+- 文档
+- 公文
+- 统计
+- RAG
+- 交叉评查
+- RBAC
+- 合同模板
+- 规则/评查点
+
+这份文档的价值非常高，因为它会成为：
+
+- 后端改造依据
+- 前端联调依据
+- 测试验收依据
+
+## 3.5 P0：角色去硬编码迁移清单.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/角色去硬编码迁移清单.md`
+
+为什么还要单独再补一份：
+
+- 现在已经有“专项分析”
+- 但还没有“逐文件、逐逻辑、逐替换策略”的迁移执行清单
+
+建议文档内容：
+
+1. 当前硬编码点总表
+2. 每个硬编码点所属类型
+3. 替换目标
+4. 替换优先级
+5. 是否影响接口行为
+6. 是否影响前端显示
+7. 是否需要兼容过渡
+
+建议按表格列：
+
+- 文件
+- 位置
+- 当前写法
+- 问题类型
+- 替换方式
+- 优先级
+- 风险等级
+
+---
+
+## 4. 建议第二批补充的文档
+
+这些不是第一优先，但补了会明显提升协作效率。
+
+## 4.1 P1：前端权限消费改造方案.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/前端权限消费改造方案.md`
+
+为什么建议补：
+
+- 当前前端既有 permission 消费，也有角色硬编码，也有 route fallback
+- 需要一份单独文档把前端边界讲清楚
+
+建议内容：
+
+- 菜单权限来源
+- `permission_map` 的定位
+- `user_role` 的新定位
+- UI 按钮可见性策略
+- 页面 guard 改造策略
+- fallback 收口路径
+
+## 4.2 P1：RBAC管理台改造细化方案.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/RBAC管理台改造细化方案.md`
+
+为什么建议补：
+
+- RBAC 管理台不是普通业务模块
+- 它是权限体系的“运营端”
+
+建议内容：
+
+- 角色管理
+- 路由管理
+- 权限点管理
+- scope 展示
+- 用户最终权限预览
+- 冲突检测
+- 灰度观察
+
+## 4.3 P1：权限可观测性与审计日志方案.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/权限可观测性与审计日志方案.md`
+
+为什么建议补：
+
+- 当前方案里已经指出缺观测能力
+- 但还没有专门说明“记录什么、怎么记录、怎么查”
+
+建议内容：
+
+- 权限决策日志
+- data_scope 解析日志
+- deny 原因日志
+- 管理操作审计日志
+- 命中/拒绝统计指标
+
+## 4.4 P1：权限迁移灰度发布与回滚手册.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/权限迁移灰度发布与回滚手册.md`
+
+为什么建议补：
+
+- 权限改造是高风险变更
+- 需要单独文档说明如何灰度和回滚
+
+建议内容：
+
+- 灰度开关
+- 新旧逻辑并行方式
+- shadow compare 方案
+- 回滚条件
+- 回滚操作步骤
+
+---
+
+## 5. 建议第三批补充的文档
+
+这些文档不一定马上要写，但后续如果项目进入实施期，会很有价值。
+
+## 5.1 P2：模块Policy设计清单.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/模块Policy设计清单.md`
+
+适用场景：
+
+- 当系统开始明确区分 `CrossReviewPolicy`、`RagDatasetPolicy`、`RuleConfigPolicy` 时
+
+作用：
+
+- 统一记录哪些模块走通用 scope，哪些模块走关系型访问模型
+
+## 5.2 P2：权限术语表与统一口径说明.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/权限术语表与统一口径说明.md`
+
+适用场景：
+
+- 项目成员较多、跨前后端协作频繁时
+
+作用：
+
+- 统一 `ALL/DEPT/SELF`
+- 统一 `area/region`
+- 统一 `role/permission/capability/policy`
+
+## 5.3 P2：legacy权限治理遗留清单.md
+
+建议文件名：
+
+- `docs/权限与地区隔离/legacy权限治理遗留清单.md`
+
+适用场景：
+
+- 实施进入中后期，需要记录还没收掉的旧逻辑时
+
+作用：
+
+- 防止历史兼容逻辑永久留在系统里无人认领
+
+---
+
+## 6. 当前最推荐立刻补的 5 份文档
+
+如果只选最重要的，我建议立刻补下面 5 份：
+
+1. `统一数据范围执行器设计.md`
+2. `权限改造实施任务拆解与排期.md`
+3. `权限测试验收与回归用例清单.md`
+4. `权限接口矩阵与数据边界清单.md`
+5. `角色去硬编码迁移清单.md`
+
+原因很简单：
+
+- 这 5 份补齐后，就能真正开始实施
+- 如果只继续写“大方案”，信息会越来越多，但落地抓手不够
+
+---
+
+## 7. 当前目录建议结构
+
+建议后续把这个目录里的文档分成 4 组理解：
+
+### A. 现行设计
+
+- `用户与地区权限完整设计方案.md`
+- `用户权限与权限点清单.md`
+- `用户权限初始化SQL.sql`
+
+### B. 架构改造
+
+- `权限架构全面优化改造方案.md`
+- `角色硬编码与接口影响专项补充分析.md`
+
+### C. 需补的实施文档
+
+- `统一数据范围执行器设计.md`
+- `权限改造实施任务拆解与排期.md`
+- `权限测试验收与回归用例清单.md`
+- `权限接口矩阵与数据边界清单.md`
+- `角色去硬编码迁移清单.md`
+
+### D. 后续治理文档
+
+- `前端权限消费改造方案.md`
+- `RBAC管理台改造细化方案.md`
+- `权限可观测性与审计日志方案.md`
+- `权限迁移灰度发布与回滚手册.md`
+
+---
+
+## 8. 最终建议
+
+当前权限文档体系的状态可以概括为：
+
+- **设计层基本够了**
+- **改造方向层基本够了**
+- **执行层明显还不够**
+
+所以后续补文档时，不建议继续优先写“大而全总方案”。
+
+最优先应该补的是：
+
+- 可直接指导写代码的设计文档
+- 可直接指导排期的实施文档
+- 可直接指导测试的验收文档
+- 可直接指导联调和排查的接口矩阵文档
+
+如果按价值排序，我的建议顺序是：
+
+1. `统一数据范围执行器设计.md`
+2. `权限接口矩阵与数据边界清单.md`
+3. `权限测试验收与回归用例清单.md`
+4. `权限改造实施任务拆解与排期.md`
+5. `角色去硬编码迁移清单.md`
+
+这 5 份一旦补齐，当前权限体系就从“分析充分”进入“可工程化推进”的状态。