158 lines
4.2 KiB
Markdown
158 lines
4.2 KiB
Markdown
# Qt 管理端 README
|
|
|
|
这是人脸识别考勤系统的 Qt 管理端，支持 Windows 桌面端和 Android 端。更完整的说明见：
|
|
|
|
```text
|
|
../docs/04_Qt管理端文档.md
|
|
../docs/00_项目总文档.md
|
|
```
|
|
|
|
## 1. 功能概览
|
|
|
|
Qt 管理端用于连接考勤服务端，完成以下工作：
|
|
|
|
1. 查看考勤记录。
|
|
2. 按班级、学号、姓名和日期筛选记录。
|
|
3. 导出考勤记录 CSV。
|
|
4. 查看学生维度的统计分析。
|
|
5. 导出统计 CSV。
|
|
6. 配置服务端地址。
|
|
7. 新增、编辑、删除、清空签到时间段。
|
|
8. 配置学号到姓名、班级编号到班级名称的显示映射。
|
|
9. 查看 K210 上传的人脸照片。
|
|
10. 为 K210 face_id 绑定真实学号。
|
|
11. 删除人脸信息，并可选择删除关联考勤记录。
|
|
|
|
## 2. 当前重要行为
|
|
|
|
### 2.1 默认服务端地址
|
|
|
|
```text
|
|
http://127.0.0.1:8082
|
|
```
|
|
|
|
启动后会优先读取本地保存的 `server/url`。
|
|
|
|
### 2.2 默认签到时间段
|
|
|
|
当前默认签到时间段为空：
|
|
|
|
```json
|
|
{
|
|
"time_slots": []
|
|
}
|
|
```
|
|
|
|
第一次使用时，需要在“配置中心”里新增时间段并保存同步到服务端。旧版本本地保存的四个默认时间段会被自动迁移为空配置。
|
|
|
|
### 2.3 API Token
|
|
|
|
Qt 每个请求都会带：
|
|
|
|
```text
|
|
X-Api-Token: <Token>
|
|
```
|
|
|
|
默认 Token 写在 `src/ApiClient.cpp`。可以通过环境变量覆盖：
|
|
|
|
```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
|
|
├── 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\code\Reconstruct_Qt\QT
|
|
cmake -S . -B build\Desktop -DCMAKE_PREFIX_PATH=D:\Qt\6.10.0\mingw_64
|
|
cmake --build build\Desktop
|
|
```
|
|
|
|
Qt 安装路径需要按本机实际情况修改。
|
|
|
|
## 8. 本地数据
|
|
|
|
Qt 会保存这些本地数据：
|
|
|
|
| 数据 | 保存方式 |
|
|
| --- | --- |
|
|
| 服务端地址 | `QSettings`，键名 `server/url` |
|
|
| 时间段配置 | `QStandardPaths::AppDataLocation/timeslot_config.json` |
|
|
| 学生/班级映射 | `QStandardPaths::AppDataLocation/mapping_config.json` |
|
|
| 人脸照片缓存 | `QStandardPaths::AppDataLocation/face_photos/*.jpg` |
|
|
|
|
## 9. 常见问题
|
|
|
|
| 现象 | 处理 |
|
|
| --- | --- |
|
|
| 测试连接失败 | 检查服务端是否启动、地址是否正确、Token 是否一致 |
|
|
| 没有时间段 | 这是当前默认行为，需要手动新增并保存 |
|
|
| 识别成功但没有记录 | 检查 STM32 是否在时间段内、是否成功加密上传 |
|
|
| 人脸照片不显示 | 检查 K210 是否上传照片，服务端 `faces/` 是否有图片 |
|
|
| Android 布局拥挤 | 当前 QML 已做窄屏自适应，若仍异常请检查实际设备宽度 |
|
|
|