目录
[1. 代码仓库](#1. 代码仓库)
[2. 环境准备](#2. 环境准备)
[2.1 项目创建](#2.1 项目创建)
[2.2 VS Code 连接到 Linux 主机](#2.2 VS Code 连接到 Linux 主机)
[3. 需求梳理](#3. 需求梳理)
[3.1 git 提交](#3.1 git 提交)
[4. 安装依赖](#4. 安装依赖)
1. 代码仓库
cpp-oj-vibecoding-wsj: 基于Vibe Coding的OJ平台（wsj）
项目背景
通过VibeCoding的方式，构建一个仿leetcode的OJ平台。
目前leetcode是一个功能非常丰富的网站了。我们只实现其中的核心功能。
- 题目列表
- 题目详情
- 做题判题
- 题目的增加/删除
- 普通用户/管理员用户
页面效果如下：
| 分类 | 技术要点 | 简介 |
|---|---|---|
| 开发工具 | OpenCode | CLI风格的 AI Agent 开发工具 |
| MinMax 2.7 | 国产大语言模型 | |
| VS Code | 代码编辑器 | |
| 后端 | C++17 | C++语言企业主流版本 |
| cpp-httplib | 轻量级 C++HTTP 框架 | |
| 进程/线程/锁/资源限制等相关控制 | Linux 原生 API | |
| MySQL 8.0 | 数据库 | |
| 自主实现数据库连接池 | 数据库连接池 | |
| 自主实现日志库 | 日志库 | |
| 自主实现基于 yaml 的配置管理 | 配置库 | |
| 自主实现会话管理机制 | 会话管理 | |
| bcrypt | 密码加密机制 | |
| CMake | C++主流项目构建工具 | |
| 前端 | HTML/CSS/JavaScript | 前端开发基础方案 |
| ace.js | 前端代码编辑器 | |
| ui-ux-pro-max skill | 页面设计 AI skill | |
| 测试 | google test | 单元测试方案 |
| LLM + curl | 接口自动化测试方案 | |
| python + requests | 接口自动化测试方案 | |
| LLM + playwright-cli | web 自动化测试方案 |
2. 环境准备
2.1 项目创建
在 gitee上创建项目，并 clone 到本地，Vibe Coding 过程中，git 的使用是非常重要的一环，通过git可以随时回退已有的修改。
2.2 VS Code 连接到 Linux 主机
参考：vscode连接云服务器_vscode连接云服务器csdn-CSDN博客
3. 需求梳理
通过提示词引导AI对用户 "深度访谈" (反问)，进一步强化需求。
你现在是资深产品架构师 + 技术负责⼈。
我的初始需求是：我想搭建⼀个仿 leetcode 的 OJ 项⽬. 后端采⽤ C++ (cpp-httplib), 前端
采⽤原⽣ HTML + CSS + JS
规则（必须严格遵守）：
不要直接写代码或⽣成⽅案。
先使⽤ AskUserQuestion ⼯具（或直接输出问题列表）对我进⾏**深度访谈**，像 Socratic
提问法⼀样挖掘细节。
- 必须覆盖以下维度（每个维度⾄少问 1-2 个具体问题）：
业务⽬标和成功标准
技术栈/架构选型及理由
⾮功能需求（性能、可扩展性、安全、成本等）
边缘案例、异常处理、⽤⼾流程
UI/UX 或 API 边界
潜在⻛险、权衡取舍
每轮只问 3-5 个最关键的问题，等待我回答后继续追问，直到需求完整。
当我确认"规格已完整"时，再输出完整的 SPEC.md（包含需求、架构图、TODO 清单、验收标
准）。
开始访谈吧。
- 给 AI 赋予身份
- 给出需求
- 指定技术栈
- 约束规则
- 让 AI 先向自己提问，直到需求完整
- 最后总结出一个 SPEC.md （规格）文档
访谈效果形如：
大约经过二十多个问题后，OpenCode 认为自己已经理解清楚，开始整理 SPEC.md，此时，spec文档已经完成，这里包含了目录结构划分，页面划分，数据库设计，api接口设计，里程碑等等内容。
bash
# OJ 系统规格说明书
## 1. 需求概述
| 维度 | 规格 |
|------|------|
| **业务目标** | 教学/训练平台 |
| **目标用户规模** | 1-20 人同时在线 |
| **核心功能** | 题目列表、题目描述、测试用例、在线编辑/编译/运行/返回结果、题目管理后台 |
| **角色** | 普通用户（做题）、管理员（增删题目） |
| **语言支持** | 仅 C++ |
| **题目来源** | 管理员手动导入 |
| **执行隔离** | 进程级隔离（基础） |
| **部署形态** | 单机部署 |
| **性能要求** | <500ms 响应 |
| **持久化** | 题目存 MySQL，提交记录/代码暂不持久化 |
---
## 2. 系统架构
```
┌─────────────────────────────────────────────────┐
│ 前端 (Browser) │
│ HTML + CSS + JS (原生，无框架) │
└──────────────────┬──────────────────────────────┘
│ HTTP REST
┌──────────────────▼──────────────────────────────┐
│ C++ Backend │
│ cpp-httplib (HTTP) │
│ ┌─────────────┬─────────────┬────────────────┐ │
│ │ 题目服务 │ 代码执行服务 │ 认证/权限服务 │ │
│ │ (MySQL) │ (fork/popen)│ (Session) │ │
│ └─────────────┴─────────────┴────────────────┘ │
└─────────────────────────────────────────────────┘
```
---
## 2.1 项目目录结构
```
cpp-oj-vibecoding-teach/
├── SPEC.md
├── README.md
├── CMakeLists.txt # 后端构建配置
├── config/
│ └── config.yaml # 配置文件
├── database/
│ └── init.sql # 数据库初始化脚本
├── src/
│ ├── main.cc # 程序入口
│ ├── server/
│ │ ├── server.cc # HTTP 服务器
│ │ ├── router.cc # 路由处理
│ │ └── router.h
│ ├── handler/
│ │ ├── problem_handler.cc # 题目相关 API
│ │ ├── submit_handler.cc # 代码提交执行
│ │ ├── auth_handler.cc # 登录注册
│ │ └── admin_handler.cc # 管理接口
│ ├── service/
│ │ ├── problem_service.cc # 题目业务逻辑
│ │ ├── executor_service.cc # 代码执行服务
│ │ └── auth_service.cc # 认证业务逻辑
│ ├── model/
│ │ ├── problem.cc # 题目数据模型
│ │ ├── test_case.cc # 测试用例模型
│ │ └── user.cc # 用户模型
│ ├── db/
│ │ ├── connection_pool.cc # MySQL 连接池
│ │ └── connection_pool.h
│ └── utils/
│ ├── logger.cc # 日志工具
│ ├── logger.h
│ ├── config.cc # 配置加载
│ └── config.h
├── public/
│ ├── index.html # 大屏落地页
│ ├── problem_list.html # 题目列表页
│ ├── login.html # 登录页
│ ├── register.html # 注册页
│ ├── problem.html # 题目详情页
│ ├── admin.html # 管理后台页
│ ├── css/
│ │ └── style.css # 样式文件
│ └── js/
│ ├── api.js # API 调用封装
│ ├── auth.js # 认证状态管理
│ ├── problem.js # 题目列表逻辑
│ ├── problem_detail.js # 题目详情逻辑
│ ├── submit.js # 提交执行逻辑
│ └── admin.js # 管理后台逻辑
└── tests/
├── unit/
│ ├── problem_test.cc
│ └── executor_test.cc
└── integration/
└── api_test.cc
```
---
## 3. API 边界
### 3.1 公开接口（普通用户）
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/problems` | 题目列表 |
| GET | `/api/problems/:id` | 题目详情（含描述/用例） |
| POST | `/api/submit` | 提交代码执行 |
| POST | `/api/login` | 登录 |
| POST | `/api/logout` | 登出 |
| POST | `/api/register` | 注册新用户 |
### 3.2 管理接口（管理员）
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/admin/problems` | 新增题目 |
| DELETE | `/api/admin/problems/:id` | 删除题目 |
---
## 4. 前端页面
| 页面 | 路径 | 说明 | 访问权限 |
|------|------|------|----------|
| 落地页 | `/index.html` | 大屏展示页，含系统介绍、统计信息、功能特性 | 所有人 |
| 登录页 | `/login.html` | 用户名 + 密码登录，登录成功跳转题目列表 | 所有人 |
| 注册页 | `/register.html` | 用户名 + 密码 + 确认密码，注册成功跳转登录页 | 所有人 |
| 题目列表页 | `/problem_list.html` | 展示所有题目（编号、标题、难度），点击进入详情 | 已登录用户 |
| 题目详情页 | `/problem.html?id=:id` | 题目描述 + 在线代码编辑器 + 提交按钮 + 结果展示 | 已登录用户 |
| 后台管理页 | `/admin.html` | 新增题目表单、题目列表（含删除操作） | 管理员 |
---
## 5. 数据模型 (MySQL)
```sql
-- 题目表
CREATE TABLE problems (
id INT PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(255) NOT NULL,
difficulty ENUM('Easy','Medium','Hard') NOT NULL,
content TEXT NOT NULL, -- 题目描述 (Markdown)
template TEXT, -- 代码模板
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 测试用例表 (与题目 1:N 关联)
CREATE TABLE test_cases (
id INT PRIMARY KEY AUTO_INCREMENT,
problem_id INT NOT NULL,
input TEXT NOT NULL, -- 输入数据
expected TEXT NOT NULL, -- 期望输出
position INT NOT NULL DEFAULT 0, -- 排序序号
FOREIGN KEY (problem_id) REFERENCES problems(id) ON DELETE CASCADE
);
-- 用户表
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(64) UNIQUE NOT NULL,
password VARCHAR(128) NOT NULL, -- bcrypt 哈希
role ENUM('user','admin') DEFAULT 'user',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
---
## 5.1 数据库配置
| 配置项 | 值 |
|--------|-----|
| 数据库类型 | MySQL 8.0 |
| 数据库名 | `oj_system` |
| 字符集 | utf8mb4 |
| 连接用户 | 同系统用户名（使用 `auth_socket` 插件认证） |
| 初始化脚本 | `database/init.sql` |
### 初始化步骤
```bash
# 1. 创建 MySQL 用户（需 sudo 权限）
sudo mysql -e "CREATE USER IF NOT EXISTS '你的用户名'@'localhost' IDENTIFIED WITH auth_socket; GRANT ALL ON *.* TO '你的用户名'@'localhost';"
# 2. 执行初始化脚本
mysql -u 你的用户名 < database/init.sql
```
---
## 6. TODO 清单
### Phase 1 - 基础设施
- [ ] 项目目录结构搭建
- [ ] MySQL 数据库初始化脚本
- [ ] cpp-httplib 基础 HTTP 服务
- [ ] 配置管理
- [ ] 日志封装
- [ ] 数据库连接池实现
### Phase 2 - 题目模块
- [ ] 题目数据模型映射
- [ ] 题目 CRUD API（管理员）
- [ ] 题目列表/详情 API（用户）
### Phase 3 - 代码执行模块
- [ ] C++ 代码编译（fork + g++）
- [ ] 代码运行 + 超时控制
- [ ] 结果比较（stdout vs expected）
- [ ] 进程级资源限制（CPU/内存）
### Phase 4 - 登录注册模块
- [ ] Session/Cookie 认证机制
- [ ] 用户注册 API（用户名唯一性校验）
- [ ] 用户登录 API
- [ ] 用户退出登录
### Phase 5 - 前端
- [ ] 登录页面 (`/login.html`)
- [ ] 注册页面 (`/register.html`)
- [ ] 题目列表页面
- [ ] 题目详情页面（描述 + 在线编辑器）
- [ ] 提交结果展示
- [ ] 管理后台（新增/删除题目）
- [ ] 大屏落地页
### Phase 6 - 安全与部署
- [ ] 管理员权限校验
- [ ] 用户认证（Session/Cookie）
- [ ] 基础输入校验
- [ ] 部署文档, README文档
---
## 7. 验收标准
| # | 标准 |
|---|------|
| 1 | 管理员可成功新增题目并在前端列表看到 |
| 2 | 普通用户可查看题目、在线编辑 C++ 代码并提交 |
| 3 | 代码在 <5s 超时限制内执行并返回结果 |
| 4 | 正确判断 AC/WA/TLE/RE 并反馈给用户 |
| 5 | 管理员可删除题目 |
| 6 | 普通用户无法访问管理接口 |
| 7 | 部署文档完整，单机可运行 |
| 8 | 页面无需刷新可完成一次完整提交 |
| 9 | 新用户可注册账号并登录 |
---
## 8. 潜在风险与权衡
| 风险 | 权衡 |
|------|------|
| 进程级隔离安全性低（恶意代码可能影响系统） | 小规模教学场景可接受，建议后期升级容器级隔离 |
| 代码不持久化，重启丢失 | 当前阶段明确知晓，后续按需加 Redis/DB |
| <500ms 在代码编译时难以保证 | 放宽至 5s 内返回，或预编译缓存优化 |
| MySQL 单机部署无主从 | 小规模可接受，注意备份 |3.1 git 提交
此处的SPEC中生成的内容不一定就符合我们的预期，我们还需要仔细检查，和LLM反复沟通，直到调整成自己期望的样子。每次调整一个版本，都可以提交一次git。
4. 安装依赖
可以让AI帮我们梳理出都有哪些依赖需要安装，并给出安装命令。
@SPEC.md 请根据文档中设计好的方案，梳理一下有哪些依赖需要进行安装，并给出对应的安装命令 （假定当前系统是一个空白的 ubuntu 24.04），内容写入到 /dependence.md 中
按照给出的命令，在root下逐个安装即可。
虽然opencode 也有安装依赖的能力，但是我们知道，安装依赖通常需要root权限。如果赋予opencode root权限，在后续执行过程中，万一opencode 执行了一些"极端命令"（比如rm -rf / ），那么后果就不堪设想了。因此，我们选择手动安装依赖。
bash
# OJ 系统依赖说明
## 系统级依赖
```bash
# 构建工具
sudo apt update
sudo apt install -y cmake g++ make
# MySQL 服务器
sudo apt install -y mysql-server
```
## C++ 库依赖
```bash
# MySQL Connector/C++
sudo apt install -y libmysqlclient-dev
# YAML 配置文件解析
sudo apt install -y libyaml-cpp-dev
```
## 一键安装命令
```bash
sudo apt update && sudo apt install -y \
cmake g++ make \
mysql-server \
libmysqlclient-dev \
libyaml-cpp-dev \
```
## 验证安装
```bash
g++ --version
cmake --version
mysql --version
```
## 依赖说明
| 依赖 | 用途 |
|------|------|
| cmake | C++ 项目构建工具 |
| g++ | C++ 编译器，用于编译后端代码和用户提交的代码 |
| make | 构建辅助工具 |
| mysql-server | 数据库服务，存储题目和用户数据 |
| libhttplib-dev | C++ HTTP 库，用于构建 REST API 服务 |
| libmysqlclient-dev | MySQL 客户端库，用于连接数据库 |
| libyaml-cpp-dev | YAML 配置文件解析库 |
| libbcrypt-dev | bcrypt 密码哈希库，用于用户密码加密 |