sync-docs-and-fixes

2026-03-03 17:32:26 +08:00
parent 538805bad0
commit eb08c0ab68
73 changed files with 2218 additions and 422 deletions
--- a/docs/design/008_teacher_pages_implementation.md
+++ b/docs/design/008_teacher_pages_implementation.md
@@ -0,0 +1,313 @@
+# 教师端页面实现分析文档
+
+**日期**: 2026-03-03  
+**范围**: Teacher 路由与页面实现（`src/app/(dashboard)/teacher`）  
+
+---
+
+## 1. 总览
+
+教师端页面采用服务端组件为主、按页面聚合数据的方式实现，页面负责：
+
+- 读取数据（模块 data-access）
+- 组装 UI（模块 components）
+- 处理空状态与跳转
+
+所有页面路由位于 `src/app/(dashboard)/teacher`，各业务能力落在 `src/modules/*` 中。
+
+---
+
+## 2. 路由总表
+
+### 2.1 教师工作台
+- `/teacher/dashboard`  
+  实现：[dashboard/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/dashboard/page.tsx)
+
+### 2.2 班级
+- `/teacher/classes` → `/teacher/classes/my`  
+  实现：[classes/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/page.tsx)
+- `/teacher/classes/my`  
+  实现：[classes/my/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/my/page.tsx)
+- `/teacher/classes/my/[id]`  
+  实现：[classes/my/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/my/%5Bid%5D/page.tsx)
+- `/teacher/classes/students`  
+  实现：[classes/students/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/students/page.tsx)
+- `/teacher/classes/schedule`  
+  实现：[classes/schedule/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/schedule/page.tsx)
+
+### 2.3 作业
+- `/teacher/homework` → `/teacher/homework/assignments`  
+  实现：[homework/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/page.tsx)
+- `/teacher/homework/assignments`  
+  实现：[homework/assignments/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/page.tsx)
+- `/teacher/homework/assignments/create`  
+  实现：[homework/assignments/create/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/create/page.tsx)
+- `/teacher/homework/assignments/[id]`  
+  实现：[homework/assignments/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/page.tsx)
+- `/teacher/homework/assignments/[id]/submissions`  
+  实现：[homework/assignments/[id]/submissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/submissions/page.tsx)
+- `/teacher/homework/submissions`  
+  实现：[homework/submissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/page.tsx)
+- `/teacher/homework/submissions/[submissionId]`  
+  实现：[homework/submissions/[submissionId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/%5BsubmissionId%5D/page.tsx)
+
+### 2.4 考试
+- `/teacher/exams` → `/teacher/exams/all`  
+  实现：[exams/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/page.tsx)
+- `/teacher/exams/all`  
+  实现：[exams/all/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/all/page.tsx)
+- `/teacher/exams/create`  
+  实现：[exams/create/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/create/page.tsx)
+- `/teacher/exams/[id]/build`  
+  实现：[exams/[id]/build/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/%5Bid%5D/build/page.tsx)
+- `/teacher/exams/grading` → `/teacher/homework/submissions`  
+  实现：[exams/grading/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/page.tsx)
+- `/teacher/exams/grading/[submissionId]` → `/teacher/homework/submissions`  
+  实现：[exams/grading/[submissionId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/%5BsubmissionId%5D/page.tsx)
+
+### 2.5 题库
+- `/teacher/questions`  
+  实现：[questions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/questions/page.tsx)
+
+### 2.6 教材
+- `/teacher/textbooks`  
+  实现：[textbooks/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/textbooks/page.tsx)
+- `/teacher/textbooks/[id]`  
+  实现：[textbooks/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/textbooks/%5Bid%5D/page.tsx)
+
+---
+
+## 3. 页面详解（逐页）
+
+### 3.1 教师工作台 `/teacher/dashboard`
+实现：[dashboard/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/dashboard/page.tsx)
+
+- **目的**: 教师总览工作台，展示班级、课表、作业、提交、成绩趋势与教师姓名。
+- **数据来源**:
+  - 班级与课表：`getTeacherClasses`、`getClassSchedule`
+  - 作业与提交：`getHomeworkAssignments`、`getHomeworkSubmissions`
+  - 教师姓名：`users` 表查询
+  - 成绩趋势：`getTeacherGradeTrends`
+- **关键组件**: `TeacherDashboardView`
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.2 班级入口 `/teacher/classes`
+实现：[classes/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/page.tsx)
+
+- **目的**: 跳转入口，统一导向“我的班级”。
+- **行为**: `redirect("/teacher/classes/my")`
+
+### 3.3 我的班级 `/teacher/classes/my`
+实现：[classes/my/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/my/page.tsx)
+
+- **目的**: 展示教师负责班级的卡片列表，并支持学科筛选/加入。
+- **数据来源**:
+  - 班级：`getTeacherClasses`
+  - 学科选项：`getClassSubjects`
+- **关键组件**: `MyClassesGrid`
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.4 班级详情 `/teacher/classes/my/[id]`
+实现：[classes/my/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/my/%5Bid%5D/page.tsx)
+
+- **目的**: 展示班级概览（作业趋势、学生、课表、作业摘要）。
+- **数据来源**:
+  - 班级作业洞察：`getClassHomeworkInsights`
+  - 学生列表：`getClassStudents`
+  - 课表：`getClassSchedule`
+  - 学科成绩：`getClassStudentSubjectScoresV2`
+- **关键组件**:
+  - `ClassHeader`
+  - `ClassOverviewStats`
+  - `ClassTrendsWidget`
+  - `ClassStudentsWidget`
+  - `ClassScheduleWidget`
+  - `ClassAssignmentsWidget`
+- **空状态**: `insights` 缺失返回 `notFound()`
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.5 学生列表 `/teacher/classes/students`
+实现：[classes/students/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/students/page.tsx)
+
+- **目的**: 按班级、关键词、状态筛选学生，并显示学科成绩。
+- **数据来源**:
+  - 教师班级：`getTeacherClasses`
+  - 学生列表：`getClassStudents`
+  - 学科成绩：`getStudentsSubjectScores`
+- **关键组件**:
+  - `StudentsFilters`
+  - `StudentsTable`
+  - `EmptyState` / `Skeleton`
+- **筛选逻辑**: 未显式选择班级时默认第一班级
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.6 课表 `/teacher/classes/schedule`
+实现：[classes/schedule/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/schedule/page.tsx)
+
+- **目的**: 按班级查看课表。
+- **数据来源**:
+  - 班级：`getTeacherClasses`
+  - 课表：`getClassSchedule`
+- **关键组件**:
+  - `ScheduleFilters`
+  - `ScheduleView`
+  - `EmptyState` / `Skeleton`
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.7 作业入口 `/teacher/homework`
+实现：[homework/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/page.tsx)
+
+- **目的**: 统一导向作业列表。
+- **行为**: `redirect("/teacher/homework/assignments")`
+
+### 3.8 作业列表 `/teacher/homework/assignments`
+实现：[homework/assignments/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/page.tsx)
+
+- **目的**: 查看作业列表与状态，支持按班级筛选，提供创建入口。
+- **数据来源**:
+  - 作业列表：`getHomeworkAssignments`
+  - 班级列表（用于显示名称）：`getTeacherClasses`
+- **关键组件**: `Table`、`Badge`、`EmptyState`
+- **空状态**: 无作业时提示创建
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.9 创建作业 `/teacher/homework/assignments/create`
+实现：[homework/assignments/create/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/create/page.tsx)
+
+- **目的**: 从 Exam 派发作业。
+- **数据来源**:
+  - 可派发的 Exam：`getExams`
+  - 班级列表：`getTeacherClasses`
+- **关键组件**: `HomeworkAssignmentForm`
+- **空状态**:
+  - 无 Exam：提示先创建考试
+  - 无班级：提示先创建班级
+
+### 3.10 作业详情 `/teacher/homework/assignments/[id]`
+实现：[homework/assignments/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/page.tsx)
+
+- **目的**: 展示作业详情、错题概览与试卷内容。
+- **数据来源**: `getHomeworkAssignmentAnalytics`
+- **关键组件**:
+  - `HomeworkAssignmentQuestionErrorOverviewCard`
+  - `HomeworkAssignmentExamContentCard`
+- **空状态**: 查不到作业时 `notFound()`
+
+### 3.11 作业提交列表 `/teacher/homework/assignments/[id]/submissions`
+实现：[homework/assignments/[id]/submissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/submissions/page.tsx)
+
+- **目的**: 按作业查看提交与评分进度。
+- **数据来源**:
+  - 作业信息：`getHomeworkAssignmentById`
+  - 提交列表：`getHomeworkSubmissions`
+- **关键组件**: `Table`、`Badge`
+- **空状态**: 作业不存在时 `notFound()`
+
+### 3.12 全部提交 `/teacher/homework/submissions`
+实现：[homework/submissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/page.tsx)
+
+- **目的**: 按作业汇总查看所有提交与批改入口。
+- **数据来源**:
+  - 教师身份：`getTeacherIdForMutations`
+  - 作业审阅列表：`getHomeworkAssignmentReviewList`
+- **关键组件**: `Table`、`Badge`、`EmptyState`
+
+### 3.13 提交批改 `/teacher/homework/submissions/[submissionId]`
+实现：[homework/submissions/[submissionId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/%5BsubmissionId%5D/page.tsx)
+
+- **目的**: 作业批改视图，按题打分与反馈。
+- **数据来源**: `getHomeworkSubmissionDetails`
+- **关键组件**: `HomeworkGradingView`
+- **空状态**: 查不到提交时 `notFound()`
+
+### 3.14 考试入口 `/teacher/exams`
+实现：[exams/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/page.tsx)
+
+- **目的**: 统一导向考试列表。
+- **行为**: `redirect("/teacher/exams/all")`
+
+### 3.15 考试列表 `/teacher/exams/all`
+实现：[exams/all/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/all/page.tsx)
+
+- **目的**: 列出考试并支持筛选、统计、创建入口。
+- **数据来源**: `getExams`（按关键词/状态/难度过滤）
+- **关键组件**:
+  - `ExamFilters`
+  - `ExamDataTable`
+  - `EmptyState` / `Skeleton`
+- **统计**: 对列表结果进行状态数量统计（draft/published/archived）
+
+### 3.16 创建考试 `/teacher/exams/create`
+实现：[exams/create/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/create/page.tsx)
+
+- **目的**: 创建考试基础信息。
+- **关键组件**: `ExamForm`
+
+### 3.17 组卷 `/teacher/exams/[id]/build`
+实现：[exams/[id]/build/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/%5Bid%5D/build/page.tsx)
+
+- **目的**: 从题库选择题目并构建考试结构。
+- **数据来源**:
+  - 考试数据：`getExamById`
+  - 题库数据：`getQuestions`
+- **关键组件**: `ExamAssembly`
+- **关键逻辑**:
+  - 读取已选题并初始化 `initialSelected`
+  - 将题目数据映射为 `Question` 类型
+  - 归一化 `structure` 并保证节点 `id` 唯一
+
+### 3.18 阅卷入口 `/teacher/exams/grading*`
+实现：[exams/grading/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/page.tsx)、[exams/grading/[submissionId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/%5BsubmissionId%5D/page.tsx)
+
+- **目的**: 统一重定向至作业批改视图。
+- **行为**: `redirect("/teacher/homework/submissions")`
+
+### 3.19 题库 `/teacher/questions`
+实现：[questions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/questions/page.tsx)
+
+- **目的**: 题库管理与筛选。
+- **数据来源**: `getQuestions`（按关键词/题型/难度过滤）
+- **关键组件**:
+  - `QuestionFilters`
+  - `QuestionDataTable`
+  - `CreateQuestionButton`
+  - `EmptyState` / `Skeleton`
+
+### 3.20 教材列表 `/teacher/textbooks`
+实现：[textbooks/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/textbooks/page.tsx)
+
+- **目的**: 教材管理与筛选，创建入口。
+- **数据来源**: `getTextbooks`
+- **关键组件**:
+  - `TextbookFilters`
+  - `TextbookCard`
+  - `TextbookFormDialog`
+  - `EmptyState`
+- **渲染策略**: `dynamic = "force-dynamic"`
+
+### 3.21 教材详情 `/teacher/textbooks/[id]`
+实现：[textbooks/[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/textbooks/%5Bid%5D/page.tsx)
+
+- **目的**: 教材章节与知识点结构阅读与维护。
+- **数据来源**:
+  - 教材：`getTextbookById`
+  - 章节：`getChaptersByTextbookId`
+  - 知识点：`getKnowledgePointsByTextbookId`
+- **关键组件**:
+  - `TextbookReader`
+  - `TextbookSettingsDialog`
+- **空状态**: 教材不存在时 `notFound()`
+
+---
+
+## 4. 依赖模块清单
+
+教师端页面主要依赖以下模块：
+
+- 班级与排课：`src/modules/classes`
+- 作业：`src/modules/homework`
+- 考试：`src/modules/exams`
+- 题库：`src/modules/questions`
+- 教材：`src/modules/textbooks`
+- 工作台：`src/modules/dashboard`
+