csp/docs/API参考.md

API 参考（v1）

统一前缀：/api/v1

Docker/生产推荐通过前端同域反代访问：/admin139/api/v1/...

通用约定

• 鉴权头：Authorization: Bearer <token>
• 成功响应：{ "ok": true, "data": ... }（Auth 接口除外）
• 失败响应：{ "ok": false, "error": "..." }

---

1) Auth

POST /auth/register

请求：

{ "username": "alice", "password": "password123" }

响应：

{ "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（需鉴权）

请求：

{
  "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

请求：

{ "code": "...", "input": "1 2\n" }

返回：运行状态、stdout/stderr、compile_log。

---

5) 错题本

GET /me/wrong-book（需鉴权）

返回当前用户错题本。

PATCH /me/wrong-book/:problemId（需鉴权）

请求：

{ "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）。

请求体（可选）：

{ "clear_all_problems": true }

也支持本地 PDF + RAG + LLM 出题模式（异步执行，进度同样写入 import_jobs/import_job_items）：

{
  "mode": "local_pdf_rag",
  "workers": 3,
  "local_pdf_dir": "/data/local_pdfs",
  "target_total": 5000
}

---

9) 后台日志（题解异步队列）

GET /backend/logs?limit=100

返回最近题解生成任务日志（按任务 ID 倒序），并包含当前排队任务数 pending_jobs。