feat: rebuild CSP practice workflow, UX and automation

docs/API参考.md

@@ -0,0 +1,142 @@
+# API 参考（v1）
+
+统一前缀：`/api/v1`
+
+> Docker/生产推荐通过前端同域反代访问：`/admin139/api/v1/...`
+
+## 通用约定
+
+- 鉴权头：`Authorization: Bearer <token>`
+- 成功响应：`{ "ok": true, "data": ... }`（Auth 接口除外）
+- 失败响应：`{ "ok": false, "error": "..." }`
+
+---
+
+## 1) Auth
+
+### `POST /auth/register`
+请求：
+```json
+{ "username": "alice", "password": "password123" }
+```
+响应：
+```json
+{ "ok": true, "user_id": 1, "token": "...", "expires_at": 1730000000 }
+```
+
+### `POST /auth/login`
+请求同上，响应同上。
+
+---
+
+## 2) 用户与排行榜
+
+### `GET /me`（需鉴权）
+返回当前用户信息。
+
+### `GET /leaderboard/global?limit=100`
+返回全站 rating 排行。
+
+---
+
+## 3) 题库
+
+### `GET /problems?q=&tag=&difficulty=&page=&page_size=`
+返回题目列表。
+
+### `GET /problems/:id`
+返回题目详情。`Problem` 结构包含：
+
+- `statement_url`：原始 PDF 链接
+- `llm_profile_json`：固定 JSON 字符串（`title/difficulty/answer/explanation/knowledge_points/tags/...`）
+
+---
+
+## 4) 提交与在线运行
+
+### `POST /problems/:id/submit`（需鉴权）
+请求：
+```json
+{
+  "language": "cpp",
+  "code": "#include <bits/stdc++.h> ...",
+  "contest_id": 1
+}
+```
+- `contest_id` 可选；若提交到比赛，需已报名且比赛进行中。
+
+### `GET /submissions?user_id=&problem_id=&contest_id=&page=&page_size=`
+返回提交列表。
+
+### `GET /submissions/:id`
+返回提交详情（含代码、编译日志、运行日志）。
+
+### `POST /run/cpp`
+请求：
+```json
+{ "code": "...", "input": "1 2\n" }
+```
+返回：运行状态、stdout/stderr、compile_log。
+
+---
+
+## 5) 错题本
+
+### `GET /me/wrong-book`（需鉴权）
+返回当前用户错题本。
+
+### `PATCH /me/wrong-book/:problemId`（需鉴权）
+请求：
+```json
+{ "note": "复盘思路" }
+```
+
+### `DELETE /me/wrong-book/:problemId`（需鉴权）
+删除错题项。
+
+---
+
+## 6) 模拟竞赛
+
+### `GET /contests`
+返回比赛列表。
+
+### `GET /contests/:id`
+返回比赛详情与题单；若请求带 token，还会返回 `registered`。
+
+### `POST /contests/:id/register`（需鉴权）
+报名比赛。
+
+### `GET /contests/:id/leaderboard`
+比赛排行榜（按 solved desc, penalty asc）。
+
+---
+
+## 7) 学习知识库
+
+### `GET /kb/articles`
+返回知识库文章列表。
+
+### `GET /kb/articles/:slug`
+返回文章详情与关联题目。
+
+---
+
+## 8) 题库导入任务（PDF + LLM）
+
+### `GET /import/jobs/latest`
+返回最近一次导入任务及运行状态（`runner_running`）。
+
+### `GET /import/jobs/:id`
+返回指定导入任务详情。
+
+### `GET /import/jobs/:id/items?status=&page=&page_size=`
+返回任务明细（每个 PDF 的处理状态、结果或错误）。
+
+### `POST /import/jobs/run`
+手动触发导入任务（若已有运行中的任务会返回 `409`）。
+
+请求体（可选）：
+```json
+{ "clear_all_problems": true }
+```