api_reference.md

API 说明文档

一、说明

• 交互式文档：启动服务后访问 http://localhost:8000/docs
• 认证方式：Session Cookie
• 未登录访问需要认证的接口时，返回 401
• 非资源所有者访问受限资源时，返回 403

---

二、认证接口 /api/auth

方法	路径	认证	说明
POST	/api/auth/register	无	注册用户
POST	/api/auth/login	无	登录并写入 Session
POST	/api/auth/logout	需登录	登出并清空 Session
GET	/api/auth/me	需登录	获取当前用户信息

---

三、题目资产接口 /api/questions

3.1 题目资产基础操作

方法	路径	认证	说明
POST	/api/questions	需登录	创建题目资产和初始版本
GET	/api/questions	需登录	题目资产列表
GET	/api/questions/{root_id}	需登录	题目资产详情

3.2 版本相关

方法	路径	认证	说明
GET	/api/questions/{root_id}/versions	需登录	版本列表
GET	/api/questions/{root_id}/versions/{version_id}	需登录	单个版本详情
POST	/api/questions/{root_id}/versions	需登录（owner）	基于当前题目创建新版本
POST	/api/questions/{root_id}/restore	需登录（owner）	基于旧版本恢复出新的最新版本

3.3 共享、使用情况与统计

方法	路径	认证	说明
PUT	/api/questions/{root_id}/sharing	需登录（owner）	修改共享设置
GET	/api/questions/{root_id}/usages	需登录	查看该题被哪些问卷使用
GET	/api/questions/{root_id}/stats	需登录	查看该题的跨问卷统计，可带 version_id

---

四、题库接口 /api/question-banks

方法	路径	认证	说明
POST	/api/question-banks	需登录	创建题库
GET	/api/question-banks	需登录	题库列表
GET	/api/question-banks/{bank_id}	需登录	题库详情
POST	/api/question-banks/{bank_id}/questions	需登录（owner）	向题库加入题目资产
DELETE	/api/question-banks/{bank_id}/questions/{root_id}	需登录（owner）	从题库移出题目资产

---

五、问卷接口 /api/surveys

5.1 问卷基础操作

方法	路径	认证	说明
POST	/api/surveys	需登录	创建问卷
GET	/api/surveys	需登录	我创建的问卷列表
GET	/api/surveys/{survey_id}	需登录（创建者）	问卷详情
PUT	/api/surveys/{survey_id}	需登录（创建者）	更新问卷元信息
POST	/api/surveys/{survey_id}/publish	需登录（创建者）	发布问卷
POST	/api/surveys/{survey_id}/close	需登录（创建者）	关闭问卷
GET	/api/surveys/by-code/{share_code}	无	通过分享码获取已发布问卷

5.2 问卷中的题目引用操作

方法	路径	认证	说明
POST	/api/surveys/{survey_id}/questions	需登录（创建者）	向问卷加入题目，可加入资产引用或兼容内嵌题
PUT	/api/surveys/{survey_id}/questions/{qid}	需登录（创建者）	更新问卷中的题目引用、排序或兼容内嵌题内容
POST	/api/surveys/{survey_id}/questions/{qid}/switch-version	需登录（创建者）	切换问卷中该题引用的版本
DELETE	/api/surveys/{survey_id}/questions/{qid}	需登录（创建者）	删除问卷中的题目引用

---

六、答卷接口 /api/surveys/{survey_id}/responses

方法	路径	认证	说明
POST	/api/surveys/{survey_id}/responses	需登录	提交答卷，包含后端跳转与校验约束
GET	/api/surveys/{survey_id}/responses	需登录（创建者）	查看该问卷所有答卷

---

七、统计接口

7.1 问卷统计

方法	路径	认证	说明
GET	/api/surveys/{survey_id}/stats	需登录（创建者）	查看整卷统计
GET	/api/surveys/{survey_id}/stats/{qid}	需登录（创建者）	查看单卷单题统计

7.2 单题跨问卷统计

方法	路径	认证	说明
GET	/api/questions/{root_id}/stats	需登录	查看某题在所有问卷中的统计

---

八、页面路由（SSR）

路径	说明
/	首页
/login	登录页
/register	注册页
/dashboard	我的问卷
/questions	题目资产页
/questions/{root_id}	题目详情页
/question-banks	题库列表页
/question-banks/{bank_id}	题库详情页
/surveys/new	新建问卷
/surveys/{survey_id}/edit	问卷编排页
/survey/{share_code}	填写问卷页
/surveys/{survey_id}/stats	问卷统计页

---

九、接口语义变化说明

phase1 中，问卷接口更多是在操作“问卷内嵌题目本体”。
phase2 中，接口语义变为：

• 题目内容由 /api/questions 管
• 题库由 /api/question-banks 管
• 问卷接口主要管理“题目版本的引用关系、排序和跳转”

这是当前 API 设计最重要的变化。