gongxiangp2/docs/stage4-implementation-summary.md

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

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

---

📋 实施内容

1. Schema 变更

文件: prisma/schema.prisma

变更内容: 扩展 Role 枚举

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. 验证角色数据完整性

使用方法:

# 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

新增函数:

/**
 * 判断是否是系统管理员（包括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 变更

• 扩展 Role 枚举，添加 DEPT_ADMIN
• 扩展 Role 枚举，添加 SYSTEM_ADMIN
• 保留 ADMIN 角色（向后兼容）

迁移脚本

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

权限检查函数

• 创建 isSystemAdmin() 函数
• 创建 isDepartmentAdmin() 函数
• 创建 isAdmin() 函数
• 创建 hasSystemAdminPermission() 函数
• 创建 hasDepartmentAdminPermission() 函数

API更新

• 更新 app/api/admin/users/set-role/route.ts
• 更新 app/api/admin/users/route.ts
• 更新 app/api/admin/users/toggle-active/route.ts
• 更新 app/api/admin/users/toggle-download/route.ts
• 更新 app/api/departments/route.ts
• 更新 app/api/departments/[id]/route.ts
• 更新 app/api/system-settings/route.ts
• 更新 app/api/platforms/route.ts
• 更新 app/api/admin/super-admins/route.ts
• 更新 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