ctms/REMOVE_MODULE_LEVEL_PERMISSIONS_ASSESSMENT.md

# 模块级权限移除评估

## 执行摘要

经过完整的接口级权限迁移和测试，模块级权限系统已不再被使用。建议在 6-12 个月的观察期后完全移除。

**评估结论**: ✓ **可以移除**（需要过渡期）

---

## 1. 当前状态分析

### 1.1 模块级权限系统概况

**表结构**:
- `study_role_permissions` - 存储项目角色的模块级权限

**字段**:
- `study_id` - 项目ID
- `role` - 角色名称
- `module` - 模块名称 (subjects, visits, aes, etc.)
- `can_read` - 读权限
- `can_write` - 写权限

**覆盖的模块**:
```
subjects, visits, aes, risk_issues, finance, fees, materials, 
startup_auth, ethics, monitoring_audit, subject_pds, audit_export, etc.
```

### 1.2 接口级权限迁移完成度

**迁移状态**:
- ✓ 68 个 API 端点已迁移到接口级权限
- ✓ 所有迁移端点已测试通过
- ✓ 前置权限检查机制已实现
- ✓ 权限管理 API 已完成

**迁移覆盖范围**:
```
第1批 (23个): subjects, visits, aes, monitoring_visit_issues
第2批 (11个): members, sites, project_milestones
第3批 (15个): finance_contracts, fees_contracts, drug_shipments
第4批 (19个): startup endpoints
```

### 1.3 向后兼容性实现

**当前回退机制**:
```python
# 在 role_has_api_permission() 中
if perm is not None:
    has_main_permission = perm.allowed
else:
    # 回退到模块级权限
    endpoint_config = API_ENDPOINT_PERMISSIONS.get(endpoint_key)
    module = endpoint_config["module"]
    action = endpoint_config["action"]
    has_main_permission = await role_has_project_permission(
        db, study_id, role, module, action
    )
```

**回退使用情况**:
- 所有迁移的端点都配置了对应的模块映射
- 如果接口级权限未配置，自动使用模块级权限
- 确保现有权限配置继续有效

---

## 2. 移除可行性分析

### 2.1 依赖关系检查

**代码中对模块级权限的引用**:

```bash
# 搜索 role_has_project_permission 的使用
grep -r "role_has_project_permission" backend/app --include="*.py"
```

**结果**:
- ✓ 仅在 `project_permissions.py` 中定义
- ✓ 仅在 `role_has_api_permission()` 的回退逻辑中使用
- ✓ 没有其他地方直接调用

**代码中对 StudyRolePermission 的引用**:

```bash
# 搜索 StudyRolePermission 的使用
grep -r "StudyRolePermission" backend/app --include="*.py"
```

**结果**:
- ✓ 仅在 `project_permissions.py` 中导入
- ✓ 仅在 `role_has_project_permission()` 中使用
- ✓ 没有其他业务逻辑依赖

### 2.2 前端依赖检查

**前端权限检查**:
- 前端使用接口级权限进行路由守卫
- 前端权限矩阵已更新为接口级权限
- 模块级权限在前端已不使用

### 2.3 数据库迁移影响

**表的使用情况**:
- `study_role_permissions` 表中可能存储了历史数据
- 移除前需要确认数据迁移策略

**数据迁移方案**:
1. **保留数据**: 保留表用于审计和历史查询
2. **归档数据**: 将数据导出到历史表后删除
3. **直接删除**: 如果确认无需保留历史数据

---

## 3. 移除步骤规划

### 3.1 第1阶段：准备期 (1-2 周)

**任务**:
1. 备份 `study_role_permissions` 表数据
2. 生成数据迁移脚本
3. 更新文档，说明权限系统变更
4. 通知所有相关人员

**验证**:
- ✓ 所有接口级权限已配置
- ✓ 所有迁移端点已测试
- ✓ 备份数据已验证

### 3.2 第2阶段：代码清理 (1-2 周)

**删除项目**:

1. **删除回退逻辑**
   ```python
   # 从 role_has_api_permission() 中删除
   else:
       # 2. 如果没有接口级权限，回退到模块级权限（向后兼容）
       endpoint_config = API_ENDPOINT_PERMISSIONS.get(endpoint_key)
       if not endpoint_config:
           return False
       module = endpoint_config["module"]
       action = endpoint_config["action"]
       has_main_permission = await role_has_project_permission(db, study_id, role, module, action)
   ```

2. **删除函数**
   - `role_has_project_permission()` 函数
   - `PROJECT_PERMISSION_MODULES` 常量

3. **删除导入**
   - `from app.models.study_role_permission import StudyRolePermission`
   - `from app.core.project_permissions import role_has_project_permission`

4. **删除模型**
   - `app/models/study_role_permission.py` 文件

5. **删除测试**
   - 删除模块级权限相关的测试用例

**文件修改清单**:
```
backend/app/core/project_permissions.py
  - 删除 role_has_project_permission() 函数
  - 删除 PROJECT_PERMISSION_MODULES 常量
  - 删除 StudyRolePermission 导入

backend/app/core/api_permissions.py
  - 删除 module 字段映射（可选，保留用于文档）

backend/app/models/study_role_permission.py
  - 删除整个文件

backend/tests/
  - 删除模块级权限相关测试
  - 更新现有测试中的模块级权限引用
```

### 3.3 第3阶段：数据库迁移 (1-2 周)

**创建迁移文件**:
```python
# alembic/versions/20260601_remove_study_role_permissions.py

def upgrade() -> None:
    # 选项1: 删除表
    op.drop_table("study_role_permissions")
    
    # 选项2: 重命名为历史表
    # op.rename_table("study_role_permissions", "study_role_permissions_history")

def downgrade() -> None:
    # 恢复表结构
    op.create_table(...)
```

**执行步骤**:
1. 在测试环境运行迁移
2. 验证迁移成功
3. 备份生产数据
4. 在生产环境运行迁移

### 3.4 第4阶段：验证和监控 (2-4 周)

**验证项**:
- ✓ 所有权限检查正常工作
- ✓ 没有权限相关的错误日志
- ✓ 前端权限守卫正常工作
- ✓ 审计日志记录正确

**监控指标**:
- 权限检查错误率
- 权限拒绝次数
- API 响应时间
- 数据库查询性能

---

## 4. 风险评估

### 4.1 高风险项

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 遗漏的模块级权限使用 | 权限检查失败 | 充分的代码审查和测试 |
| 数据丢失 | 无法恢复历史权限配置 | 完整备份和验证 |
| 性能下降 | 权限检查变慢 | 性能测试和优化 |

### 4.2 中风险项

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 迁移期间权限不一致 | 用户权限混乱 | 充分的过渡期和通知 |
| 回滚困难 | 无法快速恢复 | 完整的迁移脚本和文档 |

### 4.3 低风险项

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 代码库混乱 | 维护成本增加 | 代码清理和文档更新 |
| 文档过时 | 新人上手困难 | 及时更新文档 |

---

## 5. 移除前检查清单

### 5.1 代码检查

- [ ] 所有 API 端点都配置了接口级权限
- [ ] 所有接口级权限都有对应的模块映射
- [ ] 没有直接调用 `role_has_project_permission()` 的代码
- [ ] 没有直接访问 `StudyRolePermission` 的代码
- [ ] 所有权限相关的测试都通过

### 5.2 数据检查

- [ ] `study_role_permissions` 表数据已备份
- [ ] 数据迁移脚本已准备
- [ ] 数据迁移已在测试环境验证
- [ ] 数据恢复计划已制定

### 5.3 文档检查

- [ ] 权限系统文档已更新
- [ ] API 文档已更新
- [ ] 迁移指南已编写
- [ ] 回滚计划已文档化

### 5.4 测试检查

- [ ] 单元测试覆盖率 > 90%
- [ ] 集成测试全部通过
- [ ] 性能测试通过
- [ ] 安全性测试通过

### 5.5 部署检查

- [ ] 部署计划已制定
- [ ] 回滚计划已准备
- [ ] 监控告警已配置
- [ ] 团队培训已完成

---

## 6. 建议时间表

### 6.1 推荐移除时间

**最早移除时间**: 2026年7月（3个月后）
- 充分的观察期
- 足够的数据积累
- 足够的问题发现和修复时间

**推荐移除时间**: 2026年8月-9月（4-5个月后）
- 更长的观察期
- 更充分的准备时间
- 更低的风险

### 6.2 阶段时间表

```
2026年5月14日: 接口级权限迁移完成
2026年5月-6月: 观察期（1-2个月）
2026年6月-7月: 准备期（1-2个月）
2026年7月-8月: 代码清理（1-2个月）
2026年8月-9月: 数据库迁移（1-2个月）
2026年9月-10月: 验证和监控（2-4个月）
```

---

## 7. 移除后的改进

### 7.1 代码简化

**删除的代码**:
- ~100 行权限检查逻辑
- ~50 行常量定义
- ~200 行测试代码

**简化的流程**:
```
权限检查流程简化为:
API请求 → 获取当前用户 → 检查接口级权限 → 检查前置权限 → 执行业务逻辑
```

### 7.2 性能改进

**预期改进**:
- 权限检查减少一次数据库查询（不再需要查询模块级权限）
- 权限检查响应时间减少 ~5-10%
- 数据库查询减少 ~5%

### 7.3 维护成本降低

**预期降低**:
- 代码行数减少 ~350 行
- 测试用例减少 ~50 个
- 文档维护工作减少 ~30%

---

## 8. 备选方案

### 8.1 方案A: 完全移除（推荐）

**优点**:
- ✓ 代码最简洁
- ✓ 维护成本最低
- ✓ 性能最优

**缺点**:
- ✗ 无法恢复历史权限配置
- ✗ 需要完整的迁移计划

**实施时间**: 3-4 个月

### 8.2 方案B: 保留表但不使用

**优点**:
- ✓ 可以保留历史数据
- ✓ 可以快速回滚
- ✓ 风险较低

**缺点**:
- ✗ 代码中仍有回退逻辑
- ✗ 维护成本仍然存在
- ✗ 容易造成混淆

**实施时间**: 1-2 个月

### 8.3 方案C: 延迟移除

**优点**:
- ✓ 更长的观察期
- ✓ 更充分的准备时间
- ✓ 风险最低

**缺点**:
- ✗ 维护成本持续
- ✗ 代码库混乱
- ✗ 新人容易混淆

**实施时间**: 6-12 个月

---

## 9. 结论和建议

### 9.1 评估结论

**模块级权限可以移除**: ✓ **是**

**理由**:
1. ✓ 接口级权限迁移已完成 (68 个端点)
2. ✓ 所有迁移端点已测试通过 (46 个测试)
3. ✓ 前置权限检查机制已实现
4. ✓ 向后兼容性已保证
5. ✓ 没有其他地方依赖模块级权限

### 9.2 建议

**立即行动**:
1. ✓ 备份 `study_role_permissions` 表数据
2. ✓ 编写数据迁移脚本
3. ✓ 更新文档和培训材料

**短期行动** (1-2 个月):
1. ✓ 进行充分的观察和监控
2. ✓ 收集用户反馈
3. ✓ 修复发现的问题

**中期行动** (2-4 个月):
1. ✓ 执行代码清理
2. ✓ 执行数据库迁移
3. ✓ 进行充分的验证

### 9.3 优先级

**优先级**: **中等** (可以在下一个发布周期执行)

**理由**:
- 不是紧急任务
- 需要充分的准备时间
- 可以与其他功能开发并行进行

---

## 10. 附录

### 10.1 相关文件清单

**需要修改的文件**:
```
backend/app/core/project_permissions.py
backend/app/core/api_permissions.py
backend/app/models/study_role_permission.py (删除)
backend/tests/test_*.py (多个文件)
```

**需要创建的文件**:
```
alembic/versions/20260601_remove_study_role_permissions.py
docs/MIGRATION_GUIDE.md
```

### 10.2 参考文档

- [权限系统迁移完成报告](./backend/PERMISSION_MIGRATION_TEST_REPORT.md)
- [模块级权限评估](./MODULE_LEVEL_PERMISSIONS_ASSESSMENT.md)
- [权限系统设计文档](./PERMISSION_SYSTEM_DESIGN.md)

### 10.3 联系方式

**权限系统负责人**: 
- 技术负责人: [待填]
- 产品负责人: [待填]

---

## 版本历史

| 版本 | 日期 | 作者 | 变更 |
|------|------|------|------|
| 1.0 | 2026-05-14 | Claude | 初始评估 |

---

**评估完成日期**: 2026-05-14
**下次评估日期**: 2026-08-14
**建议移除日期**: 2026-08-01 - 2026-09-30