OJ_UI

OJ 在线判题系统 · 前端

基于 Vue 3 + TypeScript + Vite 6 的在线判题（Online Judge）前端，提供题目浏览与提交、比赛与排名、后台管理等功能。

技术栈

分类	选型
框架	Vue 3.5（<script setup> SFC）
语言	TypeScript 5.8
构建	Vite 6
路由	Vue Router 4
状态管理	Pinia 3 + pinia-plugin-persistedstate
UI 组件库	Element Plus 2（中文语言环境）
HTTP	Axios（统一拦截器）
接口生成	Orval 7（基于 OpenAPI 生成 TypeScript 客户端与类型）
代码编辑器	Monaco Editor（当前仅 Java）
Markdown	ByteMD（GFM + 代码高亮）
时间处理	Day.js

功能特性

用户端

• 题目：列表支持按标题、难度、分类搜索与分页；详情页展示描述、限制信息、样例、统计与分类标签，并可在页内使用 Monaco 提交代码、查看判题结果。
• 比赛：列表按状态/类型筛选；详情页展示赛题列表与分值，支持报名（密码型比赛先校验口令）；独立排名页展示名次、用户、总分与 AC 最大耗时。
• 我的提交：分页表格展示提交记录，展开行可查看提交的代码与判题详情。
• 账号：登录/退出，用户信息与登录态持久化。

管理后台

• 题目管理：题目 CRUD，维护分类勾选，详情弹窗管理样例与评测用例（含隐藏标记）。
• 分类管理：题目分类 CRUD。
• 比赛管理：比赛 CRUD，配置赛题（多选题目 + 显示顺序 + 分值），查看报名名单。
• 用户管理：用户分页查询、状态与角色管理、改密与头像。

快速开始

环境要求

• Node.js 18+
• 后端服务运行在 http://localhost:8080（提供 /v3/api-docs OpenAPI 文档）

安装与运行

npm install
npm run dev        # 本地开发，默认 http://localhost:5173
npm run build      # vue-tsc 类型检查 + 生产构建，产物在 dist/
npm run preview    # 本地预览构建产物
npm run api:gen    # 依据后端 OpenAPI 文档重新生成接口代码

后端联调

开发环境通过 Vite 代理转发请求，/api 前缀会被重写后转发到 http://localhost:8080：

// vite.config.ts
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}

Axios 实例的 baseURL 取 import.meta.env.VITE_API_BASE_URL，未配置时回退为 /api（即走上面的代理）。如需直连后端或部署到其他地址，创建 .env.local 覆盖即可：

VITE_API_BASE_URL=http://localhost:8080

请求与响应约定

src/util/axios-instance.ts 集中处理鉴权与提示：

• 请求拦截器从 localStorage.token 读取令牌并注入 Authorization: Bearer <token>。
• 响应拦截器按业务状态码判断：code 为 0 或 200 视为成功并直接返回 response.data；失败时统一弹出后端返回的 message 并 reject。
• HTTP/网络异常同样由拦截器统一提示（相同文案 1.5 秒内去重）；HTTP 401 统一提示并跳转登录页。
• 后端成功响应的 message 固定为 success，因此拦截器不再弹成功提示；操作成功文案与表单校验提示保留在视图层。

视图层不再处理接口错误提示，只需 try/catch 保留必要的状态重置、页面跳转等控制流。

接口代码生成

Orval 读取后端 OpenAPI 文档，按标签拆分为控制器文件，类型输出到 src/api/models，并使用自定义 mutator 走统一的 Axios 实例：

// orval.config.ts 关键配置
input: { target: 'http://localhost:8080/v3/api-docs' },
output: {
  mode: 'tags',
  client: 'axios',
  target: './src/api/client.ts',
  schemas: './src/api/models',
  clean: true,
  override: {
    mutator: { path: './src/util/axios-instance.ts', name: 'customAxiosInstance' },
    query: { useQuery: true, useMutation: true }
  }
},
hooks: { afterAllFilesWrite: 'prettier --write' }

后端每完成一批接口后执行 npm run api:gen，产物示例：

src/api/
├── auth-controller.ts        # 登录认证
├── category-controller.ts    # 题目分类
├── contest-controller.ts     # 比赛
├── problem-controller.ts     # 题目
├── submission-controller.ts  # 代码提交与判题
├── user-controller.ts        # 用户管理
└── models/                   # 请求/响应 DTO、VO 与枚举

视图层按控制器调用接口，类型统一从 @/api/models 引入：

import { getProblemController } from '@/api/problem-controller'
import type { ProblemVo, QueryByPage1Params } from '@/api/models'

const page = await getProblemController().queryByPage1({ pageNum, pageSize } as QueryByPage1Params)

src/api 目录由 Orval 生成（clean: true，每次生成会清空重建），不要手动修改。

目录结构

src/
├── api/                 # Orval 生成的接口客户端与数据模型
├── components/          # 公共组件（MonacoEditor）
├── layout/              # 布局：UserLayout（顶部导航）、AdminLayout（侧边菜单）
├── router/              # 路由定义与权限守卫
├── store/               # Pinia：meta（站点配置）、user（登录态）
├── type/                # 手工维护的公共类型
├── util/                # axios-instance、markdown、format-time、submission 状态映射
├── view/
│   ├── admin/           # 后台：题目/分类/比赛/用户管理
│   ├── contest/         # 比赛列表、详情、排名
│   ├── problem/         # 题目列表、详情
│   └── submission/      # 我的提交
├── App.vue
└── main.ts              # 应用入口：注册 Router、Pinia、Element Plus（zh-cn）

路径别名 @ 指向 src（见 vite.config.ts）。

路由与权限

路径	页面	访问权限
/login	登录	公开
/	首页	公开
/about	关于	公开
/problems	题目列表	公开
/problems/:id	题目详情	公开（提交需登录）
/contests	比赛列表	公开
/contests/:id	比赛详情	公开（报名需登录）
/contests/:id/ranking	比赛排名	公开
/submissions	我的提交	公开（仅展示本人记录）
/admin/problems	题目管理	admin / coach
/admin/categories	分类管理	admin / coach
/admin/contests	比赛管理	admin / coach
/admin/users	用户管理	admin

权限通过路由 meta 声明，由 router.beforeEach 统一守卫：

• meta.requiresAdmin：仅 admin 可访问。
• meta.requiresCoach：admin 与 coach 均可访问。
• 未登录时携带 redirect 参数跳转登录页，登录后返回原页面。

布局菜单同样按角色过滤：顶部导航的“后台管理”入口只对 admin/coach 展示，后台侧边菜单按每条路由的 meta 过滤，用户管理仅对 admin 可见。

角色取值：admin（管理员）、coach（教练）、user（普通用户）、guest（未登录）。

状态管理

Pinia 采用 setup 语法 store，并开启 persist 持久化，刷新后登录态与站点配置保留在 localStorage：

• useLoginUserStore（store/user.ts）：loginUser 状态、userId getter、loginSuccess / logoutUser 等 action。
• useMetaStore（store/meta.ts）：站点标题、Logo、后端地址。

判题状态

util/submission.ts 维护提交状态到展示文案的映射（getStatusInfo），覆盖 SUBMITTED、JUDGING、AC、WA、TLE、MLE、RE、CE、SE，并给出对应的 Element Plus 标签类型。

开发约定

• 时间展示统一使用 util/format-time.ts 的 formatTime()（YYYY-MM-DD HH:mm），无效值回退为 -。
• Markdown 渲染统一使用 util/markdown.ts 导出的异步组件 MdEditor / MdViewer（按需加载，避免首屏引入编辑器体积）。
• 组件使用 <script setup lang="ts">，路径引用使用 @/ 别名。
• 提交代码前先跑 npm run build（含 vue-tsc 严格类型检查）。