ctms/MODULE_LEVEL_PERMISSIONS_ASSESSMENT.md

模块级权限必要性评估

评估日期: 2026-05-14
评估结论: ✅ 模块级权限仍有必要保留

---

1. 当前权限系统现状

权限层级结构

系统级权限 (ADMIN)
    ↓
项目级权限
    ├─ 模块级权限 (Module-level) - 87处使用
    └─ 接口级权限 (API-level) - 32处使用

使用统计

• 模块级权限检查: 87处（占比 73%）
• 接口级权限检查: 32处（占比 27%）
• 权限模块数: 16个
• 权限操作数: 97个

---

2. 模块级权限的价值

2.1 向后兼容性

现状: 接口级权限检查会自动回退到模块级权限

# 权限检查优先级
1. 接口级权限（如果已配置）
2. 模块级权限（向后兼容）

意义:

• 允许渐进式迁移，无需一次性改造所有接口
• 新增接口可直接使用接口级权限
• 旧接口可保持模块级权限

2.2 粗粒度权限管理

应用场景:

• 项目管理员快速配置整个模块的权限
• 不需要逐个配置每个操作
• 适合权限配置简单的项目

示例:

PM 角色权限配置：
- 项目成员: 读写
- 中心管理: 读写
- 合同费用: 读写
- 参与者管理: 读写

2.3 前端路由权限控制

现状: 前端使用模块级权限控制路由访问

// projectRoutePermissions.ts
{ 
  prefixes: ["/project/overview"], 
  permission: { module: "project_overview", action: "read" } 
}

意义:

• 前端路由与后端权限保持一致
• 用户界面权限检查更简洁
• 避免用户访问无权限的页面

2.4 权限管理 UI 的两层结构

现状: 权限管理页面提供两个标签页

权限管理
├─ 模块级权限 (ProjectPermissionsModule)
└─ 接口级权限 (ApiEndpointPermissions)

意义:

• 模块级权限: 快速配置，适合大多数场景
• 接口级权限: 细粒度控制，适合复杂场景
• 两者互补，满足不同需求

---

3. 接口级权限的价值

3.1 细粒度权限控制

解决的问题: 跨模块数据访问权限混乱

示例:

问题: risk_issues 模块需要读取 subjects 数据
- 模块级权限: 无法表达"只能查看自己创建的"
- 接口级权限: 可以精确控制 GET /subjects 的访问权限

3.2 业务语言权限名称

改进: 从技术性改为业务语言

旧: "POST:/subjects", "GET:/subjects/{id}"
新: "subjects:create", "subjects:read"

优势:

• 权限名称更易理解
• 与业务流程对应
• 便于权限审计和合规

3.3 权限操作数量

• 模块级: 16个模块 × 2个操作 = 32个权限
• 接口级: 97个权限操作
• 覆盖范围: 接口级权限更全面

---

4. 迁移成本分析

4.1 完全移除模块级权限的成本

项目	工作量	风险
后端接口迁移	87处代码改造	高
前端路由权限	20+个路由	中
权限管理 UI	简化为单标签页	低
数据库迁移	权限数据转换	中
测试覆盖	完整回归测试	高
总计	3-5天	中高

4.2 保留模块级权限的成本

• 维护成本: 极低（已稳定运行）
• 学习成本: 低（文档完善）
• 扩展成本: 低（两套系统并行）

---

5. 权限系统对比

维度	模块级权限	接口级权限
粒度	粗（模块+操作）	细（具体操作）
易用性	高（配置简单）	中（配置复杂）
灵活性	低（无法精确控制）	高（精确到操作）
性能	高（缓存友好）	中（查询更多）
覆盖范围	32个权限	97个权限
跨模块支持	不支持	支持
维护成本	低	中

---

6. 建议方案

6.1 短期（现在）

✅ 保留两套权限系统

• 模块级权限: 继续用于快速配置和前端路由
• 接口级权限: 用于细粒度控制和新增接口
• 优先级: 接口级 > 模块级（自动回退）

6.2 中期（3-6个月）

📋 逐步迁移

• 新增接口直接使用接口级权限
• 不改造现有接口（保持稳定）
• 收集用户反馈，优化权限模型

6.3 长期（6-12个月）

🎯 可选完全迁移

• 如果接口级权限完全满足需求
• 可考虑移除模块级权限
• 但成本较高，收益有限

---

7. 风险评估

7.1 保留模块级权限的风险

• 权限混乱: 两套权限系统可能产生不一致
  • 缓解: 接口级权限优先级更高
• 维护复杂: 需要维护两套权限逻辑
  • 缓解: 代码已清晰分离，维护成本低

7.2 移除模块级权限的风险

• 回归风险: 87处代码改造可能引入 bug
  • 影响: 高，涉及所有业务接口
• 用户影响: 权限配置方式改变
  • 影响: 中，需要重新培训
• 数据迁移: 现有权限数据转换
  • 影响: 中，需要数据验证

---

8. 结论

✅ 模块级权限应该保留，原因：

1. 成本效益差: 移除成本高（3-5天），收益有限
2. 向后兼容: 现有系统运行稳定，无需改造
3. 用户友好: 模块级权限配置更简单直观
4. 风险可控: 两套系统并行，相互补充
5. 前端依赖: 路由权限控制依赖模块级权限

📌 最佳实践：

权限检查策略：
├─ 前端路由: 使用模块级权限（快速检查）
├─ 后端接口: 优先使用接口级权限
│  └─ 如果未配置，自动回退到模块级权限
└─ 权限管理: 提供两个标签页
   ├─ 模块级权限: 快速配置
   └─ 接口级权限: 细粒度控制

🎯 建议行动：

1. 保持现状 - 两套权限系统并行运行
2. 新增接口 - 直接使用接口级权限
3. 监控效果 - 收集用户反馈
4. 定期评估 - 每季度评估一次迁移必要性

---

9. 附录：权限系统架构图

┌─────────────────────────────────────────────────┐
│           权限检查请求                          │
└────────────────┬────────────────────────────────┘
                 │
         ┌───────▼────────┐
         │  ADMIN 角色?   │
         │  是 → 允许所有 │
         └───────┬────────┘
                 │ 否
         ┌───────▼──────────────┐
         │ 查询接口级权限       │
         │ (ApiEndpointPerm)    │
         └───────┬──────────────┘
                 │
         ┌───────▼────────────┐
         │ 找到配置?          │
         │ 是 → 返回结果      │
         │ 否 → 继续          │
         └───────┬────────────┘
                 │
         ┌───────▼──────────────┐
         │ 回退到模块级权限     │
         │ (StudyRolePermission)│
         └───────┬──────────────┘
                 │
         ┌───────▼────────────┐
         │ 返回权限检查结果   │
         └────────────────────┘

---

评估完成: ✅ 2026-05-14