ACMHelper — ICPC 出题 Agent 系统

基于 React 18 + TypeScript 的 ICPC 智能出题平台客户端，配合 Mock 服务与完整技术文档，覆盖从"选难度+选知识点"到"一键发布完整题目"的全链路交互。

项目简介

ACMHelper 是面向 ICPC（国际大学生程序设计竞赛）出题场景的智能辅助平台。系统采用 Client-Server 架构，前端负责用户交互与展示，后端负责业务逻辑、AI Agent 编排与数据持久化。本项目交付的是 客户端应用 + Mock 服务 + 完整技术文档 三部分，可在没有真实后端的情况下，通过 Mock 服务完整体验所有功能。

核心业务流程：

用户选择难度与知识点
    → 题目生成 Agent 生成题目描述（结合知识库 RAG 检索）
    → 自动构造测试数据并通过校验器验证
    → 生成标准程序并对拍验证
    → 撰写题解与知识点分析
    → 用户确认后发布题目到数据库

核心特性

完整客户端：基于 React 18 + TypeScript + Vite 5 构建，开箱即用。
企业级 UI：Ant Design 5 + Tailwind CSS，界面风格统一、支持中文。
智能出题工作台：向导式配置（难度/知识点/知识库/题目类型）+ 工作台实时生成与预览。
代码编辑器：集成 Monaco Editor，支持 C++/Java/Python 多语言高亮。
Markdown 编辑与预览：react-markdown + remark-gfm，支持 GFM 语法与代码高亮。
知识库管理：支持创建/编辑/删除、文档上传、向量化状态跟踪、检索测试。
题目全生命周期：草稿 / 待审核 / 已发布 / 已下架状态流转，支持收藏、导出、版本管理。
测试数据模块：生成器/校验器在线编辑与运行、子任务分组、数据预览与下载。
标程与题解模块：自动生成标程、对拍验证、题解结构化编辑与预览。
管理后台：系统配置、Agent 配置、知识点体系管理、使用统计、健康检查。
Mock 服务：基于 Express 的完整后端模拟，支持 JWT 鉴权、文件上传、异步任务进度模拟。
完整文档：接口文档、后端开发指南、数据库设计、SQL 脚本一站式交付。

技术栈

层面	技术	说明
前端框架	React 18 + TypeScript	组件化开发，类型安全
构建工具	Vite 5	极速 HMR
状态管理	Zustand + TanStack Query	轻量全局状态 + 服务端状态
路由	React Router v6	声明式路由，支持懒加载与守卫
UI 组件库	Ant Design 5	企业级组件库
样式方案	Tailwind CSS + CSS Modules	原子化 + 局部作用域
HTTP 客户端	Axios	拦截器、取消请求
代码编辑器	Monaco Editor	VS Code 同款
Markdown	react-markdown + remark-gfm + rehype-highlight	题面/题解渲染
Mock 服务	Express + CORS + Multer	完整后端行为模拟

目录结构

ACMHelper/
├── doc/                          # 技术文档
│   ├── README.md                 # 文档索引
│   ├── api.md                    # 接口文档
│   ├── backend-guide.md          # 后端开发指南
│   ├── database-design.md        # 数据库设计
│   └── sql/
│       ├── schema.sql            # 建表脚本
│       ├── seed.sql              # 初始数据
│       └── migration.sql         # 迁移脚本
├── mock/                         # Mock 服务
│   ├── server.js                 # 入口
│   ├── data.js                   # 内存数据
│   ├── test.js                   # Mock 服务测试脚本
│   ├── middleware/auth.js        # 鉴权中间件
│   └── routes/                   # 各业务路由
│       ├── auth.js
│       ├── knowledge.js
│       ├── generation.js
│       ├── problem.js
│       ├── testdata.js
│       ├── solution.js
│       └── system.js
├── src/                          # 客户端源码
│   ├── assets/styles/            # 全局样式
│   ├── components/               # 通用与业务组件
│   │   ├── business/             # 业务组件（题目卡片、知识库卡片等）
│   │   ├── common/               # 通用组件（状态标签、空状态、文件上传）
│   │   ├── editor/               # 编辑器组件（代码、Markdown）
│   │   └── layout/               # 布局组件（Header、Sidebar、PageContainer）
│   ├── config/                   # 环境与主题配置
│   ├── pages/                    # 页面
│   │   ├── admin/                # 系统管理
│   │   ├── auth/                 # 登录/注册
│   │   ├── generate/             # 智能出题
│   │   ├── knowledge/            # 知识库
│   │   ├── problem/              # 题目库
│   │   ├── settings/             # 个人设置
│   │   ├── Dashboard.tsx         # 工作台
│   │   └── NotFound.tsx          # 404
│   ├── router/                   # 路由与守卫
│   ├── services/                 # API 服务层
│   ├── stores/                   # Zustand 状态
│   ├── types/                    # TypeScript 类型定义
│   ├── utils/                    # 工具函数
│   ├── App.tsx
│   └── main.tsx
├── .env.development              # 开发环境变量
├── .env.production               # 生产环境变量
├── index.html
├── package.json
├── tailwind.config.js
├── postcss.config.js
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── setup.bat                      # CMD 环境配置工具（绕过 PowerShell 执行策略）
└── ICPC 出题 Agent 系统 — 完整技术设计文档.md

快速开始

环境要求

Node.js >= 18.0.0
npm >= 9.0.0（或 pnpm / yarn）

安装与运行

# 1. 安装依赖
npm install

# 2. 启动开发服务（同时启动客户端 + Mock 服务）
npm run dev

启动成功后：

客户端：http://localhost:5173
Mock 服务：http://localhost:3001
API 健康检查：http://localhost:3001/api/v1/system/health

仅启动客户端（已有真实后端）

npm run dev:client

仅启动 Mock 服务

npm run mock

运行 Mock 服务测试

# 先启动 Mock 服务（新终端窗口）
npm run mock

# 再运行测试
npm run test:mock

测试脚本（mock/test.js）覆盖全部 7 大模块、80+ 断言，验证：

成功响应（登录、CRUD、生成、导出等）
错误响应（401 未登录、403 无权限、404 不存在、409 冲突、400 参数错误）
鉴权流程（Token 校验、角色权限、公开接口）

PowerShell 执行策略受限时

如果 PowerShell 执行策略阻止 npm 命令运行，可直接双击 setup.bat 启动配置工具，在 CMD 环境中完成安装、启动和测试。

环境变量

项目根目录提供两套环境变量文件：

.env.development

VITE_API_BASE_URL=/api/v1
VITE_MOCK_ENABLED=true

.env.production

VITE_API_BASE_URL=/api/v1
VITE_MOCK_ENABLED=false

变量	说明
`VITE_API_BASE_URL`	API 基础路径，默认 `/api/v1`
`VITE_MOCK_ENABLED`	是否启用 Mock 标识（前端逻辑判断用）

开发环境下，Vite 已配置代理，将 /api 转发到 http://localhost:3001，无需处理跨域。

可用脚本

命令	说明
`npm run dev`	并行启动客户端（5173）与 Mock 服务（3001）
`npm run dev:client`	仅启动客户端
`npm run mock`	仅启动 Mock 服务
`npm run build`	类型检查 + 生产构建，输出到 `dist/`
`npm run preview`	预览生产构建产物
`npm run lint`	ESLint 代码检查
`npm run format`	Prettier 格式化源码
`npm run test:mock`	运行 Mock 服务测试脚本（需先启动 Mock 服务）

功能模块

1. 用户认证

登录 / 注册 / 退出登录
Access Token + Refresh Token 双令牌机制
路由守卫 RequireAuth 与角色守卫 RequireRole
个人信息修改、密码修改、头像上传

2. 工作台（Dashboard）

快捷操作入口（智能出题、知识库、题目库、系统管理）
统计概览（题目数、知识库数、出题会话数、Token 消耗）
难度分布可视化
最近创建题目列表

3. 知识库管理

知识库列表（搜索、筛选、排序、分页）
知识库详情（基本信息、统计、文档列表）
文档上传（拖拽上传、批量上传）
文档在线预览（Markdown 渲染 / 代码高亮）
文档编辑与删除
向量化状态跟踪
检索测试

4. 智能出题

向导式参数配置：难度等级、知识点标签、关联知识库、题目类型、语言
出题工作台：题目生成、预览、编辑、重新生成
生成进度展示（题目生成 → 测试数据 → 标程 → 题解）
生成历史版本

5. 测试数据

数据生成器在线编辑（C++/Python）
生成器运行与批量生成
校验器编辑与运行
数据预览与下载（zip 打包）
子任务分组与分值配置

6. 标程与题解

自动生成标程（多语言）
标程在线编辑与运行
标程对拍验证
题解结构化编辑（题目大意、思路分析、算法详解、复杂度分析、代码实现）
题解 Markdown 预览

7. 题目库

题目列表（搜索、按难度/标签/状态筛选、排序、分页）
题目详情（题面、数据、标程、题解一站式查看）
题目编辑、删除（软删除）
题目发布（含发布前完整性检查）
题目收藏
题目导出（Markdown / JSON）
题目版本管理

8. 系统管理（仅管理员）

系统配置：LLM 模型、Embedding、向量数据库、对象存储、沙箱
Agent 配置：6 种 Agent 的 Prompt 与参数
知识点体系管理：树形结构增删改查
使用统计：出题数、Token 消耗、API 调用
健康检查：各服务组件状态

Mock 服务

Mock 服务基于 Express 实现，完整模拟后端 API 行为，是客户端开发与测试的核心依赖。

特性

完整 API 覆盖：8 大模块全部接口均有 Mock 实现
JWT 鉴权模拟：Access Token / Refresh Token 双令牌
角色权限：admin / user / guest 三种角色
文件上传：基于 Multer，支持拖拽上传与批量上传
异步任务模拟：出题会话、向量化等异步流程通过状态机模拟进度
统一响应格式：与接口文档完全一致
错误码模拟：支持成功与各类错误响应（401/403/404/409/429/500）

启动

npm run mock
# 或通过 npm run dev 同时启动客户端与 Mock

验证

启动后访问 http://localhost:3001，应返回：

{
  "code": 0,
  "message": "success",
  "data": {
    "name": "ACMHelper Mock Server",
    "version": "1.0.0",
    "apiPrefix": "/api/v1",
    "docs": "/api/v1/system/health"
  }
}

测试账号

Mock 服务内置以下测试账号：

角色	用户名	密码	邮箱	权限
管理员	`admin`	`admin123`	admin@acmhelper.com	全部功能
普通用户	`user`	`user123`	user@acmhelper.com	自有数据 + 出题

生产环境部署真实后端时，初始管理员账号见 doc/README.md。

路由与权限

路径	页面	权限
`/login`	登录	公开
`/register`	注册	公开
`/`	工作台	需登录
`/generate`	出题向导	需登录
`/generate/:sessionId`	出题工作台	需登录
`/problems`	题目列表	需登录
`/problems/:id`	题目详情	需登录
`/knowledge`	知识库列表	需登录
`/knowledge/:id`	知识库详情	需登录
`/settings`	个人设置	需登录
`/admin/*`	系统管理	需登录 + admin 角色
`*`	404	公开

文档导航

所有技术文档位于 doc/ 目录：

文档	说明
接口文档	8 大模块全部接口的路径、方法、请求参数、响应格式
后端开发指南	架构模式、最佳实践、6 种 Agent 设计、安全与部署
数据库设计	ER 关系图、19 张表字段说明、索引设计
建表脚本	数据库与表结构创建
初始数据	管理员、系统配置、知识点标签体系
迁移脚本	版本记录与常用迁移模板

数据库初始化

部署真实后端时，按以下顺序执行 SQL 脚本：

# 1. 创建数据库与表结构
mysql -u root -p < doc/sql/schema.sql

# 2. 插入初始数据
mysql -u root -p acmhelper < doc/sql/seed.sql

# 3. 记录迁移版本
mysql -u root -p acmhelper < doc/sql/migration.sql

详细说明见 doc/README.md。

开发约定

代码规范

TypeScript 严格模式
ESLint + Prettier 统一代码风格
组件采用函数式组件 + Hooks
状态管理：全局状态用 Zustand，服务端状态用 TanStack Query
API 调用统一通过 src/services 层封装，禁止在组件中直接调用 axios

目录约定

components/common：与业务无关的通用组件
components/business：业务组件
components/editor：编辑器类组件
components/layout：布局组件
pages：页面组件，按模块分子目录
services：API 服务层，按模块拆分
stores：Zustand 状态
types：TypeScript 类型定义，按模块拆分

API 约定

统一前缀：/api/v1
统一响应格式：{ code, message, data, timestamp }
鉴权：Authorization: Bearer {token}
分页参数：page（从 1 开始）、pageSize（默认 20）
排序参数：sortBy、sortOrder（asc/desc）

详见接口文档。

构建与部署

生产构建

npm run build

构建产物输出到 dist/ 目录，包含静态资源与入口 HTML。

部署方式

静态托管：将 dist/ 部署到 Nginx / Vercel / Netlify 等静态托管服务
反向代理：Nginx 配置反向代理，将 /api 转发到真实后端服务

Nginx 参考配置：

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    # SPA 路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://backend-server:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

常见问题

1. PowerShell 执行策略阻止脚本运行

在 Windows PowerShell 中运行 npm 脚本时，可能遇到执行策略限制。解决方案：

方案一：直接双击 setup.bat，在 CMD 环境中完成所有操作（安装、启动、测试）。

方案二：以管理员身份运行 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

方案三：使用 CMD 终端（cmd.exe）运行 npm 命令，CMD 不受 PowerShell 执行策略限制。

2. 端口被占用

客户端默认端口：5173
Mock 服务默认端口：3001

如需修改端口，编辑 vite.config.ts（客户端）与 mock/server.js（Mock 服务）。

3. Mock 服务无法启动

确认 3001 端口未被占用，且已执行 npm install 安装依赖。Mock 服务依赖 express、cors、multer，已包含在 devDependencies 中。

4. 接口返回 401

检查请求头是否携带 Authorization: Bearer {token}
Token 是否过期（Access Token 模拟为长期有效，真实环境为 2 小时）
使用正确的测试账号登录获取新 Token

5. 文件上传失败

Mock 服务对单文件大小有限制，如需上传大文件，修改 mock/server.js 中的 express.json({ limit }) 与对应路由的 multer 配置。

许可证

本项目仅供学习与内部使用。

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.idea		.idea
.trae/specs		.trae/specs
dist		dist
doc		doc
gateway		gateway
mock		mock
public		public
src		src
.env.development		.env.development
.env.production		.env.production
.gitignore		.gitignore
ICPC 出题 Agent 系统 — 完整技术设计文档.md		ICPC 出题 Agent 系统 — 完整技术设计文档.md
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
setup.bat		setup.bat
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.node.tsbuildinfo		tsconfig.node.tsbuildinfo
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.d.ts		vite.config.d.ts
vite.config.js		vite.config.js
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation