# 阶段四实施总结：角色枚举扩展

> **实施日期**: 2025-12-30  
> **状态**: ✅ Schema更新完成，权限检查逻辑已更新  
> **下一步**: 需要在应用Schema变更后运行迁移脚本

---

## 📋 实施内容

### 1. Schema 变更

**文件**: `prisma/schema.prisma`

**变更内容**: 扩展 `Role` 枚举

```prisma
enum Role {
  USER           // 普通用户（保留）
  ADMIN          // 管理员（保留，向后兼容，建议迁移到SYSTEM_ADMIN）
  DEPT_ADMIN     // 部门管理员（阶段四新增）
  SYSTEM_ADMIN   // 系统管理员（阶段四新增）
}
```

**关键设计**:
- ✅ **向后兼容**: 保留 `ADMIN` 角色，现有代码继续工作
- ✅ **渐进迁移**: 建议将现有 `ADMIN` 逐步迁移为 `SYSTEM_ADMIN`
- ✅ **角色层次**: 支持4种角色，满足不同权限需求

### 2. 数据迁移脚本

**文件**: `scripts/migrate-role-enum-safe.ts`

**功能**:
1. 统计当前角色分布
2. 可选：将现有 ADMIN 角色迁移为 SYSTEM_ADMIN（默认不执行，建议保留兼容）
3. 验证角色数据完整性

**使用方法**:
```bash
# 1. 先应用Schema变更（生成Prisma客户端）
npx prisma db push
# 或
npx prisma migrate dev --name add_role_enum_values

# 2. 运行迁移脚本（可选：迁移ADMIN到SYSTEM_ADMIN）
DATABASE_URL="your_database_url" npx tsx scripts/migrate-role-enum-safe.ts
```

**注意**: 
- 迁移脚本默认**不迁移**现有ADMIN角色，以保持向后兼容
- 如需迁移，可以取消脚本中的注释部分

### 3. 权限检查辅助函数

**文件**: `lib/department-permission.ts`

**新增函数**:

```typescript
/**
 * 判断是否是系统管理员（包括ADMIN和SYSTEM_ADMIN，向后兼容）
 */
export function isSystemAdmin(role: string | null | undefined): boolean {
  if (!role) return false;
  // ADMIN 视为 SYSTEM_ADMIN（向后兼容）
  return role === 'ADMIN' || role === 'SYSTEM_ADMIN';
}

/**
 * 判断是否是部门管理员
 */
export function isDepartmentAdmin(role: string | null | undefined): boolean {
  if (!role) return false;
  return role === 'DEPT_ADMIN';
}

/**
 * 判断是否是管理员（系统管理员或部门管理员）
 */
export function isAdmin(role: string | null | undefined): boolean {
  if (!role) return false;
  // 包括所有管理员角色：ADMIN（兼容）、SYSTEM_ADMIN、DEPT_ADMIN
  return isSystemAdmin(role) || isDepartmentAdmin(role);
}

/**
 * 判断是否有系统管理权限（系统管理员或超级管理员）
 */
export function hasSystemAdminPermission(
  role: string | null | undefined,
  isSuperAdminFlag: boolean = false
): boolean {
  return isSuperAdminFlag || isSystemAdmin(role);
}

/**
 * 判断是否有部门管理权限（部门管理员、系统管理员或超级管理员）
 */
export function hasDepartmentAdminPermission(
  role: string | null | undefined,
  isSuperAdminFlag: boolean = false
): boolean {
  return isSuperAdminFlag || isSystemAdmin(role) || isDepartmentAdmin(role);
}
```

### 4. API更新

**已更新的API文件**:

1. **`app/api/admin/users/set-role/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()` 替代 `role !== 'ADMIN'`
   - 支持所有角色：`USER`, `ADMIN`, `DEPT_ADMIN`, `SYSTEM_ADMIN`

2. **`app/api/admin/users/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

3. **`app/api/admin/users/toggle-active/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

4. **`app/api/admin/users/toggle-download/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

5. **`app/api/departments/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

6. **`app/api/departments/[id]/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

7. **`app/api/system-settings/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

8. **`app/api/platforms/route.ts`**
   - 更新权限检查：使用 `isSystemAdmin()`

9. **`app/api/admin/super-admins/route.ts`**
   - 更新角色检查：允许 `SYSTEM_ADMIN` 被设置为超级管理员

10. **`app/api/materials/update/route.ts`**
    - 更新权限检查：使用 `isSystemAdmin()` 替代 `role !== 'ADMIN'`

**更新模式**:
- 将 `session.user.role !== 'ADMIN'` 替换为 `!isSystemAdmin(session.user.role)`
- 将 `role === 'ADMIN'` 替换为 `isSystemAdmin(role)`
- 导入 `isSystemAdmin` 辅助函数

---

## 📊 角色权限矩阵

| 功能 | 超级管理员 | 系统管理员 | 部门管理员 | 普通用户 |
|------|----------|----------|----------|---------|
| 系统设置 | ✅ | ❌ | ❌ | ❌ |
| 用户管理（全部） | ✅ | ✅ | ❌ | ❌ |
| 用户管理（本部门） | ✅ | ✅ | ✅ | ❌ |
| 部门管理 | ✅ | ✅ | ❌ | ❌ |
| 部门权限配置 | ✅ | ✅ | ✅（本部门） | ❌ |
| 素材审核 | ✅ | ✅ | ✅（本部门） | ❌ |
| 素材上传 | ✅ | ✅ | ✅ | ✅ |
| 素材查看/下载 | ✅ | ✅（受权限） | ✅（受权限） | ✅（受权限） |
| 素材编辑（他人） | ✅ | ✅ | ✅（本部门） | ❌ |
| 素材删除 | ✅ | ✅ | ✅（本部门） | ❌（仅自己） |

---

## 🔄 下一步工作

### 待完成任务

- [ ] 在影子系统应用 Schema 变更（`prisma db push`）
- [ ] 运行迁移脚本（可选：迁移ADMIN到SYSTEM_ADMIN）
- [ ] 更新前端 UI 支持新角色选择
- [ ] 在影子系统进行功能测试
- [ ] 更新其他API（如果有遗漏）

---

## ✅ 检查清单

### Schema 变更

- [x] 扩展 `Role` 枚举，添加 `DEPT_ADMIN`
- [x] 扩展 `Role` 枚举，添加 `SYSTEM_ADMIN`
- [x] 保留 `ADMIN` 角色（向后兼容）

### 迁移脚本

- [x] 创建迁移脚本
- [x] 实现角色统计逻辑
- [x] 实现数据验证逻辑
- [x] 提供可选迁移选项（默认不迁移，保持兼容）

### 权限检查函数

- [x] 创建 `isSystemAdmin()` 函数
- [x] 创建 `isDepartmentAdmin()` 函数
- [x] 创建 `isAdmin()` 函数
- [x] 创建 `hasSystemAdminPermission()` 函数
- [x] 创建 `hasDepartmentAdminPermission()` 函数

### API更新

- [x] 更新 `app/api/admin/users/set-role/route.ts`
- [x] 更新 `app/api/admin/users/route.ts`
- [x] 更新 `app/api/admin/users/toggle-active/route.ts`
- [x] 更新 `app/api/admin/users/toggle-download/route.ts`
- [x] 更新 `app/api/departments/route.ts`
- [x] 更新 `app/api/departments/[id]/route.ts`
- [x] 更新 `app/api/system-settings/route.ts`
- [x] 更新 `app/api/platforms/route.ts`
- [x] 更新 `app/api/admin/super-admins/route.ts`
- [x] 更新 `app/api/materials/update/route.ts`

---

## 🚨 注意事项

### 向后兼容

- ✅ 保留 `ADMIN` 角色，现有代码继续工作
- ✅ `isSystemAdmin()` 函数将 `ADMIN` 视为 `SYSTEM_ADMIN`
- ✅ 现有管理员用户无需立即迁移

### 数据迁移

- ⚠️ **必须先应用Schema变更**（`prisma db push` 或 `prisma migrate dev`）
- ⚠️ **迁移脚本默认不迁移**现有ADMIN角色（保持兼容）
- ⚠️ 如需迁移ADMIN到SYSTEM_ADMIN，需要手动取消脚本中的注释
- ⚠️ 建议在测试环境验证后再在生产环境执行迁移

### 权限控制

- ✅ 所有权限检查都使用辅助函数，便于维护
- ✅ 支持角色层次：USER < DEPT_ADMIN < SYSTEM_ADMIN < SUPER_ADMIN
- ⚠️ 前端UI需要更新以支持新角色选择
- ⚠️ 部门管理员权限控制需要根据部门层级实现（阶段三配合）

---

**文档版本**: 1.0  
**创建日期**: 2025-12-30  
**最后更新**: 2025-12-30