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； 看板顶栏窄屏下拉与按钮换行，消除横向滚动
5.0 KiB
5.0 KiB
架构与目录
技术栈
- 后端：PHP 8（过程式 + 少量静态类），零 Composer 依赖
- 前端：原生 HTML / CSS / JavaScript（无框架、无构建步骤）
- 存储：SQLite（PDO），缺失
pdo_sqlite时自动降级为 JSON 文件 - 外部依赖：仅卷王（SurveyKing）开放 API
目录结构
ny-exam-platform/
├─ index.php 主系统页面（服务端渲染骨架 + 前端挂载）
├─ dashboard.php 数据看板页面
├─ draw.php 随机抽取页面
├─ login.php / logout.php 登录与登出
├─ api.php 所有后端接口（单一入口，?action=xxx）
├─ bootstrap.php 常量、自动加载、配置读写、CSRF、限流、公共函数
├─ lib/
│ ├─ SurveyKingClient.php 卷王 API 客户端（登录 / 令牌 / 项目 / 答卷）
│ ├─ DataService.php 数据组装：姓名→学号匹配、统计、去重
│ ├─ Roster.php 名单管理（xlsx/csv 导入、列识别、持久化）
│ ├─ Db.php SQLite 封装（三方言兼容的 DDL 与 upsert）
│ ├─ DataCache.php 结果缓存（TTL + flock 防惊群）
│ ├─ XlsxReader.php 零依赖 XLSX 读取
│ └─ XlsxWriter.php 零依赖 XLSX 写入（支持多工作表）
├─ assets/ style.css / app.js / draw.js
├─ data/ 运行时数据（需可写，已 gitignore）
│ ├─ ny.db SQLite 主库
│ ├─ config.json 配置（文件备份）
│ ├─ roster.json 名单（文件备份）
│ ├─ project_config.json 每卷配置（文件备份）
│ ├─ cache/ 卷王令牌 + 结果缓存
│ └─ uploads/ 导入临时目录（解析后即删）
├─ tests/ PHP 自测 + 一键运行脚本
├─ tools/ mock 服务与 Node e2e
└─ docs/ 本文档站（VitePress）
请求流程
浏览器 ──► api.php?action=data
│
├─► ny_is_auth() 未登录 → 401 + {auth:false}
├─► 写操作 → ny_csrf_ok() 校验
├─► ny_build_data()（带结果缓存）
│ └─► DataService::build()
│ ├─► SurveyKingClient::listAnswers() 拉卷王答卷
│ ├─► Roster::all() 读名单
│ ├─► 姓名 → 学号匹配
│ ├─► dedupe（决定代表成绩）
│ └─► 统计
└─► ny_resolve_score_cfg() 解析本卷满分与合格率
└─► ny_ok(JSON)
关键设计
单一入口 + 白名单
api.php 用 switch ($action) 分发。所有写操作集中在 $WRITE_ACTIONS 白名单里统一校验 CSRF，
新增写接口时必须把 action 加进该数组。
配置双写
ny_save_config() 同时写 SQLite 与 data/config.json；ny_load_config() 优先读库，
库为空时自动从文件迁回。这样即使数据库不可用，也不会静默回落到出厂的 admin/123456。
只在连接信息变化时才重新登录
config_save 会比较 base_url / api_prefix / username / password / verify_ssl 五项，
只有真变化才删除令牌缓存并重新 ping。修改满分、布局、刷新间隔不会打断数据刷新。
结果缓存
DataCache 以「配置 + 名单指纹 + 试卷 ID」为键缓存构建结果，默认 TTL 15 秒；
用 flock 防止并发惊群。名单指纹（Roster::fingerprint()）参与缓存键，改名单会自动失效。
点「立即刷新」带 force=1 跳过缓存。
内存防护
拉取卷王答卷时单页条数被夹在 20–200 之间，避免单页响应过大导致
json_decode 一次性撑爆内存（曾出现过 128M 耗尽的问题）。
零依赖 XLSX
- 读取：
XlsxReader直接解析 ZIP（优先ZipArchive，无zip扩展时用内置实现）与 XML； - 写入：
XlsxWriter手写 ZIP（stored 模式），单元格统一写共享字符串 +numFmtId=49文本样式，天然防公式注入、防长学号变科学计数法； renderMulti()支持多工作表，表名做 31 字截断与(2)去重。
前端要点
| 主题 | 实现 |
|---|---|
| 大表格 | 虚拟滚动（占位行 + 可视区渲染），ROW_H=41，overscan 12 |
| 自动刷新 | setTimeout 链 + 失败指数退避；visibilitychange 时后台暂停 |
| 提示 | 顶部 Toast 系统，showAlert(msg, type) 4 种颜色，最多 5 条 |
| 全屏 | document.exitFullscreen()（注意不是 documentElement） |
| 事件绑定 | 表格行点击用事件委托挂在 #tbody 上，避免内联 onclick 作用域问题 |