fix(security): 修复上传名单文件可被 URL 直连访问（nginx 下可 getshell）

严重漏洞：roster_import 使用 $_FILES 的原始扩展名拼 roster_YYYYMMDD_HHMMSS.<ext>
落在 Web 根目录内的 data/uploads/，既无扩展名白名单（可上传 .php），文件名又
可按秒枚举；而 bootstrap 只写了 data/.htaccess，nginx 不读 .htaccess，
生产环境（nginx + PHP-FPM）下可直接远程代码执行。

修复（api.php roster_import 四层防护）：
- 扩展名白名单：仅 xlsx / xlsm / csv / txt
- 随机文件名：bin2hex(random_bytes(16))，杜绝枚举
- 解析完成后 @unlink 立即删除，Web 目录下不留存任何上传文件
- 20MB 大小限制 + UPLOAD_ERR 检查

加固（bootstrap.php）：data 及 cache/uploads/snapshots 每个目录都写
.htaccess（Deny from all）+ index.html 占位；README 与文档补充 nginx
location ^~ /data/ { deny all; return 404; } 规则。

测试：新增 e2e tools/test-upload-guard.js（11 断言，覆盖 .php/.phtml 被拒、
无残留、合法 csv 导入成功且即删、无可枚举文件名），并入 tests/run-all.sh。
全套 90 项通过。

docs: 新增 VitePress 文档站（18 页）
- 使用指南 12 页：简介/部署/快速上手/系统设置/名单管理/统计口径/试卷设置/
  快照趋势异常/导出打印/数据看板/随机抽取/常见问题
- 安全 2 页：安全总览（含本次漏洞复盘）与部署加固清单（P0-P2）
- 开发 4 页：架构与目录/接口一览/SQLite 存储/测试
- 配图迁移至 docs/public/images/；.gitignore 忽略文档构建产物

README.md

@@ -14,15 +14,44 @@
 | 统计卡片 | 名单总人数、已提交、缺考、提交率、平均分、**合格率**（≥60% 满分）、最高分、最低分、平均用时；**选择班级后，全部卡片只统计该班级** |
 | 缺考名单 | 名单中有、但未提交的人 |
 | 未匹配答卷 | 提交了但姓名不在名单中的答卷，方便排查 |
-| 名单导入 | 上传 `.xlsx` / `.csv`，自动识别「学号」「姓名」「班级」列（班级可选）；支持覆盖 / 追加、手动增删改 |
-| 导出 | 成绩明细 CSV（学号/姓名/班级/成绩/提交时间/考试时长）、缺考名单 CSV（学号/姓名/班级） |
+| 名单导入 | 上传 `.xlsx` / `.xlsm` / `.csv` / `.txt`，自动识别「学号」「姓名」「班级」列（班级可选）；支持覆盖 / 追加、手动增删改 |
+| 导出 | 成绩明细 / 缺考名单 `.xlsx`（零依赖生成，支持多工作表、按最新成绩、按班级分表） |
 | 排序 / 班级 | 点击表头排序，**成绩明细默认按提交时间降序**；支持学号/姓名/班级/成绩/提交时间/时长排序；按班级下拉筛选 |
 | 全屏 / 自适应 | 右上角「全屏」按钮进入全屏（布局自动铺满、表格更高）；页面适配手机 / 平板 / 桌面三端 |
 
 ## 环境要求
 
 - PHP ≥ 8.0（需启用 `curl`、`json`、`mbstring`、`openssl`（可选，用于 RSA 加密密码）；`zip` 可选，无 zip 扩展时会用内置解析器读 xlsx）
-- 无需数据库、无需 Composer 依赖，数据以 JSON 存放在 `data/`
+- 推荐启用 `pdo_sqlite`（用于 SQLite 存储）；未启用时自动降级为 JSON 文件存储
+- 无需数据库服务、无需 Composer 依赖
+
+## 文档
+
+完整文档见 `docs/`（VitePress）：
+
+```bash
+cd docs
+npm install
+npm run docs:dev      # 本地预览
+npm run docs:build    # 构建静态站到 docs/.vitepress/dist
+```
+
+## 安全
+
+- 登录凭据即卷王后台账密；连续 5 次失败锁定 10 分钟
+- 所有写接口强制校验会话绑定的 CSRF 令牌
+- 上传文件：扩展名白名单（`.xlsx` / `.xlsm` / `.csv` / `.txt`）+ 随机文件名 + **解析后立即删除**
+- **部署时必须屏蔽 `data/` 目录**，否则配置、名单、卷王账密可被直接下载：
+
+```nginx
+# nginx 不读 .htaccess，必须显式配置
+location ^~ /data/ {
+    deny all;
+    return 404;
+}
+```
+
+详见 `docs/security/hardening.md`。
 
 ## 部署
 
@@ -76,7 +105,8 @@ Windows 也可双击 `启动平台.bat`。
 - **平台启动时不预设任何名单**，请通过右上角 **名单管理** 上传你自己的名单（`.xlsx` / `.csv`）。
 - 名单文件可包含「学号」「姓名」两列，**「班级」为可选列**；含班级时，成绩明细会显示班级列并支持按班级筛选（一份考试涉及多个班级时很实用）。
 - 上传方式：名单管理 → 点击或拖拽文件 → 选择覆盖 / 追加 → **保存名单**；也可手动增 / 删 / 改。
-- 名单数据保存在 `data/roster.json`。
+- 上传文件仅用于解析，落盘后**立即删除**，不会残留在 `data/uploads/`。
+- 名单数据保存在 SQLite `data/ny.db`（无 `pdo_sqlite` 时回落到 `data/roster.json`）。
 
 ## 目录结构
 
@@ -91,16 +121,18 @@ ny-exam-platform/
 │  ├─ Roster.php              学号名单管理（xlsx/csv 导入与持久化）
 │  └─ XlsxReader.php          零依赖 XLSX 读取器
 ├─ assets/                    前端样式与脚本
-├─ data/                      配置、名单、令牌缓存（需可写）
-└─ tools/                     开发辅助（PHP 语法校验脚本）
+├─ data/                      配置、名单、SQLite 库、令牌缓存（需可写，且必须禁止 Web 直接访问）
+├─ docs/                      VitePress 文档站
+├─ tests/                     PHP 自测 + 一键运行脚本
+└─ tools/                     开发辅助（mock 服务、e2e 测试）
 ```
 
 ## 统计口径与显示说明
 
 - **班级联动统计**：顶部「班级」下拉选择某一班级后，统计卡片（总人数 / 已提交 / 缺考 / 提交率 / 平均分 / 合格率 / 最高分 / 最低分 / 平均用时）与成绩明细、缺考名单都只统计该班级；选「全部班级」则统计整体。切换班级在本地即时重算，不额外请求服务器。
 - **面板计数随班级**：选择班级后，成绩明细标题右侧的「共 X 人已提交 · 名单 X 人」、缺考名单标题右侧的「共 X 人」也都只统计该班级（不再用全部班级的数据）。
-- **每套试卷独立满分**：不同试卷满分不同，可在「设置 → 满分」中按当前选中的试卷单独设置，保存后仅作用于该试卷；未选中试卷时设置的满分作为所有试卷的默认值。合格率按「成绩 ≥ 满分 × 60%」计算。
-- **合格率**：成绩 ≥ 满分 × 60% 视为合格（满分见上）。
+- **每套试卷独立满分 / 合格率 / 免考**：在主页面「试卷设置」里为**当前选中的试卷**单独设置，试卷之间互相隔离；未设置时回落到「设置」里的全局默认值。
+- **合格率**：成绩 ≥ 满分 × 合格率阈值 视为合格；阈值全局默认 60%，可在「试卷设置」里按卷覆盖，卡片标题会实时显示当前阈值。
 - **平均用时不换行**：平均用时（如「9 分 55 秒」）强制单行显示，避免「秒」字换行。
 - **成绩明细不再显示每人的「状态」列**：缺考人员统一在「缺考名单」面板查看，成绩明细只保留学号 / 姓名 / 班级 / 成绩 / 提交时间 / 考试时长。
 - **新增数据标记**：每次刷新后，相较上一次新出现的提交（按学号判断）整行显示绿色底纹，方便一眼看出谁刚交卷；首次加载不标记。