990 lines
30 KiB
Markdown
990 lines
30 KiB
Markdown
> ⚠️ **已归档文档**
|
||
> 本文档记录的是 2026-06 初的 RBAC 权限体系重构方案，描述的是修复前的安全隐患（如 exams/actions.ts 中的硬编码 getCurrentUser 存根）。
|
||
> 当前已由 [004 架构影响地图](./004_architecture_impact_map.md) 与 [005 架构数据](./005_architecture_data.json) 取代——所有 Server Action 已接入 `requirePermission()`/`requireAuth()`，54 个权限点与 6 角色映射已落地。
|
||
> 保留用于历史参考，不再维护。
|
||
|
||
---
|
||
|
||
# 企业级权限体系重构方案
|
||
|
||
> 基于源码逆向分析，覆盖 proxy.ts / auth.ts / 各模块 actions.ts / 前端组件
|
||
|
||
---
|
||
|
||
## 一、问题诊断
|
||
|
||
### 1.1 安全隐患
|
||
|
||
#### 隐患 A：考试模块 Server Action 零鉴权
|
||
|
||
[exams/actions.ts:721-723](file:///e:/Desktop/CICD/src/modules/exams/actions.ts#L721-L723) 中的 `getCurrentUser()` 是一个硬编码存根：
|
||
|
||
```typescript
|
||
async function getCurrentUser() {
|
||
return { id: "user_teacher_math", role: "teacher" }
|
||
}
|
||
```
|
||
|
||
**后果**：任何已登录用户（包括 student/parent）都可以调用 `deleteExamAction`、`updateExamAction`、`duplicateExamAction`，删除或修改任意考试。攻击路径：
|
||
|
||
1. 学生 A 登录系统，获取合法 session
|
||
2. 直接调用 `deleteExamAction`，传入任意 `examId`
|
||
3. Server Action 不校验调用者身份，直接执行 `db.delete(exams).where(eq(exams.id, examId))`
|
||
4. 考试被删除
|
||
|
||
#### 隐患 B：越权修改他人考试
|
||
|
||
即使修复了 `getCurrentUser()`，`updateExamAction` 和 `deleteExamAction` 仍不检查资源归属：
|
||
|
||
```typescript
|
||
// updateExamAction — 任何 teacher 可修改任何考试
|
||
await db.update(exams).set(updateData).where(eq(exams.id, examId))
|
||
// 缺少: AND creatorId = currentUserId
|
||
```
|
||
|
||
教师 B 可以修改教师 A 创建的考试，只需知道 examId。
|
||
|
||
#### 隐患 C：班级管理部分接口无鉴权
|
||
|
||
[classes/actions.ts](file:///e:/Desktop/CICD/src/modules/classes/actions.ts) 中：
|
||
- `enrollStudentByEmailAction` — 无任何 auth 检查
|
||
- `setStudentEnrollmentStatusAction` — 无任何 auth 检查
|
||
- `createClassScheduleItemAction` — 无任何 auth 检查
|
||
- `deleteClassScheduleItemAction` — 无任何 auth 检查
|
||
- `ensureClassInvitationCodeAction` — 无任何 auth 检查
|
||
- `regenerateClassInvitationCodeAction` — 无任何 auth 检查
|
||
|
||
任何已登录用户都可以操作任意班级的学生和课表。
|
||
|
||
#### 隐患 D：作业批改无资源归属校验
|
||
|
||
`gradeHomeworkSubmissionAction` 只调用 `ensureTeacher()`，确认调用者是教师身份，但不检查该教师是否有权批改此作业。任何教师可批改任何班级的作业。
|
||
|
||
### 1.2 扩展性问题
|
||
|
||
#### 问题 A：角色硬编码散布全栈
|
||
|
||
前端 14 处 `role === "xxx"` 硬编码，后端各模块各自实现鉴权逻辑：
|
||
|
||
| 位置 | 模式 |
|
||
|------|------|
|
||
| `proxy.ts` | `if (role === "admin")` |
|
||
| `onboarding-gate.tsx` | `if (role === "admin")` / `role === "teacher"` / `role === "student"` |
|
||
| `dashboard/page.tsx` | `if (role === "admin") redirect(...)` |
|
||
| `settings/page.tsx` | `if (role === "admin") return <AdminSettingsView>` |
|
||
| `homework/actions.ts` | `ensureTeacher()` / `ensureStudent()` |
|
||
| `classes/actions.ts` | `session.user.role !== "admin"` |
|
||
|
||
新增角色（如 `teaching_head`、`grade_head`）需要改动所有这些位置。
|
||
|
||
#### 问题 B：多角色用户被强制取一个
|
||
|
||
[auth.ts](file:///e:/Desktop/CICD/src/auth.ts) 中多角色解析逻辑取优先级最高的一个角色，存入 JWT 的单一 `role` 字段。一个同时是 `teacher` + `grade_head` 的用户，在 JWT 中只保留 `teacher`，导致年级管理功能不可用。
|
||
|
||
#### 问题 C：数据权限无统一抽象
|
||
|
||
`homework/actions.ts` 手动实现了"教师只能为自己班级的作业发布任务"的逻辑（30+ 行），`classes/actions.ts` 手动实现了"年级主任只能管理自己年级"的逻辑（20+ 行）。每个模块各自实现，无法复用。
|
||
|
||
### 1.3 可维护性问题
|
||
|
||
#### 问题 A：鉴权逻辑与业务逻辑耦合
|
||
|
||
每个 Server Action 的前 10-30 行都是鉴权代码，与业务逻辑混杂，难以测试和复用。
|
||
|
||
#### 问题 B：前端条件渲染依赖角色字符串
|
||
|
||
```tsx
|
||
// 当前：硬编码角色判断
|
||
{role === "teacher" ? <TeacherView /> : <StudentView />}
|
||
|
||
// 无法支持：年级主任看到额外的管理入口
|
||
```
|
||
|
||
---
|
||
|
||
## 二、企业级权限模型设计
|
||
|
||
### 2.1 权限模型：RBAC + 数据权限
|
||
|
||
```
|
||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
│ User │────→│ UserRole │←────│ Role │
|
||
│ │ M:N │ (多角色) │ │ (角色定义) │
|
||
└─────────────┘ └──────────────┘ └──────┬──────┘
|
||
│ M:N
|
||
┌──────┴──────┐
|
||
│ RolePermission│
|
||
└──────┬──────┘
|
||
│ N:1
|
||
┌──────┴──────┐
|
||
│ Permission │
|
||
│ (权限点) │
|
||
└─────────────┘
|
||
```
|
||
|
||
### 2.2 权限点定义
|
||
|
||
权限点采用 `resource:action` 命名规范：
|
||
|
||
```typescript
|
||
// src/shared/types/permissions.ts
|
||
|
||
export const Permissions = {
|
||
// 考试
|
||
EXAM_CREATE: "exam:create",
|
||
EXAM_READ: "exam:read",
|
||
EXAM_UPDATE: "exam:update",
|
||
EXAM_DELETE: "exam:delete",
|
||
EXAM_DUPLICATE: "exam:duplicate",
|
||
EXAM_PUBLISH: "exam:publish",
|
||
EXAM_AI_GENERATE: "exam:ai_generate",
|
||
|
||
// 作业
|
||
HOMEWORK_CREATE: "homework:create",
|
||
HOMEWORK_GRADE: "homework:grade",
|
||
HOMEWORK_SUBMIT: "homework:submit",
|
||
|
||
// 题库
|
||
QUESTION_CREATE: "question:create",
|
||
QUESTION_READ: "question:read",
|
||
QUESTION_UPDATE: "question:update",
|
||
QUESTION_DELETE: "question:delete",
|
||
|
||
// 教材
|
||
TEXTBOOK_CREATE: "textbook:create",
|
||
TEXTBOOK_READ: "textbook:read",
|
||
TEXTBOOK_UPDATE: "textbook:update",
|
||
TEXTBOOK_DELETE: "textbook:delete",
|
||
|
||
// 班级
|
||
CLASS_CREATE: "class:create",
|
||
CLASS_READ: "class:read",
|
||
CLASS_UPDATE: "class:update",
|
||
CLASS_DELETE: "class:delete",
|
||
CLASS_ENROLL: "class:enroll",
|
||
CLASS_SCHEDULE: "class:schedule",
|
||
|
||
// 学校管理
|
||
SCHOOL_MANAGE: "school:manage",
|
||
GRADE_MANAGE: "grade:manage",
|
||
USER_MANAGE: "user:manage",
|
||
|
||
// AI
|
||
AI_CHAT: "ai:chat",
|
||
AI_CONFIGURE: "ai:configure",
|
||
|
||
// 设置
|
||
SETTINGS_ADMIN: "settings:admin",
|
||
} as const
|
||
|
||
export type Permission = typeof Permissions[keyof typeof Permissions]
|
||
```
|
||
|
||
### 2.3 角色-权限映射
|
||
|
||
```typescript
|
||
// src/shared/lib/permissions.ts
|
||
|
||
import { Permissions, type Permission } from "@/shared/types/permissions"
|
||
|
||
export const ROLE_PERMISSIONS: Record<string, Permission[]> = {
|
||
admin: [
|
||
Permissions.EXAM_CREATE, Permissions.EXAM_READ, Permissions.EXAM_UPDATE,
|
||
Permissions.EXAM_DELETE, Permissions.EXAM_DUPLICATE, Permissions.EXAM_PUBLISH,
|
||
Permissions.EXAM_AI_GENERATE,
|
||
Permissions.HOMEWORK_CREATE, Permissions.HOMEWORK_GRADE,
|
||
Permissions.QUESTION_CREATE, Permissions.QUESTION_READ,
|
||
Permissions.QUESTION_UPDATE, Permissions.QUESTION_DELETE,
|
||
Permissions.TEXTBOOK_CREATE, Permissions.TEXTBOOK_READ,
|
||
Permissions.TEXTBOOK_UPDATE, Permissions.TEXTBOOK_DELETE,
|
||
Permissions.CLASS_CREATE, Permissions.CLASS_READ,
|
||
Permissions.CLASS_UPDATE, Permissions.CLASS_DELETE,
|
||
Permissions.CLASS_ENROLL, Permissions.CLASS_SCHEDULE,
|
||
Permissions.SCHOOL_MANAGE, Permissions.GRADE_MANAGE,
|
||
Permissions.USER_MANAGE,
|
||
Permissions.AI_CHAT, Permissions.AI_CONFIGURE,
|
||
Permissions.SETTINGS_ADMIN,
|
||
],
|
||
teacher: [
|
||
Permissions.EXAM_CREATE, Permissions.EXAM_READ, Permissions.EXAM_UPDATE,
|
||
Permissions.EXAM_DELETE, Permissions.EXAM_DUPLICATE, Permissions.EXAM_PUBLISH,
|
||
Permissions.EXAM_AI_GENERATE,
|
||
Permissions.HOMEWORK_CREATE, Permissions.HOMEWORK_GRADE,
|
||
Permissions.QUESTION_CREATE, Permissions.QUESTION_READ,
|
||
Permissions.QUESTION_UPDATE, Permissions.QUESTION_DELETE,
|
||
Permissions.TEXTBOOK_CREATE, Permissions.TEXTBOOK_READ,
|
||
Permissions.TEXTBOOK_UPDATE,
|
||
Permissions.CLASS_READ, Permissions.CLASS_ENROLL,
|
||
Permissions.CLASS_SCHEDULE,
|
||
Permissions.AI_CHAT,
|
||
],
|
||
student: [
|
||
Permissions.EXAM_READ,
|
||
Permissions.HOMEWORK_SUBMIT,
|
||
Permissions.QUESTION_READ,
|
||
Permissions.TEXTBOOK_READ,
|
||
Permissions.CLASS_READ,
|
||
Permissions.AI_CHAT,
|
||
],
|
||
parent: [
|
||
Permissions.EXAM_READ,
|
||
Permissions.TEXTBOOK_READ,
|
||
Permissions.CLASS_READ,
|
||
],
|
||
// 可扩展：年级主任、教研组长等
|
||
grade_head: [
|
||
Permissions.EXAM_CREATE, Permissions.EXAM_READ, Permissions.EXAM_UPDATE,
|
||
Permissions.EXAM_DELETE, Permissions.EXAM_DUPLICATE, Permissions.EXAM_PUBLISH,
|
||
Permissions.EXAM_AI_GENERATE,
|
||
Permissions.HOMEWORK_CREATE, Permissions.HOMEWORK_GRADE,
|
||
Permissions.QUESTION_CREATE, Permissions.QUESTION_READ,
|
||
Permissions.QUESTION_UPDATE, Permissions.QUESTION_DELETE,
|
||
Permissions.TEXTBOOK_CREATE, Permissions.TEXTBOOK_READ,
|
||
Permissions.TEXTBOOK_UPDATE,
|
||
Permissions.CLASS_CREATE, Permissions.CLASS_READ,
|
||
Permissions.CLASS_UPDATE, Permissions.CLASS_ENROLL,
|
||
Permissions.CLASS_SCHEDULE,
|
||
Permissions.GRADE_MANAGE,
|
||
Permissions.AI_CHAT,
|
||
],
|
||
}
|
||
```
|
||
|
||
### 2.4 数据权限策略
|
||
|
||
数据权限通过 `DataScope` 定义，在 data-access 层自动注入过滤条件：
|
||
|
||
```typescript
|
||
// src/shared/types/permissions.ts
|
||
|
||
export type DataScope =
|
||
| { type: "all" } // admin: 全量
|
||
| { type: "owned" } // 仅自己创建的
|
||
| { type: "class_members" } // 所在班级的成员数据
|
||
| { type: "grade_managed"; gradeIds: string[] } // 管理的年级
|
||
| { type: "class_taught"; classIds: string[]; subjectIds?: string[] } // 教学的班级（可限定科目）
|
||
| { type: "children"; childrenIds: string[] } // 家长：子女数据
|
||
|
||
export interface AuthContext {
|
||
userId: string
|
||
roles: string[] // 所有角色，不再只取一个
|
||
permissions: Permission[] // 合并所有角色的权限（去重）
|
||
dataScope: DataScope // 数据权限范围
|
||
}
|
||
```
|
||
|
||
### 2.5 数据库变更
|
||
|
||
**新增一张表**（最小变更，不修改现有表结构）：
|
||
|
||
```sql
|
||
CREATE TABLE role_permissions (
|
||
role_id VARCHAR(128) NOT NULL,
|
||
permission VARCHAR(100) NOT NULL,
|
||
PRIMARY KEY (role_id, permission),
|
||
FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
|
||
INDEX idx_role_permissions_role (role_id)
|
||
);
|
||
```
|
||
|
||
Drizzle schema：
|
||
|
||
```typescript
|
||
// 追加到 src/shared/db/schema.ts
|
||
|
||
export const rolePermissions = mysqlTable("role_permissions", {
|
||
roleId: varchar("role_id", { length: 128 }).notNull()
|
||
.references(() => roles.id, { onDelete: "cascade" }),
|
||
permission: varchar("permission", { length: 100 }).notNull(),
|
||
}, (table) => ({
|
||
pk: primaryKey({ columns: [table.roleId, table.permission] }),
|
||
roleIdIdx: index("role_permissions_role_idx").on(table.roleId),
|
||
}))
|
||
```
|
||
|
||
**不修改现有表**。`ROLE_PERMISSIONS` 常量作为初始 seed 数据，运行时优先从数据库读取（支持动态调整），数据库无记录时 fallback 到常量。
|
||
|
||
---
|
||
|
||
## 三、实现方案
|
||
|
||
### 3.1 NextAuth Session 携带权限信息
|
||
|
||
#### 修改 JWT 和 Session 类型
|
||
|
||
```typescript
|
||
// src/next-auth.d.ts
|
||
|
||
declare module "next-auth" {
|
||
interface Session {
|
||
user: DefaultSession["user"] & {
|
||
id: string
|
||
roles: string[] // 所有角色
|
||
permissions: string[] // 合并后的权限列表
|
||
}
|
||
}
|
||
}
|
||
|
||
declare module "next-auth/jwt" {
|
||
interface JWT {
|
||
id: string
|
||
roles: string[]
|
||
permissions: string[]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 修改 auth.ts callbacks
|
||
|
||
```typescript
|
||
// src/auth.ts — 关键改动
|
||
|
||
import { ROLE_PERMISSIONS } from "@/shared/lib/permissions"
|
||
|
||
function resolvePermissions(roleNames: string[]): string[] {
|
||
const set = new Set<string>()
|
||
for (const name of roleNames) {
|
||
const perms = ROLE_PERMISSIONS[name] ?? []
|
||
for (const p of perms) set.add(p)
|
||
}
|
||
return Array.from(set)
|
||
}
|
||
|
||
export const authConfig = {
|
||
callbacks: {
|
||
async jwt({ token, user }) {
|
||
if (user) {
|
||
token.id = user.id
|
||
// 查询用户所有角色
|
||
const userRoles = await db
|
||
.select({ name: roles.name })
|
||
.from(usersToRoles)
|
||
.innerJoin(roles, eq(usersToRoles.roleId, roles.id))
|
||
.where(eq(usersToRoles.userId, user.id))
|
||
|
||
const roleNames = userRoles.map(r => r.name)
|
||
token.roles = roleNames
|
||
token.permissions = resolvePermissions(roleNames)
|
||
}
|
||
return token
|
||
},
|
||
async session({ session, token }) {
|
||
session.user.id = token.id
|
||
session.user.roles = token.roles
|
||
session.user.permissions = token.permissions
|
||
return session
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### 3.2 `requirePermission()` 服务端权限断言
|
||
|
||
```typescript
|
||
// src/shared/lib/auth-guard.ts
|
||
|
||
import { auth } from "@/auth"
|
||
import { ROLE_PERMISSIONS } from "@/shared/lib/permissions"
|
||
import type { Permission, DataScope, AuthContext } from "@/shared/types/permissions"
|
||
import { db } from "@/shared/db"
|
||
import { users, usersToRoles, roles, classes, classEnrollments, classSubjectTeachers, grades } from "@/shared/db/schema"
|
||
import { eq, and, inArray } from "drizzle-orm"
|
||
|
||
class PermissionDeniedError extends Error {
|
||
constructor(permission: string) {
|
||
super(`Permission denied: ${permission}`)
|
||
this.name = "PermissionDeniedError"
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 获取当前用户的完整认证上下文
|
||
*/
|
||
export async function getAuthContext(): Promise<AuthContext> {
|
||
const session = await auth()
|
||
const userId = session?.user?.id
|
||
if (!userId) throw new PermissionDeniedError("auth_required")
|
||
|
||
const roles = session.user.roles ?? []
|
||
const permissions = session.user.permissions ?? []
|
||
const dataScope = await resolveDataScope(userId, roles)
|
||
|
||
return { userId, roles, permissions, dataScope }
|
||
}
|
||
|
||
/**
|
||
* 断言当前用户拥有指定权限
|
||
*/
|
||
export async function requirePermission(permission: Permission): Promise<AuthContext> {
|
||
const ctx = await getAuthContext()
|
||
if (!ctx.permissions.includes(permission)) {
|
||
throw new PermissionDeniedError(permission)
|
||
}
|
||
return ctx
|
||
}
|
||
|
||
/**
|
||
* 断言当前用户拥有指定权限，并返回上下文（不抛异常版本）
|
||
*/
|
||
export async function checkPermission(permission: Permission): Promise<{ allowed: boolean; ctx: AuthContext }> {
|
||
const ctx = await getAuthContext()
|
||
return { allowed: ctx.permissions.includes(permission), ctx }
|
||
}
|
||
|
||
/**
|
||
* 根据角色解析数据权限范围
|
||
*/
|
||
async function resolveDataScope(userId: string, roleNames: string[]): Promise<DataScope> {
|
||
if (roleNames.includes("admin")) {
|
||
return { type: "all" }
|
||
}
|
||
|
||
// 年级主任
|
||
if (roleNames.includes("grade_head")) {
|
||
const managedGrades = await db
|
||
.select({ id: grades.id })
|
||
.from(grades)
|
||
.where(
|
||
and(
|
||
eq(grades.gradeHeadId, userId),
|
||
// 或 teachingHeadId
|
||
)
|
||
)
|
||
if (managedGrades.length > 0) {
|
||
return { type: "grade_managed", gradeIds: managedGrades.map(g => g.id) }
|
||
}
|
||
}
|
||
|
||
// 教师
|
||
if (roleNames.includes("teacher")) {
|
||
const taughtClasses = await db
|
||
.select({ classId: classes.id, subjectId: classSubjectTeachers.subjectId })
|
||
.from(classes)
|
||
.leftJoin(classSubjectTeachers, eq(classSubjectTeachers.classId, classes.id))
|
||
.where(eq(classes.teacherId, userId))
|
||
|
||
const classIds = [...new Set(taughtClasses.map(c => c.classId))]
|
||
const subjectIds = taughtClasses
|
||
.map(c => c.subjectId)
|
||
.filter((s): s is string => s !== null)
|
||
|
||
return { type: "class_taught", classIds, subjectIds: subjectIds.length > 0 ? subjectIds : undefined }
|
||
}
|
||
|
||
// 学生
|
||
if (roleNames.includes("student")) {
|
||
return { type: "class_members" }
|
||
}
|
||
|
||
// 家长
|
||
if (roleNames.includes("parent")) {
|
||
// TODO: 查询关联子女
|
||
return { type: "children", childrenIds: [] }
|
||
}
|
||
|
||
return { type: "owned" }
|
||
}
|
||
|
||
/**
|
||
* 在 data-access 层使用：根据 DataScope 生成查询过滤条件
|
||
*/
|
||
export function applyDataScope(
|
||
scope: DataScope,
|
||
options: {
|
||
creatorIdField?: unknown // 如 exams.creatorId
|
||
classIdField?: unknown // 如 classes.id
|
||
gradeIdField?: unknown // 如 grades.id
|
||
studentIdField?: unknown // 如 classEnrollments.studentId
|
||
}
|
||
): unknown[] {
|
||
const conditions: unknown[] = []
|
||
|
||
switch (scope.type) {
|
||
case "all":
|
||
break // 无过滤
|
||
case "owned":
|
||
if (options.creatorIdField) {
|
||
conditions.push(eq(options.creatorIdField, /* currentUserId */))
|
||
}
|
||
break
|
||
case "class_taught":
|
||
if (options.classIdField && scope.classIds.length > 0) {
|
||
conditions.push(inArray(options.classIdField, scope.classIds))
|
||
}
|
||
break
|
||
case "grade_managed":
|
||
if (options.gradeIdField && scope.gradeIds.length > 0) {
|
||
conditions.push(inArray(options.gradeIdField, scope.gradeIds))
|
||
}
|
||
break
|
||
case "class_members":
|
||
// 需要子查询：学生所在班级
|
||
break
|
||
}
|
||
|
||
return conditions
|
||
}
|
||
|
||
export { PermissionDeniedError }
|
||
```
|
||
|
||
### 3.3 `usePermission()` 前端 Hook
|
||
|
||
```typescript
|
||
// src/shared/hooks/use-permission.ts
|
||
|
||
"use client"
|
||
|
||
import { useSession } from "next-auth/react"
|
||
import type { Permission } from "@/shared/types/permissions"
|
||
|
||
export function usePermission(): {
|
||
permissions: Permission[]
|
||
roles: string[]
|
||
hasPermission: (permission: Permission) => boolean
|
||
hasAnyPermission: (...perms: Permission[]) => boolean
|
||
hasAllPermissions: (...perms: Permission[]) => boolean
|
||
hasRole: (role: string) => boolean
|
||
} {
|
||
const { data: session } = useSession()
|
||
const permissions = session?.user?.permissions ?? []
|
||
const roles = session?.user?.roles ?? []
|
||
|
||
const hasPermission = (permission: Permission): boolean => {
|
||
return permissions.includes(permission)
|
||
}
|
||
|
||
const hasAnyPermission = (...perms: Permission[]): boolean => {
|
||
return perms.some(p => permissions.includes(p))
|
||
}
|
||
|
||
const hasAllPermissions = (...perms: Permission[]): boolean => {
|
||
return perms.every(p => permissions.includes(p))
|
||
}
|
||
|
||
const hasRole = (role: string): boolean => {
|
||
return roles.includes(role)
|
||
}
|
||
|
||
return { permissions, roles, hasPermission, hasAnyPermission, hasAllPermissions, hasRole }
|
||
}
|
||
```
|
||
|
||
### 3.4 Server Action 集成模式
|
||
|
||
#### 改造前（exams/actions.ts）
|
||
|
||
```typescript
|
||
// 零鉴权，getCurrentUser() 返回硬编码值
|
||
export async function deleteExamAction(prevState, formData) {
|
||
const { examId } = parsed.data
|
||
await db.delete(exams).where(eq(exams.id, examId)) // 任何人可删任何考试
|
||
}
|
||
```
|
||
|
||
#### 改造后
|
||
|
||
```typescript
|
||
import { requirePermission, getAuthContext, PermissionDeniedError } from "@/shared/lib/auth-guard"
|
||
import { Permissions } from "@/shared/types/permissions"
|
||
|
||
export async function deleteExamAction(prevState, formData): Promise<ActionState> {
|
||
try {
|
||
const ctx = await requirePermission(Permissions.EXAM_DELETE)
|
||
const { examId } = parsed.data
|
||
|
||
// 数据权限：非 admin 只能删自己的考试
|
||
if (ctx.dataScope.type !== "all") {
|
||
const exam = await db.query.exams.findFirst({
|
||
where: eq(exams.id, examId),
|
||
columns: { creatorId: true },
|
||
})
|
||
if (!exam || exam.creatorId !== ctx.userId) {
|
||
return failState("You can only delete your own exams")
|
||
}
|
||
}
|
||
|
||
await db.delete(exams).where(eq(exams.id, examId))
|
||
} catch (e) {
|
||
if (e instanceof PermissionDeniedError) return failState(e.message)
|
||
throw e
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 data-access 层数据权限过滤
|
||
|
||
```typescript
|
||
// src/modules/exams/data-access.ts — 改造后
|
||
|
||
import { applyDataScope } from "@/shared/lib/auth-guard"
|
||
import type { DataScope } from "@/shared/types/permissions"
|
||
|
||
export const getExams = cache(async (params: GetExamsParams & { scope: DataScope }) => {
|
||
const conditions = []
|
||
|
||
// 原有筛选条件
|
||
if (params.q) { /* ... */ }
|
||
if (params.status && params.status !== "all") { /* ... */ }
|
||
|
||
// 数据权限过滤
|
||
const scopeConditions = applyDataScope(params.scope, {
|
||
creatorIdField: exams.creatorId,
|
||
gradeIdField: exams.gradeId,
|
||
})
|
||
conditions.push(...scopeConditions)
|
||
|
||
const data = await db.query.exams.findMany({
|
||
where: conditions.length ? and(...conditions) : undefined,
|
||
// ...
|
||
})
|
||
})
|
||
```
|
||
|
||
### 3.6 Middleware 改造
|
||
|
||
```typescript
|
||
// src/proxy.ts — 改造后
|
||
|
||
import { NextResponse } from "next/server"
|
||
import type { NextRequest } from "next/server"
|
||
import { getToken } from "next-auth/jwt"
|
||
|
||
// 路由 → 所需权限映射
|
||
const ROUTE_PERMISSIONS: Record<string, string> = {
|
||
"/admin": "school:manage",
|
||
"/teacher": "exam:read", // teacher 区域最低权限
|
||
"/student": "exam:read", // student 区域最低权限
|
||
"/parent": "exam:read", // parent 区域最低权限
|
||
}
|
||
|
||
// API 路由 → 所需权限映射
|
||
const API_PERMISSIONS: Record<string, string> = {
|
||
"/api/ai/chat": "ai:chat",
|
||
"/api/onboarding": "auth_required", // 特殊标记：仅需登录
|
||
}
|
||
|
||
export async function middleware(request: NextRequest): Promise<NextResponse> {
|
||
const token = await getToken({ req: request })
|
||
|
||
if (!token) {
|
||
const loginUrl = new URL("/login", request.url)
|
||
loginUrl.searchParams.set("callbackUrl", request.url)
|
||
return NextResponse.redirect(loginUrl)
|
||
}
|
||
|
||
const { pathname } = request.nextUrl
|
||
const permissions: string[] = (token.permissions as string[]) ?? []
|
||
const roles: string[] = (token.roles as string[]) ?? []
|
||
|
||
// 检查 API 路由权限
|
||
for (const [prefix, requiredPerm] of Object.entries(API_PERMISSIONS)) {
|
||
if (pathname.startsWith(prefix)) {
|
||
if (requiredPerm === "auth_required") break // 仅需登录
|
||
if (!permissions.includes(requiredPerm)) {
|
||
return NextResponse.json({ error: "Forbidden" }, { status: 403 })
|
||
}
|
||
break
|
||
}
|
||
}
|
||
|
||
// 检查页面路由权限
|
||
for (const [prefix, requiredPerm] of Object.entries(ROUTE_PERMISSIONS)) {
|
||
if (pathname.startsWith(prefix)) {
|
||
if (!permissions.includes(requiredPerm)) {
|
||
// 无权限 → 重定向到角色首页
|
||
const defaultPath = resolveDefaultPath(roles)
|
||
return NextResponse.redirect(new URL(defaultPath, request.url))
|
||
}
|
||
break
|
||
}
|
||
}
|
||
|
||
return NextResponse.next()
|
||
}
|
||
|
||
function resolveDefaultPath(roles: string[]): string {
|
||
if (roles.includes("admin")) return "/admin/dashboard"
|
||
if (roles.includes("teacher")) return "/teacher/dashboard"
|
||
if (roles.includes("student")) return "/student/dashboard"
|
||
if (roles.includes("parent")) return "/parent/dashboard"
|
||
return "/dashboard"
|
||
}
|
||
|
||
export const config = {
|
||
matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
|
||
}
|
||
```
|
||
|
||
### 3.7 前端组件改造
|
||
|
||
#### 改造前
|
||
|
||
```tsx
|
||
// 硬编码角色判断
|
||
{role === "teacher" ? <TeacherView /> : <StudentView />}
|
||
```
|
||
|
||
#### 改造后
|
||
|
||
```tsx
|
||
import { usePermission } from "@/shared/hooks/use-permission"
|
||
import { Permissions } from "@/shared/types/permissions"
|
||
|
||
function DashboardPage() {
|
||
const { hasPermission, hasRole } = usePermission()
|
||
|
||
return (
|
||
<>
|
||
{hasPermission(Permissions.HOMEWORK_GRADE) && <GradingWidget />}
|
||
{hasPermission(Permissions.EXAM_CREATE) && <CreateExamButton />}
|
||
{hasPermission(Permissions.SCHOOL_MANAGE) && <AdminPanel />}
|
||
</>
|
||
)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、渐进式重构路线图
|
||
|
||
### Phase 1：基础设施（1-2 天）
|
||
|
||
1. 创建 `src/shared/types/permissions.ts` — 权限点定义
|
||
2. 创建 `src/shared/lib/permissions.ts` — 角色-权限映射
|
||
3. 创建 `src/shared/lib/auth-guard.ts` — `requirePermission()` / `getAuthContext()`
|
||
4. 创建 `src/shared/hooks/use-permission.ts` — 前端 Hook
|
||
5. 修改 `src/next-auth.d.ts` — Session/JWT 类型扩展
|
||
6. 修改 `src/auth.ts` — JWT/Session callbacks 注入权限
|
||
7. 新增 `role_permissions` 数据库表 + seed 脚本
|
||
|
||
### Phase 2：修复高危模块（2-3 天）
|
||
|
||
优先修复零鉴权和越权漏洞：
|
||
|
||
1. **exams/actions.ts** — 替换 `getCurrentUser()` 存根，所有 Action 加 `requirePermission()`
|
||
2. **classes/actions.ts** — 无鉴权接口补全，统一使用 `requirePermission()`
|
||
3. **homework/actions.ts** — 用 `requirePermission()` 替换 `ensureTeacher()`/`ensureStudent()`
|
||
4. **questions/actions.ts** — 补全鉴权
|
||
5. **textbooks/actions.ts** — 补全鉴权
|
||
|
||
### Phase 3：数据权限集成（2-3 天）
|
||
|
||
1. 各模块 `data-access.ts` 接受 `DataScope` 参数
|
||
2. `getExams()` / `getHomeworkAssignments()` 等查询函数自动过滤
|
||
3. 页面级 Server Component 传入 `AuthContext`
|
||
|
||
### Phase 4：Middleware 升级（1 天）
|
||
|
||
1. `proxy.ts` 从角色路由匹配 → 权限点路由匹配
|
||
2. API 路由增加权限检查
|
||
|
||
### Phase 5：前端改造（2-3 天）
|
||
|
||
1. 逐步替换 `role === "xxx"` 为 `hasPermission()`
|
||
2. 侧边栏导航从 `NAV_CONFIG[role]` → `NAV_CONFIG.filter(item => hasPermission(item.permission))`
|
||
3. 条件渲染统一使用 `usePermission()`
|
||
|
||
---
|
||
|
||
## 五、考试模块改造对比
|
||
|
||
### 5.1 Server Actions 改造
|
||
|
||
#### 改造前 — createExamAction
|
||
|
||
```typescript
|
||
export async function createExamAction(prevState, formData) {
|
||
// ... 解析表单 ...
|
||
try {
|
||
const user = await getCurrentUser() // 硬编码存根！
|
||
await persistExamDraft({
|
||
examId: context.examId,
|
||
creatorId: user?.id ?? "user_teacher_math", // 硬编码 fallback！
|
||
// ...
|
||
})
|
||
} catch (error) {
|
||
return failState("Database error")
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 改造后 — createExamAction
|
||
|
||
```typescript
|
||
export async function createExamAction(prevState, formData): Promise<ActionState> {
|
||
let ctx: AuthContext
|
||
try {
|
||
ctx = await requirePermission(Permissions.EXAM_CREATE)
|
||
} catch (e) {
|
||
if (e instanceof PermissionDeniedError) return failState(e.message)
|
||
throw e
|
||
}
|
||
|
||
// ... 解析表单 ...
|
||
|
||
try {
|
||
await persistExamDraft({
|
||
examId: context.examId,
|
||
creatorId: ctx.userId, // 真实用户 ID
|
||
// ...
|
||
})
|
||
} catch (error) {
|
||
return failState("Database error")
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 改造前 — deleteExamAction
|
||
|
||
```typescript
|
||
export async function deleteExamAction(prevState, formData) {
|
||
const { examId } = parsed.data
|
||
// 无任何鉴权！任何人可删任何考试！
|
||
await db.delete(exams).where(eq(exams.id, examId))
|
||
}
|
||
```
|
||
|
||
#### 改造后 — deleteExamAction
|
||
|
||
```typescript
|
||
export async function deleteExamAction(prevState, formData): Promise<ActionState> {
|
||
let ctx: AuthContext
|
||
try {
|
||
ctx = await requirePermission(Permissions.EXAM_DELETE)
|
||
} catch (e) {
|
||
if (e instanceof PermissionDeniedError) return failState(e.message)
|
||
throw e
|
||
}
|
||
|
||
const { examId } = parsed.data
|
||
|
||
// 数据权限：非 admin 只能删自己创建的考试
|
||
if (ctx.dataScope.type !== "all") {
|
||
const exam = await db.query.exams.findFirst({
|
||
where: eq(exams.id, examId),
|
||
columns: { creatorId: true },
|
||
})
|
||
if (!exam) return failState("Exam not found")
|
||
if (exam.creatorId !== ctx.userId) {
|
||
return failState("You can only delete your own exams")
|
||
}
|
||
}
|
||
|
||
await db.delete(exams).where(eq(exams.id, examId))
|
||
revalidatePath("/teacher/exams/all")
|
||
return successState(examId, "Exam deleted")
|
||
}
|
||
```
|
||
|
||
### 5.2 Data-Access 层改造
|
||
|
||
#### 改造前 — getExams
|
||
|
||
```typescript
|
||
export const getExams = cache(async (params: GetExamsParams) => {
|
||
// 任何调用者都能看到所有考试
|
||
const data = await db.query.exams.findMany({
|
||
where: conditions.length ? and(...conditions) : undefined,
|
||
})
|
||
})
|
||
```
|
||
|
||
#### 改造后 — getExams
|
||
|
||
```typescript
|
||
export const getExams = cache(async (params: GetExamsParams & { scope: DataScope }) => {
|
||
const conditions = []
|
||
|
||
// 原有筛选
|
||
if (params.q) conditions.push(or(like(exams.title, search), like(exams.description, search)))
|
||
if (params.status && params.status !== "all") conditions.push(eq(exams.status, params.status))
|
||
|
||
// 数据权限自动过滤
|
||
switch (params.scope.type) {
|
||
case "all":
|
||
break
|
||
case "owned":
|
||
conditions.push(eq(exams.creatorId, /* userId from caller */))
|
||
break
|
||
case "class_taught": {
|
||
// 教师能看到自己班级关联的年级的考试
|
||
if (params.scope.classIds.length > 0) {
|
||
// 通过 class → grade 关联查询
|
||
const teacherGradeIds = await db
|
||
.selectDistinct({ gradeId: classes.gradeId })
|
||
.from(classes)
|
||
.where(inArray(classes.id, params.scope.classIds))
|
||
if (teacherGradeIds.length > 0) {
|
||
conditions.push(inArray(exams.gradeId, teacherGradeIds.map(g => g.gradeId)))
|
||
}
|
||
}
|
||
break
|
||
}
|
||
case "grade_managed":
|
||
if (params.scope.gradeIds.length > 0) {
|
||
conditions.push(inArray(exams.gradeId, params.scope.gradeIds))
|
||
}
|
||
break
|
||
case "class_members": {
|
||
// 学生看到自己年级的已发布考试
|
||
// 需要子查询获取学生所在班级的年级
|
||
break
|
||
}
|
||
}
|
||
|
||
const data = await db.query.exams.findMany({
|
||
where: conditions.length ? and(...conditions) : undefined,
|
||
})
|
||
})
|
||
```
|
||
|
||
### 5.3 前端改造
|
||
|
||
#### 改造前 — exam-actions.tsx
|
||
|
||
```tsx
|
||
// 仅通过路由守卫保护，组件内无权限判断
|
||
<Button onClick={handleDelete}>删除考试</Button>
|
||
```
|
||
|
||
#### 改造后 — exam-actions.tsx
|
||
|
||
```tsx
|
||
import { usePermission } from "@/shared/hooks/use-permission"
|
||
import { Permissions } from "@/shared/types/permissions"
|
||
|
||
function ExamActions({ examId }) {
|
||
const { hasPermission } = usePermission()
|
||
|
||
return (
|
||
<>
|
||
{hasPermission(Permissions.EXAM_UPDATE) && (
|
||
<Button onClick={handleEdit}>编辑</Button>
|
||
)}
|
||
{hasPermission(Permissions.EXAM_DELETE) && (
|
||
<Button onClick={handleDelete}>删除</Button>
|
||
)}
|
||
{hasPermission(Permissions.EXAM_DUPLICATE) && (
|
||
<Button onClick={handleDuplicate}>复制</Button>
|
||
)}
|
||
</>
|
||
)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、验收标准
|
||
|
||
- [ ] 所有 Server Action 都有 `requirePermission()` 调用
|
||
- [ ] `getCurrentUser()` 硬编码存根已移除
|
||
- [ ] 前端零 `role === "xxx"` 硬编码
|
||
- [ ] `exams/actions.ts` 的 CRUD 操作有资源归属校验
|
||
- [ ] `classes/actions.ts` 所有接口有鉴权
|
||
- [ ] `homework/actions.ts` 批改操作有资源归属校验
|
||
- [ ] Middleware 基于权限点而非角色字符串拦截
|
||
- [ ] 多角色用户可同时使用所有角色的功能
|
||
- [ ] `role_permissions` 表有 seed 数据
|
||
- [ ] 新增角色只需修改 `ROLE_PERMISSIONS` 映射 + seed，无需改动业务代码
|