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

权限文档补充清单与编写建议

适用范围：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 份一旦补齐，当前权限体系就从“分析充分”进入“可工程化推进”的状态。