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

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