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

也支持本地 PDF + RAG + LLM 出题模式（异步执行，进度同样写入 `import_jobs/import_job_items`）：
```json
{
  "mode": "local_pdf_rag",
  "workers": 3,
  "local_pdf_dir": "/data/local_pdfs",
  "target_total": 5000
}
```

---

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

### `GET /backend/logs?limit=100`
返回最近题解生成任务日志（按任务 ID 倒序），并包含当前排队任务数 `pending_jobs`。