423 lines
11 KiB
Markdown
423 lines
11 KiB
Markdown
# 人脸识别考勤系统 Qt 客户端说明文档
|
||
|
||
## 1. 项目简介
|
||
|
||
本项目是基于 Qt 6 Quick/QML 开发的人脸识别考勤系统客户端，用于连接考勤服务端，完成考勤记录查看、筛选导出、统计分析、签到时段配置、学生和班级名称映射、人脸照片映射管理等功能。
|
||
|
||
程序入口为 `main.cpp`。启动后创建 `QGuiApplication` 和 `AppController`，并将 `AppController` 通过 QML 上下文属性 `appController` 暴露给 `qml/Main.qml`。界面由 QML 实现，业务逻辑、网络请求、数据模型、配置保存和 CSV 导出由 C++ 实现。
|
||
|
||
默认服务端地址：
|
||
|
||
```text
|
||
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. 当前目录结构
|
||
|
||
```text
|
||
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
|
||
|
||
1. 打开项目根目录下的 `CMakeLists.txt`。
|
||
2. 选择合适的 Qt Kit，例如 Desktop Qt 6.x 或 Android Qt 6.x。
|
||
3. 重新配置 CMake。
|
||
4. 构建并运行目标 `apprewrite_qt`。
|
||
|
||
### 4.3 使用命令行
|
||
|
||
Windows 示例：
|
||
|
||
```powershell
|
||
cmake -S . -B build -DCMAKE_PREFIX_PATH=D:/Qt/6.10.0/mingw_64
|
||
cmake --build build
|
||
```
|
||
|
||
Linux 示例：
|
||
|
||
```bash
|
||
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64
|
||
cmake --build build
|
||
```
|
||
|
||
安装到系统路径：
|
||
|
||
```bash
|
||
cmake --install build
|
||
```
|
||
|
||
## 5. 多平台图标配置
|
||
|
||
项目已经配置为多平台使用同一套应用图标。
|
||
|
||
### 5.1 Windows
|
||
|
||
Windows exe 图标使用：
|
||
|
||
```text
|
||
assets/favicon.ico
|
||
```
|
||
|
||
CMake 会在 Windows 构建时根据 `cmake/app_icon.rc.in` 生成资源文件，并把图标嵌入到可执行文件中。
|
||
|
||
### 5.2 桌面运行时图标
|
||
|
||
`main.cpp` 会设置应用窗口图标：
|
||
|
||
```cpp
|
||
QIcon appIcon(QStringLiteral(":/assets/favicon.ico"));
|
||
```
|
||
|
||
同时会加入多尺寸 PNG 作为回退资源：
|
||
|
||
```text
|
||
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` 文件：
|
||
|
||
```text
|
||
cmake/rewrite_qt.desktop.in
|
||
```
|
||
|
||
并把不同尺寸的 PNG 安装到：
|
||
|
||
```text
|
||
share/icons/hicolor/{size}x{size}/apps/rewrite_qt.png
|
||
```
|
||
|
||
`.desktop` 文件中使用的图标名为：
|
||
|
||
```text
|
||
rewrite_qt
|
||
```
|
||
|
||
### 5.4 Android
|
||
|
||
Android 启动器图标位于：
|
||
|
||
```text
|
||
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 相关配置：
|
||
|
||
```cmake
|
||
QT_ANDROID_PACKAGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/android"
|
||
QT_ANDROID_APP_ICON "@mipmap/ic_launcher"
|
||
```
|
||
|
||
`QT_ANDROID_APP_ICON` 需要 Qt 6.9 或更高版本。当前 Qt 6.10 可正常使用。
|
||
|
||
## 6. 功能说明
|
||
|
||
### 6.1 考勤记录
|
||
|
||
考勤记录页支持：
|
||
|
||
- 查看总记录数、今日记录数、已加载记录数和当前筛选结果数。
|
||
- 按班级、学号、姓名关键字筛选。
|
||
- 按今天、最近 7 天、最近 30 天或指定日期范围筛选。
|
||
- 导出当前筛选结果为 CSV。
|
||
- 清空服务端全部考勤记录。
|
||
|
||
导出的记录 CSV 字段：
|
||
|
||
```text
|
||
签到时间,班级编号,班级名称,学号,姓名,置信度,状态
|
||
```
|
||
|
||
### 6.2 统计分析
|
||
|
||
统计页基于已加载记录在本地计算，支持：
|
||
|
||
- 今天、最近 7 天、最近 30 天、本月等快捷范围。
|
||
- 自定义统计日期范围。
|
||
- 按学生汇总签到次数、今日签到次数、最后签到时间和平均置信度。
|
||
- 导出统计结果为 CSV。
|
||
|
||
导出的统计 CSV 字段：
|
||
|
||
```text
|
||
学号,姓名,总签到次数,今日签到,最后签到时间,平均置信度
|
||
```
|
||
|
||
### 6.3 配置中心
|
||
|
||
配置中心包含：
|
||
|
||
- 服务端地址配置和连接测试。
|
||
- 签到时段新增、编辑、删除、启用和禁用。
|
||
- 学号到姓名的映射。
|
||
- 班级编号到班级名称的映射。
|
||
|
||
默认签到时段：
|
||
|
||
| 名称 | 开始时间 | 结束时间 | 默认状态 |
|
||
| --- | --- | --- | --- |
|
||
| 上午签到 | 08:00 | 09:30 | 启用 |
|
||
| 中午签退 | 12:00 | 13:00 | 启用 |
|
||
| 下午签到 | 14:00 | 15:00 | 启用 |
|
||
| 晚上签退 | 17:00 | 18:30 | 启用 |
|
||
|
||
### 6.4 人脸管理
|
||
|
||
人脸管理页支持：
|
||
|
||
- 从服务端同步人脸照片 ID。
|
||
- 从服务端同步所有学生 ID。
|
||
- 展示人脸照片和绑定状态。
|
||
- 为人脸 ID 绑定真实学号。
|
||
- 保存人脸 ID 与学号映射。
|
||
- 删除指定人脸信息，可选择同时删除该学生的考勤记录。
|
||
|
||
照片访问地址格式：
|
||
|
||
```text
|
||
{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 数组。单条记录示例：
|
||
|
||
```json
|
||
{
|
||
"timestamp": "2026-04-24 08:10:23",
|
||
"student_id": "20240001",
|
||
"name": "张三",
|
||
"confidence": 0.9821,
|
||
"status": "success",
|
||
"class_id": "1"
|
||
}
|
||
```
|
||
|
||
### 8.2 统计数据格式
|
||
|
||
```json
|
||
{
|
||
"total": 120,
|
||
"today": 8,
|
||
"server_time": "2026-04-24 10:30:00"
|
||
}
|
||
```
|
||
|
||
### 8.3 签到时段格式
|
||
|
||
```json
|
||
{
|
||
"time_slots": [
|
||
{
|
||
"name": "上午签到",
|
||
"start_time": "08:00",
|
||
"end_time": "09:30",
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 8.4 映射配置格式
|
||
|
||
```json
|
||
{
|
||
"student_name_map": {
|
||
"20240001": "张三"
|
||
},
|
||
"class_name_map": {
|
||
"1": "软件工程一班"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.5 人脸映射格式
|
||
|
||
```json
|
||
{
|
||
"mappings": {
|
||
"face_001": "20240001"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 9. 本地配置
|
||
|
||
应用会保存以下本地状态：
|
||
|
||
- 服务端地址：`QSettings`，键名为 `server/url`。
|
||
- 映射配置：`QStandardPaths::AppDataLocation/mapping_config.json`。
|
||
- 签到时段配置：`QStandardPaths::AppDataLocation/timeslot_config.json`。
|
||
|
||
应用信息：
|
||
|
||
```text
|
||
ApplicationName: 人脸识别考勤系统
|
||
ApplicationVersion: 3.0.0
|
||
OrganizationName: STM32 Face Recognition
|
||
```
|
||
|
||
## 10. 加密响应
|
||
|
||
`/api/records` 和 `/api/statistics` 请求会带上：
|
||
|
||
```text
|
||
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 构建流程。
|