CICD/docs/design/002_teacher_dashboard_implementation.md

教师仪表盘实现与 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):

修改前 (有风险):

<p className="text-sm font-medium leading-none">
  {item.studentName}
</p>

修改后 (安全):

<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" (查看全部) 跳转导航。