# course_system

**Repository Path**: jaraluron/course_system

## Basic Information

- **Project Name**: course_system
- **Description**: 智能课程系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 课程系统

这是一个前后端分离的课程系统，前端使用 Vue 3 + Vite，后端使用 Flask + SQLAlchemy + JWT。系统覆盖教师端课程管理、学生管理、作业/项目提交、查重、评分、讨论区、资源管理、数据集、开源项目库、游戏化练习和 AI 辅助分析等场景。

这份 README 是**项目总入口**，只写整体结构、快速启动和文档导航。后端 API、数据库、上传、AI 接入等细节看 `backend/README.md`；前端页面、路由、组件和构建细节看 `frontend/README.md`。

## 文档导航

| 文档 | 负责内容 | 适合什么时候看 |
| --- | --- | --- |
| `README.md` | 项目整体介绍、目录结构、快速启动、文档入口 | 第一次打开项目，或想知道整体怎么跑 |
| `backend/README.md` | Flask 后端、数据库、环境变量、API 模块、模型、上传、AI 接入 | 改后端、配数据库、查接口、部署后端 |
| `frontend/README.md` | Vue 前端、页面结构、路由、状态管理、API 调用、构建 | 改页面、组件、路由、接口调用 |
| `DEPLOY.md` | 生产部署、nginx、gunicorn、systemd、服务器目录 | 部署到服务器或共享实验室机器 |
| `MODULE_ASSEMBLY.md` | 模块装配说明 | 调整课程功能模块时参考 |
| `EXTERNAL_MODULES.md` | 外部 Docker 模块交付、注册、挂载和启动令牌说明 | 让学生不接触主系统源码也能交付模块 |
| `CHANGELOG.md` | 变更记录 | 查看历史改动 |

## 功能概览

- **教师端**：课程管理、模块配置、资源上传、学生详情、成绩方案、讨论管理、开源项目管理、游戏关卡编辑。
- **学生端**：课程首页、作业提交、资源查看、成绩单、讨论区、数据集、开源项目、数据闯关/游戏地图。
- **公共能力**：登录鉴权、用户资料、头像、数据集浏览、项目库、AI 工具、Markdown/公式渲染。
- **后端能力**：作业/项目提交、文件上传下载、查重、评分、成绩导入、课表导入、报告生成、Dify/Kimi 代理。

## 技术栈

| 层 | 技术 |
| --- | --- |
| 前端 | Vue 3、Vite、TypeScript、Vue Router、Pinia、Element Plus、Axios、ECharts、Markdown-it、KaTeX |
| 后端 | Flask、Blueprint、Flask-SQLAlchemy、Flask-JWT-Extended、Flask-CORS、PyMySQL |
| 数据库 | MySQL/MariaDB 或 SQLite |
| AI 接入 | Dify API、Kimi/Moonshot OpenAI 兼容接口 |
| 部署 | gunicorn、nginx、systemd |

## 目录结构

```text
course_system/
├── backend/                 # Flask 后端，详见 backend/README.md
│   ├── api/                 # Blueprint 路由
│   ├── modules/             # 课程模块注册
│   ├── services/            # 查重、AI provider 等服务
│   ├── app.py               # 本地启动入口，默认 1234 端口
│   ├── wsgi.py              # 生产 WSGI 入口
│   └── models.py            # SQLAlchemy ORM 模型
├── frontend/                # Vue 前端，详见 frontend/README.md
│   ├── src/pages/           # 页面
│   ├── src/layouts/         # 学生端/教师端布局
│   ├── src/components/      # 通用组件
│   ├── src/api/             # 前端 API 封装
│   └── vite.config.ts       # Vite 开发代理与构建配置
├── deploy/                  # gunicorn、nginx、systemd 示例配置
├── external_modules/        # 外部 Docker 模块示例，包含剥离后的闯关工坊
├── external_module_starter/ # 学生外部 Docker 模块最小模板
├── uploads/                 # 本地上传目录，生产建议改为独立路径
├── DEPLOY.md                # 部署说明
├── EXTERNAL_MODULES.md      # 外部 Docker 模块交付说明
├── MODULE_ASSEMBLY.md       # 模块装配说明
├── CHANGELOG.md             # 变更记录
└── pyproject.toml           # Python 工具配置
```

## 快速启动

建议环境：

- Python 3.10+
- Node.js 18+
- MySQL/MariaDB 或 SQLite

### 1. 启动后端

```powershell
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python app.py
```

后端默认地址：

```text
http://localhost:1234
```

数据库默认行为：

- Windows 本地未设置 `DATABASE_URL` 时，会沿用历史 MySQL 默认连接：`mysql+pymysql://root:12345678@localhost:3306/course_system`。
- 非 Windows 环境未设置 `DATABASE_URL` 时，默认使用 `backend/instance/app.db`。
- 想显式指定数据库时，设置 `DATABASE_URL` 即可。

后端更详细的数据库、环境变量、API 和上传说明见 `backend/README.md`。

### 2. 启动前端

```powershell
cd frontend
npm install
npm run dev
```

前端默认地址：

```text
http://localhost:5173
```

Vite 已配置开发代理：

```text
/api -> http://localhost:1234
```

前端页面、路由、状态管理和构建说明见 `frontend/README.md`。

## 常用配置

后端常用环境变量：

- `DATABASE_URL`：数据库连接串
- `SECRET_KEY` / `JWT_SECRET_KEY`：生产环境必须替换
- `UPLOAD_FOLDER`：上传根目录
- `MAX_CONTENT_LENGTH`：最大上传大小，默认 50MB
- `CORS_ORIGINS`：允许访问后端的前端来源
- `FRONTEND_DIST`：让 Flask 托管前端构建产物时使用
- `DIFY_*`：Dify 聊天、工作流、知识库配置
- `MOONSHOT_API_KEY` / `KIMI_BASE_URL`：Kimi/Moonshot 配置

配置模板在 `backend/.env.example`。当前代码不会自动读取 `.env`，需要通过终端、启动脚本、systemd 或部署平台注入环境变量。

## 开发分工建议

- 改 API、数据库模型、上传、查重、评分、AI 代理：看 `backend/README.md`，改 `backend/`。
- 改页面、路由、菜单、组件、接口调用：看 `frontend/README.md`，改 `frontend/`。
- 改线上部署方式：看 `DEPLOY.md` 和 `deploy/`。
- 改课程功能模块默认开关或模块定义：看 `MODULE_ASSEMBLY.md`、`backend/course_modules.py` 和前端模块配置页面。

## 生产部署

生产环境推荐：

- MySQL/MariaDB 存储业务数据；
- 独立上传目录，例如 `/var/lib/course-system/uploads`；
- gunicorn 运行 Flask；
- nginx 托管前端构建产物并反代 `/api`；
- systemd 管理后端服务。

完整部署步骤见 `DEPLOY.md`。

## 注意事项

- 本项目目前没有 Alembic 迁移，表结构主要依赖后端启动时的 `db.create_all()` 创建缺失表；正式上线前建议补齐迁移方案。
- 本地上传目录方便调试，生产环境不要把上传文件放在 Git 仓库里。
- AI 相关功能需要配置 Dify 或 Kimi/Moonshot token；未配置时，相关接口可能返回配置缺失或占位结果。
- 接口参数和返回结构以 `backend/api/*.py` 实现为准，前端调用封装在 `frontend/src/api/` 和各页面组件中。