这套接口是干什么的

题库中台是粒方所有系统取题的唯一来源。行课系统、家校小程序、办学系统都不用再各自存一份题库，统一调这里的接口即可。后台（首页）改一道题，所有系统下一次请求就是新的。

接口一览

题库里的「三个来源」

组合和题目都带一个 src / source 字段，标的是这道题从哪来的。取题时可以按它筛。

组合还带一个 subject 字段（学科）。粒方题库有 数学 和 英语 两个学科 （2026-10-16 加英语），取题时可以用 &subject=英语 只要英语的； 章节序 / 爱学习体系目前只导入了数学。学科记在组合上，题目本身不带这个字段。

快速上手

1）先看有哪些组合，挑一个

# curl
curl -H "X-API-Key: qb_live_xxx" BASE_URL/api/v1/combos

// 返回（节选）
{
  "combos": [
    { "id": "t_5_5_340", "grade": "四年级", "version": "苏教版", "vol": "上册",
      "title": "四年级 · 苏教版 · 上册", "q_uniq": 4520 },
    { "id": "a_7_13_3_48", "grade": "六年级", "version": "全国版",
      "period": "秋季", "system": "α体系", "title": "六年级 · 全国版 · 秋季·α体系" }
  ]
}

2）按知识点取题（行课系统最常见的用法）

// 拿到树 → 找到知识点 node id → 取题
const r = await fetch(`${BASE}/api/v1/questions?combo=t_5_5_340&node=t_5_5_340:387419&size=20`, {
  headers: { 'X-API-Key': KEY }
});
const { total, items } = await r.json();

node 传知识点节点 id 时，会连同它的所有子节点一起取，所以传「章」也能拿到整章题目。

3）随机抽 10 题做课堂随练

const r = await fetch(`${BASE}/api/v1/questions/random?combo=t_5_5_340&type=1&difficulty=2&n=10`, {
  headers: { 'X-API-Key': KEY }
});

4）在后台组好卷，线上按试卷 id 取

const r = await fetch(`${BASE}/api/v1/papers/p_m1x2k3`, { headers: { 'X-API-Key': KEY } });
const { paper, questions } = await r.json();   // questions 已按试卷顺序排好

取题参数（/api/v1/questions）

单题字段说明

各系统怎么接

行课系统（merged-app）

• 服务端（NestJS）直接调 /api/v1/questions，把密钥放在服务器的环境变量里，不要写进前端。
• 典型场景：老师排课时选章节 → 取该章题目当课后练习 → 在后台组卷，行课系统按试卷 id 取。
• 学生提交后，你可以把作答结果记在行课系统自己的库里，不需要回写题库中台（题库只管内容，不管作答）。

家校小程序（banxue）

• ⚠️ 小程序不能直接连任意域名：要在微信后台把 request 合法域名配成题库中台对外域名，且必须 HTTPS + 已备案。
• 更省事的做法：小程序照旧调 banxue 自己的服务端，由 banxue 服务端去调题库中台。这样题库中台不用暴露给小程序的每一个用户，密钥也只存在服务端。
• banxue 现在已有一张 question_bank 表（老师自编题）。建议：自编题留在本地，题库中台出的题只存 source_ref 引用，不要把 15 万道题同步进小程序库。

办学系统 / 其它

• 只要能发 HTTP 请求就行。题库中台允许跨域（Access-Control-Allow-Origin: *），但建议走服务端调用，别把密钥放进浏览器里。
• 同一个密钥可以给多个小系统共用，但建议一个系统一个密钥——这样出问题能单独停掉某一方。

错误码

自检

curl -H "X-API-Key: qb_live_xxx" BASE_URL/api/v1/ping
# {"ok":true,"service":"粒方教育题库中台","version":"v1","system":"行课系统","at":"…"}