wren
437 lines
9.9 KiB
Markdown
437 lines
9.9 KiB
Markdown
# 权限文档补充清单与编写建议
|
||
|
||
> 适用范围：`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 份一旦补齐，当前权限体系就从“分析充分”进入“可工程化推进”的状态。
|