181 lines
5.3 KiB
Markdown
181 lines
5.3 KiB
Markdown
# Qt 管理端 README
|
||
|
||
这是人脸识别考勤系统的 Qt 管理端，支持 Windows 桌面端和 Android 端。更完整的说明见：
|
||
|
||
```text
|
||
../docs/04_Qt管理端文档.md
|
||
../docs/00_项目总文档.md
|
||
```
|
||
|
||
## 1. 功能概览
|
||
|
||
Qt 管理端用于连接考勤服务端，完成以下工作：
|
||
|
||
1. 查看考勤记录。
|
||
2. 按班级、学号、姓名和日期筛选记录。
|
||
3. 导出考勤记录 CSV。
|
||
4. 清空服务端考勤记录。
|
||
5. 查看学生维度的统计分析。
|
||
6. 导出统计 CSV。
|
||
7. 配置服务端地址和 API Token。
|
||
8. 新增、编辑、删除、清空签到时间段。
|
||
9. 配置学号到姓名、学号到班级编号、班级编号到班级名称的显示映射。
|
||
10. 查看 K210 上传的人脸照片。
|
||
11. 为 K210 face_id 绑定真实学号。
|
||
12. 删除人脸信息，并可选择删除关联考勤记录。
|
||
|
||
## 2. 当前重要行为
|
||
|
||
### 2.1 默认服务端地址
|
||
|
||
```text
|
||
http://127.0.0.1:8082
|
||
```
|
||
|
||
启动后会优先读取本地保存的 `server/url`，API Token 会优先读取 `server/apiToken`，没有本地值时再使用环境变量。
|
||
|
||
### 2.2 默认签到时间段
|
||
|
||
当前默认签到时间段为空：
|
||
|
||
```json
|
||
{
|
||
"time_slots": []
|
||
}
|
||
```
|
||
|
||
第一次使用时，需要在“配置中心”里新增时间段并保存同步到服务端；当前以服务端 SQLite 中的时间段配置为准。
|
||
|
||
### 2.3 API Token
|
||
|
||
Qt 每个请求都会带：
|
||
|
||
```text
|
||
X-Api-Token: <Token>
|
||
```
|
||
|
||
API Token 不写入源码。可以通过“配置中心”保存，也可以通过环境变量提供：
|
||
|
||
```powershell
|
||
$env:ATTENDANCE_API_TOKEN="你的Token"
|
||
```
|
||
|
||
### 2.4 响应加密
|
||
|
||
服务端支持通过请求头 `X-Encrypted-Response: true` 返回 AES 加密响应，Qt 代码中保留了解密能力。
|
||
|
||
当前普通记录和统计请求没有默认开启这个请求头，实际按 JSON 明文解析。
|
||
|
||
## 3. 技术栈
|
||
|
||
| 分类 | 内容 |
|
||
| --- | --- |
|
||
| 语言 | C++17、QML |
|
||
| UI | Qt Quick / Qt Quick Controls 2 |
|
||
| Qt 模块 | Core、Gui、Qml、Quick、QuickControls2、Network |
|
||
| 构建 | CMake 3.16+ |
|
||
| 平台 | Windows 桌面端、Android |
|
||
|
||
## 4. 目录结构
|
||
|
||
```text
|
||
QT/
|
||
├── android/ # Android 打包配置和图标
|
||
├── assets/ # 桌面端图标
|
||
├── cmake/ # 平台模板
|
||
├── qml/Main.qml # 主界面
|
||
├── src/
|
||
│ ├── ApiClient.* # HTTP API 客户端
|
||
│ ├── AppController.* # 业务逻辑中枢
|
||
│ ├── AttendanceTypes.h # 数据结构
|
||
│ ├── CryptoUtils.* # AES 解密工具
|
||
│ └── *ListModel.* # QML 列表模型
|
||
├── CMakeLists.txt
|
||
├── clear_qt_cache.ps1 # 清理 Qt Creator/CMake 本地缓存
|
||
├── LICENSE
|
||
├── README.md
|
||
└── main.cpp
|
||
```
|
||
|
||
## 5. 构建环境
|
||
|
||
基础要求：
|
||
|
||
1. Qt 6.2 或更高。
|
||
2. CMake 3.16 或更高。
|
||
3. 支持 C++17 的编译器。
|
||
|
||
Windows 推荐使用 Qt 6.x MinGW 64-bit Kit。
|
||
|
||
Android 还需要：
|
||
|
||
1. Qt for Android。
|
||
2. Android SDK。
|
||
3. Android NDK。
|
||
4. JDK。
|
||
5. Android 平台版本，例如 `android-35`。
|
||
|
||
## 6. Qt Creator 构建
|
||
|
||
1. 打开 Qt Creator。
|
||
2. 打开 `QT/CMakeLists.txt`。
|
||
3. 选择 Desktop Qt 或 Android Kit。
|
||
4. 等待 CMake 配置完成。
|
||
5. 构建目标 `apprewrite_qt`。
|
||
6. 桌面端直接运行；Android 端部署到设备或模拟器。
|
||
|
||
## 7. 命令行构建示例
|
||
|
||
Windows 示例：
|
||
|
||
```powershell
|
||
cd D:\University\graduation\thesis\code\QT
|
||
cmake -S . -B build\Desktop -DCMAKE_PREFIX_PATH=D:\Qt\6.10.0\mingw_64
|
||
cmake --build build\Desktop
|
||
```
|
||
|
||
Qt 安装路径需要按本机实际情况修改。
|
||
|
||
## 8. 迁移后清理缓存
|
||
|
||
项目移动到新目录后，Qt Creator 可能仍沿用旧的 `.qtcreator`、`build` 或 CMake 缓存。可在 Qt 工程目录运行：
|
||
|
||
```powershell
|
||
cd D:\University\graduation\thesis\code\QT
|
||
powershell -ExecutionPolicy Bypass -File .\clear_qt_cache.ps1
|
||
```
|
||
|
||
该脚本只清理当前项目目录内的 Qt/CMake 缓存，不清理 Qt Creator 全局配置，也不会备份。
|
||
|
||
## 9. 配置中心
|
||
|
||
服务端配置区包含“服务器地址”和“API Token”两个输入框：
|
||
|
||
| 按钮 | 作用 |
|
||
| --- | --- |
|
||
| 保存 | 同时保存服务器地址和 API Token 到 `QSettings`，并切换 `ApiClient` 配置 |
|
||
| 测试连接 | 使用当前配置请求 `/api/v1/system/health` |
|
||
|
||
## 10. 本地数据
|
||
|
||
Qt 会保存这些本地数据：
|
||
|
||
| 数据 | 保存方式 |
|
||
| --- | --- |
|
||
| 服务端地址 | `QSettings`，键名 `server/url` |
|
||
| API Token | `QSettings`，键名 `server/apiToken` |
|
||
| 时间段配置 | `QStandardPaths::AppDataLocation/timeslot_config.json` |
|
||
| 学生/班级映射 | `QStandardPaths::AppDataLocation/mapping_config.json` |
|
||
| 人脸照片缓存 | `QStandardPaths::AppDataLocation/face_photos/*.jpg` |
|
||
|
||
## 11. 常见问题
|
||
|
||
| 现象 | 处理 |
|
||
| --- | --- |
|
||
| 测试连接失败 | 检查服务端是否启动、地址是否正确、Token 是否一致 |
|
||
| 迁移目录后 Qt Creator 报错或构建目录不对 | 关闭 Qt Creator 后运行 `clear_qt_cache.ps1`，再重新打开 `CMakeLists.txt` |
|
||
| 没有时间段 | 这是当前默认行为，需要手动新增并保存 |
|
||
| 识别成功但没有记录 | 检查 STM32 是否在时间段内、是否成功加密上传 |
|
||
| 人脸照片不显示 | 检查 K210 是否上传照片，服务端 `faces/` 是否有图片 |
|
||
| Android 布局拥挤 | 当前 QML 已做窄屏自适应，若仍异常请检查实际设备宽度 |
|