314 lines
13 KiB
Markdown
314 lines
13 KiB
Markdown
# 教师端页面实现分析文档
|
||
|
||
**日期**: 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`
|
||
|