Skip to content

Home

Jump to bottom
DameAwsome edited this page May 29, 2025 · 7 revisions

Welcome to the team-project-25spring-15 wiki!

智能课程感知IDE - 开发者文档

开发者团队：孙杨洋，林易成，朱育辰，梁煜，朱柯奇

（一）目录

  1. 项目概述
  2. 技术栈
  3. 项目架构
  4. 核心数据模型
  5. API接口文档
  6. 状态管理
  7. UI组件库
  8. 路由结构
  9. 开发指南
  10. 部署说明
  11. 代码分析
  12. 功能简介
  13. 功能及使用
  14. 常见问题

（二）项目概述

智能课程感知IDE是一个基于Next.js的教育平台，支持三种用户身份：学生(student)、教师(teacher)、超级用户(superuser)。平台提供课程管理、讲座内容、练习系统、评论互动、AI助手和协作功能。

核心功能

  • 课程管理: 创建、编辑、删除课程，管理学生
  • 讲座系统: 课件上传、笔记编辑、内容展示
  • 练习系统: 代码编辑器、在线运行、测试样例管理
  • 评论互动: 实时评论、回复、点赞功能
  • AI助手: 智能对话、代码辅助
  • 协作功能: 实时协作编辑、头脑风暴

（三）技术栈

前端框架

  • Next.js 15: React全栈框架，支持SSR/SSG
  • React 19: 用户界面库
  • TypeScript: 类型安全的JavaScript

UI组件库

  • Material-UI (MUI): 主要UI组件库
  • Tailwind CSS: 原子化CSS框架
  • Heroicons: 图标库

状态管理

  • Zustand: 轻量级状态管理库
  • SWR: 数据获取和缓存

代码编辑器

  • CodeMirror: 代码编辑器核心
  • Sandpack: 在线代码运行环境

实时协作

  • Yjs: 实时协作数据结构
  • Tiptap: 富文本编辑器
  • Hocuspocus: 协作服务器

其他核心库

  • Axios: HTTP客户端
  • NextAuth.js: 身份认证
  • React Markdown: Markdown渲染
  • Framer Motion: 动画库

（四）项目架构

nextjs-dashboard/
├── app/                    # Next.js App Router
│   ├── api/               # API路由
│   ├── dashboard/         # 主要页面
│   ├── lib/              # 核心库文件
│   ├── login/            # 登录页面
│   └── ui/               # UI组件
├── store/                # 状态管理
├── public/               # 静态资源
└── db/                   # 数据库相关

核心目录说明

/app/lib/

  • definitions.ts: 核心数据类型定义
  • client-api.ts: 客户端API接口
  • server-api.ts: 服务端API接口
  • utils.ts: 工具函数
  • prompts.ts: AI提示词模板

/app/ui/

  • course/: 课程相关组件
  • lecture/: 讲座相关组件
  • dashboard/: 仪表板组件
  • collab/: 协作功能组件

/store/

  • useStore.ts: Zustand状态管理配置

（五）核心数据模型

用户信息 (UserInfo)

export type UserInfo = {
  userId: number;
  userName: string;
  usersign?: string;
  university?: string;
  birthday?: string;
  identity?: string;  // 'student' | 'teacher' | 'superuser'
  email: string;
};

课程 (Course)

export interface Course {
  courseId: number;
  courseName: string;
  description?: string;
  endTime: string;
  startTime: string;
  teacherId: number;
  chatId: number;
  lectures: Lecture[];
}

讲座 (Lecture)

export interface Lecture {
  lectureId: number;
  lectureName: string;
  description?: string;
  status?: 'notStarted' | 'inProgress' | 'done';
  courseId: number;
}

作业 (Assignment)

export interface Assignment {
  assignmentId: number;
  publisherId: number;
  assignmentName: string;
  description: string;
  deadline: string;
  score: number;
  courseId: number;
  lectureId: number;
}

评论 (Comment)

export interface Comment {
  id: number;
  lectureId: number;
  content: string;
  authorId: number;
  authorName: string;
  createTime: string;
  likes: number;
  repliedToCommentId: number | null;
  repliedToUserId?: number;
  repliedToUserName?: string;
}

（六）API接口文档

1. 认证相关

获取认证头

export async function getAuthHeader(): Promise<{Authorization?: string}>
  • 功能: 获取当前用户的认证头信息
  • 返回: 包含Bearer token的认证头对象

2. 课程API (CourseAPI)

获取课程列表

async fetchCourses(): Promise<Course[]>
  • 端点: GET /api/course/searchCourseWithLectures/byStudentId
  • 功能: 获取当前用户的课程列表（包含讲座信息）
  • 返回: 课程数组

添加课程

async addCourse(course: {
  courseName: string;
  description: string;
  startTime?: string;
  endTime?: string;
}): Promise<void>
  • 端点: POST /api/course/createCourse
  • 功能: 创建新课程
  • 权限: 仅教师可用

删除课程

async deleteCourse(courseId: number): Promise<any>
  • 端点: DELETE /api/course/deleteCourse
  • 参数: CourseId (query parameter)
  • 权限: 仅课程创建者可用

更新课程

async updateCourse(courseId: number, updatedCourse: {
  courseName: string;
  description: string;
}): Promise<void>
  • 端点: PUT /api/course/updateCourse
  • 权限: 仅课程创建者可用

获取课程学生列表

async getCourseStudents(courseId: number): Promise<UserInfo[]>
  • 端点: GET /api/course/getAllStudentsOfACourse/{courseId}
  • 权限: 仅教师可用

添加学生到课程

async addStudentToCourse(courseId: number, email: string): Promise<any>
  • 端点: POST /api/course/addStudents
  • 请求体: { courseId: number, studentsEmail: string[] }
  • 权限: 仅教师可用

从课程移除学生

async removeStudentFromCourse(courseId: number, studentId: number): Promise<any>
  • 端点: DELETE /api/course/removeStudent
  • 参数: courseId, studentId (query parameters)
  • 权限: 仅教师可用

3. 讲座API (LectureAPI)

获取课程讲座列表

async fetchLecturesByCourse(courseId: number): Promise<Lecture[]>
  • 端点: GET /api/lecture/getLectures/{courseId}
  • 功能: 获取指定课程的所有讲座

添加讲座

async addLecture(courseId: number, payload: {
  lectureName: string;
  description: string;
}): Promise<void>
  • 端点: POST /api/lecture/createLecture
  • 权限: 仅教师可用

删除讲座

async deleteLecture(courseId: number, lectureId: number): Promise<void>
  • 端点: DELETE /api/lecture/deleteLecture
  • 参数: CourseId, LectureId (query parameters)
  • 权限: 仅教师可用

更新讲座

async updateLecture(chatId: number, courseId: number, lectureId: number, updatedLecture: {
  lectureName: string;
  description: string;
}): Promise<void>
  • 端点: PUT /api/lecture/updateLecture
  • 权限: 仅教师可用

4. 作业API (AssignmentAPI)

获取讲座作业列表

async fetchAssignments(lectureId: number): Promise<Assignment[]>
  • 端点: GET /api/assignment/getAllAssignmentOfALecture
  • 参数: lectureId (query parameter)

创建作业

async createAssignment(assignment: Assignment, courseName: string, chatId: number): Promise<void>
  • 端点: POST /api/assignment/createAssignment
  • 权限: 仅教师可用

更新作业

async updateAssignment(assignment: Assignment, courseName: string, chatId: number): Promise<void>
  • 端点: PUT /api/assignment/updateAssignment
  • 权限: 仅教师可用

删除作业

async deleteAssignment(assignmentId: number, courseId: number): Promise<any>
  • 端点: DELETE /api/assignment/deleteAssignment
  • 参数: assignmentId, courseId (query parameters)
  • 权限: 仅教师可用

5. 评论API (CommentAPI)

获取讲座评论

async fetchComments(lectureId: number): Promise<Comment[]>
  • 端点: GET /api/comment/getComment/{lectureId}

发布评论

async publishComment(newCommentData: {
  lectureId: number | null;
  content: string | null;
  authorId: number | null;
  createTime: string | null;
  repliedToCommentId: number | null;
}): Promise<void>
  • 端点: POST /api/comment/createComment

删除评论

async deleteComment(commentId: number, userId: number): Promise<any>
  • 端点: DELETE /api/comment/deleteComment
  • 参数: commentId, userId (query parameters)
  • 权限: 仅评论作者可用

点赞评论

async likeComment(payload: {
  userId: number;
  commentId: number;
  likes: number;
}): Promise<void>
  • 端点: PUT /api/comment/updateComment

6. 文件API (FileAPI)

上传文件

async uploadFile(file: File, lectureId: number): Promise<{result: string, fileId: string}>
  • 端点: POST /api/Files/lectureFile/upload
  • 请求体: FormData (multipart/form-data)
  • 功能: 上传课件文件或测试样例

获取文件

async getFile(lectureId: number): Promise<Blob>
  • 端点: GET /api/Files/lectureFile/lecture/{lectureId}
  • 返回: 文件二进制数据

7. 代码运行API (CodeAPI)

运行代码

async runCode(code_str: string, lang: string): Promise<string>
  • 端点: POST /api/codeRunner/run
  • 请求体: { codeInfo: { code: string }, type: string }
  • 功能: 在线运行代码并返回结果

8. 课件API (CourseWareAPI)

上传PDF课件

async uploadPdf(file: File, lectureId: string): Promise<any>
  • 端点: POST /api/Files/lectureFile/upload

获取PDF课件

async getPdf(lectureId: string): Promise<any>
  • 端点: GET /api/Files/lectureFile/lecture/{lectureId}

上传Markdown笔记

async uploadMarkdown(formData: FormData): Promise<any>
  • 端点: POST /api/Files/lectureNote/upload

获取Markdown笔记

async getMarkdown(lectureId: string): Promise<any>
  • 端点: GET /api/Files/lectureNote/lecture/{lectureId}

（七）状态管理

Zustand Store结构

interface Store {
  // 认证状态
  token: string;
  setToken: (token: string) => void;
  userInfo: UserInfo | null;
  setUserInfo: (info: UserInfo | null) => void;
  isLoggedIn: boolean;
  setLoggedIn: (status: boolean) => void;
  
  // 课程数据
  courses: Course[];
  setCourses: (c: Course[]) => void;
  lectures: Lecture[];
  setLectures: (l: Lecture[]) => void;
  
  // 选择状态
  selectedCourseId: number;
  setSelectedCourseId: (id: number) => void;
  selectedLectureId: number;
  setSelectedLectureId: (id: number) => void;
}

使用示例

import { useStore } from '@/store/useStore';

function MyComponent() {
  const userInfo = useStore(state => state.userInfo);
  const courses = useStore(state => state.courses);
  const setCourses = useStore(state => state.setCourses);
  
  // 组件逻辑...
}

（八）UI组件库

核心组件

CourseList (app/ui/course/course-list.tsx)

  • 功能: 显示课程列表，支持"全部课程"和"我的课程"标签切换
  • Props: 无
  • 权限: 所有用户

LectureList (app/ui/course/lecture-list.tsx)

  • 功能: 显示课程的讲座列表
  • Props: { courseId: number }
  • 权限: 课程成员

StudentList (app/ui/course/student-list.tsx)

  • 功能: 学生管理页面，教师可查看、添加、移除学生
  • Props: { courseId: number }
  • 权限: 仅教师

ExerciseRender (app/ui/lecture/exercise-render.tsx)

  • 功能: 练习页面，包含题目描述和代码编辑器
  • Props: { assignment: Assignment }
  • 权限: 课程成员

组件使用示例

// 课程列表页面
import CourseList from '@/app/ui/course/course-list';

export default function Dashboard() {
  return <CourseList />;
}

// 讲座列表页面
import LectureList from '@/app/ui/course/lecture-list';

export default function CoursePage({ params }: { params: { courseId: string } }) {
  return <LectureList courseId={parseInt(params.courseId)} />;
}

（九）路由结构

主要路由

/                           # 首页（重定向到登录或仪表板）
/login                      # 登录页面
/dashboard                  # 课程列表页面
/dashboard/course/[courseId]              # 课程详情页（讲座列表）
/dashboard/course/[courseId]/students     # 学生管理页（仅教师）
/dashboard/[courseId]/[lectureId]         # 讲座功能页面

动态路由参数

  • [courseId]: 课程ID
  • [lectureId]: 讲座ID

权限控制

路由级别的权限控制通过组件内部检查用户身份实现：

const userInfo = useStore(state => state.userInfo);
const isTeacher = userInfo?.identity === 'teacher';

if (!isTeacher) {
  router.push('/dashboard');
  return null;
}

（十）开发指南

1. 环境设置

  1. 安装依赖
pnpm install
  1. 启动开发服务器
pnpm dev
  1. 构建生产版本
pnpm build
pnpm start

2. 开发规范

组件开发

  • 使用TypeScript进行类型安全开发
  • 组件应该有明确的Props接口定义
  • 使用Material-UI组件保持UI一致性
  • 添加适当的错误处理和加载状态

API调用

  • 所有API调用都应该通过client-api.ts中的封装函数
  • 使用getAuthHeader()获取认证信息
  • 添加适当的错误处理和日志记录

状态管理

  • 使用Zustand进行全局状态管理
  • 避免在组件间传递过多props
  • 持久化重要的用户状态（token、userInfo等）

3. 代码示例

创建新的API接口

// 在 client-api.ts 中添加新的API
export const NewAPI = {
  fetchData: async (id: number) => {
    const headers = await getAuthHeader();
    try {
      const response = await axios.get(`/api/new-endpoint/${id}`, { headers });
      return response.data.data;
    } catch (error) {
      console.error('Failed to fetch data:', error);
      throw error;
    }
  }
};

创建新的UI组件

// 新组件文件
'use client';

import { useState, useEffect } from 'react';
import { Container, Typography } from '@mui/material';
import { useStore } from '@/store/useStore';

interface MyComponentProps {
  id: number;
}

export default function MyComponent({ id }: MyComponentProps) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const userInfo = useStore(state => state.userInfo);

  useEffect(() => {
    // 数据加载逻辑
  }, [id]);

  if (loading) {
    return <Typography>加载中...</Typography>;
  }

  return (
    <Container>
      {/* 组件内容 */}
    </Container>
  );
}

4. 测试指南

单元测试

  • 使用Jest和React Testing Library
  • 测试组件的渲染和交互
  • 模拟API调用和状态变化

集成测试

  • 测试完整的用户流程
  • 验证API集成的正确性
  • 测试权限控制逻辑

5. 性能优化

代码分割

  • 使用动态导入进行路由级代码分割
  • 懒加载非关键组件

数据获取优化

  • 使用SWR进行数据缓存
  • 避免重复的API调用
  • 实现适当的加载状态

渲染优化

  • 使用React.memo避免不必要的重渲染
  • 优化大列表的渲染性能
  • 使用虚拟滚动处理大量数据

（十一）部署说明

环境变量

创建.env.local文件：

# 认证相关
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

# API端点
NEXT_PUBLIC_API_BASE_URL=http://your-api-server

# 数据库连接
DATABASE_URL=your-database-url

构建部署

前端

  1. 构建应用
pnpm build
  1. 启动生产服务器
pnpm start

Docker部署

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

注意事项

  • 确保所有环境变量正确配置
  • 检查API端点的可访问性
  • 配置适当的CORS策略
  • 设置生产环境的错误监控

后端

本项目为后端提供了Makefile实现自动化构建，同时支持dev和ope模式，分别以docker compose和docker swarm提供支持，相关docker-compose.yml为位于/Backend下的docker-compose.dev.yml和docker-compose.ope.yml

dev

运行：

make setup-backend-dev

停止：

make close-backend-dev

ope

运行：

make setup-backend-ope

停止：

make close-backend-ope

（十二）代码分析

本仓库使用cloc、jq、gocyclo进行代码分析，如果希望进行测试，请执行一下命令

make analyze

也可以分别测试前后端代码

前端

make analyze-frontend

后端

make analyze-backend

已有的代码分析报告可见 https://github.com/sustech-cs304/team-project-25spring-15/blob/main/evaluate.log

（十三）贡献指南

提交代码

  1. Fork项目仓库
  2. 创建功能分支：git checkout -b feature/new-feature
  3. 提交更改：git commit -m 'Add new feature'
  4. 推送分支：git push origin feature/new-feature
  5. 创建Pull Request

代码审查

  • 确保通过github actions测试/提供合理证据证明代码正确性
  • 确保代码符合项目规范
  • 添加适当的测试覆盖
  • 更新相关文档
  • 验证功能的正确性

问题报告

使用GitHub Issues报告bug或请求新功能，请包含：

  • 详细的问题描述
  • 重现步骤
  • 期望的行为
  • 实际的行为
  • 环境信息

功能简介

  • 实现回复他人界面
  • 在上传文件时，可自动识别PDF和PPT里面的代码
  • AI根据课件生成思维导图
  • 支持多人同时编辑和共享文档，编辑时会产生高亮
  • 可返回讲座里评论区里的高频热词
  • 提供嵌入式Ai的接口，可以和AI交互
  • 更安全的登陆验证模式

功能及使用

课件

功能介绍

老师可以上传 PDF 或 Markdown 格式的文件，学生可以在线预览并阅读课件内容。Markdown 文件可用于编辑笔记，PDF 用于展示正式课件，支持代码运行等互动功能。

使用步骤

1. 老师点击上传 PDF 或 Notes，选择本地文件上传到课程中
2. 学生点击课件文件即可在线预览内容
3. 老师可以对 Notes 文件进行编辑，作为课堂笔记或补充讲解
4. 老师可以直接运行 Notes 中的代码，进行示范

练习

功能介绍

老师可以发布编程练习，学生可以在线编写代码、运行和提交，支持自动高亮和反馈机制。

使用步骤

1. 老师填写练习的标题和文本内容，点击发布
2. 学生在左侧查看题目说明，在右侧代码区编写解答
3. 编写完成后可点击运行测试代码，也可点击提交完成作答
4. 系统支持代码高亮显示，提升书写和阅读体验

评论

功能介绍

学生可以对课程内容、课件或练习发表评论和问题，老师可以进行回复和讨论。

使用步骤

1. 学生填写评论文本后点击发布，即可完成评论
2. 每条评论显示评论人姓名和时间，可查看回复记录，支持多层嵌套回复

AI

功能介绍

学生可以与 AI 互动，提出学习问题，生成思维导图、Quiz 等学习辅助内容。

使用步骤

1. 在 AI 问答框中输入问题后提交，即可获得 AI 的解答
2. 输入命令让 AI 生成思维导图，系统会自动渲染并展示
3. 可以请求 AI 自动生成 Quiz，并进行实时答题和批改

头脑风暴

功能介绍

学生可以在共享文档中实时多人编辑，用于头脑风暴、小组讨论或课堂互动。

使用步骤

1. 多位学生可同时编辑同一文档，系统显示每位用户的光标和操作
2. 可用于表达不同的想法、记录讨论内容，实时保存

课程

功能介绍

用户可以查看课程信息和参与成员列表，老师和助教可以进行成员管理和邮件邀请。

使用步骤

1. 老师点击按钮创建新的课程或讲座
2. 所有用户可以查看课程参与者列表，包含姓名和身份（老师、学生等）
3. 老师和助教可以通过邮箱邀请新用户加入课程

注册与登录

功能介绍

平台支持用户注册与登录，确保课程内容仅对授权用户开放。

使用步骤

1. 新用户点击注册按钮，填写邮箱、姓名和密码完成注册
2. 注册用户在登录页输入邮箱和密码即可登录平台

常见问题

Q：如何获取技术支持

A：您可以联系技术团队，12211226@mail.sustech.edu.cn

本文档将随着项目的发展持续更新。如有疑问或建议，请联系开发团队。

Clone this wiki locally