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

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。

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`）自动生成层级导航。
+    *   解决了深层嵌套页面（如教材详情页）缺乏上下文回退路径的问题。
+

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
 

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 值。
+

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**: 头像 + 下拉菜单。