feat: 首次登录引导与注册修复

BUG FIX && 权限验证
fix: login suspense + migrate middleware to proxy
2026-01-12 10:49:30 +08:00 · 2026-01-09 14:10:04 +08:00 · 2026-01-08 11:35:15 +08:00
17 changed files with 747 additions and 13 deletions
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -330,3 +330,31 @@ jobs:
          # 构建时跳过 ESLint/TS 检查 (因为已经在 quality-check job 做过了，加速构建)
          NEXT_TELEMETRY_DISABLED: 1
 ```
+
+## 工作记录（2026-01-12）
+
+### 注册与首次登录引导
+- 注册流程调整为“仅创建账户并跳转登录”，首次登录后通过全局弹窗分步骤完成资料配置
+- 全局引导弹窗包含：选择角色 → 通用信息（姓名/电话/住址）→ 角色信息（可跳过，后续在设置中补全）→ 完成
+- 新增/补齐用户扩展字段与迁移：phone、address、gender、age、gradeId、departmentId、onboardedAt
+- 新增引导状态与提交接口：`/api/onboarding/status`、`/api/onboarding/complete`
+
+相关文件：
+- src/shared/components/onboarding-gate.tsx
+- src/app/api/onboarding/status/route.ts
+- src/app/api/onboarding/complete/route.ts
+- src/shared/db/schema.ts
+- drizzle/0008_add_user_profile_fields.sql
+
+### 注册失败排查与错误提示
+- 注册 server action 增强错误信息（可识别重复邮箱、未迁移、权限错误、连接失败等），开发环境可返回更具体的底层错误消息
+- 本地排查曾出现 `ECONNREFUSED`，属于数据库连接不可达问题（需检查 MySQL 服务状态与 DATABASE_URL 配置）
+
+相关文件：
+- src/app/(auth)/register/page.tsx
+
+### 顶部头像信息修复
+- 修复右上角头像/下拉信息写死为 admin 的问题，改为从 NextAuth session 动态读取当前用户 name/email 并生成头像 fallback
+
+相关文件：
+- src/modules/layout/components/site-header.tsx
--- a/docs/design/002_teacher_dashboard_implementation.md
+++ b/docs/design/002_teacher_dashboard_implementation.md
@@ -170,6 +170,9 @@ Seed 脚本已覆盖班级相关数据，以便在开发环境快速验证页面
 - Next dev 锁文件：出现 `.next/dev/lock` 无法获取锁时，需要确保只有一个 dev 实例在运行，并清理残留 lock。
 - 头像资源 404：移除 Header 中硬编码的本地头像资源引用，避免 `public/avatars/...` 不存在导致的 404 噪音（见 `src/modules/layout/components/site-header.tsx`）。
 - 班级人数统计查询失败：`class_enrollments` 表实际列名为 `class_enrollment_status`，修复查询中引用的列名以恢复教师端班级列表渲染。
+- Students 页面 key 冲突：学生列表跨班级汇总时，`<TableRow key={studentId}>` 会重复，改为使用 `classId:studentId` 作为 key。
+- Build 预渲染失败（/login）：`LoginForm` 使用 `useSearchParams()` 获取回跳地址，需在 `/login` 页面用 `Suspense` 包裹以避免 CSR bailout 报错。
+- 构建警告（middleware）：Next.js 16 将文件约定从 `middleware.ts` 改为 `proxy.ts`，已迁移以消除警告。

 ### 6.6 班级详情页（聚合视图 + Schedule Builder + Homework 统计）

@@ -211,3 +214,18 @@ Seed 脚本已覆盖班级相关数据，以便在开发环境快速验证页面

 #### 6.7.4 Seed 支持
 - `scripts/seed.ts` 为示例班级补充 `invitationCode`，便于在开发环境直接验证加入流程。
+
+### 6.8 更新记录（2026-01-09）
+
+#### 6.8.1 班级创建权限收紧
+- 目标：仅允许年级组长与 admin 创建班级。
+- 后端：`createTeacherClassAction` 增加权限校验，非 admin 必须是对应年级的 `gradeHead`；`createAdminClassAction` 强制仅 admin 可调用（`src/modules/classes/actions.ts`）。
+- 前端：教师端「My Classes」页基于当前用户是否为任一年级 `gradeHead` 计算 `canCreateClass`，并禁用创建入口（`src/app/(dashboard)/teacher/classes/my/page.tsx`、`src/modules/classes/components/my-classes-grid.tsx`）。
+
+#### 6.8.2 注册页面从演示提交改为真实注册
+- `/register` 增加服务端注册动作：校验输入、邮箱查重、插入 `users` 表，默认 `role=student`（`src/app/(auth)/register/page.tsx`）。
+- 注册表单接入注册动作并展示成功/失败提示，成功后跳转至 `/login`（`src/modules/auth/components/register-form.tsx`）。
+
+#### 6.8.3 生产环境登录 UntrustedHost 修复
+- 问题：服务器上访问 `/api/auth/session` 报 `[auth][error] UntrustedHost`。
+- 修复：Auth.js 配置开启 `trustHost: true` 并显式设置 `secret`（`src/auth.ts`）。
--- a/drizzle/0008_add_user_profile_fields.sql
+++ b/drizzle/0008_add_user_profile_fields.sql
@@ -0,0 +1,17 @@
+ALTER TABLE `users` ADD `phone` varchar(30);
+--> statement-breakpoint
+ALTER TABLE `users` ADD `address` varchar(255);
+--> statement-breakpoint
+ALTER TABLE `users` ADD `gender` varchar(20);
+--> statement-breakpoint
+ALTER TABLE `users` ADD `age` int;
+--> statement-breakpoint
+ALTER TABLE `users` ADD `grade_id` varchar(128);
+--> statement-breakpoint
+ALTER TABLE `users` ADD `department_id` varchar(128);
+--> statement-breakpoint
+ALTER TABLE `users` ADD `onboarded_at` timestamp;
+--> statement-breakpoint
+CREATE INDEX `users_grade_id_idx` ON `users` (`grade_id`);
+--> statement-breakpoint
+CREATE INDEX `users_department_id_idx` ON `users` (`department_id`);
--- a/drizzle/meta/_journal.json
+++ b/drizzle/meta/_journal.json
@@ -57,6 +57,13 @@
      "when": 1767782500000,
      "tag": "0007_add_class_invitation_code",
      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "5",
+      "when": 1767941300000,
+      "tag": "0008_add_user_profile_fields",
+      "breakpoints": true
    }
  ]
 }
--- a/src/app/(auth)/register/page.tsx
+++ b/src/app/(auth)/register/page.tsx
@@ -1,4 +1,8 @@
 import { Metadata } from "next"
+import { createId } from "@paralleldrive/cuid2"
+import { eq } from "drizzle-orm"
+
+import type { ActionState } from "@/shared/types/action-state"
 import { RegisterForm } from "@/modules/auth/components/register-form"

 export const metadata: Metadata = {
@@ -7,5 +11,104 @@ export const metadata: Metadata = {
 }

 export default function RegisterPage() {
-  return <RegisterForm />
+  async function registerAction(formData: FormData): Promise<ActionState> {
+    "use server"
+
+    const databaseUrl = process.env.DATABASE_URL
+    if (!databaseUrl) return { success: false, message: "DATABASE_URL 未配置" }
+
+    try {
+      const [{ db }, { users }] = await Promise.all([
+        import("@/shared/db"),
+        import("@/shared/db/schema"),
+      ])
+
+      const name = String(formData.get("name") ?? "").trim()
+      const email = String(formData.get("email") ?? "").trim().toLowerCase()
+      const password = String(formData.get("password") ?? "")
+
+      if (!email) return { success: false, message: "请输入邮箱" }
+      if (!password) return { success: false, message: "请输入密码" }
+      if (password.length < 6) return { success: false, message: "密码至少 6 位" }
+
+      const existing = await db.query.users.findFirst({
+        where: eq(users.email, email),
+        columns: { id: true },
+      })
+      if (existing) return { success: false, message: "该邮箱已注册" }
+
+      await db.insert(users).values({
+        id: createId(),
+        name: name.length ? name : null,
+        email,
+        password,
+        role: "student",
+      })
+
+      return { success: true, message: "账户创建成功" }
+    } catch (error) {
+      const isProd = process.env.NODE_ENV === "production"
+
+      const anyErr = error as unknown as {
+        code?: string
+        message?: string
+        sqlMessage?: string
+        cause?: unknown
+      }
+
+      const cause1 = anyErr?.cause as
+        | { code?: string; message?: string; sqlMessage?: string; cause?: unknown }
+        | undefined
+      const cause2 = (cause1?.cause ?? undefined) as
+        | { code?: string; message?: string; sqlMessage?: string }
+        | undefined
+
+      const code = String(cause2?.code ?? cause1?.code ?? anyErr?.code ?? "").trim()
+      const msg = String(
+        cause2?.sqlMessage ??
+          cause1?.sqlMessage ??
+          anyErr?.sqlMessage ??
+          cause2?.message ??
+          cause1?.message ??
+          anyErr?.message ??
+          ""
+      ).trim()
+      const msgLower = msg.toLowerCase()
+
+      if (
+        code === "ER_DUP_ENTRY" ||
+        msgLower.includes("duplicate") ||
+        msgLower.includes("unique")
+      ) {
+        return { success: false, message: "该邮箱已注册" }
+      }
+
+      if (
+        code === "ER_NO_SUCH_TABLE" ||
+        msgLower.includes("doesn't exist") ||
+        msgLower.includes("unknown column")
+      ) {
+        return {
+          success: false,
+          message: "数据库未初始化或未迁移，请先运行 npm run db:migrate",
+        }
+      }
+
+      if (code === "ER_ACCESS_DENIED_ERROR") {
+        return { success: false, message: "数据库账号/权限错误，请检查 DATABASE_URL" }
+      }
+
+      if (code === "ECONNREFUSED" || code === "ENOTFOUND") {
+        return { success: false, message: "数据库连接失败，请检查 DATABASE_URL 与网络" }
+      }
+
+      if (!isProd && msg) {
+        return { success: false, message: `创建账户失败：${msg}` }
+      }
+
+      return { success: false, message: "创建账户失败，请稍后重试" }
+    }
+  }
+
+  return <RegisterForm registerAction={registerAction} />
 }
--- a/src/app/(dashboard)/teacher/classes/my/page.tsx
+++ b/src/app/(dashboard)/teacher/classes/my/page.tsx
@@ -1,5 +1,9 @@
+import { eq } from "drizzle-orm"
 import { getTeacherClasses } from "@/modules/classes/data-access"
 import { MyClassesGrid } from "@/modules/classes/components/my-classes-grid"
+import { auth } from "@/auth"
+import { db } from "@/shared/db"
+import { grades } from "@/shared/db/schema"

 export const dynamic = "force-dynamic"

@@ -9,6 +13,16 @@ export default function MyClassesPage() {

 async function MyClassesPageImpl() {
  const classes = await getTeacherClasses()
+  const session = await auth()
+  const role = String(session?.user?.role ?? "")
+  const userId = String(session?.user?.id ?? "").trim()
+
+  const canCreateClass = await (async () => {
+    if (role === "admin") return true
+    if (!userId) return false
+    const [row] = await db.select({ id: grades.id }).from(grades).where(eq(grades.gradeHeadId, userId)).limit(1)
+    return Boolean(row)
+  })()

  return (
    <div className="flex h-full flex-col space-y-8 p-8">
@@ -21,7 +35,7 @@ async function MyClassesPageImpl() {
        </div>
      </div>

-      <MyClassesGrid classes={classes} />
+      <MyClassesGrid classes={classes} canCreateClass={canCreateClass} />
    </div>
  )
 }
--- a/src/app/api/onboarding/complete/route.ts
+++ b/src/app/api/onboarding/complete/route.ts
@@ -0,0 +1,109 @@
+import { NextResponse } from "next/server"
+import { eq, inArray } from "drizzle-orm"
+
+import { auth } from "@/auth"
+import { db } from "@/shared/db"
+import { classes, classSubjectTeachers, users } from "@/shared/db/schema"
+import { DEFAULT_CLASS_SUBJECTS, type ClassSubject } from "@/modules/classes/types"
+import { enrollStudentByInvitationCode } from "@/modules/classes/data-access"
+
+export const dynamic = "force-dynamic"
+
+function parseCodes(input: string) {
+  const raw = input
+    .split(/[\s,，;；]+/g)
+    .map((s) => s.trim())
+    .filter(Boolean)
+  return Array.from(new Set(raw))
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null
+}
+
+export async function POST(req: Request) {
+  const session = await auth()
+  const userId = String(session?.user?.id ?? "").trim()
+  if (!userId) return NextResponse.json({ success: false, message: "Unauthorized" }, { status: 401 })
+
+  const body = await req.json().catch(() => null)
+  if (!isRecord(body)) return NextResponse.json({ success: false, message: "Invalid payload" }, { status: 400 })
+
+  const roleRaw = String(body.role ?? "").trim()
+  const allowedRoles = ["student", "teacher", "parent", "admin"] as const
+  const role = (allowedRoles as readonly string[]).includes(roleRaw) ? roleRaw : null
+  if (!role) return NextResponse.json({ success: false, message: "Invalid role" }, { status: 400 })
+
+  const current = await db.query.users.findFirst({
+    where: eq(users.id, userId),
+    columns: { role: true },
+  })
+  const currentRole = String(current?.role ?? "student")
+
+  if (role === "admin" && currentRole !== "admin") {
+    return NextResponse.json({ success: false, message: "Forbidden" }, { status: 403 })
+  }
+
+  const name = String(body.name ?? "").trim()
+  if (!name) return NextResponse.json({ success: false, message: "Name is required" }, { status: 400 })
+
+  const phone = String(body.phone ?? "").trim()
+  const address = String(body.address ?? "").trim()
+
+  const classCodesText = String(body.classCodes ?? "").trim()
+  const codes = classCodesText.length ? parseCodes(classCodesText) : []
+
+  const teacherSubjectsRaw = Array.isArray(body.teacherSubjects) ? body.teacherSubjects : []
+  const teacherSubjects = teacherSubjectsRaw
+    .map((s) => String(s).trim())
+    .filter((s): s is ClassSubject => DEFAULT_CLASS_SUBJECTS.includes(s as ClassSubject))
+
+  await db
+    .update(users)
+    .set({
+      role,
+      name,
+      phone: phone.length ? phone : null,
+      address: address.length ? address : null,
+    })
+    .where(eq(users.id, userId))
+
+  if (role === "student" && codes.length) {
+    for (const code of codes) {
+      await enrollStudentByInvitationCode(userId, code)
+    }
+  }
+
+  if (role === "teacher" && codes.length && teacherSubjects.length) {
+    const classRows = await db
+      .select({ id: classes.id, invitationCode: classes.invitationCode })
+      .from(classes)
+      .where(inArray(classes.invitationCode, codes))
+
+    const byCode = new Map<string, string>()
+    for (const r of classRows) {
+      if (typeof r.invitationCode === "string") {
+        byCode.set(r.invitationCode, r.id)
+      }
+    }
+
+    for (const code of codes) {
+      const classId = byCode.get(code)
+      if (!classId) continue
+      for (const subject of teacherSubjects) {
+        await db
+          .insert(classSubjectTeachers)
+          .values({ classId, subject, teacherId: userId })
+          .onDuplicateKeyUpdate({ set: { teacherId: userId, updatedAt: new Date() } })
+      }
+    }
+  }
+
+  await db
+    .update(users)
+    .set({ onboardedAt: new Date() })
+    .where(eq(users.id, userId))
+
+  return NextResponse.json({ success: true })
+}
+
--- a/src/app/api/onboarding/status/route.ts
+++ b/src/app/api/onboarding/status/route.ts
@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server"
+import { eq } from "drizzle-orm"
+
+import { auth } from "@/auth"
+import { db } from "@/shared/db"
+import { users } from "@/shared/db/schema"
+
+export const dynamic = "force-dynamic"
+
+export async function GET() {
+  const session = await auth()
+  const userId = String(session?.user?.id ?? "").trim()
+  if (!userId) {
+    return NextResponse.json({ required: false })
+  }
+
+  const row = await db.query.users.findFirst({
+    where: eq(users.id, userId),
+    columns: { onboardedAt: true, role: true },
+  })
+
+  const required = !row?.onboardedAt
+  return NextResponse.json({ required, role: row?.role ?? "student" })
+}
+
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -3,6 +3,7 @@ import { ThemeProvider } from "@/shared/components/theme-provider";
 import { Toaster } from "@/shared/components/ui/sonner";
 import { NuqsAdapter } from 'nuqs/adapters/next/app'
 import { AuthSessionProvider } from "@/shared/components/auth-session-provider"
+import { OnboardingGate } from "@/shared/components/onboarding-gate"
 import "./globals.css";

 export const metadata: Metadata = {
@@ -29,6 +30,7 @@ export default function RootLayout({
          <AuthSessionProvider>
            <NuqsAdapter>
              {children}
+              <OnboardingGate />
            </NuqsAdapter>
          </AuthSessionProvider>
          <Toaster />
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -2,6 +2,8 @@ import NextAuth from "next-auth"
 import Credentials from "next-auth/providers/credentials"

 export const { handlers, auth, signIn, signOut } = NextAuth({
+  trustHost: true,
+  secret: process.env.NEXTAUTH_SECRET,
  session: { strategy: "jwt" },
  pages: { signIn: "/login" },
  providers: [
@@ -47,13 +49,37 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
      if (user) {
        token.id = (user as { id: string }).id
        token.role = (user as { role?: string }).role ?? "student"
+        token.name = (user as { name?: string }).name
      }
+
+      const userId = String(token.id ?? "").trim()
+      if (userId) {
+        const [{ eq }, { db }, { users }] = await Promise.all([
+          import("drizzle-orm"),
+          import("@/shared/db"),
+          import("@/shared/db/schema"),
+        ])
+
+        const fresh = await db.query.users.findFirst({
+          where: eq(users.id, userId),
+          columns: { role: true, name: true },
+        })
+
+        if (fresh) {
+          token.role = fresh.role ?? token.role ?? "student"
+          token.name = fresh.name ?? token.name
+        }
+      }
+
      return token
    },
    session: async ({ session, token }) => {
      if (session.user) {
        session.user.id = String(token.id ?? "")
        session.user.role = String(token.role ?? "student")
+        if (typeof token.name === "string") {
+          session.user.name = token.name
+        }
      }
      return session
    },
--- a/src/modules/auth/components/register-form.tsx
+++ b/src/modules/auth/components/register-form.tsx
@@ -2,24 +2,44 @@

 import * as React from "react"
 import Link from "next/link"
+import { useRouter } from "next/navigation"
+import { toast } from "sonner"
 import { Button } from "@/shared/components/ui/button"
 import { Input } from "@/shared/components/ui/input"
 import { Label } from "@/shared/components/ui/label"
 import { cn } from "@/shared/lib/utils"
 import { Loader2, Github } from "lucide-react"
+import type { ActionState } from "@/shared/types/action-state"

-type RegisterFormProps = React.HTMLAttributes<HTMLDivElement>
+type RegisterFormProps = React.HTMLAttributes<HTMLDivElement> & {
+  registerAction: (formData: FormData) => Promise<ActionState>
+}

-export function RegisterForm({ className, ...props }: RegisterFormProps) {
+export function RegisterForm({ className, registerAction, ...props }: RegisterFormProps) {
  const [isLoading, setIsLoading] = React.useState<boolean>(false)
+  const router = useRouter()

  async function onSubmit(event: React.SyntheticEvent) {
    event.preventDefault()
    setIsLoading(true)

-    setTimeout(() => {
+    try {
+      const form = event.currentTarget as HTMLFormElement
+      const formData = new FormData(form)
+      const res = await registerAction(formData)
+
+      if (res.success) {
+        toast.success(res.message || "Account created")
+        router.push("/login")
+        router.refresh()
+      } else {
+        toast.error(res.message || "Failed to create account")
+      }
+    } catch {
+      toast.error("Failed to create account")
+    } finally {
      setIsLoading(false)
-    }, 3000)
+    }
  }

  return (
@@ -38,6 +58,7 @@ export function RegisterForm({ className, ...props }: RegisterFormProps) {
            <Label htmlFor="name">Full Name</Label>
            <Input
              id="name"
+              name="name"
              placeholder="John Doe"
              type="text"
              autoCapitalize="words"
@@ -50,6 +71,7 @@ export function RegisterForm({ className, ...props }: RegisterFormProps) {
            <Label htmlFor="email">Email</Label>
            <Input
              id="email"
+              name="email"
              placeholder="name@example.com"
              type="email"
              autoCapitalize="none"
@@ -62,6 +84,7 @@ export function RegisterForm({ className, ...props }: RegisterFormProps) {
            <Label htmlFor="password">Password</Label>
            <Input
              id="password"
+              name="password"
              type="password"
              autoComplete="new-password"
              disabled={isLoading}
--- a/src/modules/classes/actions.ts
+++ b/src/modules/classes/actions.ts
@@ -1,8 +1,11 @@
 "use server";

 import { revalidatePath } from "next/cache"
+import { and, eq, sql } from "drizzle-orm"
 import { auth } from "@/auth"

+import { db } from "@/shared/db"
+import { grades } from "@/shared/db/schema"
 import type { ActionState } from "@/shared/types/action-state"
 import {
  createAdminClass,
@@ -44,6 +47,26 @@ export async function createTeacherClassAction(
    return { success: false, message: "Grade is required" }
  }

+  const session = await auth()
+  if (!session?.user) return { success: false, message: "Unauthorized" }
+
+  const role = String(session.user.role ?? "")
+  if (role !== "admin") {
+    const userId = String(session.user.id ?? "").trim()
+    if (!userId) return { success: false, message: "Unauthorized" }
+
+    const normalizedGradeId = typeof gradeId === "string" ? gradeId.trim() : ""
+    const normalizedGradeName = grade.trim().toLowerCase()
+    const where = normalizedGradeId
+      ? and(eq(grades.id, normalizedGradeId), eq(grades.gradeHeadId, userId))
+      : and(eq(grades.gradeHeadId, userId), sql`LOWER(${grades.name}) = ${normalizedGradeName}`)
+
+    const [ownedGrade] = await db.select({ id: grades.id }).from(grades).where(where).limit(1)
+    if (!ownedGrade) {
+      return { success: false, message: "Only admins and grade heads can create classes" }
+    }
+  }
+
  try {
    const id = await createTeacherClass({
      schoolName: typeof schoolName === "string" ? schoolName : null,
@@ -311,6 +334,11 @@ export async function createAdminClassAction(
  prevState: ActionState<string> | undefined,
  formData: FormData
 ): Promise<ActionState<string>> {
+  const session = await auth()
+  if (!session?.user?.id || String(session.user.role ?? "") !== "admin") {
+    return { success: false, message: "Unauthorized" }
+  }
+
  const schoolName = formData.get("schoolName")
  const schoolId = formData.get("schoolId")
  const name = formData.get("name")
--- a/src/modules/classes/components/my-classes-grid.tsx
+++ b/src/modules/classes/components/my-classes-grid.tsx
@@ -50,7 +50,7 @@ import {
  updateTeacherClassAction,
 } from "../actions"

-export function MyClassesGrid({ classes }: { classes: TeacherClass[] }) {
+export function MyClassesGrid({ classes, canCreateClass }: { classes: TeacherClass[]; canCreateClass: boolean }) {
  const router = useRouter()
  const [isWorking, setIsWorking] = useState(false)
  const [createOpen, setCreateOpen] = useState(false)
@@ -133,12 +133,13 @@ export function MyClassesGrid({ classes }: { classes: TeacherClass[] }) {
        <Dialog
          open={createOpen}
          onOpenChange={(open) => {
+            if (!canCreateClass) return
            if (isWorking) return
            setCreateOpen(open)
          }}
        >
          <DialogTrigger asChild>
-            <Button className="gap-2" disabled={isWorking}>
+            <Button className="gap-2" disabled={isWorking || !canCreateClass}>
              <Plus className="size-4" />
              New class
            </Button>
@@ -209,7 +210,7 @@ export function MyClassesGrid({ classes }: { classes: TeacherClass[] }) {
            title="No classes yet"
            description="Create your first class to start managing students and schedules."
            icon={Users}
-            action={{ label: "Create class", onClick: () => setCreateOpen(true) }}
+            action={canCreateClass ? { label: "Create class", onClick: () => setCreateOpen(true) } : undefined}
            className="h-[360px] bg-card sm:col-span-2 lg:col-span-3"
          />
        ) : filteredClasses.length === 0 ? (
--- a/src/modules/layout/components/site-header.tsx
+++ b/src/modules/layout/components/site-header.tsx
@@ -3,7 +3,7 @@
 import * as React from "react"
 import Link from "next/link"
 import { Bell, Menu, Search } from "lucide-react"
-import { signOut } from "next-auth/react"
+import { signOut, useSession } from "next-auth/react"

 import { Button } from "@/shared/components/ui/button"
 import { Input } from "@/shared/components/ui/input"
@@ -30,6 +30,19 @@ import { useSidebar } from "./sidebar-provider"

 export function SiteHeader() {
  const { toggleSidebar, isMobile } = useSidebar()
+  const { data: session, status } = useSession()
+
+  const name = session?.user?.name ?? ""
+  const email = session?.user?.email ?? ""
+  const displayName = name || email || (status === "loading" ? "加载中..." : "未登录")
+
+  const fallbackBase = name || email || "?"
+  const avatarFallback = fallbackBase
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((p) => p[0]?.toUpperCase())
+    .join("")

  return (
    <header className="bg-background/95 supports-[backdrop-filter]:bg-background/60 sticky top-0 z-50 flex h-16 items-center border-b px-4 backdrop-blur-sm">
@@ -80,15 +93,17 @@ export function SiteHeader() {
            <DropdownMenuTrigger asChild>
                <Button variant="ghost" className="relative size-8 rounded-full">
                    <Avatar className="size-8">
-                        <AvatarFallback>AD</AvatarFallback>
+                        <AvatarFallback>{avatarFallback}</AvatarFallback>
                    </Avatar>
                </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent className="w-56" align="end" forceMount>
                <DropdownMenuLabel className="font-normal">
                    <div className="flex flex-col space-y-1">
-                        <p className="text-sm font-medium leading-none">Admin User</p>
-                        <p className="text-muted-foreground text-xs leading-none">admin@nextedu.com</p>
+                        <p className="text-sm font-medium leading-none">{displayName}</p>
+                        {email ? (
+                          <p className="text-muted-foreground text-xs leading-none">{email}</p>
+                        ) : null}
                    </div>
                </DropdownMenuLabel>
                <DropdownMenuSeparator />
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -42,3 +42,4 @@ export default auth((req: NextAuthRequest) => {
 export const config = {
  matcher: ["/dashboard", "/admin/:path*", "/teacher/:path*", "/student/:path*", "/parent/:path*", "/settings/:path*", "/profile"],
 }
+
--- a/src/shared/components/onboarding-gate.tsx
+++ b/src/shared/components/onboarding-gate.tsx
@@ -0,0 +1,307 @@
+"use client"
+
+import { useEffect, useMemo, useState } from "react"
+import { useRouter } from "next/navigation"
+import { useSession } from "next-auth/react"
+import { toast } from "sonner"
+
+import { Button } from "@/shared/components/ui/button"
+import { Checkbox } from "@/shared/components/ui/checkbox"
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@/shared/components/ui/dialog"
+import { Input } from "@/shared/components/ui/input"
+import { Label } from "@/shared/components/ui/label"
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/shared/components/ui/select"
+import { Textarea } from "@/shared/components/ui/textarea"
+import { cn } from "@/shared/lib/utils"
+
+type Role = "student" | "teacher" | "parent" | "admin"
+
+const TEACHER_SUBJECTS = ["语文", "数学", "英语", "美术", "体育", "科学", "社会", "音乐"] as const
+type TeacherSubject = (typeof TEACHER_SUBJECTS)[number]
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null
+}
+
+export function OnboardingGate() {
+  const router = useRouter()
+  const { status, data: session } = useSession()
+  const [required, setRequired] = useState(false)
+  const [currentRole, setCurrentRole] = useState<Role>("student")
+  const [open, setOpen] = useState(false)
+  const [step, setStep] = useState(0)
+  const [isSubmitting, setIsSubmitting] = useState(false)
+
+  const [role, setRole] = useState<Role>("student")
+  const [name, setName] = useState("")
+  const [phone, setPhone] = useState("")
+  const [address, setAddress] = useState("")
+
+  const [classCodes, setClassCodes] = useState("")
+  const [teacherSubjects, setTeacherSubjects] = useState<TeacherSubject[]>([])
+
+  const canClose = useMemo(() => !required, [required])
+
+  useEffect(() => {
+    if (status !== "authenticated") return
+    let cancelled = false
+    ;(async () => {
+      const res = await fetch("/api/onboarding/status", { cache: "no-store" }).catch(() => null)
+      const json = res ? await res.json().catch(() => null) : null
+      if (cancelled) return
+      if (isRecord(json)) {
+        const required = Boolean(json.required)
+        const role = String(json.role ?? "student") as Role
+        setRequired(required)
+        setCurrentRole(role)
+        setRole(role === "admin" ? "admin" : "student")
+        setName(String(session?.user?.name ?? "").trim())
+        if (required) {
+          setOpen(true)
+          setStep(0)
+        }
+      }
+    })()
+
+    return () => {
+      cancelled = true
+    }
+  }, [status, session?.user?.name])
+
+  useEffect(() => {
+    if (!open) return
+    if (!required) return
+    setOpen(true)
+  }, [open, required])
+
+  const title =
+    step === 0 ? "角色选择" : step === 1 ? "通用信息" : step === 2 ? "角色信息（可跳过）" : "完成"
+  const description =
+    step === 0
+      ? "请选择你在系统中的角色"
+      : step === 1
+        ? "填写姓名、电话、住址等信息"
+        : step === 2
+          ? "不同角色可配置班级代码、教学科目等"
+          : "配置完成，可以进入系统"
+
+  const canNextFromStep0 = role.length > 0
+  const canNextFromStep1 = name.trim().length > 0 && phone.trim().length > 0
+
+  const onNext = async () => {
+    if (step === 0) {
+      if (!canNextFromStep0) return
+      setStep(1)
+      return
+    }
+    if (step === 1) {
+      if (!canNextFromStep1) {
+        toast.error("请填写姓名与电话")
+        return
+      }
+      if (role === "admin") {
+        setStep(3)
+      } else {
+        setStep(2)
+      }
+      return
+    }
+    if (step === 2) {
+      setStep(3)
+      return
+    }
+  }
+
+  const onBack = () => {
+    if (step === 0) return
+    setStep((s) => Math.max(0, s - 1))
+  }
+
+  const toggleSubject = (subject: TeacherSubject) => {
+    setTeacherSubjects((prev) => (prev.includes(subject) ? prev.filter((s) => s !== subject) : [...prev, subject]))
+  }
+
+  const onFinish = async () => {
+    setIsSubmitting(true)
+    try {
+      const res = await fetch("/api/onboarding/complete", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          role,
+          name,
+          phone,
+          address,
+          classCodes,
+          teacherSubjects,
+        }),
+      })
+      const json = await res.json().catch(() => null)
+      if (!res.ok || !isRecord(json) || json.success !== true) {
+        const msg = isRecord(json) ? String(json.message ?? "") : ""
+        throw new Error(msg || "提交失败")
+      }
+
+      toast.success("配置完成")
+      setRequired(false)
+      setOpen(false)
+      router.push("/dashboard")
+      router.refresh()
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : "提交失败"
+      toast.error(msg)
+    } finally {
+      setIsSubmitting(false)
+    }
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(v) => {
+        if (canClose) setOpen(v)
+        else setOpen(true)
+      }}
+    >
+      <DialogContent className="sm:max-w-[720px]">
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+
+        <div className="grid gap-4">
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <div className={cn("h-1 flex-1 rounded", step >= 0 ? "bg-primary" : "bg-muted")} />
+            <div className={cn("h-1 flex-1 rounded", step >= 1 ? "bg-primary" : "bg-muted")} />
+            <div className={cn("h-1 flex-1 rounded", step >= 2 ? "bg-primary" : "bg-muted")} />
+            <div className={cn("h-1 flex-1 rounded", step >= 3 ? "bg-primary" : "bg-muted")} />
+          </div>
+
+          {step === 0 ? (
+            <div className="grid gap-2">
+              <Label>Role</Label>
+              {currentRole === "admin" ? (
+                <div className="rounded-md border px-3 py-2 text-sm">admin</div>
+              ) : (
+                <Select value={role} onValueChange={(v) => setRole(v as Role)}>
+                  <SelectTrigger>
+                    <SelectValue placeholder="Select role" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="student">student</SelectItem>
+                    <SelectItem value="teacher">teacher</SelectItem>
+                    <SelectItem value="parent">parent</SelectItem>
+                  </SelectContent>
+                </Select>
+              )}
+            </div>
+          ) : null}
+
+          {step === 1 ? (
+            <div className="grid gap-4">
+              <div className="grid gap-2">
+                <Label htmlFor="onb_name">姓名</Label>
+                <Input id="onb_name" value={name} onChange={(e) => setName(e.target.value)} />
+              </div>
+              <div className="grid gap-2">
+                <Label htmlFor="onb_phone">电话</Label>
+                <Input id="onb_phone" value={phone} onChange={(e) => setPhone(e.target.value)} />
+              </div>
+              <div className="grid gap-2">
+                <Label htmlFor="onb_address">住址</Label>
+                <Input id="onb_address" value={address} onChange={(e) => setAddress(e.target.value)} />
+              </div>
+            </div>
+          ) : null}
+
+          {step === 2 ? (
+            <div className="grid gap-4">
+              {role === "teacher" ? (
+                <>
+                  <div className="grid gap-2">
+                    <Label htmlFor="onb_codes_teacher">班级代码（可多个）</Label>
+                    <Textarea
+                      id="onb_codes_teacher"
+                      value={classCodes}
+                      onChange={(e) => setClassCodes(e.target.value)}
+                      placeholder="每行一个或用逗号分隔"
+                    />
+                  </div>
+                  <div className="grid gap-2">
+                    <Label>教学科目</Label>
+                    <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+                      {TEACHER_SUBJECTS.map((s) => (
+                        <label key={s} className="flex items-center gap-2 text-sm">
+                          <Checkbox checked={teacherSubjects.includes(s)} onCheckedChange={() => toggleSubject(s)} />
+                          {s}
+                        </label>
+                      ))}
+                    </div>
+                  </div>
+                </>
+              ) : null}
+
+              {role === "student" ? (
+                <div className="grid gap-2">
+                  <Label htmlFor="onb_codes_student">班级代码</Label>
+                  <Textarea
+                    id="onb_codes_student"
+                    value={classCodes}
+                    onChange={(e) => setClassCodes(e.target.value)}
+                    placeholder="每行一个或用逗号分隔"
+                  />
+                </div>
+              ) : null}
+
+              {role === "parent" ? (
+                <div className="rounded-md border px-3 py-2 text-sm text-muted-foreground">
+                  家长角色暂不需要配置，可跳过
+                </div>
+              ) : null}
+            </div>
+          ) : null}
+
+          {step === 3 ? (
+            <div className="rounded-md border px-3 py-3 text-sm">
+              <div className="font-medium">已准备完成</div>
+              <div className="text-muted-foreground">点击完成后进入系统。</div>
+            </div>
+          ) : null}
+        </div>
+
+        <DialogFooter>
+          <div className="flex w-full flex-col-reverse gap-2 sm:flex-row sm:justify-between">
+            <div className="flex gap-2">
+              <Button type="button" variant="outline" onClick={onBack} disabled={step === 0 || isSubmitting}>
+                上一步
+              </Button>
+              {step === 2 ? (
+                <Button
+                  type="button"
+                  variant="secondary"
+                  onClick={() => setStep(3)}
+                  disabled={isSubmitting}
+                >
+                  跳过
+                </Button>
+              ) : null}
+            </div>
+
+            <div className="flex gap-2 justify-end">
+              {step < 3 ? (
+                <Button type="button" onClick={onNext} disabled={isSubmitting}>
+                  下一步
+                </Button>
+              ) : (
+                <Button type="button" onClick={onFinish} disabled={isSubmitting}>
+                  完成
+                </Button>
+              )}
+            </div>
+          </div>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
--- a/src/shared/db/schema.ts
+++ b/src/shared/db/schema.ts
@@ -31,11 +31,21 @@ export const users = mysqlTable("users", {
  
  // Credentials Auth (Optional)
  password: varchar("password", { length: 255 }), 
+
+  phone: varchar("phone", { length: 30 }),
+  address: varchar("address", { length: 255 }),
+  gender: varchar("gender", { length: 20 }),
+  age: int("age"),
+  gradeId: varchar("grade_id", { length: 128 }),
+  departmentId: varchar("department_id", { length: 128 }),
+  onboardedAt: timestamp("onboarded_at", { mode: "date" }),
  
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().onUpdateNow().notNull(),
 }, (table) => ({
  emailIdx: index("email_idx").on(table.email),
+  gradeIdIdx: index("users_grade_id_idx").on(table.gradeId),
+  departmentIdIdx: index("users_department_id_idx").on(table.departmentId),
 }));

 // Auth.js: Accounts (OAuth providers)
Author	SHA1	Message	Date
SpecialX	8577280ab2	feat: 首次登录引导与注册修复 All checks were successful CI / build-and-test (push) Successful in 20m12s Details CI / deploy (push) Successful in 1m18s Details	2026-01-12 10:49:30 +08:00
SpecialX	15fcf2bc78	BUG FIX && 权限验证 All checks were successful CI / build-and-test (push) Successful in 18m11s Details CI / deploy (push) Successful in 1m19s Details	2026-01-09 14:10:04 +08:00
SpecialX	15d9ea9cb8	fix: login suspense + migrate middleware to proxy	2026-01-08 11:35:15 +08:00