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)

src/app/(dashboard)/admin/school/grades/insights/page.tsx

@@ -1,65 +1,75 @@
-import Link from "next/link"
+import Link from "next/link"
+import type { Metadata } from "next"
+import type { JSX } from "react"
+import { BarChart3 } from "lucide-react"
 
 import { getGrades } from "@/modules/school/data-access"
 import { getGradeHomeworkInsights } from "@/modules/classes/data-access"
 import { EmptyState } from "@/shared/components/ui/empty-state"
+import { StatCard } from "@/shared/components/ui/stat-card"
 import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
 import { Badge } from "@/shared/components/ui/badge"
 import { Button } from "@/shared/components/ui/button"
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/shared/components/ui/table"
-import { formatDate } from "@/shared/lib/utils"
-import { BarChart3 } from "lucide-react"
+import { formatDate, formatNumber, getSearchParam, type SearchParams } from "@/shared/lib/utils"
+
+export const metadata: Metadata = {
+  title: "年级作业洞察 - Next_Edu",
+  description: "按年级聚合的作业统计与班级排名",
+}
 
 export const dynamic = "force-dynamic"
 
-type SearchParams = { [key: string]: string | string[] | undefined }
-
-const getParam = (params: SearchParams, key: string) => {
-  const v = params[key]
-  if (typeof v === "string") return v
-  if (Array.isArray(v)) return v[0]
-  return undefined
-}
-
-const fmt = (v: number | null, digits = 1) => (typeof v === "number" && Number.isFinite(v) ? v.toFixed(digits) : "-")
-
-export default async function AdminGradeInsightsPage({ searchParams }: { searchParams: Promise<SearchParams> }) {
+export default async function AdminGradeInsightsPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}): Promise<JSX.Element> {
   const params = await searchParams
-  const gradeId = getParam(params, "gradeId")
-
-  const grades = await getGrades()
+  const gradeId = getSearchParam(params, "gradeId")
   const selected = gradeId && gradeId !== "all" ? gradeId : ""
 
-  const insights = selected ? await getGradeHomeworkInsights({ gradeId: selected, limit: 50 }) : null
+  // grades 与 insights 无数据依赖，并行查询
+  const [grades, insights] = await Promise.all([
+    getGrades(),
+    selected ? getGradeHomeworkInsights({ gradeId: selected, limit: 50 }) : Promise.resolve(null),
+  ])
 
   return (
     <div className="flex h-full flex-col space-y-8 p-8">
       <div className="flex flex-col gap-4 md:flex-row md:items-end md:justify-between">
         <div className="space-y-1">
-          <h2 className="text-2xl font-bold tracking-tight">Grade Insights</h2>
-          <p className="text-muted-foreground">Homework statistics aggregated across all classes in a grade.</p>
+          <h2 className="text-2xl font-bold tracking-tight">年级作业洞察</h2>
+          <p className="text-muted-foreground">按年级聚合的作业统计与班级排名。</p>
         </div>
         <Button asChild variant="outline">
-          <Link href="/admin/school/grades">Manage grades</Link>
+          <Link href="/admin/school/grades">管理年级</Link>
         </Button>
       </div>
 
       <Card className="shadow-none">
         <CardHeader className="flex flex-row items-center justify-between space-y-0">
-          <CardTitle className="text-base">Filters</CardTitle>
+          <CardTitle className="text-base">筛选</CardTitle>
           <Badge variant="secondary" className="tabular-nums">
             {grades.length}
           </Badge>
         </CardHeader>
         <CardContent>
-          <form action="/admin/school/grades/insights" method="get" className="flex flex-col gap-3 md:flex-row md:items-center">
-            <label className="text-sm font-medium">Grade</label>
+          <form
+            action="/admin/school/grades/insights"
+            method="get"
+            className="flex flex-col gap-3 md:flex-row md:items-center"
+          >
+            <label htmlFor="grade-filter" className="text-sm font-medium">
+              年级
+            </label>
             <select
+              id="grade-filter"
               name="gradeId"
               defaultValue={selected || "all"}
-              className="h-10 w-full rounded-md border bg-background px-3 text-sm md:w-[360px]"
+              className="h-10 w-full rounded-md border bg-background px-3 text-sm md:w-80"
             >
-              <option value="all">Select a grade</option>
+              <option value="all">请选择年级</option>
               {grades.map((g) => (
                 <option key={g.id} value={g.id}>
                   {g.school.name} / {g.name}
@@ -67,7 +77,7 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
               ))}
             </select>
             <Button type="submit" className="md:ml-2">
-              Apply
+              应用
             </Button>
           </form>
         </CardContent>
@@ -76,72 +86,56 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
       {!selected ? (
         <EmptyState
           icon={BarChart3}
-          title="Select a grade to view insights"
-          description="Pick a grade to see latest homework and historical score statistics."
-          className="h-[360px] bg-card"
+          title="请选择年级以查看洞察"
+          description="选择一个年级，查看最新作业与历史成绩统计。"
+          className="h-80 bg-card"
         />
       ) : !insights ? (
         <EmptyState
           icon={BarChart3}
-          title="Grade not found"
-          description="This grade may not exist or has no accessible data."
-          className="h-[360px] bg-card"
+          title="年级未找到"
+          description="该年级可能不存在或无可访问数据。"
+          className="h-80 bg-card"
         />
       ) : insights.assignments.length === 0 ? (
         <EmptyState
           icon={BarChart3}
-          title="No homework data for this grade"
-          description="No homework assignments were targeted to students in this grade yet."
-          className="h-[360px] bg-card"
+          title="该年级暂无作业数据"
+          description="尚未向该年级学生布置任何作业。"
+          className="h-80 bg-card"
         />
       ) : (
         <div className="space-y-6">
           <div className="grid gap-4 md:grid-cols-4">
-            <Card>
-              <CardHeader className="pb-2">
-                <CardTitle className="text-sm font-medium">Classes</CardTitle>
-              </CardHeader>
-              <CardContent>
-                <div className="text-2xl font-bold tabular-nums">{insights.classCount}</div>
-                <div className="text-xs text-muted-foreground">
-                  {insights.grade.school.name} / {insights.grade.name}
-                </div>
-              </CardContent>
-            </Card>
-            <Card>
-              <CardHeader className="pb-2">
-                <CardTitle className="text-sm font-medium">Students</CardTitle>
-              </CardHeader>
-              <CardContent>
-                <div className="text-2xl font-bold tabular-nums">{insights.studentCounts.total}</div>
-                <div className="text-xs text-muted-foreground">
-                  Active {insights.studentCounts.active} • Inactive {insights.studentCounts.inactive}
-                </div>
-              </CardContent>
-            </Card>
-            <Card>
-              <CardHeader className="pb-2">
-                <CardTitle className="text-sm font-medium">Overall Avg</CardTitle>
-              </CardHeader>
-              <CardContent>
-                <div className="text-2xl font-bold tabular-nums">{fmt(insights.overallScores.avg)}</div>
-                <div className="text-xs text-muted-foreground">Across graded homework</div>
-              </CardContent>
-            </Card>
-            <Card>
-              <CardHeader className="pb-2">
-                <CardTitle className="text-sm font-medium">Latest Avg</CardTitle>
-              </CardHeader>
-              <CardContent>
-                <div className="text-2xl font-bold tabular-nums">{fmt(insights.latest?.scoreStats.avg ?? null)}</div>
-                <div className="text-xs text-muted-foreground">{insights.latest ? insights.latest.title : "-"}</div>
-              </CardContent>
-            </Card>
+            <StatCard
+              title="班级数"
+              value={insights.classCount}
+              description={`${insights.grade.school.name} / ${insights.grade.name}`}
+              valueClassName="tabular-nums"
+            />
+            <StatCard
+              title="学生数"
+              value={insights.studentCounts.total}
+              description={`在读 ${insights.studentCounts.active} • 停用 ${insights.studentCounts.inactive}`}
+              valueClassName="tabular-nums"
+            />
+            <StatCard
+              title="总体均分"
+              value={formatNumber(insights.overallScores.avg)}
+              description="基于已批改作业"
+              valueClassName="tabular-nums"
+            />
+            <StatCard
+              title="最新均分"
+              value={formatNumber(insights.latest?.scoreStats.avg ?? null)}
+              description={insights.latest?.title ?? "-"}
+              valueClassName="tabular-nums"
+            />
           </div>
 
           <Card className="shadow-none">
             <CardHeader className="flex flex-row items-center justify-between space-y-0">
-              <CardTitle className="text-base">Latest homework</CardTitle>
+              <CardTitle className="text-base">最新作业</CardTitle>
               <Badge variant="secondary" className="tabular-nums">
                 {insights.assignments.length}
               </Badge>
@@ -151,14 +145,14 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
                 <Table>
                   <TableHeader>
                     <TableRow className="bg-muted/50">
-                      <TableHead>Assignment</TableHead>
-                      <TableHead>Status</TableHead>
-                      <TableHead>Created</TableHead>
-                      <TableHead className="text-right">Targeted</TableHead>
-                      <TableHead className="text-right">Submitted</TableHead>
-                      <TableHead className="text-right">Graded</TableHead>
-                      <TableHead className="text-right">Avg</TableHead>
-                      <TableHead className="text-right">Median</TableHead>
+                      <TableHead>作业</TableHead>
+                      <TableHead>状态</TableHead>
+                      <TableHead>创建时间</TableHead>
+                      <TableHead className="text-right">目标数</TableHead>
+                      <TableHead className="text-right">提交数</TableHead>
+                      <TableHead className="text-right">已批改</TableHead>
+                      <TableHead className="text-right">均分</TableHead>
+                      <TableHead className="text-right">中位数</TableHead>
                     </TableRow>
                   </TableHeader>
                   <TableBody>
@@ -174,8 +168,8 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
                         <TableCell className="text-right tabular-nums">{a.targetCount}</TableCell>
                         <TableCell className="text-right tabular-nums">{a.submittedCount}</TableCell>
                         <TableCell className="text-right tabular-nums">{a.gradedCount}</TableCell>
-                        <TableCell className="text-right tabular-nums">{fmt(a.scoreStats.avg)}</TableCell>
-                        <TableCell className="text-right tabular-nums">{fmt(a.scoreStats.median)}</TableCell>
+                        <TableCell className="text-right tabular-nums">{formatNumber(a.scoreStats.avg)}</TableCell>
+                        <TableCell className="text-right tabular-nums">{formatNumber(a.scoreStats.median)}</TableCell>
                       </TableRow>
                     ))}
                   </TableBody>
@@ -186,7 +180,7 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
 
           <Card className="shadow-none">
             <CardHeader className="flex flex-row items-center justify-between space-y-0">
-              <CardTitle className="text-base">Class ranking</CardTitle>
+              <CardTitle className="text-base">班级排名</CardTitle>
               <Badge variant="secondary" className="tabular-nums">
                 {insights.classes.length}
               </Badge>
@@ -196,12 +190,12 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
                 <Table>
                   <TableHeader>
                     <TableRow className="bg-muted/50">
-                      <TableHead>Class</TableHead>
-                      <TableHead className="text-right">Students</TableHead>
-                      <TableHead className="text-right">Latest Avg</TableHead>
-                      <TableHead className="text-right">Prev Avg</TableHead>
+                      <TableHead>班级</TableHead>
+                      <TableHead className="text-right">学生数</TableHead>
+                      <TableHead className="text-right">最新均分</TableHead>
+                      <TableHead className="text-right">上次均分</TableHead>
                       <TableHead className="text-right">Δ</TableHead>
-                      <TableHead className="text-right">Overall Avg</TableHead>
+                      <TableHead className="text-right">总体均分</TableHead>
                     </TableRow>
                   </TableHeader>
                   <TableBody>
@@ -209,13 +203,15 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
                       <TableRow key={c.class.id}>
                         <TableCell className="font-medium">
                           {c.class.name}
-                          {c.class.homeroom ? <span className="text-muted-foreground"> • {c.class.homeroom}</span> : null}
+                          {c.class.homeroom ? (
+                            <span className="text-muted-foreground"> • {c.class.homeroom}</span>
+                          ) : null}
                         </TableCell>
                         <TableCell className="text-right tabular-nums">{c.studentCounts.total}</TableCell>
-                        <TableCell className="text-right tabular-nums">{fmt(c.latestAvg)}</TableCell>
-                        <TableCell className="text-right tabular-nums">{fmt(c.prevAvg)}</TableCell>
-                        <TableCell className="text-right tabular-nums">{fmt(c.deltaAvg)}</TableCell>
-                        <TableCell className="text-right tabular-nums">{fmt(c.overallScores.avg)}</TableCell>
+                        <TableCell className="text-right tabular-nums">{formatNumber(c.latestAvg)}</TableCell>
+                        <TableCell className="text-right tabular-nums">{formatNumber(c.prevAvg)}</TableCell>
+                        <TableCell className="text-right tabular-nums">{formatNumber(c.deltaAvg)}</TableCell>
+                        <TableCell className="text-right tabular-nums">{formatNumber(c.overallScores.avg)}</TableCell>
                       </TableRow>
                     ))}
                   </TableBody>
@@ -228,4 +224,3 @@ export default async function AdminGradeInsightsPage({ searchParams }: { searchP
     </div>
   )
 }
-