教育考试签到与补助管理系统

项目简介

本系统是为教育考试中心开发的考务人员签到与补助管理平台,包含微信小程序端和Spring Boot后端服务。系统支持考务人员在考试期间进行地理位置签到,并上传税务发票申领补助。

核心功能

用户管理

✅ 微信小程序一键登录(基于openid)
✅ 用户注册(姓名、性别、身份证号、单位类型、单位名称、考务角色)
✅ 身份证号严格校验(18位格式+校验码算法)
✅ JWT token认证(有效期7天)

签到功能

✅ 实时地理位置获取
✅ Haversine公式精确距离计算
✅ 500米范围自动校验
✅ 考试时间范围校验
✅ 每日签到限制(数据库唯一索引保证)
✅ 显示最近考点名称和距离

发票管理

✅ PDF格式发票上传(最大5MB)
✅ 同一考试多次上传自动覆盖旧文件
✅ MinIO对象存储
✅ 预签名URL安全下载(15分钟有效期)
✅ 显示上传时间和更新时间

考试管理

✅ 考试列表查询
✅ 考试详情展示
✅ 考点信息管理
✅ 考试与考点关联

公告系统

✅ 最新公告列表
✅ 公告详情查看
✅ 分页查询支持

技术栈

前端(微信小程序)

微信小程序原生开发(WXML + WXSS + JavaScript)
TDesign for MiniProgram UI组件库
微信登录(wx.login)
地理位置API(wx.getLocation)

后端

Java 17
Spring Boot 3.2.0
Spring Data JPA
MySQL 8.0+
MinIO (对象存储)
JWT (用户认证)

项目结构

exam-manager/
├── backend/                           # Spring Boot后端项目
│   ├── src/main/java/com/examcenter/
│   │   ├── config/                    # 配置类
│   │   ├── controller/                # 控制器层
│   │   ├── dto/                       # 数据传输对象
│   │   ├── entity/                    # 实体类
│   │   ├── enums/                     # 枚举类
│   │   ├── exception/                 # 异常类
│   │   ├── repository/                # 数据访问层
│   │   ├── service/                   # 服务层
│   │   └── util/                      # 工具类
│   ├── src/main/resources/
│   │   └── application.yml            # 配置文件
│   └── pom.xml                        # Maven依赖配置
├── miniprogram/                       # 微信小程序项目
│   ├── pages/                         # 页面目录
│   │   ├── index/                     # 首页(考试列表+公告)
│   │   ├── exam-detail/               # 考试详情+签到
│   │   ├── register/                  # 用户注册
│   │   ├── my/                        # 个人中心
│   │   ├── invoice/                   # 发票管理
│   │   └── announcement/              # 公告详情
│   ├── utils/                         # 工具函数
│   │   ├── api.js                     # API请求封装
│   │   ├── location.js                # 地理位置计算
│   │   └── validator.js               # 数据校验
│   ├── app.js                         # 小程序入口
│   ├── app.json                       # 全局配置
│   └── app.wxss                       # 全局样式
├── database/                          # 数据库脚本
│   └── schema.sql                     # 建表SQL
└── README.md                          # 项目说明

快速开始

环境要求

Java 17+
Maven 3.6+
MySQL 8.0+
MinIO服务器
Node.js 14+ (用于小程序开发工具)
微信开发者工具

后端部署

1. 创建数据库

mysql -u root -p < database/schema.sql

2. 配置环境变量

在backend/src/main/resources/application.yml中配置或设置环境变量:

export DB_PASSWORD=your_db_password
export MINIO_ENDPOINT=http://localhost:9000
export MINIO_ACCESS_KEY=your_minio_key
export MINIO_SECRET_KEY=your_minio_secret
export WECHAT_APP_ID=your_wechat_appid
export WECHAT_APP_SECRET=your_wechat_appsecret
export JWT_SECRET=your_jwt_secret_key

3. 编译运行

cd backend
mvn clean package
java -jar target/exam-checkin-system-1.0.0.jar

后端服务将启动在 http://localhost:8080

小程序部署

1. 安装TDesign组件库

cd miniprogram
npm install tdesign-miniprogram

2. 配置小程序

在miniprogram/utils/api.js中配置后端API地址:

const BASE_URL = 'https://your-domain.com/api'

3. 使用微信开发者工具打开小程序项目

填入AppID
配置服务器域名(request、uploadFile、downloadFile)
上传代码到微信后台
提交审核

API接口文档

用户模块

接口	方法	说明	是否需要Token
`/api/user/login`	POST	微信登录(code换token)	❌
`/api/user/register`	POST	用户注册	❌
`/api/user/profile`	GET	获取个人信息	✅

考试模块

接口	方法	说明	是否需要Token
`/api/exam/list`	GET	获取考试列表	✅
`/api/exam/{examId}`	GET	获取考试详情	✅
`/api/exam/{examId}/sites`	GET	获取考点列表	✅

签到模块

接口	方法	说明	是否需要Token
`/api/checkin`	POST	执行签到(需传入经纬度)	✅

发票模块

接口	方法	说明	是否需要Token
`/api/invoice/upload`	POST	上传发票PDF文件	✅
`/api/invoice/status/{examId}`	GET	查询发票状态	✅

公告模块

接口	方法	说明	是否需要Token
`/api/announcement/latest`	GET	获取最新公告	✅
`/api/announcement/list`	GET	分页查询公告	✅
`/api/announcement/{id}`	GET	获取公告详情	✅

数据模型

核心表结构

user - 用户表

主键: id
字段: openid(微信唯一标识)、姓名、性别、身份证号、单位类型、单位名称、考务角色
唯一约束: openid、身份证号

exam - 考试表

主键: id
字段: 考试名称、开始日期、结束日期、描述
索引: (end_date, start_date) 用于高效查询进行中的考试

exam_site - 考点表

主键: id
字段: 考点名称、地址、经度、维度、考试ID
外键: exam_id 级联删除

checkin_record - 签到记录表

主键: id
字段: 用户ID、考试ID、考点ID、签到日期、签到时间、经度、维度、距离
唯一约束: (user_id, exam_id, checkin_date) 防止同一天多次签到
外键: user_id, exam_id, exam_site_id 级联删除

invoice - 发票表

主键: id
字段: 用户ID、考试ID、文件名、文件路径、上传时间、更新时间
唯一约束: (user_id, exam_id) 确保每场考试只保留一个发票
外键: user_id, exam_id 级联删除

announcement - 公告表

主键: id
字段: 标题、内容、发布时间、是否有效
索引: (is_active, publish_time) 用于高效查询有效公告

业务规则

签到规则

签到有效距离: 用户位置距离任一考点 ≤ 500米
签到有效时间: 当前日期在考试开始和结束日期之间
每日签到限制: 每个用户每场考试每天只能签到一次
距离计算: 使用Haversine公式,地球半径取6371公里

发票上传规则

文件格式: 仅支持PDF格式
文件大小: 最大5MB
存储策略: 同一考试可多次上传,保留最新文件并删除旧文件
存储路径: invoices/{examId}/{userId}_{timestamp}.pdf

用户认证

首次登录: 通过微信wx.login获取code换取openid,跳转注册页
已注册用户: 自动生成JWT token(有效期7天)
注册信息: 一旦提交不可修改,需联系管理员

安全性设计

✅ 身份证号正则校验
✅ JWT token认证
✅ 敏感信息环境变量配置
✅ MinIO文件访问预签名URL(15分钟有效期)
✅ 数据库唯一索引防重复签到
✅ HTTPS传输(生产环境)

测试数据

系统已内置测试数据:

2025年全国硕士研究生招生考试(2025-12-21 ~ 2025-12-23)
2025年普通高等学校招生全国统一考试(2025-06-07 ~ 2025-06-09)
北京大学考点、清华大学考点、北京师范大学考点

开发说明

后端开发

项目使用Spring Boot 3.x,采用MVC三层架构:

Controller层: 处理HTTP请求,参数校验
Service层: 业务逻辑实现
Repository层: 数据访问(Spring Data JPA)

小程序开发

使用TDesign组件库保持UI一致性
工具函数封装(api.js, location.js, validator.js)
页面间通过URL参数传递数据

注意事项

数据库连接: 确保MySQL服务正常运行,字符集为utf8mb4
MinIO配置: 需提前创建bucket: exam-invoices
微信配置: 需在微信公众平台配置服务器域名白名单
生产环境: 务必修改JWT密钥、数据库密码等敏感配置
位置权限: 小程序需用户授权地理位置权限

技术亮点

1. 精确的地理距离计算

采用Haversine公式计算地球表面两点间的距离，精度可达米级：

// DistanceUtil.java
public static double calculateDistance(double lat1, double lon1, double lat2, double lon2) {
    double R = 6371000; // 地球半径（米）
    // ... Haversine公式实现
}

2. 发票智能覆盖策略

数据库唯一索引 (user_id, exam_id) 确保每场考试只保留一个发票
上传新文件时自动删除旧文件，避免存储浪费
MinIO事务性操作确保数据一致性

3. 安全的身份证号校验

实现完整的身份证号校验算法：

18位长度校验
格式正则校验
校验码算法验证（ISO 7064:1983.MOD 11-2）

4. 防重复签到设计

数据库唯一索引 (user_id, exam_id, checkin_date) 从根本上防止重复签到
无需应用层复杂逻辑，性能更优

exam-management-system