# 教师端页面实现分析文档

**日期**: 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`