feat(error-book): implement error book module with SM2 spaced repetition

- Add SM2 algorithm implementation with tests for spaced repetition review scheduling

- Add data-access, schema, types, and server actions for error book CRUD

- Add components: add dialog, class overview, filters, item card, stats cards, review buttons, top wrong questions

- Add error-book routes for admin, teacher, parent, and student roles

- Add i18n messages (en, zh-CN) for error book module
This commit is contained in:
SpecialX
2026-06-23 17:36:42 +08:00
parent 396c2c568d
commit bf056399c6
26 changed files with 3613 additions and 0 deletions

View File

@@ -0,0 +1,19 @@
"use client"
import { BarChart3 } from "lucide-react"
import { EmptyState } from "@/shared/components/ui/empty-state"
export default function AdminErrorBookError() {
return (
<div className="p-8">
<EmptyState
icon={BarChart3}
title="加载全校错题分析失败"
description="发生了一些错误,请刷新页面重试。"
action={{ label: "刷新页面", onClick: () => window.location.reload() }}
className="border-none shadow-none"
/>
</div>
)
}

View File

@@ -0,0 +1,23 @@
import { Skeleton } from "@/shared/components/ui/skeleton"
export default function AdminErrorBookLoading() {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div className="space-y-2">
<Skeleton className="h-8 w-[200px]" />
<Skeleton className="h-4 w-[300px]" />
</div>
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
{Array.from({ length: 4 }).map((_, idx) => (
<Skeleton key={idx} className="h-[120px] w-full rounded-md" />
))}
</div>
<div className="grid gap-4 md:grid-cols-2">
{Array.from({ length: 2 }).map((_, idx) => (
<Skeleton key={idx} className="h-[300px] w-full rounded-md" />
))}
</div>
<Skeleton className="h-[400px] w-full rounded-md" />
</div>
)
}

View File

@@ -0,0 +1,113 @@
import type { JSX } from "react"
import { BarChart3 } from "lucide-react"
import { requirePermission } from "@/shared/lib/auth-guard"
import { Permissions } from "@/shared/types/permissions"
import { EmptyState } from "@/shared/components/ui/empty-state"
import {
getStudentErrorBookSummaries,
getTopWrongQuestionsByStudentIds,
getKnowledgePointWeakness,
getSubjectErrorDistribution,
getStudentNameMap,
getAllStudentIds,
} from "@/modules/error-book/data-access"
import { ClassErrorBookOverview, StudentErrorTable } from "@/modules/error-book/components/class-error-overview"
import { TopWrongQuestions } from "@/modules/error-book/components/top-wrong-questions"
export const dynamic = "force-dynamic"
export default async function AdminErrorBookPage(): Promise<JSX.Element> {
const ctx = await requirePermission(Permissions.ERROR_BOOK_ANALYTICS_READ)
if (ctx.dataScope.type !== "all") {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground"></p>
</div>
<EmptyState
icon={BarChart3}
title="权限不足"
description="您没有权限查看全校错题分析数据。"
className="h-[360px] bg-card"
/>
</div>
)
}
// 通过 data-access 层查询所有学生 ID遵循三层架构app 层不直接访问 DB
const studentIds = await getAllStudentIds()
if (studentIds.length === 0) {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground"></p>
</div>
<EmptyState
icon={BarChart3}
title="暂无学生数据"
description="系统中还没有学生用户,无法查看错题分析。"
className="h-[360px] bg-card"
/>
</div>
)
}
// 限制查询数量,避免性能问题(取最近活跃的 500 名学生)
const limitedStudentIds = studentIds.slice(0, 500)
const [summaries, topWrongQuestions, weakKps, subjectDist, nameMap] = await Promise.all([
getStudentErrorBookSummaries(limitedStudentIds),
getTopWrongQuestionsByStudentIds(limitedStudentIds, 10),
getKnowledgePointWeakness(limitedStudentIds, 10),
getSubjectErrorDistribution(limitedStudentIds),
getStudentNameMap(limitedStudentIds),
])
const studentsWithErrorBook = summaries.filter((s) => s.totalCount > 0)
const totalErrorItems = summaries.reduce((sum, s) => sum + s.totalCount, 0)
const averageMasteryRate = studentsWithErrorBook.length > 0
? studentsWithErrorBook.reduce((sum, s) => sum + s.masteredRate, 0) / studentsWithErrorBook.length
: 0
const sortedSummaries = [...summaries]
.filter((s) => s.totalCount > 0)
.sort((a, b) => b.totalCount - a.totalCount)
.slice(0, 50)
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground">
</p>
</div>
<ClassErrorBookOverview
totalStudents={studentIds.length}
studentsWithErrorBook={studentsWithErrorBook.length}
totalErrorItems={totalErrorItems}
averageMasteryRate={averageMasteryRate}
topWeakKnowledgePoints={weakKps}
subjectDistribution={subjectDist}
/>
<div className="space-y-4">
<h2 className="text-lg font-semibold"> Top 50</h2>
<StudentErrorTable
students={sortedSummaries}
studentNames={nameMap}
basePath="/admin/error-book"
/>
</div>
<TopWrongQuestions questions={topWrongQuestions} />
</div>
)
}

View File

@@ -0,0 +1,19 @@
"use client"
import { BookX } from "lucide-react"
import { EmptyState } from "@/shared/components/ui/empty-state"
export default function ParentErrorBookError() {
return (
<div className="p-8">
<EmptyState
icon={BookX}
title="加载子女错题本失败"
description="发生了一些错误,请刷新页面重试。"
action={{ label: "刷新页面", onClick: () => window.location.reload() }}
className="border-none shadow-none"
/>
</div>
)
}

View File

@@ -0,0 +1,18 @@
import { Skeleton } from "@/shared/components/ui/skeleton"
export default function ParentErrorBookLoading() {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div className="space-y-2">
<Skeleton className="h-8 w-[180px]" />
<Skeleton className="h-4 w-[280px]" />
</div>
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-5">
{Array.from({ length: 5 }).map((_, idx) => (
<Skeleton key={idx} className="h-[120px] w-full rounded-md" />
))}
</div>
<Skeleton className="h-[300px] w-full rounded-md" />
</div>
)
}

View File

@@ -0,0 +1,138 @@
import type { JSX } from "react"
import { Users } from "lucide-react"
import { requirePermission } from "@/shared/lib/auth-guard"
import { Permissions } from "@/shared/types/permissions"
import { EmptyState } from "@/shared/components/ui/empty-state"
import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
import { Badge } from "@/shared/components/ui/badge"
import { Progress } from "@/shared/components/ui/progress"
import { formatNumber } from "@/shared/lib/utils"
import {
getErrorBookStats,
getStudentNameMap,
getTopWrongQuestionsByStudentIds,
getKnowledgePointWeakness,
} from "@/modules/error-book/data-access"
import { ErrorBookStatsCards } from "@/modules/error-book/components/error-book-stats-cards"
import { TopWrongQuestions } from "@/modules/error-book/components/top-wrong-questions"
export const dynamic = "force-dynamic"
export default async function ParentErrorBookPage(): Promise<JSX.Element> {
const ctx = await requirePermission(Permissions.ERROR_BOOK_READ)
if (ctx.dataScope.type !== "children" || ctx.dataScope.childrenIds.length === 0) {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground"></p>
</div>
<EmptyState
icon={Users}
title="暂无子女关联"
description="您的账号尚未关联子女,请联系学校管理员进行关联。"
className="h-[360px] bg-card"
/>
</div>
)
}
const childrenIds = ctx.dataScope.childrenIds
const [nameMap, ...childStatsList] = await Promise.all([
getStudentNameMap(childrenIds),
...childrenIds.map((id) => getErrorBookStats(id)),
])
// 汇总所有子女的错题
const [topWrongQuestions, weakKps] = await Promise.all([
getTopWrongQuestionsByStudentIds(childrenIds, 5),
getKnowledgePointWeakness(childrenIds, 5),
])
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground"></p>
</div>
{childrenIds.length === 1 ? (
// 单子女:直接展示统计卡片
<ErrorBookStatsCards stats={childStatsList[0]} />
) : (
// 多子女:每个子女一张卡片
<div className="grid gap-4 md:grid-cols-2">
{childrenIds.map((childId, idx) => {
const stats = childStatsList[idx]
const name = nameMap.get(childId) ?? "未知"
return (
<Card key={childId}>
<CardHeader>
<CardTitle className="flex items-center justify-between text-base">
<span>{name}</span>
<Badge variant="outline">
{formatNumber(stats.masteredRate * 100, 0)}%
</Badge>
</CardTitle>
</CardHeader>
<CardContent className="space-y-3">
<div className="grid grid-cols-2 gap-3 text-sm">
<div>
<div className="text-muted-foreground"></div>
<div className="text-lg font-bold">{stats.totalCount}</div>
</div>
<div>
<div className="text-muted-foreground"></div>
<div className="text-lg font-bold text-rose-600 dark:text-rose-400">
{stats.dueReviewCount}
</div>
</div>
<div>
<div className="text-muted-foreground"></div>
<div className="font-medium text-blue-600 dark:text-blue-400">{stats.newCount}</div>
</div>
<div>
<div className="text-muted-foreground"></div>
<div className="font-medium text-emerald-600 dark:text-emerald-400">{stats.masteredCount}</div>
</div>
</div>
<Progress value={stats.masteredRate * 100} className="h-2" />
</CardContent>
</Card>
)
})}
</div>
)}
{/* 薄弱知识点 */}
{weakKps.length > 0 ? (
<Card>
<CardHeader>
<CardTitle className="text-base"></CardTitle>
</CardHeader>
<CardContent>
<div className="space-y-3">
{weakKps.map((kp) => (
<div key={kp.knowledgePointId} className="space-y-1">
<div className="flex items-center justify-between text-sm">
<span>{kp.knowledgePointName}</span>
<span className="text-muted-foreground">
{kp.errorCount} · {formatNumber(kp.masteryRate * 100, 0)}%
</span>
</div>
<Progress value={kp.masteryRate * 100} className="h-1.5" />
</div>
))}
</div>
</CardContent>
</Card>
) : null}
<TopWrongQuestions questions={topWrongQuestions} />
</div>
)
}

View File

@@ -0,0 +1,19 @@
"use client"
import { BookX } from "lucide-react"
import { EmptyState } from "@/shared/components/ui/empty-state"
export default function StudentErrorBookError() {
return (
<div className="p-8">
<EmptyState
icon={BookX}
title="加载错题本失败"
description="发生了一些错误,请刷新页面重试。如果问题持续,请联系管理员。"
action={{ label: "刷新页面", onClick: () => window.location.reload() }}
className="border-none shadow-none"
/>
</div>
)
}

View File

@@ -0,0 +1,30 @@
import { Skeleton } from "@/shared/components/ui/skeleton"
export default function StudentErrorBookLoading() {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div className="flex flex-col justify-between space-y-4 md:flex-row md:items-center md:space-y-0">
<div className="space-y-2">
<Skeleton className="h-8 w-[180px]" />
<Skeleton className="h-4 w-[280px]" />
</div>
<Skeleton className="h-10 w-[120px]" />
</div>
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-5">
{Array.from({ length: 5 }).map((_, idx) => (
<Skeleton key={idx} className="h-[120px] w-full rounded-md" />
))}
</div>
<div className="space-y-4">
<Skeleton className="h-10 w-full" />
<div className="grid gap-3 md:grid-cols-2">
{Array.from({ length: 4 }).map((_, idx) => (
<Skeleton key={idx} className="h-[180px] w-full rounded-md" />
))}
</div>
</div>
</div>
)
}

View File

@@ -0,0 +1,19 @@
"use client"
import { BarChart3 } from "lucide-react"
import { EmptyState } from "@/shared/components/ui/empty-state"
export default function TeacherErrorBookError() {
return (
<div className="p-8">
<EmptyState
icon={BarChart3}
title="加载错题分析失败"
description="发生了一些错误,请刷新页面重试。"
action={{ label: "刷新页面", onClick: () => window.location.reload() }}
className="border-none shadow-none"
/>
</div>
)
}

View File

@@ -0,0 +1,26 @@
import { Skeleton } from "@/shared/components/ui/skeleton"
export default function TeacherErrorBookLoading() {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div className="space-y-2">
<Skeleton className="h-8 w-[180px]" />
<Skeleton className="h-4 w-[300px]" />
</div>
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
{Array.from({ length: 4 }).map((_, idx) => (
<Skeleton key={idx} className="h-[120px] w-full rounded-md" />
))}
</div>
<div className="grid gap-4 md:grid-cols-2">
{Array.from({ length: 2 }).map((_, idx) => (
<Skeleton key={idx} className="h-[300px] w-full rounded-md" />
))}
</div>
<Skeleton className="h-[400px] w-full rounded-md" />
</div>
)
}

View File

@@ -0,0 +1,119 @@
import type { JSX } from "react"
import { BarChart3 } from "lucide-react"
import { requirePermission } from "@/shared/lib/auth-guard"
import { Permissions } from "@/shared/types/permissions"
import { EmptyState } from "@/shared/components/ui/empty-state"
import { getStudentIdsByClassIds, getClassIdsByGradeIds } from "@/modules/classes/data-access"
import {
getStudentErrorBookSummaries,
getTopWrongQuestionsByStudentIds,
getKnowledgePointWeakness,
getSubjectErrorDistribution,
getStudentNameMap,
} from "@/modules/error-book/data-access"
import { ClassErrorBookOverview, StudentErrorTable } from "@/modules/error-book/components/class-error-overview"
import { TopWrongQuestions } from "@/modules/error-book/components/top-wrong-questions"
export const dynamic = "force-dynamic"
export default async function TeacherErrorBookPage(): Promise<JSX.Element> {
const ctx = await requirePermission(Permissions.ERROR_BOOK_ANALYTICS_READ)
// 教师的 dataScope 为 class_taught年级主任/教研组长为 grade_managed管理员为 all
const classIds = ctx.dataScope.type === "class_taught" ? ctx.dataScope.classIds : []
const gradeIds = ctx.dataScope.type === "grade_managed" ? ctx.dataScope.gradeIds : []
if (classIds.length === 0 && gradeIds.length === 0 && ctx.dataScope.type !== "all") {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground"></p>
</div>
<EmptyState
icon={BarChart3}
title="暂无可查看的班级"
description="您还未被分配到任何班级,无法查看错题分析数据。"
className="h-[360px] bg-card"
/>
</div>
)
}
// 年级主任/教研组长:先根据 gradeIds 查询班级,再查询学生
let targetClassIds = classIds
if (gradeIds.length > 0) {
const gradeClassIds = await getClassIdsByGradeIds(gradeIds)
targetClassIds = [...new Set([...classIds, ...gradeClassIds])]
}
const studentIds = await getStudentIdsByClassIds(targetClassIds)
if (studentIds.length === 0) {
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground"></p>
</div>
<EmptyState
icon={BarChart3}
title="班级暂无学生"
description="班级中没有学生,无法查看错题分析数据。"
className="h-[360px] bg-card"
/>
</div>
)
}
// 并行查询所有统计数据
const [summaries, topWrongQuestions, weakKps, subjectDist, nameMap] = await Promise.all([
getStudentErrorBookSummaries(studentIds),
getTopWrongQuestionsByStudentIds(studentIds, 10),
getKnowledgePointWeakness(studentIds, 10),
getSubjectErrorDistribution(studentIds),
getStudentNameMap(studentIds),
])
const studentsWithErrorBook = summaries.filter((s) => s.totalCount > 0)
const totalErrorItems = summaries.reduce((sum, s) => sum + s.totalCount, 0)
const averageMasteryRate = studentsWithErrorBook.length > 0
? studentsWithErrorBook.reduce((sum, s) => sum + s.masteredRate, 0) / studentsWithErrorBook.length
: 0
// 按错题数降序排列
const sortedSummaries = [...summaries].sort((a, b) => b.totalCount - a.totalCount)
return (
<div className="flex h-full flex-col space-y-8 p-8">
<div>
<h1 className="text-2xl font-bold tracking-tight"></h1>
<p className="text-muted-foreground">
</p>
</div>
<ClassErrorBookOverview
totalStudents={studentIds.length}
studentsWithErrorBook={studentsWithErrorBook.length}
totalErrorItems={totalErrorItems}
averageMasteryRate={averageMasteryRate}
topWeakKnowledgePoints={weakKps}
subjectDistribution={subjectDist}
/>
<div className="space-y-4">
<h2 className="text-lg font-semibold"></h2>
<StudentErrorTable
students={sortedSummaries}
studentNames={nameMap}
basePath="/teacher/error-book"
/>
</div>
<TopWrongQuestions questions={topWrongQuestions} />
</div>
)
}