bishe-STM32/QT/README.md

Qt 管理端 README

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

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

http://127.0.0.1:8082

启动后会优先读取本地保存的 server/url。

2.2 默认签到时间段

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

{
  "time_slots": []
}

第一次使用时，需要在“配置中心”里新增时间段并保存同步到服务端。旧版本本地保存的四个默认时间段会被自动迁移为空配置。

2.3 API Token

Qt 每个请求都会带：

X-Api-Token: <Token>

默认 Token 写在 src/ApiClient.cpp。可以通过环境变量覆盖：

$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. 目录结构

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

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 已做窄屏自适应，若仍异常请检查实际设备宽度