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 向后兼容性
**现状**: 接口级权限检查会自动回退到模块级权限
```python
# 权限检查优先级
1. 接口级权限（如果已配置）
2. 模块级权限（向后兼容）
```

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

### 2.2 粗粒度权限管理
**应用场景**:
- 项目管理员快速配置整个模块的权限
- 不需要逐个配置每个操作
- 适合权限配置简单的项目

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

### 2.3 前端路由权限控制
**现状**: 前端使用模块级权限控制路由访问
```typescript
// 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