leaudit-platform-backend/docs/权限与地区隔离/权限文档总导航与阅读顺序.md

权限文档总导航与阅读顺序

适用范围：docs/权限与地区隔离/ 当前整套权限、地区隔离、统一执行器、去硬编码、实施文档
文档定位：给研发、测试、产品、评审、实施同事提供统一阅读顺序，避免只看到局部文档、漏掉关键约束。

---

1. 先看结论

现在这套文档已经不只是“权限设计稿”，而是完整覆盖了：

1. 现行模型
2. 权限点与接口
3. 架构问题
4. 去硬编码
5. 统一执行器
6. 字段和 SQL 规范
7. 地区租户化
8. 自定义租户扩展
9. 实施排期
10. 测试回归
11. 代码骨架
12. 后续扩展方向

因此不建议再按旧导航只看 2-3 份文档。

如果你当前最关心的是“已经做到哪里”，先看：

1. 权限与租户改造当前进度总览.md
2. 再按本文档进入专题阅读

---

2. 按角色的阅读顺序

2.1 架构评审 / 技术负责人

建议顺序：

1. 用户与地区权限完整设计方案.md
2. 权限架构全面优化改造方案.md
3. 角色硬编码与接口影响专项补充分析.md
4. 统一数据范围执行器设计.md
5. 地区租户化与自定义租户扩展改造方案.md
6. 租户主数据模型设计.md
7. 权限、租户能力与数据范围职责边界说明.md
8. 权限字段映射与SQL改造规范.md
9. 统一执行器落地代码骨架与接入示例.md

目的：

• 先看现状和改造方向
• 再看执行器设计
• 最后看代码级落地方式

2.2 后端研发

建议顺序：

1. 用户权限与权限点清单.md
2. 权限接口矩阵与数据边界清单.md
3. 统一数据范围执行器设计.md
4. 地区租户化与自定义租户扩展改造方案.md
5. 租户主数据模型设计.md
6. 权限、租户能力与数据范围职责边界说明.md
7. 地区到租户编码映射清洗清单.md
8. 入口模块租户配置表迁移方案.md
9. 权限字段映射与SQL改造规范.md
10. 统一执行器落地代码骨架与接入示例.md
11. 角色去硬编码迁移清单.md
12. 权限改造实施任务拆解与排期.md

目的：

• 先知道接口和 permission
• 再知道 scope 规则
• 再知道代码怎么改

2.3 前端研发

建议顺序：

1. 权限接口矩阵与数据边界清单.md
2. 角色硬编码与接口影响专项补充分析.md
3. 地区租户化与自定义租户扩展改造方案.md
4. 入口模块租户配置表迁移方案.md
5. 权限、租户能力与数据范围职责边界说明.md
6. 角色去硬编码迁移清单.md
7. 统一数据范围执行器设计.md
8. 权限改造实施任务拆解与排期.md

目的：

• 先理解后端边界
• 再理解哪些按钮、菜单、guard 需要去角色化

2.4 测试 / 验收

建议顺序：

1. 权限接口矩阵与数据边界清单.md
2. 权限测试验收与回归用例清单.md
3. 角色去硬编码迁移清单.md

目的：

• 先知道该测哪些接口
• 再知道怎么测
• 再知道哪些地方最容易回归出问题

2.5 产品 / 业务 / 实施

建议顺序：

1. 用户与地区权限完整设计方案.md
2. 权限架构全面优化改造方案.md
3. 地区租户化与自定义租户扩展改造方案.md
4. 租户主数据模型设计.md
5. 权限、租户能力与数据范围职责边界说明.md
6. 权限改造实施任务拆解与排期.md
7. 权限测试验收与回归用例清单.md

---

3. 按主题的阅读顺序

3.1 现行模型与背景

1. 用户与地区权限完整设计方案.md
2. 用户权限与权限点清单.md

回答问题：

• 现在系统权限模型到底是什么
• 角色、菜单、权限点、地区字段分别在哪

3.2 架构问题与改造方向

1. 权限架构全面优化改造方案.md
2. 角色硬编码与接口影响专项补充分析.md

回答问题：

• 为什么当前系统不能继续靠分散 if 判断演进
• 哪些硬编码会联动影响接口和前端

3.3 统一执行器与后端落地

1. 统一数据范围执行器设计.md
2. 权限、租户能力与数据范围职责边界说明.md
3. 权限字段映射与SQL改造规范.md
4. 统一执行器落地代码骨架与接入示例.md

回答问题：

• scope 怎么算
• SQL 怎么接
• 代码怎么改

3.4 接口、测试、排期

1. 权限接口矩阵与数据边界清单.md
2. 权限测试验收与回归用例清单.md
3. 权限改造实施任务拆解与排期.md

回答问题：

• 哪些接口受影响
• 怎么验收
• 怎么拆阶段实施

3.5 去硬编码执行清单

1. 角色去硬编码迁移清单.md

回答问题：

• 具体哪些文件要改
• 按什么优先级改
• 会影响哪些接口和页面

3.6 地区租户化与自定义租户扩展

1. 地区租户化与自定义租户扩展改造方案.md
2. 租户主数据模型设计.md
3. 权限、租户能力与数据范围职责边界说明.md
4. 地区到租户编码映射清洗清单.md
5. 入口模块租户配置表迁移方案.md
6. 自定义租户功能连带影响深度补充.md

回答问题：

• 为什么“地区”本质已经是租户
• 为什么新增租户不能只改前端下拉
• 租户主数据应该怎么建
• 历史 省局 / 省级 / default / 空值 应该怎么清洗
• 入口模块为什么必须从 JSON 改成关系表

---

4. 推荐总阅读顺序

如果是第一次完整阅读，建议按下面顺序：

1. 用户与地区权限完整设计方案.md
2. 用户权限与权限点清单.md
3. 权限架构全面优化改造方案.md
4. 角色硬编码与接口影响专项补充分析.md
5. 地区租户化与自定义租户扩展改造方案.md
6. 租户主数据模型设计.md
7. 权限、租户能力与数据范围职责边界说明.md
8. 地区到租户编码映射清洗清单.md
9. 入口模块租户配置表迁移方案.md
10. 自定义租户功能连带影响深度补充.md
11. 统一数据范围执行器设计.md
12. 权限字段映射与SQL改造规范.md
13. 统一执行器落地代码骨架与接入示例.md
14. 权限接口矩阵与数据边界清单.md
15. 权限测试验收与回归用例清单.md
16. 权限改造实施任务拆解与排期.md
17. 角色去硬编码迁移清单.md

---

5. 当前文档体系解决了什么

这套文档现在已经能解决下面这些问题：

1. 当前权限架构到底是什么
2. data_scope 为什么现在不统一
3. 角色硬编码具体散在哪里
4. RAG 为什么是优先治理区
5. 文档、公文、统计、RBAC、合同模板、交叉评查分别怎么接统一执行器
6. SQL 层应该怎么收敛
7. 测试应该怎么验收
8. 地区为什么本质已经是租户
9. 自定义租户为什么会连带影响入口、RAG、模板、统计和 RBAC
10. 实施应该怎么排期
11. 租户能力与角色权限为什么看起来重复、实际应如何分层

---

6. 当前仍建议继续补充的方向

如果后续继续扩展，优先级建议如下：

1. 租户接口设计与返回结构规范
2. 统一租户解析器与兼容层设计
3. 文档/公文/RAG 的真实代码实施记录

其中前两项优先级最高，因为当前“地区”在很多业务里已经实际承担了“租户”的角色，但还没有统一主数据接口和统一解析层。

---

7. 对旧导航的替代说明

旧的 权限与地区隔离文档导航.md 仍可以保留，但它已经只覆盖早期文档，不足以指导当前完整改造。

建议以后以本文档作为新的总导航入口。