101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# 教师仪表盘实现与 Hydration 修复记录
|
|
|
|
**日期**: 2025-12-23
|
|
**作者**: 资深前端工程师 (Senior Frontend Engineer)
|
|
**状态**: 已实现
|
|
|
|
## 1. 概述
|
|
|
|
本文档详细说明了教师仪表盘 (Teacher Dashboard) 的实现细节，该实现严格遵循 Next_Edu 设计系统 v1.3.0。文档还记录了开发过程中遇到的 Hydration 错误及其解决方案。
|
|
|
|
## 2. 组件架构
|
|
|
|
仪表盘采用垂直切片架构 (Vertical Slice Architecture)，代码位于 `src/modules/dashboard`。
|
|
|
|
### 2.1 文件结构
|
|
```
|
|
src/modules/dashboard/
|
|
└── components/
|
|
├── teacher-stats.tsx # 核心指标 (学生数, 课程数, 待批改作业)
|
|
├── teacher-schedule.tsx # 今日日程列表
|
|
├── recent-submissions.tsx # 最近的学生提交记录
|
|
└── teacher-quick-actions.tsx # 常用操作 (创建作业等)
|
|
```
|
|
|
|
### 2.2 设计系统集成
|
|
所有组件严格遵循 v1.3.0 规范：
|
|
- **排版 (Typography)**: 使用 `Geist Sans`，数据展示开启 `tabular-nums`。
|
|
- **色彩 (Colors)**: 使用语义化 HSL 变量 (`muted`, `primary`, `destructive`)。
|
|
- **图标 (Icons)**: 使用 `lucide-react` (如 `Users`, `BookOpen`, `Inbox`)。
|
|
- **状态 (States)**:
|
|
- **Loading**: 使用自定义骨架屏 (Skeleton)，拒绝全屏 Spinner。
|
|
- **Empty**: 使用 `EmptyState` 组件处理无数据场景。
|
|
|
|
## 3. 组件详情
|
|
|
|
### 3.1 TeacherStats (教师统计)
|
|
- **用途**: 展示教师当前状态的高层概览。
|
|
- **特性**:
|
|
- 在响应式网格中展示 4 个关键指标。
|
|
- 支持 `isLoading` 属性以渲染骨架屏。
|
|
- 使用 `Card` 组件作为容器。
|
|
|
|
### 3.2 TeacherSchedule (教师日程)
|
|
- **用途**: 展示今日课程安排。
|
|
- **特性**:
|
|
- 列出课程时间及地点。
|
|
- 使用 Badge 区分 "Lecture" (讲座) 和 "Workshop" (研讨会)。
|
|
- **空状态**: 当无日程时显示 "No Classes Today"。
|
|
|
|
### 3.3 RecentSubmissions (最近提交)
|
|
- **用途**: 追踪最新的学生活动。
|
|
- **特性**:
|
|
- 展示学生头像、姓名、作业名称及时间。
|
|
- "Late" (迟交) 状态指示器。
|
|
- **空状态**: 当列表为空时显示 "No New Submissions"。
|
|
|
|
### 3.4 EmptyState Component (空状态组件)
|
|
- **位置**: `src/shared/components/ui/empty-state.tsx`
|
|
- **规范**:
|
|
- 虚线边框容器。
|
|
- 居中图标 (Muted 背景)。
|
|
- 清晰的标题和描述。
|
|
- 可选的操作按钮插槽。
|
|
|
|
## 4. Hydration 错误修复
|
|
|
|
### 4.1 问题描述
|
|
开发过程中观察到 "Hydration failed" 错误，原因是 HTML 嵌套无效。具体来说，是 `p` 标签内包含了块级元素（或 React 在 hydration 检查期间视为块级的元素）。
|
|
|
|
### 4.2 根本原因分析
|
|
React 的 hydration 过程对 HTML 有效性要求极高。将 `div` 放入 `p` 标签中违反了 HTML5 标准，但浏览器通常会自动修正 DOM 结构，导致实际 DOM 与 React 基于虚拟 DOM 预期的结构不一致。
|
|
|
|
### 4.3 实施的修复
|
|
将所有仪表盘组件中存在风险的 `p` 标签替换为 `div` 标签，以确保嵌套结构的健壮性。
|
|
|
|
**示例 (RecentSubmissions):**
|
|
|
|
*修改前 (有风险):*
|
|
```tsx
|
|
<p className="text-sm font-medium leading-none">
|
|
{item.studentName}
|
|
</p>
|
|
```
|
|
|
|
*修改后 (安全):*
|
|
```tsx
|
|
<div className="text-sm font-medium leading-none">
|
|
{item.studentName}
|
|
</div>
|
|
```
|
|
|
|
**受影响的组件:**
|
|
1. `recent-submissions.tsx`
|
|
2. `teacher-stats.tsx`
|
|
3. `teacher-schedule.tsx`
|
|
|
|
## 5. 下一步计划
|
|
- 将 Mock Data 对接到真实的 API 端点 (React Server Actions)。
|
|
- 实现 "Quick Actions" (快捷操作) 的具体功能。
|
|
- 为 Submissions 和 Schedule 添加 "View All" (查看全部) 跳转导航。
|