ny-exam-platform/docs/dev/database.md

数据存储（SQLite）

平台使用 SQLite 单文件数据库 data/ny.db，零配置、无需额外服务。

启用条件与降级

Db::isConfigured()   // 是否有 pdo_sqlite 扩展
Db::isConnected()    // 是否真的连上了
Db::lastError()      // 失败原因

环境	行为
有 pdo_sqlite	使用 data/ny.db（同时继续双写 JSON 文件作为备份）
无 pdo_sqlite	整体降级为 JSON 文件存储，功能不受影响

前端可通过 config_get 返回的 storage（db / file）判断当前用的是哪种。

连接参数

连接建立时施加的 PRAGMA：

PRAGMA journal_mode = WAL;      -- 读写并发
PRAGMA synchronous  = NORMAL;
PRAGMA busy_timeout = 5000;     -- 写锁等待 5 秒
PRAGMA foreign_keys = ON;

连接每请求只尝试一次，失败后返回 null 而非抛异常，保证上层能优雅降级。

表结构

所有建表 / 加列都是幂等的（CREATE TABLE IF NOT EXISTS + PRAGMA table_info 探测后 ALTER TABLE），可重复执行。

ny_settings — 全局配置

列	类型	说明
k	TEXT PK	键，目前只有 config
v	TEXT	整份配置的 JSON
updated_at	—	更新时间

ny_roster — 学号名单

列	类型	说明
sid	TEXT PK	学号
name	TEXT	姓名
cls	TEXT	班级
grp	TEXT	组别
login	TEXT	登陆账号（仅用于抽取页白名单导出）
sort	INTEGER	排序

login 列是后期加入的，旧库会在启动时自动 ALTER TABLE ADD COLUMN（幂等）。

ny_project_config — 每卷独立配置

列	类型	说明
project_id	TEXT PK	卷王试卷 ID
config_json	TEXT	{ full_score, pass_rate, exempt[] }
updated_at	—	更新时间

迁移策略

首次在有 SQLite 的环境运行时：

1. ny_settings 为空 → 从 data/config.json 迁入；
2. ny_roster 为空 → 从 data/roster.json 迁入（Roster::migrateFileToDbOnce()）；
3. 每卷配置同理从 data/project_config.json 迁入。

迁移只发生在目标表为空时，不会覆盖已入库的数据；重复执行安全。

读写路径

数据	主存储	备份
配置	ny_settings['config']	data/config.json
名单	ny_roster	data/roster.json
每卷配置	ny_project_config	data/project_config.json
成绩快照	文件系统 data/snapshots/	—
结果缓存	文件系统 data/cache/	—
卷王令牌	文件系统 data/cache/token.json	—

ny_save_config() 双写：先写库，再写文件。这样即使数据库突然不可用，也不会静默回落到出厂默认值。

维护

# 备份（推荐：直接复制文件）
cp data/ny.db data/ny.db.bak

# 完整性检查
php -r '$p=new PDO("sqlite:data/ny.db"); var_dump($p->query("PRAGMA integrity_check")->fetchAll());'

# 手动查看名单
php -r '$p=new PDO("sqlite:data/ny.db"); print_r($p->query("SELECT * FROM ny_roster LIMIT 5")->fetchAll(PDO::FETCH_ASSOC));'

::: tip 命令行加载扩展 PHP CLI 常常不加载 Web 端已启用的扩展，需要显式指定：

php -d extension_dir="C:/php/ext" -d extension=pdo_sqlite script.php

:::

相关

• 架构与目录
• 接口一览