ny-exam-platform/docs/dev/api.md

接口一览

所有接口统一走 api.php?action=<name>，响应为 JSON：

// 成功
{ "ok": true, "data": { ... } }
// 失败
{ "ok": false, "error": "错误信息" }

• 未登录时返回 { "ok": false, "error": "...", "auth": false }，前端会清会话并跳登录页；
• 写操作必须在 JSON 体里带 _csrf 字段（或 X-CSRF-Token 头）， 令牌从 config_get 接口获取。

写操作白名单

config_save、roster_save、roster_import、roster_clear、 snapshot_save、snapshot_delete、unmatched_map、project_config_save

接口清单

认证与配置

Action	方法	参数	说明
auth_check	GET	—	是否已登录
config_get	GET	—	返回配置（密码不回显）+ csrf_token + storage / db_driver / db_connected
config_save	POST	JSON 配置对象	保存；返回 conn_changed 与 ping 结果
config_test	POST	连接信息	测试连接，不落库
ping	GET	—	探测卷王是否可达
diag	GET	—	诊断信息（存储后端、DB 状态等）

只有连接信息（地址 / 前缀 / 账号 / 密码 / 证书校验）变化时，config_save 才会清除令牌并重新登录。

数据

Action	方法	参数	说明
projects	GET	—	卷王项目（问卷 / 考试）列表
data	GET	projectId、nameQid、force	主系统数据：统计、成绩行、名单、缺考、未匹配、异常
dashboard	GET	projectId、nameQid、force	按班级 / 组别聚合的看板数据

data 响应关键字段：

stats        { total, submitted, absent, rate, avg, pass_rate, max, min, avg_duration }
rows[]       { sid, name, cls, grp, score, best_score, attempts, attempts_list[],
               submit_ts, submit_at, last_submit_ts, duration, duration_txt }
roster[]     { sid, name, cls, grp, login }
absent[]     缺考名单
unmatched[]  未匹配答卷
anomalies    { fast_high[], frequent[], identical[] }
project_cfg  本卷配置
_cache       { cached, at }

名单

Action	方法	参数	说明
roster	GET	—	名单与元信息
roster_import	POST	multipart：file、mode=replace|append	导入（扩展名白名单 + 随机名 + 解析后即删）
roster_save	POST	JSON { students: [...] }	全量替换（DELETE + INSERT）
roster_clear	POST	—	清空
unmatched_map	POST	JSON { name, sid, cls, grp, login }	未匹配答卷补入名单（学号已存在则更新姓名）

每卷配置

Action	方法	参数	说明
project_config	GET	projectId	返回 cfg、effective（生效值）、global（全局默认）
project_config_save	POST	JSON { full_score, pass_rate, exempt[] }	留空/0 = 清除该项，回落全局

快照

Action	方法	参数	说明
snapshot_save	POST	projectId、JSON { label }	保存当前成绩快照
snapshot_list	GET	projectId	列表
snapshot_delete	POST	projectId、JSON { file }	删除
snapshot_trend	GET	projectId（可逗号分隔多个，跨卷对比）	趋势

导出

Action	方法	参数	说明
export	GET	projectId、cls、grp、mode=latest、split=cls、sort、cols	成绩明细 .xlsx
export_absent	GET	同上	缺考名单 .xlsx
draw_export	GET	type=import|list	白名单导入模板 / 白名单列表

sort 取值：time / sid / score_desc / score_asc。

前端调用约定

// 读
const d = await api('data', { params: { projectId, force: 1 } })
// 写：api() 会自动注入 _csrf
await api('roster_save', { json: { students } })

相关

• 架构与目录
• 测试