Qt 管理端 README

这是人脸识别考勤系统的 Qt 管理端，支持 Windows 桌面端和 Android 端。更完整的说明见：

../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 默认服务端地址

http://127.0.0.1:8082

启动后会优先读取本地保存的 server/url，API Token 会优先读取 server/apiToken，没有本地值时再使用环境变量。

2.2 默认签到时间段

当前默认签到时间段为空：

{
  "time_slots": []
}

第一次使用时，需要在“配置中心”里新增时间段并保存同步到服务端；当前以服务端 SQLite 中的时间段配置为准。

2.3 API Token

Qt 每个请求都会带：

X-Api-Token: <Token>

API Token 不写入源码。可以通过“配置中心”保存，也可以通过环境变量提供：

$env:ATTENDANCE_API_TOKEN="你的Token"

2.4 加密传输

除照片 JPEG 下载外，Qt 的业务 JSON 请求和响应统一使用 AES-128-CBC + PKCS#7 + Base64。GET/DELETE 请求会要求服务端返回加密响应，POST JSON 会先加密请求体并携带 X-Encrypted: AES128-CBC。

3. 技术栈

分类	内容
语言	C++17、QML
UI	Qt Quick / Qt Quick Controls 2
Qt 模块	Core、Gui、Qml、Quick、QuickControls2、Network
构建	CMake 3.16+
平台	Windows 桌面端、Android

4. 目录结构

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 示例：

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 工程目录运行：

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/profiles_cache.json
人脸照片缓存	QStandardPaths::AppDataLocation/face_photos/*.jpg

11. 常见问题

现象	处理
测试连接失败	检查服务端是否启动、地址是否正确、Token 是否一致
迁移目录后 Qt Creator 报错或构建目录不对	关闭 Qt Creator 后运行 clear_qt_cache.ps1，再重新打开 CMakeLists.txt
没有时间段	这是当前默认行为，需要手动新增并保存
识别成功但没有记录	检查 STM32 是否在时间段内、是否成功加密上传
人脸照片不显示	检查 K210 是否上传照片，服务端 faces/ 是否有图片
Android 布局拥挤	当前 QML 已做窄屏自适应，若仍异常请检查实际设备宽度