feat(classes): optimize teacher dashboard ui and implement grade management

2026-01-14 13:59:11 +08:00
parent ade8d4346c
commit 9bfc621d3f
104 changed files with 12793 additions and 2309 deletions
--- a/docs/architecture/003_frontend_engineering_standards.md
+++ b/docs/architecture/003_frontend_engineering_standards.md
@@ -91,6 +91,9 @@
 - 若现有基础组件无法满足需求：
  1. 优先通过 Composition 在业务模块里封装“业务组件”
  2. 仅在存在 bug 或需要全局一致性调整时，才考虑改动 `src/shared/components/ui/*`（并在 PR 中明确影响面）
+- **图表库**：统一使用 `Recharts`，禁止引入其他图表库（Chart.js / ECharts 等）。
+  - 使用 `src/shared/components/ui/chart.tsx` 进行封装。
+  - 遵循 Shadcn/UI Chart 规范。

 ### 2.4 Client Component 引用边界（强制）

--- a/docs/design/002_teacher_dashboard_implementation.md
+++ b/docs/design/002_teacher_dashboard_implementation.md
@@ -234,3 +234,69 @@ Seed 脚本已覆盖班级相关数据，以便在开发环境快速验证页面
 ### 7.4 技术细节
 - 引入 `recharts` 替换手写 SVG 图表，统一图表风格。
 - 优化 Grid 布局响应式表现 (`lg:grid-cols-12`)。
+- **New Components**:
+  - `TeacherGradeTrends`: 基于 Recharts 的趋势图组件。
+  - `Chart`: 基于 Shadcn/UI 规范的通用图表包装器 (`src/shared/components/ui/chart.tsx`)。
+
+### 7.5 代码管理
+- **Branch**: `ui_opt`
+- **Scope**: `src/modules/dashboard`, `src/shared/components/ui/chart.tsx`
+- **Commit**: "feat(dashboard): optimize teacher dashboard ui and layout"
+
+---
+
+## 8. 班级详情页与学生管理优化 (2026-01-14)
+
+**目标**: 提升班级管理效率与信息可视化程度，优化大班级场景下的性能与体验。
+
+### 8.1 学生管理列表优化 (Students Table)
+- **分页 (Pagination)**: 引入客户端分页（每页 10 条），解决大班级列表渲染性能问题。
+- **信息增强**:
+  - 增加学生头像 (Avatar)、性别、加入时间展示。
+  - 增加可视化状态徽章 (Status Badge)：Active (Emerald) / Inactive (Muted)。
+- **筛选能力**:
+  - 新增状态筛选器 (Active/Inactive)，支持服务端过滤。
+- **涉及组件**:
+  - `src/modules/classes/components/students-table.tsx`
+  - `src/modules/classes/components/students-filters.tsx`
+
+### 8.2 班级详情页重构 (Class Detail Dashboard)
+- **布局重构**: 采用响应式双栏布局 (Main Content + Sidebar)，提升空间利用率。
+- **核心指标 (Key Metrics)**: 顶部增加 4 卡片统计网格：
+  - **Total Students**: 活跃/非活跃人数细分。
+  - **Schedule Items**: 每周课程数。
+  - **Active Assignments**: 活跃作业数与逾期数。
+  - **Class Average**: 基于已评分作业的平均分。
+- **侧边栏小部件**:
+  - **Class Schedule**: 快速查看近期课程。
+  - **Homework History**: 快速查看历史作业状态。
+- **涉及页面**:
+  - `src/app/(dashboard)/teacher/classes/my/[id]/page.tsx`
+
+### 8.3 数据访问层更新
+- **getClassStudents**: 扩展查询字段（头像、性别、加入时间），支持 `status` 过滤参数。
+
+### 8.4 权限与流程调整 (Role Separation)
+- **教师端变更**:
+  - 移除了“创建班级”入口，教师不再直接创建班级。
+  - 新增“加入班级” (Join Class) 功能，通过 6 位邀请码加入已由管理员创建的班级。
+  - 涉及组件：`src/modules/classes/components/my-classes-grid.tsx`
+
+## 9. 年级管理端班级模块 (2026-01-14)
+
+**目标**: 实现年级维度的班级集中管理，支持年级组长与管理员统一创建与维护班级。
+
+### 9.1 路由与入口
+- **路由**: `src/app/(dashboard)/management/grade/classes/page.tsx`
+- **权限**: 仅限拥有年级管理权限的角色（Grade Director / Teaching Head / Admin）。
+
+### 9.2 功能特性
+- **GradeClassesView**:
+  - 展示用户所管理年级的所有班级列表。
+  - 支持按年级筛选。
+  - **CRUD**: 提供创建、编辑、删除班级的完整能力。
+  - **RBAC**: 操作前校验用户对目标年级的管理权限。
+
+### 9.3 核心变更
+- **Data Access**: 新增 `getManagedGrades` 与 `getGradeManagedClasses`。
+- **Actions**: 新增 `createGradeClassAction` 等带权限校验的 Server Actions。
--- a/docs/design/003_textbooks_module_implementation.md
+++ b/docs/design/003_textbooks_module_implementation.md
@@ -1,7 +1,7 @@
 # Textbooks Module Implementation Details

 **Date**: 2025-12-23
-**Updated**: 2025-12-31
+**Updated**: 2026-01-13
 **Author**: DevOps Architect
 **Module**: Textbooks (`src/modules/textbooks`)

@@ -143,6 +143,51 @@ src/
    *   通过 `npm run lint / typecheck / build`。

 ## 8. 后续计划 (Next Steps)
-*   [ ] **富文本编辑器**: 集成编辑器替换当前 Markdown Textarea，提升编辑体验。
-*   [ ] **拖拽排序**: 实现章节树拖拽排序与持久化。
+*   [x] **富文本编辑器**: 已集成 Tiptap 富文本编辑器，支持 Markdown 读写、即时预览与工具栏操作。
+*   [x] **拖拽排序**: 实现章节树拖拽排序与持久化。
 *   [ ] **知识点能力增强**: 支持编辑、排序、分层（如需要）。
+
+---
+
+## 9. 界面与交互优化 (2026-01-12)
+
+**目标**: 提升教师端教材管理的视觉质感与操作体验，对齐 "International Typographic Style" 设计语言。
+
+### 9.1 卡片与列表 (Textbook Card & Filters)
+*   **Dynamic Covers**: 卡片封面采用动态渐变色，根据科目 (Subject) 自动映射不同色系（如数学蓝、物理紫、生物绿），提升识别度。
+*   **Information Density**: 增加元数据展示（Grade, Publisher, Chapter Count），并优化排版层级。
+*   **Quick Actions**: 在卡片底部增加 "Edit Content" / "Delete" 快捷下拉菜单。
+*   **Filters**: 简化筛选栏设计，移除厚重的容器背景，使其更轻量融入页面。
+
+### 9.2 详情页工作台 (Detail Workbench)
+*   **Immersive Layout**:
+    *   **Full Height**: 采用 `h-[calc(100vh-8rem)]` 撑满剩余空间，移除多余滚动条。
+    *   **Sticky Header**: 章节标题与操作栏吸顶，内容区独立滚动。
+    *   **Typography**: 引入 `prose-zinc` 与优化的字体排版，提升阅读舒适度。
+*   **Sidebar Refinement**:
+    *   **Chapter Tree**: 增加左侧边框线与层级缩进，选中态更明显；操作按钮（添加/删除）仅在 Hover 时显示，减少视觉干扰。
+    *   **Knowledge Points**: 改为卡片式列表，Hover 显示删除按钮；增加空状态引导。
+    *   **Drag & Drop**: 集成 `@dnd-kit` 实现章节拖拽排序，支持同级拖动并实时持久化到数据库。
+
+### 9.3 富文本编辑器 (Rich Text Editor)
+*   **Tiptap Integration**: 引入 `@tiptap/react` 替换原有的 Textarea。
+*   **Markdown Support**: 支持 Markdown 源码读写，保持数据格式兼容性。
+*   **Toolbar**: 实现悬浮工具栏，支持 Bold, Italic, Headings, Lists, Blockquote 等常用格式。
+*   **SSR Fix**: 解决 Tiptap 在 Next.js 中的 Hydration Mismatch 问题 (`immediatelyRender: false`)。
+
+### 9.4 系统组件优化 (UI Components)
+*   **Dialog**:
+    *   优化遮罩层 (`backdrop-blur`) 与弹窗阴影，提升通透感。
+    *   调整动画时长 (`duration-200`) 与缓动，移除位移动画，改为纯净的 Fade + Zoom 效果。
+    *   增加内部间距 (`gap-6`) 与圆角 (`rounded-xl`)，使排版更现代。
+    *   **Create Chapter Dialog**: 优化触发按钮样式，增加 `sr-only` 辅助文本，修复点击区域过小的问题。
+
+---
+
+## 10. 近期改进 (2026-01-13)
+
+### 10.1 导航体验 (Navigation)
+*   **Dynamic Breadcrumbs**: 接入全局动态面包屑系统。
+    *   支持从路由路径（e.g., `/teacher/textbooks/123`）自动生成层级导航。
+    *   解决了深层嵌套页面（如教材详情页）缺乏上下文回退路径的问题。
+
--- a/docs/design/005_exam_module_implementation.md
+++ b/docs/design/005_exam_module_implementation.md
@@ -153,7 +153,37 @@ type ExamNode = {
 - `getExams(params)`: 支持按 `q/status` 在数据库侧过滤；`difficulty` 因当前存储在 `description` JSON 中，采用内存过滤
 - `getExamById(id)`: 查询 exam 及其 `exam_questions`，并返回 `structure` 以用于构建器 Hydrate

-## 7. 变更记录（合并 Homework）
+### 6.5 `getExamPreviewAction` (新增)
+- **入参**: `examId` (string)
+- **行为**:
+  - 查询指定 exam 及其关联的 questions (通过 `exam_questions` 关系)。
+  - 返回完整的 `structure` (JSON 树) 和扁平化的 `questions` 列表。
+  - 用于预览弹窗的数据加载。
+
+## 7. 变更记录
+
+**日期**：2026-01-12 (当前)
+
+- **列表页优化 (`/teacher/exams/all`)**:
+  - 移除了冗余的 "All Exams" 页面标题和描述。
+  - 重构了表格列 (`ExamColumns`)：
+    - 合并标题、标签、科目、年级为 "Exam Info" 列。
+    - 合并题目数、总分、时长为 "Stats" 列。
+    - 合并创建时间和预定时间为 "Date" 列。
+    - 优化了状态 (Status) 和难度 (Difficulty) 的视觉样式 (Badge, Progress bar)。
+  - 优化了表格分页和布局 (`ExamDataTable`)。
+
+- **预览功能增强**:
+  - 新增直接预览功能：在操作列添加了 "View" (眼睛图标) 按钮。
+  - 点击 "View" 触发 `getExamPreviewAction` 获取完整试卷数据。
+  - 弹窗 (`Dialog`) 直接展示试卷内容 (`ExamPaperPreview`)，移除了冗余的头部描述，优化了滚动体验。
+  - 修复了可访问性问题 (DialogTitle)。
+
+- **组卷页面升级 (`/teacher/exams/[id]/build`)**:
+  - **布局重构**: 扩展工作区高度，调整左右面板比例 (2:1)，优化头部信息展示和进度可视化。
+  - **题库增强**: 实现了基于 Server Action (`getQuestionsAction`) 的分页加载和服务器端筛选，提升大数据量下的性能；优化了搜索和筛选器 UI。
+  - **预览优化**: 移除了内联预览，改为通过 "Preview" 按钮触发弹窗预览，避免干扰编辑流。
+  - **视觉降噪**: 移除了页面顶部冗余的标题和描述。

 **日期**：2025-12-31

--- a/docs/design/006_homework_module_implementation.md
+++ b/docs/design/006_homework_module_implementation.md
@@ -268,3 +268,39 @@
 - `npm run lint`: 通过
 - `npm run typecheck`: 通过
 - `npm run build`: 通过
+
+---
+
+## 12. UI/UX 优化更新（2026-01-12）
+
+### 12.1 教师端作业列表 (`/teacher/homework/assignments`)
+
+- **表格重构**: 从简单的卡片列表升级为功能丰富的数据表格（Table）。
+- **信息增强**: 合并展示标题/时间，使用 Badge 区分状态，清晰展示截止日期（含 Late 标记），可视化提交进度。
+- **操作便捷**: 每行增加操作菜单（Actions），支持快速跳转详情或提交列表。
+
+### 12.2 作业详情页 (`/teacher/homework/assignments/[id]`)
+
+- **布局重构**:
+  - **Sticky Header**: 头部信息栏（标题、状态、面包屑）随滚动吸顶，但后续优化为随页面滚动（移除 Sticky）以节省空间。
+  - **关键指标**: 将截止日期、目标数、提交数、已批改数整合到头部下方，使用图标增强可读性。
+  - **双栏布局**: 主体内容分为“Performance Analytics”（分析）和“Assignment Content”（内容）两部分。
+- **图表升级**:
+  - 重构 `HomeworkAssignmentQuestionErrorOverviewCard`，废弃 SVG，改用 **Recharts** 实现柱状图（BarChart）。
+  - 增强交互：支持 Tooltip 悬停查看具体题目错误率和人数。
+- **详情面板优化**:
+  - 移除了冗余的 `HomeworkAssignmentQuestionErrorDetailsCard`。
+  - 深度优化 `HomeworkAssignmentQuestionErrorDetailPanel`:
+    - 增加饼图展示单题错误率。
+    - 错误答案列表卡片化，清晰展示每个错误答案的内容及选择人数。
+    - 整合预览面板与详情面板，提供更连贯的“左侧选题-右侧分析”体验。
+
+---
+
+## 13. Bug 修复与完善 (2026-01-13)
+
+### 13.1 批改视图 (Grading View)
+- **Type Safety Fix**: 修复了 `HomeworkGradingView` 组件中的 TypeScript 类型错误。
+    - 问题：`isCorrect` 字段可能为 `boolean | null`，直接用于 JSX 渲染导致 "Type 'unknown' is not assignable to type 'ReactNode'" 错误。
+    - 修复：增加显式布尔值检查 `opt.isCorrect === true`，确保 React 条件渲染接收到合法的 boolean 值。
+
--- a/docs/design/design_system.md
+++ b/docs/design/design_system.md
@@ -114,7 +114,10 @@ Next_Edu 旨在对抗教育系统常见的信息过载。我们的设计风格
 *   **Height**: `64px` (h-16).
 *   **Layout**: `flex items-center justify-between px-6 border-b`.
 *   **Components**:
-    1.  **Breadcrumb**: 显示当前路径，层级清晰。
+    1.  **Breadcrumb**: 动态路径导航 (Dynamic Breadcrumb).
+        *   **Implementation**: 基于 `usePathname()` 自动解析路由段。
+        *   **Mapping**: 通过 `NAV_CONFIG` 或 `BREADCRUMB_MAP` 映射路径到友好标题 (e.g., `/teacher/textbooks` -> "Textbooks").
+        *   **Filtering**: 自动过滤根角色路径 (e.g., `/teacher`) 以保持简洁。
    2.  **Global Search**: `Cmd+K` 触发，居中或靠右。
    3.  **User Nav**: 头像 + 下拉菜单。

--- a/docs/work_log.md
+++ b/docs/work_log.md
@@ -0,0 +1,78 @@
+# Work Log
+
+## 2026-01-14
+
+### 1. Class Management Refactoring (Role Separation)
+*   **Separation of Duties**:
+    *   Moved class creation and management responsibilities from the generic Teacher view to a dedicated Management view.
+    *   Created **Grade Management Page** at `src/app/(dashboard)/management/grade/classes/page.tsx` for Grade Directors and Admins.
+    *   Teachers can now only **Join Classes** (via code) or view their assigned classes in "My Classes".
+
+*   **New Components & Pages**:
+    *   `GradeClassesView` (`src/modules/classes/components/grade-classes-view.tsx`): A comprehensive table view for managing classes within specific grades, supporting creation, editing, and deletion.
+    *   `GradeClassesPage`: Server Component that fetches managed grades and classes using strict RBAC (Role-Based Access Control).
+
+*   **Teacher "My Classes" Update (`my-classes-grid.tsx`)**:
+    *   Removed the "Create Class" button/dialog.
+    *   Added a **"Join Class"** dialog that accepts a 6-digit invitation code.
+    *   Updated styling to use standard design system colors (`bg-card`, `border-border`) instead of hardcoded gradients.
+
+### 2. Backend & Logic Updates
+*   **Data Access (`data-access.ts`)**:
+    *   Implemented `getGradeManagedClasses`: Fetches classes for grades where the user is either a Grade Head or Teaching Head.
+    *   Implemented `getManagedGrades`: Fetches the list of grades managed by the user for the creation dropdown.
+    *   Updated `getTeacherClasses`: Now returns both **owned classes** (assigned by admin) and **enrolled classes** (joined via code).
+    *   Fixed a SQL syntax error in `getGradeManagedClasses` (unescaped backticks in template literal).
+
+*   **Server Actions (`actions.ts`)**:
+    *   Added `createGradeClassAction`, `updateGradeClassAction`, `deleteGradeClassAction`: These actions enforce that the user manages the target grade before performing operations.
+    *   Updated `joinClassByInvitationCodeAction`: Expanded to allow Teachers (role `teacher`) to join classes, not just Students.
+
+### 3. Verification
+*   **RBAC**: Verified that users can only manage classes for grades they are assigned to.
+*   **Flow**: Verified Teacher "Join Class" flow correctly redirects and updates the list.
+*   **Syntax**: Fixed TypeScript/SQL syntax errors in the new data access functions.
+
+### 4. Class UI/UX Optimization
+*   **Students Management Interface (`students-table.tsx`, `students-filters.tsx`)**:
+    *   **Enhanced Table**: Added student avatars, gender display, and join date.
+    *   **Pagination**: Implemented client-side pagination (10 items per page) to handle larger classes gracefully.
+    *   **Status Filtering**: Added "Active/Inactive" filter with visual status badges (Emerald for active, muted for inactive).
+    *   **Data Access**: Updated `getClassStudents` to fetch extended user profile data and support server-side status filtering.
+
+*   **Class Detail Dashboard (`/teacher/classes/my/[id]/page.tsx`)**:
+    *   **Dashboard Layout**: Refactored into a responsive two-column layout (Main Content + Sidebar).
+    *   **Key Metrics**: Added a 4-card stats grid at the top displaying critical insights:
+        *   Total Students (Active/Inactive breakdown)
+        *   Schedule Items (Weekly sessions)
+        *   Active Assignments (Overdue count)
+        *   Class Average (Based on graded submissions)
+    *   **Sidebar Widgets**: Added "Class Schedule" and "Homework History" widgets for quick access to temporal data.
+    *   **Visual Polish**: Integrated `lucide-react` icons throughout for better information scanning.
+
+## 2026-01-13
+
+### 1. Navigation & Layout Improvements
+*   **Dynamic Breadcrumbs (`site-header.tsx`)**:
+    *   Replaced hardcoded "Dashboard > Overview" breadcrumbs with a dynamic system.
+    *   Implemented a path-to-title lookup using `NAV_CONFIG` from `src/modules/layout/config/navigation.ts`.
+    *   Added logic to filter out root role segments (admin/teacher/student/parent) for cleaner paths.
+    *   Added fallback capitalization for segments not found in the config.
+    *   Refactored `SiteHeader` to use `usePathname` for real-time route updates.
+
+### 2. Code Quality & Bug Fixes
+*   **Type Safety (`homework-grading-view.tsx`)**:
+    *   Fixed a TypeScript error where a boolean expression was returning `boolean | undefined` which is not a valid React node (implicit `true` check added).
+    *   Resolved "Calling setState synchronously within an effect" React warning by initializing state lazily instead of using `useEffect`.
+    *   Fixed implicit `any` type errors in map functions.
+*   **Linting**:
+    *   Cleaned up unused imports across multiple files (`exam-actions.tsx`, `exam-assembly.tsx`, `textbook-reader.tsx`, etc.).
+    *   Fixed unescaped HTML entities in `student-dashboard-header.tsx` and others.
+    *   Removed unused variables to clear ESLint warnings.
+*   **Refactoring**:
+    *   Updated `TextbookCard` to support `hideActions` prop for better reuse in student views.
+    *   Added missing `Progress` component to `src/shared/components/ui/progress.tsx`.
+
+### 3. Verification
+*   Ran `npm run typecheck`: **Passed** (0 errors).
+*   Ran `npm run lint`: **Passed** (0 errors, 28 warnings remaining for unused vars/components that may be needed later).