nxxy335
25a2e8a42c
文档站（#88） - base 默认改为 /ny-exam-platform/，可用 DOCS_BASE=/ 覆盖本地预览 - 新增 DOCS_OUT 环境变量，避免构建时清空输出目录失败导致产物半截 - 新增 tools/docs-preview.js：按子路径重写路由的本地预览服务 - 删除 docs/guide/snapshot.md，同步清理全部相关文档 移除存快照 / 趋势 / 异常（#89） - 后端：删除 api.php 的 snapshot_save/list/delete/trend 四个 action 与 $WRITE_ACTIONS 中的同名条目；删除 lib/Snapshot.php 与自动加载注册； DataService 移除 detectAnomalies() 及其调用 - 前端：移除三个按钮与三个弹窗、相关 JS 处理与 state 字段 - 测试：移除对应用例，补充 5 条名单导入列识别断言（17+9+18+32+29+11 全过） 打印完善（#90） - 改用隐藏 iframe 输出，规避弹窗拦截；@page A4 支持纵向/横向 - 表头每页重复、行内不跨页断开、全表连续名次、可选「是否合格」列 - 分组小计（人数/平均/最高/最低/合格人数与合格率）、可附缺考名单另起一页 - 末尾签字栏；缺考名单打印改为同一套输出 UI / 交互 / Bug 修复（#91） - dashboard.php：补「← 主系统 / 退出」入口（此前全屏后无法离开）； 修复成员下钻 onclick 里 JSON.stringify 双引号提前闭合属性导致点击报错， 改为 data-sid 事件委托；补 Esc 关弹窗；后台标签页暂停轮询、切回自动补拉； 刷新中断原因写入 title；数值字段统一兜底，避免 NaN / undefined% - draw.php / draw.js：结果表新增「登陆账号」列（导出前可核对，缺失显示 学号 ⚠）； 弹窗只关最上层且支持 Esc；「全部」改为跟随候选池，手工改人数即解除； 候选池不足时给出明确提示；自定义比例框隐藏时清空，避免旧权重被误读 - app.js / dashboard.php：成绩着色改为按「占本卷满分的百分比」判断， 修复满分不是 100 时整列误标红 - style.css：数值列右对齐；新增 subbar、draw-stage-sub； 看板顶栏窄屏下拉与按钮换行，消除横向滚动
97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# 接口一览
|
||
|
||
所有接口统一走 `api.php?action=<name>`，响应为 JSON：
|
||
|
||
```jsonc
|
||
// 成功
|
||
{ "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`、
|
||
`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[] 未匹配答卷
|
||
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 | 方法 | 参数 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `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`。
|
||
|
||
## 前端调用约定
|
||
|
||
```js
|
||
// 读
|
||
const d = await api('data', { params: { projectId, force: 1 } })
|
||
// 写：api() 会自动注入 _csrf
|
||
await api('roster_save', { json: { students } })
|
||
```
|
||
|
||
## 相关
|
||
|
||
- [架构与目录](./architecture.md)
|
||
- [测试](./testing.md)
|