nxxy335
d05fd4a9b5
导出-每次考试/多考试对比： - 合格次数阈值等标记项抽为常显区块，三类成绩表共用 - 附缺考名单扩展到多考试导出（取所选考试全都没交的人） - 块表每场固定2列（成绩+合并空位），修复漏推空串导致的整行左移/串列 - 列宽按实际内容估算，合并区空位只给最小宽度 - 合格次数始终显示实际次数(含0)，仅 ≥ 阈值标绿底 - 打印标题改为「成绩明细」，缺考名单分页单独成页 - 打印样式加 print-color-adjust:exact，绿底/红字可正常印出 数据大屏： - ?class= 班级大屏免登录公开访问，接口侧放行并按班级裁剪后回传 - 单班大屏移除退出按钮，仅首页保留 - 修复红绿判定真bug：membersTable 误用 window.DASH(DASH为let声明取不到) 改为 scoreGrade() 直接读自由变量，按后台合格率正确判红/黄/绿 测试/样例/文档同步更新，全量回归通过。
109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
# 架构与目录
|
||
|
||
## 技术栈
|
||
|
||
- **后端**：PHP 8（过程式 + 少量静态类），零 Composer 依赖
|
||
- **前端**：原生 HTML / CSS / JavaScript（无框架、无构建步骤）
|
||
- **存储**：SQLite（PDO），缺失 `pdo_sqlite` 时自动降级为 JSON 文件
|
||
- **外部依赖**：仅卷王（SurveyKing）开放 API
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
ny-exam-platform/
|
||
├─ index.php 主系统页面（服务端渲染骨架 + 前端挂载）
|
||
├─ dashboard.php 数据大屏：首页（班级入口）+ ?class= 单班大屏（锁后退）
|
||
├─ 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` 作用域问题 |
|
||
|
||
## 相关
|
||
|
||
- [接口一览](./api.md)
|
||
- [数据存储（SQLite）](./database.md)
|
||
- [测试](./testing.md)
|