# 平台简介

NY 问卷考试系统数据平台是一个**零第三方运行依赖**的 PHP 8 应用，直接对接
[卷王问卷系统（SurveyKing）社区版 v1.13](https://gitee.com/surveyking/surveyking) 的开放 API。

它不改变卷王本身的任何数据，只读拉取答卷，然后在本地做「姓名 → 学号」关联、
统计聚合、导出与展示。

## 它能解决什么问题

卷王自带的考试统计偏"问卷视角"，而实际教学/培训场景通常需要的是"名单视角"：

- 谁**没考**（而不是谁考了）—— 需要拿完整名单去比对；
- 某个班 / 某个组的成绩分布如何 —— 需要按班级、组别切片；
- 同一个人考了多次，该看哪一次 —— 需要去重策略 + 完整的考试次数；
- 不同试卷满分不同 —— 需要每卷独立的满分与合格率；
- 成绩要交给教务系统 —— 需要干净的 `.xlsx` 导出；
- 要抽查 / 抽考 —— 需要可去重、可留痕的随机抽取。

## 功能总览

### 主系统 `index.php`

| 模块 | 说明 |
| --- | --- |
| 试卷切换 | 下拉选择卷王中的问卷 / 考试，自动拉取该卷全部答卷 |
| 姓名关联 | 自动识别答卷中的「姓名」题，也可手动指定字段；未匹配答卷单独面板 + 一键补入名单 |
| 统计卡片 | 名单总人数、已提交、缺考、平均分、最高分、最低分、合格率、平均用时；选择班级后全部联动 |
| 成绩明细 | 虚拟滚动（无分页）、点击表头排序、搜索（提示同步显示命中数）、考试次数、新提交绿色高亮（30 秒自动清除） |
| 缺考名单 | 名单中有但未提交的人，支持复制学号 / 姓名、打印（按班级分组） |
| 试卷设置 | 为当前选中的试卷单独设置满分 / 合格率 / 免考名单，试卷间互相隔离 |
| 导出 / 打印 | 成绩明细、缺考名单 `.xlsx`；成绩明细按成绩降序打印，支持分组小计、合格标记、附缺考名单、签字栏 |

### 数据大屏 `dashboard.php`

首页先选试卷，再用卡片列出该卷的班级；点卡片进入该班专属大屏。
大屏页支持全屏切换与自动刷新，**没有返回按钮，浏览器后退键也被屏蔽**（只能靠地址栏或关标签页离开）。

### 随机抽取 `draw.php`

从「学号名单」或「某试卷已提交人员」中随机抽取，支持：

- 按班级 / 组别筛选；
- 名额分配四种模式：按人数加权（默认）、各组均分、自定义比例、不分组；
- 排除已抽中（本次会话内去重）、排除管理（手动指定不参与的人）；
- 历史批次留痕、白名单导入模板 / 白名单列表导出。

![名单管理](/images/roster.png)

## 设计约束

- **零 Composer 依赖**：不使用任何 PHP 第三方库，XLSX 读写、ZIP 打包均由仓库内代码完成；
- **不修改卷王数据**：全程只读（登录 + 项目列表 + 答卷列表 + 答卷详情）；
- **可降级**：没有 `zip` 扩展时用内置解析器读 xlsx；没有 `pdo_sqlite` 时自动回落到 JSON 文件存储；
- **单目录部署**：整个目录复制到站点目录即可，只需保证 `data/` 可写。

## 下一步

- [环境要求与部署](./install.md)
- [快速上手](./quickstart.md)