人脸识别考勤系统 Qt 客户端说明文档
1. 项目简介
本项目是基于 Qt 6 Quick/QML 开发的人脸识别考勤系统客户端，用于连接考勤服务端，完成考勤记录查看、筛选导出、统计分析、签到时段配置、学生和班级名称映射、人脸照片映射管理等功能。
程序入口为 main.cpp。启动后创建 QGuiApplication 和 AppController，并将 AppController 通过 QML 上下文属性 appController 暴露给 qml/Main.qml。界面由 QML 实现，业务逻辑、网络请求、数据模型、配置保存和 CSV 导出由 C++ 实现。
默认服务端地址：
http://27.106.113.205:8082
2. 技术栈
- 语言：C++17、QML
- 框架：Qt 6.2 或更高版本
- Qt 模块：Core、Gui、Qml、Quick、QuickControls2、Network
- 构建系统：CMake 3.16 或更高版本
- 加密处理：AES-128-CBC，相关代码位于
src/CryptoUtils.cpp
3. 当前目录结构
rewrite_qt/
├── CMakeLists.txt
├── README.md
├── main.cpp
├── android/
│ └── res/
│ ├── mipmap-mdpi/ic_launcher.png
│ ├── mipmap-hdpi/ic_launcher.png
│ ├── mipmap-xhdpi/ic_launcher.png
│ ├── mipmap-xxhdpi/ic_launcher.png
│ └── mipmap-xxxhdpi/ic_launcher.png
├── assets/
│ ├── favicon.ico
│ ├── favicon-16x16.png
│ ├── favicon-32x32.png
│ ├── favicon-48x48.png
│ ├── favicon-64x64.png
│ ├── favicon-128x128.png
│ ├── favicon-192x192.png
│ └── favicon-256x256.png
├── cmake/
│ ├── app_icon.rc.in
│ └── rewrite_qt.desktop.in
├── qml/
│ └── Main.qml
└── src/
├── ApiClient.h/.cpp
├── AppController.h/.cpp
├── AttendanceTypes.h
├── CryptoUtils.h/.cpp
├── FaceListModel.h/.cpp
├── MappingListModel.h/.cpp
├── RecordListModel.h/.cpp
├── StatisticsListModel.h/.cpp
├── TimeSlotListModel.h/.cpp
└── crypto/tiny_aes.hpp
4. 构建与运行
4.1 环境要求
需要安装：
- Qt 6.2+
- CMake 3.16+
- 支持 C++17 的编译器，例如 MSVC、MinGW、Clang 或 GCC
Android 构建还需要配置 Qt for Android、Android SDK、Android NDK 和 JDK。
4.2 使用 Qt Creator
- 打开项目根目录下的
CMakeLists.txt。 - 选择合适的 Qt Kit，例如 Desktop Qt 6.x 或 Android Qt 6.x。
- 重新配置 CMake。
- 构建并运行目标
apprewrite_qt。
4.3 使用命令行
Windows 示例：
cmake -S . -B build -DCMAKE_PREFIX_PATH=D:/Qt/6.10.0/mingw_64
cmake --build build
Linux 示例：
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64
cmake --build build
安装到系统路径：
cmake --install build
5. 多平台图标配置
项目已经配置为多平台使用同一套应用图标。
5.1 Windows
Windows exe 图标使用：
assets/favicon.ico
CMake 会在 Windows 构建时根据 cmake/app_icon.rc.in 生成资源文件，并把图标嵌入到可执行文件中。
5.2 桌面运行时图标
main.cpp 会设置应用窗口图标：
QIcon appIcon(QStringLiteral(":/assets/favicon.ico"));
同时会加入多尺寸 PNG 作为回退资源：
assets/favicon-256x256.png
assets/favicon-192x192.png
assets/favicon-128x128.png
assets/favicon-64x64.png
assets/favicon-48x48.png
assets/favicon-32x32.png
assets/favicon-16x16.png
这些图标文件会被加入 Qt 资源系统，路径前缀为 :/assets/...。
5.3 Linux
Linux 安装时会生成 .desktop 文件：
cmake/rewrite_qt.desktop.in
并把不同尺寸的 PNG 安装到：
share/icons/hicolor/{size}x{size}/apps/rewrite_qt.png
.desktop 文件中使用的图标名为：
rewrite_qt
5.4 Android
Android 启动器图标位于：
android/res/mipmap-mdpi/ic_launcher.png
android/res/mipmap-hdpi/ic_launcher.png
android/res/mipmap-xhdpi/ic_launcher.png
android/res/mipmap-xxhdpi/ic_launcher.png
android/res/mipmap-xxxhdpi/ic_launcher.png
对应尺寸：
| 目录 | 尺寸 |
|---|---|
mipmap-mdpi |
48x48 |
mipmap-hdpi |
72x72 |
mipmap-xhdpi |
96x96 |
mipmap-xxhdpi |
144x144 |
mipmap-xxxhdpi |
192x192 |
CMake 中 Android 相关配置：
QT_ANDROID_PACKAGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/android"
QT_ANDROID_APP_NAME "人脸识别考勤系统"
QT_ANDROID_APP_ICON "@mipmap/ic_launcher"
QT_ANDROID_APP_NAME 用于设置 Android 桌面显示名，QT_ANDROID_APP_ICON 用于设置启动图标。
6. 功能说明
6.1 考勤记录
考勤记录页支持：
- 查看总记录数、今日记录数、已加载记录数和当前筛选结果数。
- 按班级、学号、姓名关键字筛选。
- 按今天、最近 7 天、最近 30 天或指定日期范围筛选。
- 导出当前筛选结果为 CSV。
- 清空服务端全部考勤记录。
导出的记录 CSV 字段：
签到时间,班级编号,班级名称,学号,姓名,置信度,状态
6.2 统计分析
统计页基于已加载记录在本地计算，支持：
- 今天、最近 7 天、最近 30 天、本月等快捷范围。
- 自定义统计日期范围。
- 按学生汇总签到次数、今日签到次数、最后签到时间和平均置信度。
- 导出统计结果为 CSV。
导出的统计 CSV 字段：
学号,姓名,总签到次数,今日签到,最后签到时间,平均置信度
6.3 配置中心
配置中心包含：
- 服务端地址配置和连接测试。
- 签到时段新增、编辑、删除、启用和禁用。
- 学号到姓名的映射。
- 班级编号到班级名称的映射。
默认签到时段：
| 名称 | 开始时间 | 结束时间 | 默认状态 |
|---|---|---|---|
| 上午签到 | 08:00 | 09:30 | 启用 |
| 中午签退 | 12:00 | 13:00 | 启用 |
| 下午签到 | 14:00 | 15:00 | 启用 |
| 晚上签退 | 17:00 | 18:30 | 启用 |
6.4 人脸管理
人脸管理页支持：
- 从服务端同步人脸照片 ID。
- 从服务端同步所有学生 ID。
- 展示人脸照片和绑定状态。
- 为人脸 ID 绑定真实学号。
- 保存人脸 ID 与学号映射。
- 删除指定人脸信息，可选择同时删除该学生的考勤记录。
照片访问地址格式：
{serverUrl}/api/face_photo/{id}?ts={timestamp}
ts 参数用于避免缓存导致照片不刷新。
7. 核心模块
| 文件 | 说明 |
|---|---|
main.cpp |
初始化应用、设置应用信息和图标、加载 QML |
qml/Main.qml |
主界面和用户交互 |
src/AppController.* |
应用业务中枢，连接 QML、模型和网络客户端 |
src/ApiClient.* |
HTTP API 客户端 |
src/*ListModel.* |
暴露给 QML 的列表模型 |
src/AttendanceTypes.h |
业务数据结构 |
src/CryptoUtils.* |
AES-128-CBC 解密工具 |
src/crypto/tiny_aes.hpp |
AES 底层实现 |
8. 服务端 API
客户端会把服务端地址与 /api 前缀拼接后访问接口。
| 方法 | 路径 | 用途 |
|---|---|---|
GET |
/api/records?limit={limit}&offset={offset} |
获取考勤记录 |
GET |
/api/statistics |
获取总数、今日数和服务端时间 |
POST |
/api/clear |
清空全部记录 |
DELETE |
/api/record?timestamp={timestamp}&student_id={studentId} |
删除单条记录 |
GET |
/api/timeslots |
获取签到时段 |
POST |
/api/timeslots |
保存签到时段 |
GET |
/api/mapping_config |
获取学生和班级映射 |
POST |
/api/mapping_config |
保存学生和班级映射 |
GET |
/api/face_id_mapping |
获取人脸 ID 到学号映射 |
POST |
/api/face_id_mapping |
保存人脸 ID 到学号映射 |
GET |
/api/face_photos |
获取照片 ID 列表 |
GET |
/api/all_student_ids |
获取所有学生 ID |
GET |
/api/face_photo/{id} |
获取人脸照片 |
DELETE |
/api/face/{studentId} |
删除人脸信息 |
DELETE |
/api/face/{studentId}?delete_records=true |
删除人脸信息并删除相关考勤记录 |
GET |
/api/health |
健康检查 |
8.1 考勤记录格式
/api/records 解密后应返回 JSON 数组。单条记录示例：
{
"timestamp": "2026-04-24 08:10:23",
"student_id": "20240001",
"name": "张三",
"confidence": 0.9821,
"status": "success",
"class_id": "1"
}
8.2 统计数据格式
{
"total": 120,
"today": 8,
"server_time": "2026-04-24 10:30:00"
}
8.3 签到时段格式
{
"time_slots": [
{
"name": "上午签到",
"start_time": "08:00",
"end_time": "09:30",
"enabled": true
}
]
}
8.4 映射配置格式
{
"student_name_map": {
"20240001": "张三"
},
"class_name_map": {
"1": "软件工程一班"
}
}
8.5 人脸映射格式
{
"mappings": {
"face_001": "20240001"
}
}
9. 本地配置
应用会保存以下本地状态：
- 服务端地址：
QSettings，键名为server/url。 - 映射配置：
QStandardPaths::AppDataLocation/mapping_config.json。 - 签到时段配置：
QStandardPaths::AppDataLocation/timeslot_config.json。
应用信息：
ApplicationName: 人脸识别考勤系统
ApplicationVersion: 3.0.0
OrganizationName: STM32 Face Recognition
10. 加密响应
/api/records 和 /api/statistics 请求会带上：
X-Encrypted-Response: true
客户端期望服务端返回 Base64 编码的 AES-128-CBC 密文。
解密参数位于 src/CryptoUtils.cpp：
- 算法：AES-128-CBC
- Padding：PKCS#7
- Key：
2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c - IV：
00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
11. 常见问题
11.1 修改图标后没有变化
先重新运行 CMake 配置，再重新构建。Windows 资源管理器可能缓存 exe 图标，可以尝试换构建目录、改输出文件名或重启资源管理器。
11.2 启动后没有数据
检查服务端地址是否正确，并在配置中心点击连接测试。如果服务端不可达，状态栏会显示错误信息。
11.3 姓名或班级显示不正确
在配置中心维护学生姓名映射和班级名称映射，然后保存。保存后记录列表和统计结果会重新计算。
11.4 人脸照片不显示
检查 /api/face_photos 是否返回照片 ID，并确认 /api/face_photo/{id} 可以访问。
11.5 Android 图标不生效
确认使用 Qt 6.9 或更高版本，并重新配置 Android Kit。图标资源位于 android/res/mipmap-*，CMake 使用 QT_ANDROID_APP_ICON "@mipmap/ic_launcher" 指定启动图标。
12. 维护建议
- 构建目录已从项目中清理，后续重新构建时由 Qt Creator 或 CMake 自动生成。
- 如果服务端记录量超过 1000 条，需要扩展分页加载逻辑。
- 如果服务端加密参数变化，需要同步修改
src/CryptoUtils.cpp。 - 如果要发布桌面版本，建议使用 Qt 部署工具收集运行时依赖。
- 如果要发布 Android 版本，建议补充签名配置和 release 构建流程。
13. 开源协议
本项目采用 MIT License 开源，详见 LICENSE 文件。