优化数据库读写

.env.example

@@ -48,3 +48,7 @@ PUBLIC_SITE_FOOTER_NOTICE=本平台展示数据仅用于系统演示
 
 # 也可以用单个连接地址替代全部 MYSQL_* 连接参数：
 # DATABASE_URL=mysql://exam_app:password@127.0.0.1:3306/exam_information
+# 全量数据库状态快照的最长复用时间（毫秒）。应用内写入会立即失效；MySQL 外部直写最长延迟此时间可见。
+DATABASE_STATE_CACHE_TTL_MS=30000
+# Redis 未配置或暂不可用时，本机响应缓存的最大条目数。
+LOCAL_CACHE_MAX_ENTRIES=200

README.md

@@ -231,7 +231,9 @@ npm start
 
 ### Redis 缓存（可选）
 
-配置 `REDIS_URL` 后，应用会缓存公开首页、已发布公告详情和每名考生的已发布成绩查询。公开数据默认 TTL 为 60 秒，成绩默认 TTL 为 24 小时；成绩录入/发布、批量导入、考试归档和成绩复议会自动使成绩缓存失效，超级管理员也可以在成绩管理中心手动刷新全部成绩缓存。Redis 在启动或运行期间不可用时，接口会自动回源数据库，不影响登录、报名和管理功能。
+配置 `REDIS_URL` 后，应用会缓存公开首页、已发布公告详情和每名考生的已发布成绩查询。公开数据默认 TTL 为 60 秒，成绩默认 TTL 为 24 小时；成绩录入/发布、批量导入、考试归档和成绩复议会自动使成绩缓存失效，超级管理员也可以在成绩管理中心手动刷新全部成绩缓存。Redis 未配置或暂时不可用时，应用会自动切换到有界本机缓存（默认最多 200 条），避免热点接口反复回源；写入后的失效语义保持不变。
+
+数据库关系表会按写入版本复用进程内只读快照，避免每个请求重复扫描并转换全部业务表。应用自身写入会立即使快照失效；SQLite 还通过 `PRAGMA data_version` 检测其他连接的提交，MySQL 外部直写默认最多延迟 30 秒可见。可通过 `DATABASE_STATE_CACHE_TTL_MS` 调整 MySQL 快照时间，通过 `LOCAL_CACHE_MAX_ENTRIES` 控制本机接口缓存上限。
 
 ```powershell
 $env:REDIS_URL = 'redis://127.0.0.1:6379/0'

package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "start": "node server.mjs",
-    "test": "node tests/client-auth.test.mjs && node tests/cache.test.mjs && node tests/document-verification.test.mjs && node tests/admission.test.mjs && node tests/seed.test.mjs && node tests/system.test.mjs",
+    "test": "node tests/client-auth.test.mjs && node tests/api-dedup.test.mjs && node tests/cache.test.mjs && node tests/state-cache.test.mjs && node tests/document-verification.test.mjs && node tests/admission.test.mjs && node tests/seed.test.mjs && node tests/system.test.mjs",
     "test:cache": "node tests/cache.test.mjs",
     "reset-db": "node scripts/reset-dev-database.mjs",
     "seed-test-data": "node scripts/import-test-data.mjs",