数据库

.env.example

@@ -0,0 +1,20 @@
+# 本地开发（默认）
+NODE_ENV=development
+DATABASE_CLIENT=sqlite
+SQLITE_PATH=./data/exam.sqlite
+HOST=127.0.0.1
+PORT=4173
+
+# MySQL 8.4 生产环境：将 DATABASE_CLIENT 改为 mysql，并配置以下变量。
+# NODE_ENV=production
+# DATABASE_CLIENT=mysql
+# MYSQL_HOST=127.0.0.1
+# MYSQL_PORT=3306
+# MYSQL_USER=exam_app
+# MYSQL_PASSWORD=replace-with-a-strong-password
+# MYSQL_DATABASE=exam_information
+# MYSQL_CONNECTION_LIMIT=10
+# HOST=0.0.0.0
+
+# 也可以用单个连接地址替代全部 MYSQL_* 连接参数：
+# DATABASE_URL=mysql://exam_app:password@127.0.0.1:3306/exam_information

.gitignore

@@ -1,3 +1,8 @@
 data/db.json
 data/test-db.json
+data/*.sqlite
+data/*.sqlite-shm
+data/*.sqlite-wal
+node_modules/
+.env
 *.log

README.md

@@ -1,6 +1,6 @@
 # 衡准 · 考试信息管理系统
 
-一个完整可运行的双角色考试信息管理系统，使用零依赖 Node.js 后端和 JSON 持久化，开箱即可运行。
+一个完整可运行的双角色考试信息管理系统，使用 Node.js 后端；本地开发采用 SQLite，生产环境支持 MySQL 8.4。
 
 ## 已实现功能
 
@@ -37,22 +37,73 @@
 - PBKDF2 加盐密码哈希
 - HttpOnly、SameSite 登录 Cookie
 - 服务端角色权限校验
-- JSON 文件持久化
+- SQLite / MySQL 8.4 双数据库持久化
+- 规范关系模型、外键、唯一约束和业务索引
+- 业务写入与审计日志使用原子事务提交
 - 关键管理操作审计日志
 - 桌面端与移动端响应式布局
 - 零第三方运行时依赖
 
 ## 运行
 
-需要 Node.js 18 或更高版本。
+需要 Node.js 22.5 或更高版本（SQLite 使用 Node.js 内置驱动）。
 
 ```powershell
+npm install
 npm start
 ```
 
 打开 <http://127.0.0.1:4173>。
 
-首次运行会自动创建 `data/db.json`。
+本地开发无需额外配置，首次运行会自动创建 `data/exam.sqlite` 和完整关系型数据库结构。当前处于开发阶段，不兼容或导入旧版 JSON/单表数据库；更改表结构后请删除本地 SQLite 文件并重新启动。
+
+## 数据库配置
+
+应用根据 `DATABASE_CLIENT` 使用不同数据库。未设置时，开发/测试环境默认 `sqlite`，`NODE_ENV=production` 默认 `mysql`。
+
+### 本地 SQLite
+
+```powershell
+$env:DATABASE_CLIENT = 'sqlite'
+$env:SQLITE_PATH = './data/exam.sqlite'
+npm start
+```
+
+`SQLITE_PATH` 可省略，默认路径就是 `./data/exam.sqlite`。
+
+### 生产 MySQL 8.4
+
+先在 MySQL 8.4 中创建数据库和最小权限账号：
+
+```sql
+CREATE DATABASE exam_information CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
+CREATE USER 'exam_app'@'%' IDENTIFIED BY 'replace-with-a-strong-password';
+GRANT SELECT, INSERT, UPDATE, CREATE ON exam_information.* TO 'exam_app'@'%';
+```
+
+启动应用时设置连接信息，应用会自动创建以下关系表并初始化演示数据：
+
+- `users`、`candidate_profiles`
+- `exams`、`exam_subjects`
+- `registrations`、`registration_subjects`、`admit_cards`
+- `results`、`notices`、`audit_logs`
+- `organization`、`schema_metadata`
+
+所有关联均有外键约束，账号、证件号、考试代码、报名关系、准考证号和单科成绩均有对应唯一约束。
+
+```powershell
+$env:NODE_ENV = 'production'
+$env:DATABASE_CLIENT = 'mysql'
+$env:MYSQL_HOST = '127.0.0.1'
+$env:MYSQL_PORT = '3306'
+$env:MYSQL_USER = 'exam_app'
+$env:MYSQL_PASSWORD = 'replace-with-a-strong-password'
+$env:MYSQL_DATABASE = 'exam_information'
+$env:HOST = '0.0.0.0'
+npm start
+```
+
+也可以只设置标准连接地址 `DATABASE_URL=mysql://user:password@host:3306/database`。完整模板见 `.env.example`；项目不会自动加载 `.env` 文件，部署平台应将这些值作为进程环境变量注入。
 
 ## 演示账号
 
@@ -67,7 +118,7 @@ npm start
 npm test
 ```
 
-测试使用独立临时数据库，覆盖注册、审核、多科目报名、准考证生成与下载、通知发布、成绩发布和权限隔离完整流程。
+测试使用独立临时 SQLite 数据库，覆盖注册、审核、多科目报名、准考证生成与下载、通知发布、成绩发布和权限隔离完整流程。
 
 ## 项目结构
 
@@ -76,6 +127,8 @@ index.html              页面入口
 styles.css              公共首页、考生端、管理端响应式样式
 app.js                  前端路由、状态和业务交互
 server.mjs              HTTP 服务、认证、权限与全部业务 API
+database.mjs            分表结构、SQLite / MySQL 适配与事务仓储
 tests/system.test.mjs   端到端系统测试
-data/db.json            运行后生成的持久化数据
+data/exam.sqlite        本地运行后生成的 SQLite 数据库
+.env.example            开发与生产环境变量模板
 ```