# 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`