feat: 新增备课模块并修复全模块 P0/P1/P2 缺陷

主要变更: - 新增 lesson-preparation 模块: 备课编辑器、节点编辑、AI 建议、知识点选择、版本历史、作业发布 - 新增 shared 通用组件: charts/question-bank-filters/schedule-list/ui (chip-nav/filter-bar/page-header/stat-card/stat-item) - 新增 student/admin 端 loading.tsx 与 error.tsx, 优化加载与错误态体验 - 新增 teacher/lesson-plans 页面 (列表/新建/编辑) - 新增 drizzle 迁移 0002_tiny_lionheart 及 snapshot - 新增 textbooks/schema.ts 与 exams/utils/normalize-structure.ts - 修复 Tiptap v3 SSR hydration 崩溃 (rich-text-block immediatelyRender: false) - 重构多模块 data-access/actions/组件, 修复权限校验与类型规范 - 同步架构文档 004/005 反映新增模块、导出、依赖关系 - 归档 bugs/* 测试报告与 e2e 测试脚本 (admin/parent/student/teacher web_test)
2026-06-22 01:06:16 +08:00
parent d8962aba96
commit 978d9a8309
327 changed files with 34070 additions and 5642 deletions
--- a/src/modules/parent/components/child-card.tsx
+++ b/src/modules/parent/components/child-card.tsx
@@ -4,24 +4,25 @@ import { ChevronRight, GraduationCap, PenTool, TriangleAlert } from "lucide-reac
 import { Avatar, AvatarFallback, AvatarImage } from "@/shared/components/ui/avatar"
 import { Badge } from "@/shared/components/ui/badge"
 import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
+import { cn, getInitials } from "@/shared/lib/utils"
 import type { ChildDashboardData } from "@/modules/parent/types"

-const getInitials = (name: string | null) => {
-  if (!name) return "S"
-  return name.slice(0, 2).toUpperCase()
-}
-
 export function ChildCard({ child }: { child: ChildDashboardData }) {
  const { basicInfo, homeworkSummary, gradeTrend } = child
  const ranking = gradeTrend.ranking
  const latestGrade = gradeTrend.recent[0]
+  const childName = basicInfo.name ?? "Child"

  return (
-    <Link href={`/parent/children/${basicInfo.id}`} className="block">
-      <Card className="hover:bg-muted/50 transition-colors cursor-pointer h-full">
+    <Link
+      href={`/parent/children/${basicInfo.id}`}
+      aria-label={`View ${childName}'s details`}
+      className="block focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 rounded-md"
+    >
+      <Card className="hover:bg-muted/50 transition-colors h-full">
        <CardHeader className="flex flex-row items-center gap-4 space-y-0">
          <Avatar className="h-12 w-12">
-            <AvatarImage src={basicInfo.image ?? undefined} alt={basicInfo.name ?? "Child"} />
+            <AvatarImage src={basicInfo.image ?? undefined} alt={childName} />
            <AvatarFallback>{getInitials(basicInfo.name)}</AvatarFallback>
          </Avatar>
          <div className="flex-1 min-w-0 space-y-1">
@@ -40,7 +41,7 @@ export function ChildCard({ child }: { child: ChildDashboardData }) {
        </CardHeader>
        <CardContent className="space-y-3">
          <div className="grid grid-cols-3 gap-2 text-center">
-            <div className="rounded-md border bg-card p-2">
+            <div className="rounded-md bg-muted/50 p-2">
              <div className="text-xs text-muted-foreground flex items-center justify-center gap-1">
                <PenTool className="h-3 w-3" />
                Pending
@@ -49,20 +50,21 @@ export function ChildCard({ child }: { child: ChildDashboardData }) {
                {homeworkSummary.pendingCount}
              </div>
            </div>
-            <div className="rounded-md border bg-card p-2">
+            <div className="rounded-md bg-muted/50 p-2">
              <div className="text-xs text-muted-foreground flex items-center justify-center gap-1">
                <TriangleAlert className="h-3 w-3" />
                Overdue
              </div>
              <div
-                className={`text-lg font-semibold tabular-nums ${
-                  homeworkSummary.overdueCount > 0 ? "text-destructive" : ""
-                }`}
+                className={cn(
+                  "text-lg font-semibold tabular-nums",
+                  homeworkSummary.overdueCount > 0 && "text-destructive",
+                )}
              >
                {homeworkSummary.overdueCount}
              </div>
            </div>
-            <div className="rounded-md border bg-card p-2">
+            <div className="rounded-md bg-muted/50 p-2">
              <div className="text-xs text-muted-foreground flex items-center justify-center gap-1">
                <GraduationCap className="h-3 w-3" />
                Avg
@@ -73,13 +75,12 @@ export function ChildCard({ child }: { child: ChildDashboardData }) {
            </div>
          </div>
          {latestGrade ? (
-            <div className="text-xs text-muted-foreground">
-              Latest:{" "}
-              <span className="font-medium text-foreground tabular-nums">
+            <div className="text-xs text-muted-foreground flex items-center gap-1">
+              <span className="shrink-0">Latest:</span>
+              <span className="font-medium text-foreground tabular-nums shrink-0">
                {latestGrade.score}/{latestGrade.maxScore}
-              </span>{" "}
-              ({latestGrade.assignmentTitle.slice(0, 20)}
-              {latestGrade.assignmentTitle.length > 20 ? "..." : ""})
+              </span>
+              <span className="truncate">({latestGrade.assignmentTitle})</span>
            </div>
          ) : null}
        </CardContent>
--- a/src/modules/parent/components/child-detail-header.tsx
+++ b/src/modules/parent/components/child-detail-header.tsx
@@ -4,15 +4,20 @@ import { ArrowLeft, GraduationCap } from "lucide-react"
 import { Avatar, AvatarFallback, AvatarImage } from "@/shared/components/ui/avatar"
 import { Badge } from "@/shared/components/ui/badge"
 import { Button } from "@/shared/components/ui/button"
+import { getInitials } from "@/shared/lib/utils"
 import type { ChildDashboardData } from "@/modules/parent/types"

-const getInitials = (name: string | null) => {
-  if (!name) return "S"
-  return name.slice(0, 2).toUpperCase()
+/** 将邮箱掩码为 j***@example.com 形式，防止爬虫与旁人窥屏。 */
+function maskEmail(email: string): string {
+  const [local, domain] = email.split("@")
+  if (!local || !domain) return email
+  const maskedLocal = local.length <= 1 ? local : `${local[0]}***`
+  return `${maskedLocal}@${domain}`
 }

 export function ChildDetailHeader({ child }: { child: ChildDashboardData }) {
  const { basicInfo } = child
+  const childName = basicInfo.name ?? "Child"

  return (
    <div className="space-y-4">
@@ -24,7 +29,7 @@ export function ChildDetailHeader({ child }: { child: ChildDashboardData }) {
      </Button>
      <div className="flex items-center gap-4">
        <Avatar className="h-16 w-16">
-          <AvatarImage src={basicInfo.image ?? undefined} alt={basicInfo.name ?? "Child"} />
+          <AvatarImage src={basicInfo.image ?? undefined} alt={childName} />
          <AvatarFallback className="text-lg">{getInitials(basicInfo.name)}</AvatarFallback>
        </Avatar>
        <div className="space-y-1">
@@ -40,7 +45,7 @@ export function ChildDetailHeader({ child }: { child: ChildDashboardData }) {
              </span>
            ) : null}
            {basicInfo.relation ? <span>· {basicInfo.relation}</span> : null}
-            <span>· {basicInfo.email}</span>
+            <span title={basicInfo.email}>· {maskEmail(basicInfo.email)}</span>
          </div>
        </div>
      </div>
--- a/src/modules/parent/components/child-detail-panel.tsx
+++ b/src/modules/parent/components/child-detail-panel.tsx
@@ -9,8 +9,8 @@ export function ChildDetailPanel({ child }: { child: ChildDashboardData }) {

  return (
    <div className="space-y-6">
-      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
-        <div className="lg:col-span-2 space-y-6">
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+        <div className="md:col-span-1 lg:col-span-2 space-y-6">
          <ChildHomeworkSummary
            summary={homeworkSummary}
            childId={basicInfo.id}
--- a/src/modules/parent/components/child-grade-summary.tsx
+++ b/src/modules/parent/components/child-grade-summary.tsx
@@ -1,23 +1,15 @@
 "use client"

+import { useMemo } from "react"
 import Link from "next/link"
 import { BarChart3, Trophy } from "lucide-react"
-import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts"

+import { ChartCardShell } from "@/shared/components/charts/chart-card-shell"
+import { TrendLineChart } from "@/shared/components/charts/trend-line-chart"
 import { Badge } from "@/shared/components/ui/badge"
-import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
-import { EmptyState } from "@/shared/components/ui/empty-state"
-import { ChartContainer, ChartTooltip, ChartTooltipContent } from "@/shared/components/ui/chart"
 import { formatDate } from "@/shared/lib/utils"
 import type { StudentDashboardGradeProps } from "@/modules/homework/types"

-const chartConfig = {
-  score: {
-    label: "Score (%)",
-    color: "hsl(var(--primary))",
-  },
-}
-
 export function ChildGradeSummary({
  grades,
  childId,
@@ -31,133 +23,100 @@ export function ChildGradeSummary({
  const ranking = grades.ranking
  const latestGrade = grades.trend[grades.trend.length - 1]

-  const chartData = grades.trend.map((item) => ({
-    title: item.assignmentTitle,
-    score: Math.round(item.percentage),
-    fullTitle: item.assignmentTitle,
-    submittedAt: formatDate(item.submittedAt),
-    rawScore: item.score,
-    maxScore: item.maxScore,
-  }))
+  const chartData = useMemo(
+    () =>
+      grades.trend.map((item) => ({
+        title: item.assignmentTitle,
+        score: Math.round(item.percentage),
+        fullTitle: item.assignmentTitle,
+        date: formatDate(item.submittedAt),
+        rawScore: item.score,
+        maxScore: item.maxScore,
+      })),
+    [grades.trend],
+  )

  return (
-    <Card>
-      <CardHeader>
-        <CardTitle className="flex items-center gap-2 text-base">
-          <BarChart3 className="h-4 w-4 text-muted-foreground" />
-          {childName}&apos;s Grades
-        </CardTitle>
-      </CardHeader>
-      <CardContent>
-        {!hasGradeTrend ? (
-          <EmptyState
-            icon={BarChart3}
-            title="No graded work yet"
-            description="Finish and submit assignments to see score trend."
-            className="border-none h-60"
-          />
-        ) : (
-          <div className="space-y-4">
-            <div className="grid grid-cols-2 gap-3">
-              <div className="rounded-md border bg-card p-3">
-                <div className="text-xs text-muted-foreground flex items-center gap-1">
-                  <BarChart3 className="h-3 w-3" />
-                  Latest Score
-                </div>
-                <div className="text-xl font-semibold tabular-nums">
-                  {latestGrade ? `${Math.round(latestGrade.percentage)}%` : "-"}
-                </div>
-                {latestGrade ? (
-                  <div className="text-xs text-muted-foreground tabular-nums">
-                    {latestGrade.score}/{latestGrade.maxScore}
-                  </div>
-                ) : null}
-              </div>
-              <div className="rounded-md border bg-card p-3">
-                <div className="text-xs text-muted-foreground flex items-center gap-1">
-                  <Trophy className="h-3 w-3" />
-                  Class Rank
-                </div>
-                <div className="text-xl font-semibold tabular-nums">
-                  {ranking ? `${ranking.rank}/${ranking.classSize}` : "-"}
-                </div>
-                {ranking ? (
-                  <div className="text-xs text-muted-foreground">Current position</div>
-                ) : null}
-              </div>
+    <ChartCardShell
+      title={`${childName}'s Grades`}
+      icon={BarChart3}
+      iconClassName="text-muted-foreground"
+      titleClassName="text-base"
+      isEmpty={!hasGradeTrend}
+      emptyTitle="No graded work yet"
+      emptyDescription="Finish and submit assignments to see score trend."
+      emptyClassName="h-48"
+    >
+      <div className="space-y-4">
+        <div className="grid grid-cols-2 gap-3">
+          <div className="rounded-md bg-muted/50 p-3">
+            <div className="text-xs text-muted-foreground flex items-center gap-1">
+              <BarChart3 className="h-3 w-3" />
+              Latest Score
            </div>
-
-            <div className="rounded-md border bg-card p-3">
-              <ChartContainer config={chartConfig} className="h-[160px] w-full">
-                <LineChart data={chartData} margin={{ left: 8, right: 8, top: 8, bottom: 8 }}>
-                  <CartesianGrid vertical={false} strokeDasharray="4 4" strokeOpacity={0.4} />
-                  <XAxis
-                    dataKey="title"
-                    tickLine={false}
-                    axisLine={false}
-                    tickMargin={8}
-                    tickFormatter={(value) =>
-                      value.slice(0, 8) + (value.length > 8 ? "..." : "")
-                    }
-                  />
-                  <YAxis
-                    domain={[0, 100]}
-                    tickLine={false}
-                    axisLine={false}
-                    tickFormatter={(value) => `${value}%`}
-                    width={30}
-                  />
-                  <ChartTooltip
-                    cursor={{
-                      stroke: "hsl(var(--muted-foreground))",
-                      strokeWidth: 1,
-                      strokeDasharray: "4 4",
-                    }}
-                    content={
-                      <ChartTooltipContent
-                        indicator="line"
-                        labelKey="fullTitle"
-                        className="w-[200px]"
-                      />
-                    }
-                  />
-                  <Line
-                    dataKey="score"
-                    type="monotone"
-                    stroke="var(--color-score)"
-                    strokeWidth={2}
-                    dot={{ fill: "var(--color-score)", r: 3, strokeWidth: 2 }}
-                    activeDot={{ r: 5, strokeWidth: 0 }}
-                  />
-                </LineChart>
-              </ChartContainer>
+            <div className="text-xl font-semibold tabular-nums">
+              {latestGrade ? `${Math.round(latestGrade.percentage)}%` : "-"}
            </div>
-
-            {grades.recent.length > 0 ? (
-              <div className="space-y-2">
-                <div className="text-xs font-medium uppercase text-muted-foreground">
-                  Recent Grades
-                </div>
-                {grades.recent.slice(0, 3).map((r) => (
-                  <Link
-                    key={r.assignmentId}
-                    href={`/parent/children/${childId}`}
-                    className="flex items-center justify-between rounded-md border bg-card p-2 hover:bg-muted/50 transition-colors"
-                  >
-                    <div className="min-w-0 flex-1">
-                      <div className="font-medium text-sm truncate">{r.assignmentTitle}</div>
-                      <div className="text-xs text-muted-foreground">{formatDate(r.submittedAt)}</div>
-                    </div>
-                    <Badge variant="secondary" className="tabular-nums shrink-0 ml-2">
-                      {r.score}/{r.maxScore}
-                    </Badge>
-                  </Link>
-                ))}
+            {latestGrade ? (
+              <div className="text-xs text-muted-foreground tabular-nums">
+                {latestGrade.score}/{latestGrade.maxScore}
              </div>
            ) : null}
          </div>
-        )}
-      </CardContent>
-    </Card>
+          <div className="rounded-md bg-muted/50 p-3">
+            <div className="text-xs text-muted-foreground flex items-center gap-1">
+              <Trophy className="h-3 w-3" />
+              Class Rank
+            </div>
+            <div className="text-xl font-semibold tabular-nums">
+              {ranking ? `${ranking.rank}/${ranking.classSize}` : "-"}
+            </div>
+            {ranking ? <div className="text-xs text-muted-foreground">Current position</div> : null}
+          </div>
+        </div>
+
+        <div className="rounded-md bg-muted/50 p-3">
+          <TrendLineChart
+            data={chartData}
+            series={[
+              {
+                dataKey: "score",
+                name: "Score (%)",
+                color: "hsl(var(--primary))",
+                dotRadius: 3,
+                activeDotRadius: 5,
+              },
+            ]}
+            xKey="date"
+            xTickFormatter={null}
+            heightClassName="h-[160px]"
+            margin={{ left: 8, right: 8, top: 8, bottom: 8 }}
+            yWidth={30}
+            tooltipClassName="w-[200px]"
+          />
+        </div>
+
+        {grades.recent.length > 0 ? (
+          <div className="space-y-2">
+            <div className="text-xs font-medium uppercase text-muted-foreground">Recent Grades</div>
+            {grades.recent.slice(0, 3).map((r) => (
+              <Link
+                key={r.assignmentId}
+                href={`/parent/children/${childId}?tab=grades`}
+                className="flex items-center justify-between rounded-md border bg-card p-2 hover:bg-muted/50 transition-colors"
+              >
+                <div className="min-w-0 flex-1">
+                  <div className="font-medium text-sm truncate">{r.assignmentTitle}</div>
+                  <div className="text-xs text-muted-foreground">{formatDate(r.submittedAt)}</div>
+                </div>
+                <Badge variant="secondary" className="tabular-nums shrink-0 ml-2">
+                  {r.score}/{r.maxScore}
+                </Badge>
+              </Link>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </ChartCardShell>
  )
 }
--- a/src/modules/parent/components/child-homework-summary.tsx
+++ b/src/modules/parent/components/child-homework-summary.tsx
@@ -5,24 +5,40 @@ import { Badge } from "@/shared/components/ui/badge"
 import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
 import { EmptyState } from "@/shared/components/ui/empty-state"
 import { cn, formatDate } from "@/shared/lib/utils"
-import type { ChildHomeworkSummary } from "@/modules/parent/types"
+import type { StudentHomeworkProgressStatus } from "@/modules/homework/types"
+import type { ChildHomeworkSummaryData } from "@/modules/parent/types"

-const getStatusVariant = (status: string): "default" | "secondary" | "outline" => {
-  if (status === "graded") return "default"
-  if (status === "submitted" || status === "in_progress") return "secondary"
-  return "outline"
+const getStatusVariant = (
+  status: StudentHomeworkProgressStatus,
+): "default" | "secondary" | "outline" => {
+  switch (status) {
+    case "graded":
+      return "default"
+    case "submitted":
+    case "in_progress":
+      return "secondary"
+    case "not_started":
+      return "outline"
+  }
 }

-const getStatusLabel = (status: string) => {
-  if (status === "graded") return "Graded"
-  if (status === "submitted") return "Submitted"
-  if (status === "in_progress") return "In progress"
-  return "Not started"
+const getStatusLabel = (status: StudentHomeworkProgressStatus): string => {
+  switch (status) {
+    case "graded":
+      return "Graded"
+    case "submitted":
+      return "Submitted"
+    case "in_progress":
+      return "In progress"
+    case "not_started":
+      return "Not started"
+  }
 }

-const getDueUrgency = (dueAt: string | null) => {
+type DueUrgency = "overdue" | "urgent" | "normal"
+
+const getDueUrgency = (dueAt: string | null, now: Date): DueUrgency | null => {
  if (!dueAt) return null
-  const now = new Date()
  const due = new Date(dueAt)
  const diffHours = (due.getTime() - now.getTime()) / (1000 * 60 * 60)
  if (diffHours < 0) return "overdue"
@@ -35,11 +51,13 @@ export function ChildHomeworkSummary({
  childId,
  childName,
 }: {
-  summary: ChildHomeworkSummary
+  summary: ChildHomeworkSummaryData
  childId: string
  childName: string
 }) {
  const hasAssignments = summary.recentAssignments.length > 0
+  // hoist：在组件作用域计算一次 now，避免每次 map 迭代都 new Date()
+  const now = new Date()

  return (
    <Card>
@@ -51,19 +69,19 @@ export function ChildHomeworkSummary({
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="grid grid-cols-2 md:grid-cols-4 gap-2 text-center">
-          <div className="rounded-md border bg-card p-2">
+          <div className="rounded-md bg-muted/50 p-2">
            <div className="text-xs text-muted-foreground">Pending</div>
            <div className="text-lg font-semibold tabular-nums">{summary.pendingCount}</div>
          </div>
-          <div className="rounded-md border bg-card p-2">
+          <div className="rounded-md bg-muted/50 p-2">
            <div className="text-xs text-muted-foreground">Submitted</div>
            <div className="text-lg font-semibold tabular-nums">{summary.submittedCount}</div>
          </div>
-          <div className="rounded-md border bg-card p-2">
+          <div className="rounded-md bg-muted/50 p-2">
            <div className="text-xs text-muted-foreground">Graded</div>
            <div className="text-lg font-semibold tabular-nums">{summary.gradedCount}</div>
          </div>
-          <div className="rounded-md border bg-card p-2">
+          <div className="rounded-md bg-muted/50 p-2">
            <div className="text-xs text-muted-foreground flex items-center justify-center gap-1">
              <TriangleAlert className="h-3 w-3" />
              Overdue
@@ -84,7 +102,7 @@ export function ChildHomeworkSummary({
            icon={PenTool}
            title="No assignments"
            description="No homework assigned right now."
-            className="border-none h-40"
+            className="border-none h-48"
          />
        ) : (
          <div className="space-y-2">
@@ -92,12 +110,12 @@ export function ChildHomeworkSummary({
              Recent Assignments
            </div>
            {summary.recentAssignments.map((a) => {
-              const urgency = getDueUrgency(a.dueAt)
+              const urgency = getDueUrgency(a.dueAt, now)
              const isGraded = a.progressStatus === "graded"
              return (
                <Link
                  key={a.id}
-                  href={`/parent/children/${childId}`}
+                  href={`/parent/children/${childId}?tab=homework`}
                  className="flex items-center justify-between rounded-md border bg-card p-3 hover:bg-muted/50 transition-colors"
                >
                  <div className="min-w-0 flex-1 space-y-1">
@@ -123,6 +141,12 @@ export function ChildHomeworkSummary({
                </Link>
              )
            })}
+            <Link
+              href={`/parent/children/${childId}?tab=homework`}
+              className="block text-center text-xs text-muted-foreground hover:text-foreground transition-colors pt-1"
+            >
+              View all
+            </Link>
          </div>
        )}
      </CardContent>
--- a/src/modules/parent/components/child-schedule-card.tsx
+++ b/src/modules/parent/components/child-schedule-card.tsx
@@ -1,6 +1,6 @@
-import { CalendarDays, CalendarX, Clock, MapPin } from "lucide-react"
+import { CalendarDays, CalendarX } from "lucide-react"

-import { Badge } from "@/shared/components/ui/badge"
+import { ScheduleList } from "@/shared/components/schedule/schedule-list"
 import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
 import { EmptyState } from "@/shared/components/ui/empty-state"
 import type { ChildScheduleItem } from "@/modules/parent/types"
@@ -28,38 +28,14 @@ export function ChildScheduleCard({
            icon={CalendarX}
            title="No classes today"
            description="The timetable is clear for today."
-            className="border-none h-60"
+            className="border-none h-48"
          />
        ) : (
-          <div className="space-y-3">
-            {items.map((item) => (
-              <div
-                key={item.id}
-                className="flex items-center justify-between border-b pb-3 last:border-0 last:pb-0"
-              >
-                <div className="space-y-1 min-w-0">
-                  <div className="font-medium leading-none truncate">{item.course}</div>
-                  <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
-                    <div className="flex items-center">
-                      <Clock className="mr-1 h-3 w-3" />
-                      <span>
-                        {item.startTime}–{item.endTime}
-                      </span>
-                    </div>
-                    {item.location ? (
-                      <div className="flex items-center">
-                        <MapPin className="mr-1 h-3 w-3" />
-                        <span className="truncate">{item.location}</span>
-                      </div>
-                    ) : null}
-                  </div>
-                </div>
-                <Badge variant="secondary" className="shrink-0">
-                  {item.className}
-                </Badge>
-              </div>
-            ))}
-          </div>
+          <ScheduleList
+            items={items}
+            variant="separator"
+            spacingClassName="space-y-3"
+          />
        )}
      </CardContent>
    </Card>
--- a/src/modules/parent/components/parent-children-data-page.tsx
+++ b/src/modules/parent/components/parent-children-data-page.tsx
@@ -0,0 +1,86 @@
+import type { LucideIcon } from "lucide-react"
+
+import { EmptyState } from "@/shared/components/ui/empty-state"
+
+/**
+ * 家长视角下"多子女数据聚合页"的共享布局。
+ * 用于 attendance / grades 等需要遍历所有子女展示同类数据的页面，
+ * 消除重复的 dataScope 空状态处理与页面骨架代码。
+ */
+export function ParentChildrenDataPage<T>({
+  title,
+  description,
+  icon,
+  noRecordsTitle,
+  noRecordsDescription,
+  items,
+  renderItem,
+}: {
+  title: string
+  description: string
+  icon: LucideIcon
+  noRecordsTitle: string
+  noRecordsDescription: string
+  items: T[]
+  renderItem: (item: T) => React.ReactNode
+}) {
+  const hasItems = items.length > 0
+
+  return (
+    <div className="h-full flex-1 flex-col space-y-8 p-6 md:p-8 md:flex">
+      <div>
+        <h2 className="text-2xl font-bold tracking-tight">{title}</h2>
+        <p className="text-muted-foreground">{description}</p>
+      </div>
+
+      {!hasItems ? (
+        <EmptyState
+          title={noRecordsTitle}
+          description={noRecordsDescription}
+          icon={icon}
+          className="border-none shadow-none"
+        />
+      ) : (
+        <div className="space-y-8">
+          {items.map((item, idx) => (
+            <div key={idx} className="space-y-4">
+              {renderItem(item)}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * dataScope 为空（家长未关联子女）时的统一空状态页面。
+ */
+export function ParentNoChildrenPage({
+  title,
+  description,
+  icon,
+  emptyTitle,
+  emptyDescription,
+}: {
+  title: string
+  description: string
+  icon: LucideIcon
+  emptyTitle: string
+  emptyDescription: string
+}) {
+  return (
+    <div className="h-full flex-1 flex-col space-y-8 p-6 md:p-8 md:flex">
+      <div>
+        <h2 className="text-2xl font-bold tracking-tight">{title}</h2>
+        <p className="text-muted-foreground">{description}</p>
+      </div>
+      <EmptyState
+        title={emptyTitle}
+        description={emptyDescription}
+        icon={icon}
+        className="border-none shadow-none"
+      />
+    </div>
+  )
+}
--- a/src/modules/parent/components/parent-dashboard.tsx
+++ b/src/modules/parent/components/parent-dashboard.tsx
@@ -1,4 +1,5 @@
-import { CalendarDays, GraduationCap, Users } from "lucide-react"
+import Link from "next/link"
+import { CalendarCheck, CalendarDays, GraduationCap, Users } from "lucide-react"

 import { Button } from "@/shared/components/ui/button"
 import { EmptyState } from "@/shared/components/ui/empty-state"
@@ -19,7 +20,7 @@ export function ParentDashboard({ data }: { data: ParentDashboardData }) {
    <div className="space-y-6">
      <div className="flex flex-col justify-between gap-4 md:flex-row md:items-center">
        <div className="space-y-1">
-          <h1 className="text-3xl font-bold tracking-tight">Parent Dashboard</h1>
+          <h1 className="text-2xl font-bold tracking-tight">Parent Dashboard</h1>
          <div className="text-sm text-muted-foreground">
            {greeting}
            {parentName ? `, ${parentName}` : ""}. Here&apos;s an overview of your children.
@@ -27,16 +28,22 @@ export function ParentDashboard({ data }: { data: ParentDashboardData }) {
        </div>
        <div className="flex flex-wrap items-center gap-2">
          <Button asChild variant="outline" size="sm" className="gap-2">
-            <a href="/parent/grades">
+            <Link href="/parent/grades">
              <GraduationCap className="h-4 w-4" />
              Grades
-            </a>
+            </Link>
          </Button>
          <Button asChild variant="outline" size="sm" className="gap-2">
-            <a href="/announcements">
+            <Link href="/parent/attendance">
+              <CalendarCheck className="h-4 w-4" />
+              Attendance
+            </Link>
+          </Button>
+          <Button asChild variant="outline" size="sm" className="gap-2">
+            <Link href="/announcements">
              <CalendarDays className="h-4 w-4" />
              Announcements
-            </a>
+            </Link>
          </Button>
        </div>
      </div>
@@ -56,7 +63,7 @@ export function ParentDashboard({ data }: { data: ParentDashboardData }) {
              {children.length} {children.length === 1 ? "child" : "children"} linked
            </span>
          </div>
-          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
            {children.map((child) => (
              <ChildCard key={child.basicInfo.id} child={child} />
            ))}
--- a/src/modules/parent/data-access.ts
+++ b/src/modules/parent/data-access.ts
@@ -1,13 +1,12 @@
 import "server-only"

 import { cache } from "react"
-import { asc, eq } from "drizzle-orm"
+import { and, asc, eq } from "drizzle-orm"

 import { db } from "@/shared/db"
 import { parentStudentRelations } from "@/shared/db/schema"
 import {
-  getClassNameById,
-  getStudentActiveClassId,
+  getStudentActiveClass,
  getStudentClasses,
  getStudentSchedule,
 } from "@/modules/classes/data-access"
@@ -16,12 +15,12 @@ import {
  getStudentHomeworkAssignments,
 } from "@/modules/homework/data-access"
 import { getStudentGradeSummary } from "@/modules/grades/data-access"
-import { getGradeOptions } from "@/modules/school/data-access"
+import { getGradeNameById } from "@/modules/school/data-access"
 import { getUserBasicInfo, getUserNamesByIds } from "@/modules/users/data-access"
 import type {
  ChildBasicInfo,
  ChildDashboardData,
-  ChildHomeworkSummary,
+  ChildHomeworkSummaryData,
  ChildScheduleItem,
  ParentChildRelation,
  ParentDashboardData,
@@ -63,6 +62,26 @@ export const getChildren = cache(async (parentId: string): Promise<ParentChildRe
  }))
 })

+/**
+ * 校验家长与子女的关系是否存在，并返回关系类型。
+ * 同时按 parentId 与 studentId 过滤，防止跨家庭信息泄露。
+ */
+export const verifyParentChildRelation = cache(
+  async (studentId: string, parentId: string): Promise<string | null> => {
+    const [row] = await db
+      .select({ relation: parentStudentRelations.relation })
+      .from(parentStudentRelations)
+      .where(
+        and(
+          eq(parentStudentRelations.studentId, studentId),
+          eq(parentStudentRelations.parentId, parentId),
+        ),
+      )
+      .limit(1)
+    return row?.relation ?? null
+  },
+)
+
 export const getChildBasicInfo = cache(
  async (
    studentId: string,
@@ -72,31 +91,20 @@ export const getChildBasicInfo = cache(

    if (!student) return null

-    // gradeName 与 classId 相互独立，并行拉取
-    const [gradeOptions, classId] = await Promise.all([
-      student.gradeId ? getGradeOptions() : Promise.resolve([]),
-      getStudentActiveClassId(studentId),
+    // gradeName 与 activeClass 相互独立，并行拉取
+    const [gradeName, activeClass] = await Promise.all([
+      student.gradeId ? getGradeNameById(student.gradeId) : Promise.resolve(null),
+      getStudentActiveClass(studentId),
    ])

-    let gradeName: string | null = null
-    if (student.gradeId) {
-      const grade = gradeOptions.find((g) => g.id === student.gradeId)
-      gradeName = grade?.name ?? null
-    }
-
-    let className: string | null = null
-    if (classId) {
-      className = await getClassNameById(classId)
-    }
-
    return {
      id: student.id,
      name: student.name,
      email: student.email,
      image: student.image,
      gradeName,
-      className,
-      classId,
+      className: activeClass?.className ?? null,
+      classId: activeClass?.classId ?? null,
      relation,
    }
  },
@@ -104,10 +112,8 @@ export const getChildBasicInfo = cache(

 const buildHomeworkSummary = (
  assignments: Awaited<ReturnType<typeof getStudentHomeworkAssignments>>,
-): ChildHomeworkSummary => {
+): ChildHomeworkSummaryData => {
  const now = new Date()
-  const in7Days = new Date(now)
-  in7Days.setDate(in7Days.getDate() + 7)

  let pendingCount = 0
  let submittedCount = 0
@@ -133,8 +139,8 @@ const buildHomeworkSummary = (
    }
  }

-  const recentAssignments = [...assignments]
-    .sort((a, b) => {
+  const recentAssignments = assignments
+    .toSorted((a, b) => {
      const aDue = a.dueAt ? new Date(a.dueAt).getTime() : Number.POSITIVE_INFINITY
      const bDue = b.dueAt ? new Date(b.dueAt).getTime() : Number.POSITIVE_INFINITY
      return aDue - bDue
--- a/src/modules/parent/types.ts
+++ b/src/modules/parent/types.ts
@@ -5,14 +5,17 @@ import type {
 import type { StudentEnrolledClass } from "@/modules/classes/types"
 import type { StudentGradeSummary } from "@/modules/grades/types"

+/** 家长与子女的关系记录（来自 parentStudentRelations 表）。 */
 export type ParentChildRelation = {
  id: string
  parentId: string
  studentId: string
+  /** 关系类型，如 "father"、"mother"、"guardian" 等。 */
  relation: string | null
  createdAt: string
 }

+/** 子女基本信息（聚合自 users 表 + 班级 + 年级）。 */
 export type ChildBasicInfo = {
  id: string
  name: string | null
@@ -21,9 +24,11 @@ export type ChildBasicInfo = {
  gradeName: string | null
  className: string | null
  classId: string | null
+  /** 当前家长与该子女的关系类型。 */
  relation: string | null
 }

+/** 单条今日课表项。 */
 export type ChildScheduleItem = {
  id: string
  classId: string
@@ -34,23 +39,28 @@ export type ChildScheduleItem = {
  location: string | null
 }

-export type ChildHomeworkSummary = {
+/** 子女作业摘要（统计计数 + 最近作业列表）。 */
+export type ChildHomeworkSummaryData = {
  pendingCount: number
  submittedCount: number
  gradedCount: number
  overdueCount: number
+  /** 按截止时间升序排列的最近 5 条作业。 */
  recentAssignments: StudentHomeworkAssignmentListItem[]
 }

+/** 单个子女的仪表盘聚合数据。 */
 export type ChildDashboardData = {
  basicInfo: ChildBasicInfo
  enrolledClasses: StudentEnrolledClass[]
  todaySchedule: ChildScheduleItem[]
-  homeworkSummary: ChildHomeworkSummary
+  homeworkSummary: ChildHomeworkSummaryData
+  /** 成绩趋势数据；`trend` 按时间升序，`recent` 按时间降序。 */
  gradeTrend: StudentDashboardGradeProps
  gradeSummary: StudentGradeSummary | null
 }

+/** 家长仪表盘聚合数据（家长姓名 + 所有子女数据）。 */
 export type ParentDashboardData = {
  parentName: string | null
  children: ChildDashboardData[]