149 行
4.3 KiB
Markdown
149 行
4.3 KiB
Markdown
# CSP 在线学习与竞赛平台
|
||
|
||
面向 OI/CSP 学习场景的全栈 Web 系统（前后端分离）：
|
||
|
||
- 前端：Next.js 16（App Router, TypeScript）
|
||
- 后端：C++20 + Drogon + SQLite
|
||
- 部署：Docker Compose
|
||
|
||
核心能力：
|
||
|
||
- 用户注册/登录（Bearer Token）
|
||
- 题库检索、题面查看、在线提交评测
|
||
- 日常练习提交记录
|
||
- 错题本（自动沉淀 + 手动备注）
|
||
- 模拟竞赛（报名、题单、排行榜）
|
||
- 学习知识库（文章 + 题目关联）
|
||
- 在线 C++ 编写/编译/运行调试
|
||
- 题目页 Markdown 语义渲染（数学公式 / 图片本地缓存）
|
||
- 代码草稿保存、试运行、异步多解题解生成
|
||
- MCP JSON-RPC 接口（供 Agent 调用）
|
||
- Swagger API 文档页面
|
||
|
||
## 1. 快速开始
|
||
|
||
### 1.1 Docker 一键启动（推荐）
|
||
|
||
```bash
|
||
git clone ssh://git@git.hk.hao.work:2222/hao/csp.git
|
||
cd csp
|
||
docker compose up -d --build
|
||
```
|
||
|
||
访问：
|
||
|
||
- 前端：`http://<你的IP>:7888/`
|
||
- 后端健康检查（经前端反代）：`http://<你的IP>:7888/admin139/api/health`
|
||
|
||
### 1.2 本机开发启动
|
||
|
||
```bash
|
||
./scripts/bootstrap_ubuntu.sh
|
||
cmake -S . -B build -G Ninja
|
||
cmake --build build
|
||
ctest --test-dir build -V
|
||
./build/backend/csp_server
|
||
```
|
||
|
||
前端：
|
||
|
||
```bash
|
||
npm --prefix frontend ci
|
||
npm --prefix frontend run dev
|
||
```
|
||
|
||
## 2. 目录结构
|
||
|
||
- `backend/`：Drogon 后端（控制器/服务/领域模型/SQLite）
|
||
- `frontend/`：Next.js 前端
|
||
- `docs/`：架构、API、数据库、测试、部署文档
|
||
- `scripts/`：开发与初始化脚本
|
||
|
||
## 3. API 入口说明
|
||
|
||
生产/Compose 场景建议统一通过前端同域反代访问后端：
|
||
|
||
- 浏览器访问：`/admin139/...`
|
||
- 例如：`/admin139/api/v1/problems`
|
||
|
||
本地后端直连调试时可用 `http://localhost:8080`。
|
||
|
||
详细 API：见 `docs/API参考.md`，或直接访问 Swagger 页面 `/api-docs`（规范地址 `/admin139/api/openapi.json`）。
|
||
|
||
## 4. 测试与 TDD
|
||
|
||
- 后端测试框架：Catch2
|
||
- 测试命令：`ctest --test-dir build -V`
|
||
- 当前覆盖：迁移、鉴权、题库、提交评测、错题本、竞赛、知识库、HTTP 控制器核心路径
|
||
|
||
详见：`docs/测试与TDD.md`。
|
||
|
||
## 5. 端口与外部访问
|
||
|
||
- 对外端口：`7888 -> frontend:3000`
|
||
- 默认监听：`0.0.0.0:7888`
|
||
- 若需排查网络访问/Clash 影响，见 `docs/Docker部署.md` 的“故障排查”章节。
|
||
|
||
## 6. 题库初始化（默认：洛谷 CSP J/S）
|
||
|
||
默认导入脚本：`scripts/import_luogu_csp.py`，按洛谷标签抓取 CSP-J / CSP-S / NOIP 题目，结果写入 `problems` / `problem_tags`，并将任务进度写入 `import_jobs` / `import_job_items`。
|
||
|
||
```bash
|
||
python3 scripts/import_luogu_csp.py \
|
||
--db-path /var/lib/docker/volumes/csp_csp_data/_data/csp.db \
|
||
--workers 3 \
|
||
--clear-all-problems
|
||
```
|
||
|
||
前端 `/imports` 页面可查看导入状态和明细；后端容器重启后默认自动执行一次（可通过环境变量关闭）。
|
||
|
||
`.env` / `docker-compose` 常用参数：
|
||
|
||
```env
|
||
OI_IMPORT_AUTO_RUN=true
|
||
OI_IMPORT_WORKERS=3
|
||
OI_IMPORT_SCRIPT_PATH=/app/scripts/import_luogu_csp.py
|
||
OI_IMPORT_CLEAR_ALL_PROBLEMS=true
|
||
```
|
||
|
||
如果你还要使用旧的 PDF + LLM 导入流程，可手动运行 `scripts/import_winterant_oi.py`。
|
||
|
||
## 7. CSP-J 题目自动生成（RAG + 去重）
|
||
|
||
提供脚本：`scripts/generate_cspj_problem_rag.py`，流程为：
|
||
|
||
1. 爬取洛谷 CSP-J/NOIP 入门题名作为外部语料
|
||
2. 融合本地 `problems` 题库做关键词压缩（RAG 上下文）
|
||
3. 调用 LLM 生成新题 JSON
|
||
4. 生成前+入库前各做一次相似题检索，疑似重复则跳过
|
||
|
||
手动执行一次（默认 1 题）：
|
||
|
||
```bash
|
||
python3 scripts/generate_cspj_problem_rag.py \
|
||
--db-path /var/lib/docker/volumes/csp_csp_data/_data/csp.db \
|
||
--count 1
|
||
```
|
||
|
||
容器默认会在后端启动时自动尝试生成 1 题（可通过环境变量关闭）。当同时开启自动导入时，会等待导入完成后再触发生题，避免被清库流程覆盖：
|
||
|
||
```env
|
||
CSP_GEN_AUTO_RUN=true
|
||
CSP_GEN_COUNT=1
|
||
CSP_GEN_WAIT_FOR_IMPORT=true
|
||
```
|
||
|
||
## 8. MCP 接口
|
||
|
||
- 入口：`POST /admin139/api/v1/mcp`
|
||
- 支持方法：`initialize`、`tools/list`、`tools/call`
|
||
- 内置工具：`health`、`list_problems`、`get_problem`、`run_cpp`、`generate_cspj_problem`
|
||
|
||
## 9. 文档索引
|
||
|
||
- `docs/平台总体设计.md`
|
||
- `docs/数据库设计.md`
|
||
- `docs/API参考.md`
|
||
- `docs/测试与TDD.md`
|
||
- `docs/Docker部署.md`
|