# AIRA Learn 课程与题目导入规范 v1 · 九类题型

维护单位：浙大人工智能创新研究学会（AI创研会）

## 1. 使用方式

1. 打开 https://learn.zjuaira.com/courses/submit ，登录后提交。
2. 仅建课程：选择“填写课程信息”，填写代码、名称等，提交审核。
3. 批量题目：下载 `course-package-v1.json`，替换示例课程和题目，保存为 **UTF-8 JSON**；在“导入课程与题目”中选择文件。
4. 需要图片时，在同页“题目需要配图？”上传图片，复制返回的 Markdown；替换题目中的示例图链接。
5. 预览课程、题干、答案和解析，提交审核。管理员在 `/admin/course-imports` 审核，批准后自动生成课程、试卷、题目。
6. 在“我的提交”中看状态与审核备注；被退回时修改内容后重新提交。

**本 MD 是格式说明，不是导入文件。实际导入 JSON 数据包，不直接解析 Word、PDF、图片或自由格式 Markdown。** 可以请人工或 AI 把原始资料转换为该 JSON，核对题干、公式、图片和答案后再导入。示例课程不是正式课程，请替换，勿原样提交。

## 2. 数据结构

```json
{
  "schema_version": 1,
  "course": {
    "id": "MATH101",
    "name": "高等数学",
    "college": "数学科学学院",
    "category": "通识基础课",
    "credits": 4.0,
    "description": "课程介绍，支持 Markdown。"
  },
  "papers": [
    {
      "name": "2026年秋季第一章练习",
      "questions": []
    }
  ]
}
```

以上是结构说明：实际非空试卷必须至少有一道题。只创建课程时，顶层填写 `"papers": []`。

| 字段 | 要求 |
| --- | --- |
| `schema_version` | 必填，整数 `1` |
| `course.id` | 必填，课程代码；1–64 位英文字母、数字、`_`、`-`、`.`，以字母或数字开头；同课程始终使用同一代码 |
| `course.name` | 必填，1–256 字；同代码已有课程时名称必须一致 |
| `college` / `category` | 学院/类别，可为空；分别最多 256/128 字 |
| `credits` | 0–99，最多一位小数；不确定填 0 |
| `description` | 课程简介 Markdown，最多 32KB |
| `papers` | 数组，最多 20 份试卷；仅创建课程时用空数组 |
| `papers[].name` | 必填，1–256 字；同课程下试卷名不可重复 |
| `papers[].questions` | 非空数组；整个包最多 200 题；数组顺序就是题号 |

每个数据包最多 **2MB**；不可加入未定义字段，以免拼写错误导致数据丢失。JSON 不允许注释、尾逗号或单引号。

## 3. 题目通用字段

| 字段 | 要求 |
| --- | --- |
| `id` | 必填，数据来源中的稳定题目标识，如 `q001`；规则同课程代码，在同一试卷内唯一，不是数据库题号 |
| `question_type` | 必填，见下方题型表；大小写必须一致 |
| `test` | 必填，题干 Markdown；可含文字、图片、公式、表格、代码，最多 32KB |
| `options` | 仅单选/多选题填写；2–8 个选项，每项为 `{"option":"A","text":"选项内容"}` |
| `answer` | 必填，参考答案字符串；最多 32KB |
| `explanation` | 参考解析 Markdown，最多 32KB；没有可填空字符串 |
| `score` | 0–1000，最多两位小数；未知可填 0；目前展示分值，不表示主观题可自动评分 |

| 题型 | `question_type` | 答案形式与当前判分 |
| --- | --- | --- |
| 单选题 | `singleChoice` | 一个已有选项字母，如 `B`；自动比较选项 |
| 多选题 | `multipleChoice` | 逗号分隔的选项集合，如 `A,C`；忽略顺序，全部选对才判对，不计部分分 |
| 填空题 | `fillBlanks` | 一个文本答案；去除首尾空白、忽略英文字母大小写后比较，不进行数学等价或单位换算 |
| 简答题 | `shortAnswer` | Markdown 参考答案；保存作答，供对照参考答案，不自动判对错、不自动加入错题本 |
| 计算题 | `calculation` | Markdown 推导过程和结果；处理方式同简答题 |
| 判断题 | `trueOrFalse` | `T` 或 `F`，自动判分，不填写 options |
| 证明题 | `proof` | 保存证明过程，对照逻辑与评分要点，不自动判分 |
| 材料分析题 | `caseAnalysis` | 图文材料及小问整体作答，对照参考要点，不自动判分 |
| 编程题 | `programming` | 保存代码并展示参考实现；请自行在本地环境运行，不执行代码、不自动判分 |

当前不支持多个可接受文本答案、结构化多空独立判分、主观题自动批改。需要多个空时建议拆为独立填空题，或改为简答题并提供评分要点。

## 4. 题型模板

下列每个对象放入 `questions` 数组中即可。完整可导入的全题型示例见配套 JSON。投稿页另有每种题型的独立 JSON 下载，其中编程题包含 Python 和 C++ 两份示例。

### 4.1 单选题

```json
{
  "id": "q001",
  "question_type": "singleChoice",
  "test": "若 $f(n)=n(\\log n)^2$，以下哪项正确？",
  "options": [
    {"option": "A", "text": "$f(n)=O(n)$"},
    {"option": "B", "text": "$f(n)=O(n^2)$"}
  ],
  "answer": "B",
  "explanation": "因为 $(\\log n)^2=o(n)$，所以答案为 B。",
  "score": 2
}
```

选项字母使用不重复的 A–H；选项文字可包含图片和公式。不要把题号写在题干开头，页面会自动显示题号。

### 4.2 填空题

```json
{
  "id": "q002",
  "question_type": "fillBlanks",
  "test": "计算 $\\sum_{i=1}^{10}i=$ ______。只填数字。",
  "answer": "55",
  "explanation": "等差数列求和：$10(1+10)/2=55$。",
  "score": 3
}
```

在题干中说明答案格式，比如“只填数字”“保留两位小数”。`55` 与 `55.0` 当前会按不同文本处理；不能假定系统自动判断数学等价。

### 4.3 简答题（图文）

```json
{
  "id": "q003",
  "question_type": "shortAnswer",
  "test": "结合下图说明串联电路中的电流关系。\n\n![串联电路](/templates/series-circuit.svg)",
  "answer": "两电阻电流相等，即 $I_1=I_2$。稳态下无分流支路，电荷不会在节点累积。",
  "explanation": "评分要点：电流关系正确；能从电荷守恒解释。允许等价表述。",
  "score": 5
}
```

### 4.4 计算题（公式与图文）

```json
{
  "id": "q004",
  "question_type": "calculation",
  "test": "如图，$U=12\\,\\mathrm{V}$，$R_1=2\\,\\Omega$，$R_2=4\\,\\Omega$。求电流，写出过程。\n\n![串联电路](/templates/series-circuit.svg)",
  "answer": "先求总电阻：\n\n$$R=R_1+R_2=6\\,\\Omega$$\n\n再由欧姆定律：\n\n$$I=\\frac{U}{R}=2\\,\\mathrm{A}$$",
  "explanation": "检查串并联关系、公式代入和单位。结果正确但缺过程时，请自行对照评分要求。",
  "score": 5
}
```

图片也可出现在 `answer`、`explanation`、`options[].text` 中。不要把图片放到自定义的 `imageUrls` 字段，新规范不读取该字段。

### 4.5 多选题

```json
{
  "id": "q005",
  "question_type": "multipleChoice",
  "test": "以下哪些数是偶数？选择所有正确选项。",
  "options": [
    {
      "option": "A",
      "text": "$2$"
    },
    {
      "option": "B",
      "text": "$3$"
    },
    {
      "option": "C",
      "text": "$4$"
    },
    {
      "option": "D",
      "text": "$5$"
    }
  ],
  "answer": "A,C",
  "explanation": "$2$ 和 $4$ 能被 $2$ 整除。必须同时选 A、C；漏选或多选均不判对。",
  "score": 4
}
```

`answer` 至少包含两个不重复且确实存在的选项字母，使用英文逗号，如 `A,C`。`C,A` 会规范化为 `A,C`。重复、未知选项或使用中文逗号会被拒绝；只选一项应使用单选题。练习模式需要点击提交才揭晓，不会选中一个选项就自动交卷。

### 4.6 判断题

```json
{
  "id": "q006",
  "question_type": "trueOrFalse",
  "test": "判断：$n^2=O(n)$（当 $n\\to\\infty$）。",
  "answer": "F",
  "explanation": "$n^2/n=n$ 无界，因此不满足大 O 的常数倍上界。",
  "score": 2
}
```

### 4.7 编程题

```json
{
  "id": "q007",
  "question_type": "programming",
  "test": "## 题目\n输入整数 $n$，输出 $1+2+\\cdots+n$。\n\n## 输入格式\n一行一个整数 $n$，$1\\le n\\le 10^9$。\n\n## 输出格式\n输出一个整数，表示前 $n$ 个正整数的和。\n\n## 输入样例\n```text\n5\n```\n\n## 输出样例\n```text\n15\n```\n\n请使用 Python 编写程序，自行在本地运行。本站只提供参考代码对照。",
  "answer": "```python\nn = int(input().strip())\nprint(n * (n + 1) // 2)\n```",
  "explanation": "使用等差数列求和公式，时间和额外空间复杂度均为 $O(1)$。可自行测试：输入 1 应输出 1；输入 10 应输出 55；输入 1000000000 应输出 500000000500000000。不同正确实现均可，本站不比较代码文本来判分。",
  "score": 10
}
```

```json
{
  "id": "q008",
  "question_type": "programming",
  "test": "使用 C++ 实现前 $n$ 个正整数求和。\n\n**输入**：一行整数 $n$，$1\\le n\\le 10^9$。\n\n**输出**：$1+2+\\cdots+n$。\n\n**样例**：输入 `5`，输出 `15`。\n\n注意整数溢出，请自行在本地编译运行验证。",
  "answer": "```cpp\n#include <iostream>\nusing namespace std;\n\nint main() {\n    long long n;\n    cin >> n;\n    cout << n * (n + 1) / 2 << \"\\n\";\n    return 0;\n}\n```",
  "explanation": "使用 long long 存储输入和中间结果；该范围下 $n(n+1)$ 不超过 64 位有符号整数范围。可用与 Python 示例相同的输入自行验证。",
  "score": 10
}
```

编程题只保存代码并展示参考答案，不接在线评测。题干请写清语言（如有要求）、输入输出、数据范围、样例；`answer` 用带语言标记的 Markdown 代码围栏，`explanation` 写思路、复杂度、边界情况和自行验证建议。无需添加 `language`、`test_cases` 等未定义 JSON 字段。不同正确实现不会因代码文本不同而记为错题。

### 4.8 证明题

```json
{
  "id": "q009",
  "question_type": "proof",
  "test": "用数学归纳法证明：对于任意正整数 $n$，\n\n$$1+2+\\cdots+n=\\frac{n(n+1)}{2}.$$",
  "answer": "**基础情形**：$n=1$ 时两边均为 1。\n\n**归纳假设**：设 $n=k$ 时命题成立。\n\n**归纳步骤**：\n\n$$\\sum_{i=1}^{k+1}i=\\frac{k(k+1)}2+(k+1)=\\frac{(k+1)(k+2)}2.$$\n\n因此 $n=k+1$ 时也成立，命题得证。",
  "explanation": "对照检查：基础情形、归纳假设、归纳步骤和结论是否完整。允许等价证明，不自动判分。",
  "score": 8
}
```

### 4.9 材料分析题

```json
{
  "id": "q010",
  "question_type": "caseAnalysis",
  "test": "某图像识别系统在同一测试集上的结果如下。\n\n| 方案 | 准确率 | 单张延迟 | 模型大小 |\n| --- | --- | --- | --- |\n| 原始模型 | 95% | 100ms | 80MB |\n| 压缩模型 | 93% | 40ms | 20MB |\n\n1. 计算压缩后的延迟降幅和模型大小降幅。\n2. 如果部署要求为延迟不超过 50ms、模型不超过 30MB、准确率至少 92%，应选择哪个方案？说明理由。\n3. 指出正式部署前还需要验证的一项风险。",
  "answer": "1. 延迟降幅为 $(100-40)/100=60\\%$；模型大小降幅为 $(80-20)/80=75\\%$。\n2. 压缩模型同时满足三个要求，原始模型不满足延迟和存储要求，因此选择压缩模型。\n3. 例如：验证真实设备上的尾部延迟、分布变化下的准确率，或关键类别的错误率。合理答案均可。",
  "explanation": "评分参考：两项比例计算（4 分）、约束核对与方案选择（3 分）、合理风险与验证方式（3 分）。整道材料题统一作答；若需要逐小问独立作答，应拆为多道题并在题干保留材料。",
  "score": 10
}
```

## 5. Markdown、LaTeX 与图片规则

- 行内公式：`$N(\log N)^2$` 或 `\(N(\log N)^2\)`。
- 独立公式：用单独一行的 `$$` 包围公式，或 `\[...\]`。复杂推导建议分行。
- 在普通 Markdown 中，一个命令使用一个反斜杠，如 `\frac`；**写进 JSON 字符串必须转义为 `\\frac`**。换行写成 `\n`。引号写成 `\"`。用程序生成 JSON 时，交给 JSON 序列化库处理转义。
- 图片语法：`![图片说明](/static/uploads/images/日期/文件名.png)`。推荐使用上传接口返回的 `public_path`，同域可直接显示。
- 也可使用稳定、公开、支持 HTTPS 的图片直链；不支持电脑本地路径、Word 内嵌图片、需要登录的链接。不要使用 `C:\...`、`file://...` 或仅文件名 `figure.png`。
- 图示建议使用清晰的 PNG/JPG/WebP，文字可读；上传页限制单张 5MB。图片不会自动变成可识别的文字题干，关键数值应同时写进题干。
- 不使用 HTML/script/iframe；Markdown 渲染会跳过原始 HTML。
- 表格使用标准 Markdown 表格；代码用三反引号围栏，代码内的公式不会被渲染。

## 6. 接口

所有写入接口都需要 `Authorization: Bearer <accessToken>`。网站前端自动处理登录续期。

| 方法与路径 | 权限 | 内容 |
| --- | --- | --- |
| `POST /api/course-imports` | 登录用户 | 请求体为上述完整 JSON 数据包；校验通过后进入待审核，不直接公开 |
| `GET /api/course-imports/mine` | 登录用户 | 当前用户最近 100 条提交摘要，含 status/review_note |
| `GET /api/course-imports/:id` | 提交者本人或题库管理员 | 单份完整数据包，含 payload |
| `GET /api/admin/course-imports` | 题库管理员 | 最近 100 条待审核提交 |
| `POST /api/admin/course-imports/:id/review` | 题库管理员 | `{"approve":true,"note":"已核对"}` 通过；false 退回 |
| `POST /api/files/upload` | 登录用户 | multipart/form-data：`file` 为图片，`type=image`；取响应 `data.public_path` |

返回统一为 `{code,message,data}`。状态值：`pending`、`approved`、`rejected`。

常见错误：400 字段/题型/答案错误；401 需登录；403 非管理员；409 重复数据包、重复试卷、课程代码冲突或已审核；413 请求过大；429 当前用户已有 20 份待审核提交。

提交示例：

```bash
curl -X POST https://learn.zjuaira.com/api/course-imports \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @course-package-v1.json
```

## 7. 导入与重复规则

- 一次审批在一个数据库事务内完成。任何课程冲突、试卷重名或写入失败都会撤销本次写入，不留半份试卷。
- 相同数据包不会重复提交；重复点击通过也不会重复生成题目。
- 现有课程：代码和名称一致时可追加不同名称的新试卷，不修改课程的简介、学院和学分。
- 课程简介修改继续使用课程页原有的简介投稿；已发布题目修改仍走管理员编辑功能。
- 不自动覆盖、合并或删除同名试卷。退回后修改包内容重新提交；要追加大量题目，请按不同试卷名分包。
- 数据库题号、试卷 ID 由系统自动生成，前端自动提供做题、收藏、解析入口；不需要手写数据库 ID。
- JSON 不能包含真实用户作答、账号或 API 密钥，只放课程和题目资料。

## 8. 给资料整理者 / AI 的转换要求

> 请将资料转换为本规范的 UTF-8 JSON。顶层只能是 schema_version、course、papers；按原卷顺序放入 questions，每题使用唯一 id。题干、参考答案和解析用 Markdown，数学表达用 LaTeX，图片用实际可访问的 Markdown 链接。不要编造题干、答案、缺失的图片地址或课程代码；缺失时先标记并交给人工补齐，不能把占位文本当作正式答案提交。单选 answer 用选项字母；填空用明确文本；简答和计算保留步骤、图片和评分要点。完成后按模板检查 JSON 转义，并在网站预览核对。

## 9. 可扩展方式（维护者）

题型唯一维护源为 `back/services/question_types.json`。每项定义：`id`（稳定类型码）、`label`（中文名称）、`input`（输入方式）、`grading`（判分方式）和 `description`（给使用者的说明）。

现有输入方式：`single` 单选、`multiple` 多选、`boolean` 判断、`text` 文本、`code` 代码。
现有判分方式：`choice` 单选字母、`set` 选项集合、`boolean` 判断、`exact` 简单文本比较、`reference` 参考答案对照。

新增证明、论述或案例类题型时，可复用 `text + reference`；新增题型定义、对应示例后，运行：

```bash
node scripts/sync-question-types.mjs
```

该命令同步前端题型定义、公开题型目录和 JSON Schema。前端构建/测试前也会自动运行；后端测试会检查前后端定义一致。展示标签、作答输入、导入校验、判分策略不再各写一套类型列表。新增类型必须同时提供 `public/templates/types/<id>.json` 示例，并运行前后端测试。

如果新增的是完全不同的交互或判分，例如拖拽匹配、多空独立判分，仍需实现新的输入/校验/判分策略，并考虑数据格式版本；不能仅添加一个名称就声称已支持。保持既有类型码和 v1 字段兼容，未知字段和未知类型仍会被拒绝。

`/templates/course-package.schema.json` 可用于编辑器或数据整理脚本预检，`/templates/question-types.json` 提供公开题型目录。Schema 辅助检查结构和基础类型；课程冲突、选项答案对应关系、重复题号、包总题数和字节长度仍由服务端最终校验。

本次更新不重写历史作答或错题记录；更新后的编程题新作答统一标记为参考答案对照。
