feat: rebuild CSP practice workflow, UX and automation

2026-02-13 15:49:05 +08:00
--- a/README.md
+++ b/README.md
@@ -1,45 +1,148 @@
-# CSP 在线练习 / 模拟竞赛平台（前后端分离）
+# CSP 在线学习与竞赛平台

- 前端：Next.js（目录：`frontend/`）
- 后端：C++20 + Drogon + SQLite（目录：`backend/`）
+面向 OI/CSP 学习场景的全栈 Web 系统（前后端分离）：

-## 1. 本地开发（Ubuntu 24.04）
+- 前端：Next.js 16（App Router, TypeScript）
+- 后端：C++20 + Drogon + SQLite
+- 部署：Docker Compose

-### 1.1 安装依赖
+核心能力：
+
+- 用户注册/登录（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
-```
-
-### 1.2 构建与运行后端
-
-```bash
 cmake -S . -B build -G Ninja
 cmake --build build
 ctest --test-dir build -V
-
 ./build/backend/csp_server
-# http://localhost:8080/api/health
 ```

-### 1.3 运行前端
+前端：

 ```bash
-cd frontend
-npm run dev
-# http://localhost:3000
+npm --prefix frontend ci
+npm --prefix frontend run dev
 ```

 ## 2. 目录结构

- `backend/` 后端 C++ 服务与测试
- `frontend/` 前端 Next.js
- `docs/` 开发文档（设计、接口、部署等）
- `scripts/` 一键脚本
+- `backend/`：Drogon 后端（控制器/服务/领域模型/SQLite）
+- `frontend/`：Next.js 前端
+- `docs/`：架构、API、数据库、测试、部署文档
+- `scripts/`：开发与初始化脚本

-## 3. 当前状态
+## 3. API 入口说明

-已完成工程骨架：
- 后端：Drogon 服务启动 + `/api/health`
- 后端：Catch2 单测接入（`ctest` 可跑）
- 前端：Next.js 工程初始化
+生产/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`