PC 端完成
This commit is contained in:
@@ -0,0 +1,422 @@
|
||||
# 人脸识别考勤系统 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 构建流程。
|
||||
Reference in New Issue
Block a user