API 文档¶

目录¶

题目管理相关接口（Step 1）
评测相关接口（Step 2 & 4）
用户管理相关接口（Step 3）
日志与权限管理相关接口（Step 6）
高级功能接口 (Advance)
状态码与异常
安全性说明

系统初始化说明：系统启动时会自动创建初始管理员账户，用户名和密码均为 admin。

1. 题目管理相关接口（Step 1）¶

查看题目列表¶

路径：GET /api/problems/
权限：公开

响应：

{
  "code": 200,
  "msg": "success",
  "data": [
    {"id": "sum_2", "title": "两数之和"},
    {"id": "max_num", "title": "最大数"}
  ]
}

添加题目¶

路径：POST /api/problems/
权限：仅管理员
参数（JSON，参考 Step1 文档）：
id (str, 必填): 题目唯一标识
title (str, 必填): 题目标题
description (str, 必填): 题目描述
input_description (str, 必填): 输入格式说明
output_description (str, 必填): 输出格式说明
samples (list, 必填): 样例输入输出，元素为 {input, output}
constraints (str, 必填): 数据范围和限制条件
testcases (list, 必填): 测试点，元素为 {input, output}
hint (str, 可选): 额外提示
source (str, 可选): 题目来源
tags (list, 可选): 题目标签
time_limit (str, 必填): 时间限制（如 "1s"）
memory_limit (str, 必填): 内存限制（如 "128MB"）
author (str, 可选): 题目作者
difficulty (str, 可选): 难度等级

响应：

{"code": 200, "msg": "add success", "data": {"id": "sum_2"}}

异常：400 字段缺失/格式错误 / 409 id 已存在

删除题目¶

路径：DELETE /api/problems/{problem_id}
权限：仅管理员
参数：无（URL 路径参数：problem_id）

响应：

{"code": 200, "msg": "delete success", "data": {"id": "sum_2"}}

异常：404 题目不存在

查看题目信息¶

路径：GET /api/problems/{problem_id}
权限：公开

响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "P1001",
    "title": "A+B Problem",
    "description": "输入两个整数 a, b，输出它们的和（|a|,|b| <= 10^9）。",
    "input_description": "输入两个整数 a 和 b。",
    "output_description": "输出 a+b 的结果。",
    "samples": [
      {
        "input": "1 2",
        "output": "3"
      }
    ],
    "constraints": "|a|,|b| <= 10^9",
    "testcases": [
      {
        "input": "1 2",
        "output": "3"
      }
    ],
    "hint": "有负数哦！",
    "source": "洛谷",
    "tags": ["基础题"],
    "time_limit": "1s",
    "memory_limit": "128MB",
    "author": "Luogu",
    "difficulty": "入门"
  }
}

异常：404 题目不存在

2. 评测相关接口（Step 2 & 4）¶

提交评测¶

路径：POST /api/submissions/
参数（JSON）：
problem_id (str, 必填): 题目编号
language (str, 必填): 语言（如 "python", "cpp"）
code (str, 必填): 用户代码内容
权限：登录用户

响应：

{
  "code": 200,
  "msg": "success",
  "data": {"submission_id": 123, "status": "Pending"}
}

异常：400 参数错误 / 403 用户被禁用 / 404 题目不存在 / 429 提交频率超限

查询评测结果¶

路径：GET /api/submissions/{submission_id}
权限：仅本人或管理员

响应：

{
  "code": 200,
  "msg": "success",
  "data": {"status": "Accepted", "score": 100, "time": 0.23, "memory": 128, "stderr": ""}
}

异常：404 评测不存在 / 403 权限不足

查询评测列表¶

路径：GET /api/submissions/
参数：user_id、problem_id、status、page、page_size（均可选）
权限：本人/管理员

响应：

{
  "code": 200,
  "msg": "success",
  "data": {"total": 100, "submissions": [{"submission_id": 1, ...}]}
}

重新评测¶

路径：PUT /api/submissions/{submission_id}/rejudge
权限：仅管理员
参数：无（URL 路径参数：submission_id）

响应：

{"code": 200, "msg": "rejudge started", "data": {"submission_id": 1, "status": "Pending"}}

异常：404/403

动态注册新语言 (Step 2)¶

路径：POST /api/languages/
参数（JSON）：
name (str, 必填): 语言名称
file_ext (str, 必填): 代码文件扩展名
compile_cmd (str, 可选): 编译命令
run_cmd (str, 必填): 运行命令
source_template (str, 可选): 代码执行模板
time_limit (float, 可选): 默认时间限制（秒）
memory_limit (int, 可选): 默认内存限制（MB）
权限：仅管理员

响应：

{"code": 200, "msg": "language registered", "data": {"name": "go"}}

异常：400/403

示例：

{
  "name": "cpp",
  "file_ext": ".cpp",
  "compile_cmd": "g++ {src} -o {exe} -O2 -std=c++17",
  "run_cmd": "{exe}",
  "source_template": "{code}",
  "time_limit": 1.0,
  "memory_limit": 128
}

{
  "name": "python",
  "file_ext": ".py",
  "run_cmd": "python3 {src}",
  "source_template": "{code}",
  "time_limit": 1.0,
  "memory_limit": 128
}

查询支持语言列表 (Step 2)¶

路径：GET /api/languages/

响应：

{"code": 200, "msg": "success", "data": [{"name": "python", ...}]}

3. 用户管理相关接口（Step 3）¶

用户登录¶

路径：POST /api/auth/login
参数：username (str, 必填), password (str, 必填)
权限：公开

响应：

{"code": 200, "msg": "login success", "data": {"user_id": 1, "username": "alice", "role": "user"}}

异常：400 参数错误 / 401 用户名或密码错误

用户登出¶

路径：POST /api/auth/logout
参数：无
权限：登录用户

响应：

{"code": 200, "msg": "logout success", "data": null}

异常：401 未登录

创建管理员账户¶

路径：POST /api/users/admin
参数：username (str, 必填), password (str, 必填)
权限：仅管理员

响应：

{"code": 200, "msg": "success", "data": {"user_id": 2, "username": "new_admin"}}

异常：400 用户名已存在/参数错误 / 403 权限不足

用户注册¶

路径：POST /api/users/
参数（JSON）：
username (str, 必填): 用户名
password (str, 必填): 密码

响应：

{"code": 200, "msg": "register success", "data": {"user_id": 1}}

异常：400 用户名已存在/参数错误

查询用户信息¶

路径：GET /api/users/{user_id}
权限：仅本人或管理员

响应：

{"code": 200, "msg": "success", "data": {"user_id": 1, "username": "alice", "role": "user"}}

异常：404/403

用户权限变更¶

路径：PUT /api/users/{user_id}/role
参数（JSON）：
role (str, 必填): 新角色（如 "admin", "user", "banned"）
权限：仅管理员

响应：

{"code": 200, "msg": "role updated", "data": {"user_id": 1, "role": "admin"}}

异常：404/403

用户列表查询¶

路径：GET /api/users/，参数：username、role、page、page_size（可选）
权限：仅管理员

响应：

{"code": 200, "msg": "success", "data": {"total": 2, "users": [{"user_id": 1, ...}]}}

4. 日志与权限管理相关接口（Step 6）¶

查询评测日志¶

路径：GET /api/submissions/{submission_id}/log
权限：仅本人或管理员

响应：

{"code": 200, "msg": "success", "data": [{"test_id": 1, ...}]}

异常：404/403

配置日志/测例可见性¶

路径：PUT /api/problems/{problem_id}/log_visibility
权限：仅管理员
参数（JSON）：
public_cases (bool, 必填): 是否允许所有用户查看测例详情

响应：

{
  "code": 200,
  "msg": "log visibility updated",
  "data": {"problem_id": 1001, "public_cases": true}
}

异常：404 题目不存在 / 403 权限不足

日志访问审计¶

路径：GET /api/logs/access/
权限：仅管理员
参数：
user_id (int, 可选)：按用户筛选
problem_id (int, 可选)：按题目筛选
page (int, 可选)：页码
page_size (int, 可选)：每页数量

响应：

{
  "code": 200,
  "msg": "success",
  "data": [
    {"user_id": 1, "problem_id": 1001, "action": "view_log", "time": "2024-06-01T12:00:00"}
  ]
}

异常：403 权限不足

5. 高级功能接口 (Advance)¶

Advance 1: Special Judge¶

上传 SPJ 脚本：POST /api/problems/{problem_id}/spj
参数（form-data 或 multipart）：
- file (file, 必填): SPJ 脚本文件
删除 SPJ 脚本：DELETE /api/problems/{problem_id}/spj
参数：无
查询题目评测策略：GET /api/problems/{problem_id}

Advance 4: 代码查重¶

发起查重检测：POST /api/plagiarism/
参数（JSON）：
- problem_id (str, 必填): 题目编号
- threshold (float, 可选): 相似度阈值（如 0.8）
- 其他查重相关参数（如有）
查询查重结果：GET /api/plagiarism/{task_id}（仅管理员）
下载查重报告：GET /api/plagiarism/{task_id}/report（仅管理员）

6. 状态码与异常¶

HTTP 状态码	说明	示例场景
200	正常	一切正常
400	参数错误	缺少/错误参数
403	权限不足/禁用	banned 用户/无权限
404	资源不存在	题目/评测不存在
429	频率超限	提交过于频繁
500	服务器异常	未知错误

所有错误响应建议格式：

{"code": 404, "msg": "problem not found", "data": null}

作者：Haoran Wang