135 lines
4.3 KiB
Markdown
135 lines
4.3 KiB
Markdown
# 衡准 · 考试信息管理系统
|
||
|
||
一个完整可运行的双角色考试信息管理系统，使用 Node.js 后端；本地开发采用 SQLite，生产环境支持 MySQL 8.4。
|
||
|
||
## 已实现功能
|
||
|
||
### 公开服务首页
|
||
|
||
- 通知公告首页展示与详情阅读
|
||
- 已发布考试、报名时间、考试时间和科目展示
|
||
- 考试服务办理流程说明
|
||
- 考生注册与双角色登录入口
|
||
|
||
### 考生中心
|
||
|
||
- 考生自主注册、登录和实名资料维护
|
||
- 资料审核状态与管理员审核意见
|
||
- 查看开放考试并自主选择多个报考科目
|
||
- 查看报名、缴费和审核状态
|
||
- 准考证生成状态、开放时间与下载
|
||
- 已发布成绩查询
|
||
- 通知公告中心
|
||
|
||
### 管理后台
|
||
|
||
- 考务指标与审计日志
|
||
- 考生资料审核、通过或退回修改
|
||
- 考试报名及科目审核
|
||
- 创建考试、配置报名/考试/准考证时间与多个科目
|
||
- 通知发布、草稿、撤回及首页置顶
|
||
- 为审核通过的报名生成准考证号、考点、考场和座位
|
||
- 单科成绩录入、等级计算与发布控制
|
||
- 管理员与考生接口权限隔离
|
||
|
||
### 系统能力
|
||
|
||
- PBKDF2 加盐密码哈希
|
||
- HttpOnly、SameSite 登录 Cookie
|
||
- 服务端角色权限校验
|
||
- SQLite / MySQL 8.4 双数据库持久化
|
||
- 规范关系模型、外键、唯一约束和业务索引
|
||
- 业务写入与审计日志使用原子事务提交
|
||
- 关键管理操作审计日志
|
||
- 桌面端与移动端响应式布局
|
||
- 零第三方运行时依赖
|
||
|
||
## 运行
|
||
|
||
需要 Node.js 22.5 或更高版本（SQLite 使用 Node.js 内置驱动）。
|
||
|
||
```powershell
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
打开 <http://127.0.0.1:4173>。
|
||
|
||
本地开发无需额外配置，首次运行会自动创建 `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` 文件，部署平台应将这些值作为进程环境变量注入。
|
||
|
||
## 演示账号
|
||
|
||
| 角色 | 账号 | 密码 |
|
||
| --- | --- | --- |
|
||
| 管理员 | `admin` | `Admin123!` |
|
||
| 考生 | `13800138000` | `Candidate123!` |
|
||
|
||
## 自动化测试
|
||
|
||
```powershell
|
||
npm test
|
||
```
|
||
|
||
测试使用独立临时 SQLite 数据库，覆盖注册、审核、多科目报名、准考证生成与下载、通知发布、成绩发布和权限隔离完整流程。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
index.html 页面入口
|
||
styles.css 公共首页、考生端、管理端响应式样式
|
||
app.js 前端路由、状态和业务交互
|
||
server.mjs HTTP 服务、认证、权限与全部业务 API
|
||
database.mjs 分表结构、SQLite / MySQL 适配与事务仓储
|
||
tests/system.test.mjs 端到端系统测试
|
||
data/exam.sqlite 本地运行后生成的 SQLite 数据库
|
||
.env.example 开发与生产环境变量模板
|
||
```
|