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 一键启动（推荐）

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 本机开发启动

./scripts/bootstrap_ubuntu.sh
cmake -S . -B build -G Ninja
cmake --build build
ctest --test-dir build -V
./build/backend/csp_server

前端：

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。

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 常用参数：

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

6.1 本地 PDF + RAG + LLM 扩充题库（CSP-J/S）

/imports 页面支持切换到 local_pdf_rag 模式：从本地 PDF 抽取文本做 RAG，调用 LLM 生成 CSP-J/S 题目，并按现有题库相似度去重，跳过雷同题目，直到目标题量（如 5000）。

默认目录：/data/local_pdfs（Compose 已挂载 ./data/local_pdfs:/data/local_pdfs），建议先把 PDF 放到该目录。

如果你还要使用旧的 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 题）：

python3 scripts/generate_cspj_problem_rag.py \
  --db-path /var/lib/docker/volumes/csp_csp_data/_data/csp.db \
  --count 1

容器默认会在后端启动时自动尝试生成 1 题（可通过环境变量关闭）。当同时开启自动导入时，会等待导入完成后再触发生题，避免被清库流程覆盖：

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