# NewSchoolOJ **Repository Path**: synduality/new-school-oj ## Basic Information - **Project Name**: NewSchoolOJ - **Description**: 基于 Python Flask + Vue3 的轻量级校园在线评测系统 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-02 - **Last Updated**: 2026-11-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: Python, Vue, OJ, JavaScript, Online-judge ## README # 🏫 SchoolOJ - 校园在线评测系统 > 基于 Python Flask + Vue3 的轻量级校园在线评测系统 > > **第一次接手?** 先看 [AGENTS.md](AGENTS.md)(装/起/回归命令与不许动的口径), > 再看 [docs/00-接手导读.md](docs/00-接手导读.md)(阅读顺序、模块地图、关键决策)。 > 本文的「功能概览 / 接口概览」可能落后于代码,功能以 `docs/` 为准。 ## 📋 项目简介 SchoolOJ 是一个面向高校程序设计课程的在线评测系统,深度融入学校组织架构(院系→专业→班级),支持课程管理、作业布置、自动评测、成绩统计等核心教学功能。 ### ✨ 核心特性 - **组织架构管理**:院系 → 专业 → 班级 三级管理体系 - **题目管理**:支持多分类与全局 1~5 级难度,题目全局共享;批量导入支持 xlsx / csv / txt(xlsx 可一并导入测试用例) - **在线评测**:对接 go-judge 沙箱,学生端可选 Java 8 / Python 3(评测机另注册 C / C++,学生端暂未开放) - **课程作业**:课程管理、作业布置、自动批改、成绩统计与导出 - **AI 助手**:支持 DeepSeek/Kimi/OpenAI,API Key 以 Fernet 密文入库,提供思路引导与错误解释;学生端以 Live2D 桌宠为入口、回复 Markdown 渲染,教师端成绩页可一键生成 AI 失分诊断 - **安全与运维**:请求限流、人机验证码、日志落盘与访问日志、应用健康探针,判题与 AI 对话在后台异步执行(安全类开关默认关闭,上线前与原有行为一致) - **轻量部署**:无需 Redis/RabbitMQ/Docker,快速搭建 ## 🛠️ 技术栈 | 层级 | 技术 | |------|------| | 后端 | Python 3.11+ / Flask / SQLAlchemy / JWT | | 前端 | Vue 3 / Element Plus / Pinia / Vite | | 数据库 | MySQL 8.0 | | 评测引擎 | go-judge (REST API) | ## 📁 项目结构 ``` NewSchoolOJ/ ├── backend/ # Python Flask 后端 │ ├── app/ │ │ ├── api/ # 路由层(auth/admin/org/course/problem/homework/submission/score/ai/feedback/judge/captcha/health/student/teacher/uploads) │ │ ├── core/ # 核心模块(JWT、go-judge 客户端封装) │ │ ├── judge/ # go-judge 评测模块(client / languages / service) │ │ ├── ratelimit/ # 请求限流(policy / store / service,默认关闭) │ │ ├── captcha/ # 人机验证码(policy / store / service,默认关闭) │ │ ├── tasks/ # 后台任务抽象(TaskRunner:判题 / AI 对话异步执行) │ │ ├── models/ # 数据模型(SQLAlchemy) │ │ ├── schemas/ # 序列化 │ │ ├── services/ # 业务逻辑层 │ │ ├── utils/ # 工具(response/security/xlsx/ai_crypto/avatar/logging_setup/validate) │ │ ├── config.py # 配置管理(显式加载 backend/.env) │ │ ├── extensions.py # 扩展统一管理 │ │ └── __init__.py # 应用工厂 │ ├── instance/ # 实例文件 │ ├── uploads/ # 运行时上传(头像等,不入库) │ ├── test/ # 本地测试/验收脚本(.gitignore 排除,不入库) │ ├── requirements.txt # Python 依赖 │ ├── .env.example # 环境变量模板 │ ├── run.py # 开发启动入口 │ └── wsgi.py # 生产 WSGI 入口 │ ├── frontend/ # Vue3 前端 │ ├── public/ # 静态资源(live2d/ 桌宠立绘等) │ ├── src/ │ │ ├── api/ # 各模块接口封装 │ │ ├── components/ # 通用组件(AIAssistant / AIChatPanel / CaptchaImage / Live2DPet) │ │ ├── constants/ # 常量(AI 助手、桌宠台词) │ │ ├── router/ # Vue Router(三端路由 + 角色守卫) │ │ ├── stores/ # Pinia 状态管理(user / aiChat / aiContext) │ │ ├── utils/ # 工具(request / homework / scoreDiagnosis / problemTypes 等) │ │ ├── views/ # 页面视图 │ │ │ ├── admin/ # 管理员页面 │ │ │ ├── teacher/ # 教师页面 │ │ │ ├── student/ # 学生页面 │ │ │ └── common/ # 公共页面(Login / Layout) │ │ ├── App.vue │ │ └── main.js │ ├── package.json │ ├── vite.config.js # Element Plus 按需引入;dev / preview 均配置 /api 代理,别名 @ │ └── index.html │ ├── docs/ # 项目文档 │ ├── 01-requirements/ # 需求分析 / 优化清单 / 需求变更记录 │ ├── 02-api/ # 接口文档(按模块拆分,入口 index.md) │ ├── 03-database/ # schema.sql / seed_dev.sql / 数据字典 │ ├── 04-design/ # 请求限流 / 日志管理 / 验证码机制 / 异步任务 │ ├── 05-deployment/ # 部署运维 │ ├── 06-testing/ # 教学验收与回归 │ └── 90-archive/ # 历史文档(v1.0 需求 / 路线差异 / 验收手册) │ ├── build.ps1 # 项目骨架构建脚本 ├── .gitignore └── README.md ``` ## 🚀 快速开始 ### 环境要求 | 组件 | 版本 | |------|------| | Python | 3.11+ | | Node.js | 18+ | | MySQL | 8.0+ | | go-judge | 最新版(可选,后续配置)| ### 1. 克隆项目 ```bash git clone https://gitee.com/synduality/new-school-oj.git cd new-school-oj ``` ### 2. 后端配置与启动 #### 2.1 创建并激活虚拟环境 ```bash # Windows python -m venv .venv .\.venv\Scripts\activate # Linux/Mac python -m venv .venv source .venv/bin/activate ``` #### 2.2 安装后端依赖 ```bash cd backend pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``` #### 2.3 配置环境变量 ```bash # 复制环境变量模板 cp .env.example .env # Windows (PowerShell) Copy-Item .env.example .env ``` 编辑 `.env` 文件,填写实际配置: ```env # Flask SECRET_KEY=your-secret-key-here JWT_SECRET_KEY=your-jwt-secret-key-here # 数据库(修改用户名、密码) DATABASE_URL=mysql+pymysql://root:your_password@localhost:3306/newschooloj # go-judge GO_JUDGE_BASE_URL=http://localhost:5050 GO_JUDGE_TIMEOUT=30 # 用户 AI Key 的加密主密钥(建议配置;留空会退回 SECRET_KEY) AI_KEY_SECRET=your-ai-key-secret-here ``` > 以上仅为最小示例;限流 / 验证码 / 日志 / 时区 / 代理透传等**全部配置项**见 [`backend/.env.example`](./backend/.env.example)(限流、验证码、日志默认均关闭)。 #### 2.4 创建数据库并导入初始数据 库名与 `backend/.env` 的 `DATABASE_URL` 保持一致。`schema.sql` / `seed_dev.sql` 都**不含库名**, 换库名只改下面的 `DB_NAME`,不用改脚本文件: ```bash # Windows (PowerShell) $DB_NAME = 'newschooloj' mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS $DB_NAME DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci" $OutputEncoding = New-Object System.Text.UTF8Encoding($false) Get-Content ..\docs\03-database\schema.sql -Raw -Encoding UTF8 | mysql --default-character-set=utf8mb4 -u root -p --database=$DB_NAME # 演示数据(可选,仅空库):测试账号、题目、作业、提交记录、成绩 Get-Content ..\docs\03-database\seed_dev.sql -Raw -Encoding UTF8 | mysql --default-character-set=utf8mb4 -u root -p --database=$DB_NAME # Linux/Mac DB_NAME=newschooloj mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS $DB_NAME DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci" mysql -u root -p --default-character-set=utf8mb4 -D "$DB_NAME" < docs/03-database/schema.sql mysql -u root -p --default-character-set=utf8mb4 -D "$DB_NAME" < docs/03-database/seed_dev.sql ``` > 💡 **提示**:两个脚本都**不建库、不选库**,必须用 `-D` / `--database` 指定目标库,否则会报 > `No database selected`。`schema.sql` 对已有库只补建缺失的表,**不会给已存在的表补列**, > 本项目尚未部署,仓库里不保留增量迁移脚本:新机从零重建 = `schema.sql` + `seed_dev.sql`; > 已有数据的库请先备份,再按启动自检报出的差异手工补列 / 补索引。 > > `seed_dev.sql` 是开发/演示种子(测试账号密码、题目、作业等),只在空库初始化时执行;它自身做了幂等保护 > (含 `submission_detail` 的临时表去重),重复执行不会追加数据。 #### 2.5 启动后端 ```bash python run.py ``` 后端默认运行在 `http://localhost:5000` 预期输出: ``` * Serving Flask app 'app' * Debug mode: on * Running on http://0.0.0.0:5000 ``` ### 3. 前端配置与启动 #### 3.1 安装前端依赖 ```bash cd frontend npm install ``` > 💡 如果 npm 安装慢,可使用国内镜像: > ```bash > npm config set registry https://registry.npmmirror.com > ``` #### 3.2 启动前端 ```bash npm run dev ``` 前端默认运行在 `http://localhost:5173` > Vite 已配置代理,API 请求自动转发到 `http://localhost:5000` 预期输出: ``` VITE v5.x.x ready in xxx ms ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose ``` ### 4. 访问系统 浏览器打开 `http://localhost:5173`,使用测试账号登录: | 角色 | 手机号 | 密码 | |------|--------|------| | 管理员 | `13800000000` | `admin123` | | 教师 | `13900000001` | `tea123` | | 学生 | `18800000001` | `stu123` | ## 🧪 验证安装 ### 验证后端 ```bash # 测试 Flask 应用是否正常 flask --app run.py routes # 或直接运行 python run.py ``` ### 验证数据库 ```bash DB_NAME=newschooloj mysql -u root -p "$DB_NAME" -e "SHOW TABLES;" ``` 预期看到 33 张表;完整表名与字段见 [数据字典](docs/03-database/数据字典.md)。 ### 验证前端 ```bash cd frontend npm run dev ``` 浏览器访问 `http://localhost:5173`,应显示登录页面。 ### 验证自动化回归(本地 / CI) ```bash bash ci/gitee/run_regression.sh # 十套回归:作业链路 / 异步任务 / 全路由冒烟 / schema 自检 / 时区 / 重判补判 / 判题健壮性探针 / 判题重试 / 限流并发 / 学生批量导入 ``` **CI 状态在哪看**:本仓库用 Gitee Go 做持续集成,`push` 或向 `master` 发 PR 时会自动跑上面十套, 任一失败即构建失败。查看方式:打开 Gitee 仓库页 [gitee.com/synduality/new-school-oj](https://gitee.com/synduality/new-school-oj) →「流水线」→「构建历史」, 点最近的构建号即可看到「回归与前端构建」的日志。配置在 `.workflow/ci.yml`,说明与排错见 [docs/06-testing/教学验收与回归.md](./docs/06-testing/教学验收与回归.md) §14.11。 > 未放构建徽章:Gitee Go 的徽章地址需按流水线实际 ID 生成,当前不确定格式,避免放一个打不开的链接。 ## 📄 API 文档 详细 API 设计请查看 [docs/02-api/index.md](./docs/02-api/index.md)(按业务模块拆分为 8 份) ### 核心接口概览 > Base URL 为 `/api/v1`。完整接口(含各端增删改、题目审核/导入、问题反馈等)见上述文档。 | 模块 | 方法 | 端点 | 说明 | |------|------|------|------| | 认证 | POST | `/api/v1/user/register` | 用户注册 | | 认证 | POST | `/api/v1/user/login` | 用户登录 | | 认证 | GET | `/api/v1/user/me` | 获取当前用户 | | 认证 | POST | `/api/v1/user/refresh` | 刷新 Token(前端登录态自动续期) | | 认证 | POST | `/api/v1/user/logout` | 退出登录 | | 题目 | GET | `/api/v1/problems` | 题目列表 | | 题目 | GET | `/api/v1/problems/{id}` | 题目详情 | | 提交 | POST | `/api/v1/submissions` | 提交代码 | | 提交 | GET | `/api/v1/submissions/{id}` | 查询评测状态 | | 作业 | GET | `/api/v1/homeworks/{id}` | 作业详情 | | 成绩 | GET | `/api/v1/homeworks/{id}/scores` | 成绩统计 | | 成绩 | GET | `/api/v1/my-scores` | 学生个人成绩 | | AI | POST | `/api/v1/ai/chat` | AI 对话(异步提交,返回 `task_id`) | | AI | GET | `/api/v1/ai/chat/{task_id}` | 查询 AI 对话结果(轮询) | | 评测 | POST | `/api/v1/judge` | 即时运行(做题页「运行」按钮) | | 评测 | GET | `/api/v1/languages` | 支持的语言列表 | | 验证码 | POST | `/api/v1/captcha/issue` | 发放人机验证挑战(默认关闭) | | 系统 | GET | `/api/v1/health` | 应用存活 / 就绪探针(含数据库连通性) | ## 📊 数据库 数据库设计包含 33 张表,涵盖组织架构、用户、课程作业、题目、评测、成绩、反馈、AI 配置、人机验证、限流与后台任务等模块。 详细设计请查看 [docs/03-database/schema.sql](./docs/03-database/schema.sql) ### ER 图核心关系 ``` 院系 → 专业 → 班级 → 学生 院系 → 教师 → 课程 → 作业 → 题目 题目 → 测试用例 学生 → 提交记录 → 提交详情 学生 → 作业成绩 ``` ## 🤖 AI 助手 AI 助手功能帮助学生在编程过程中获得思路引导和错误解释,教师端成绩页还可一键生成 AI 失分诊断: - **支持模型**:DeepSeek、Kimi、OpenAI 兼容接口 - **密钥管理**:用户在个人中心配置 API Key,以 Fernet 密文存入服务端 `user_ai_config` 表、不回显明文(加密主密钥取 `.env` 的 `AI_KEY_SECRET`) - **功能边界**:提供思路引导和错误解释,不直接生成完整代码 - **触发方式**:学生端为右下角 Live2D 桌宠(点击进入独立对话页 `/student/ai`);教师 / 管理员端为右下角浮动按钮 ## 🛠️ 常用命令 ### 后端 ```bash # 进入后端目录 cd backend # 激活虚拟环境 # Windows .\.venv\Scripts\activate # Linux/Mac source .venv/bin/activate # 安装依赖 pip install -r requirements.txt # 启动开发服务器 python run.py # 生产模式启动(单进程 + 多线程;原因见 docs/05-deployment/部署运维.md §3.4) gunicorn -w 1 --threads 8 -b 0.0.0.0:5000 wsgi:app ``` ### 前端 ```bash # 进入前端目录 cd frontend # 安装依赖 npm install # 启动开发服务器 npm run dev # 构建生产包 npm run build # 预览生产包 npm run preview ``` ### 数据库 ```bash # 库名统一用变量,换库只改这一行 DB_NAME=newschooloj # 导出数据库 mysqldump -u root -p "$DB_NAME" > backup.sql # 导入数据库 mysql -u root -p "$DB_NAME" < backup.sql # 重置数据库(删除后重建;会清空该库全部数据) mysql -u root -p -e "DROP DATABASE IF EXISTS $DB_NAME" mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS $DB_NAME DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci" Get-Content ..\docs\03-database\schema.sql -Raw -Encoding UTF8 | mysql --default-character-set=utf8mb4 -u root -p --database=$DB_NAME Get-Content ..\docs\03-database\seed_dev.sql -Raw -Encoding UTF8 | mysql --default-character-set=utf8mb4 -u root -p --database=$DB_NAME ``` ## 🔧 常见问题 ### Q1: pip install 报错 ```bash # 使用国内镜像源 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### Q2: MySQL 连接失败 检查 `.env` 文件中的 `DATABASE_URL` 配置是否正确: ``` DATABASE_URL=mysql+pymysql://用户名:密码@localhost:3306/newschooloj ``` 如果密码包含特殊字符(如 `@`、`#` 等),需要 URL 编码: ``` # 密码 abc@123 → abc%40123 DATABASE_URL=mysql+pymysql://root:abc%40123@localhost:3306/newschooloj ``` ### Q3: 端口被占用 修改 `backend/run.py`: ```python app.run(host='0.0.0.0', port=5001, debug=True) # 改为 5001 ``` 同时修改 `frontend/vite.config.js` 中的代理目标: ```javascript proxy: { '/api': { target: 'http://localhost:5001', changeOrigin: true } } ``` ### Q4: 前端无法访问后端 API 检查后端是否正常启动,以及 Vite 代理配置是否正确。 ### Q5: 中文乱码 确保以下编码一致: - MySQL 数据库字符集:`utf8mb4` - 项目文件编码:`UTF-8` - `.env` 文件编码:`UTF-8` ### Q6: PowerShell 执行脚本报错 ```bash # 临时绕过执行策略 powershell -ExecutionPolicy Bypass -File script.ps1 ``` ### Q7: 导入 SQL 时报错 "Failed to open file" ```bash # Windows (PowerShell) 正确方式 # schema.sql 不含库名,必须用 --database 指定目标库 $DB_NAME = 'newschooloj' Get-Content ..\docs\03-database\schema.sql -Raw -Encoding UTF8 | mysql --default-character-set=utf8mb4 -u root -p --database=$DB_NAME ``` ### Q8: 密码验证失败 测试账号的密码是经过 BCrypt 加密的,空库初始化时需导入 `docs/03-database/seed_dev.sql`(`schema.sql` 只建表、不含账号)。 ## 📝 开发团队 5 人学校开发团队 ## 📄 版本历史 | 版本 | 日期 | 说明 | |------|------|------| | v1.0 | 2026-09-03 | 初始版本,完成项目骨架搭建 | ## 📜 许可证 本项目仅供学校内部教学使用。