yzfh/bishe-STM32

Fork 0

Files

T

yzfh a32baa96e3 更新文档

2026-05-01 23:03:42 +08:00

11 KiB

Raw Blame History

Qt 管理端文档

1. Qt 管理端是什么

Qt 管理端是整个系统的图形化后台。它支持 Windows 桌面端和 Android 端，主要用于：

查看考勤记录。
按班级、学号、姓名、日期筛选记录。
导出记录 CSV。
查看统计分析。
导出统计 CSV。
配置服务端地址。
配置签到时间段。
配置学号到姓名、班级编号到班级名的显示映射。
查看 K210 上传的人脸照片。
给 K210 face_id 绑定真实学号。
删除人脸信息，并可选择删除相关考勤记录。

2. 相关文件

文件	作用
`QT/main.cpp`	Qt 程序入口，设置应用信息、图标、QML 引擎
`QT/qml/Main.qml`	主界面，包括所有页面和对话框
`QT/src/AppController.*`	QML 与 C++ 业务逻辑的中枢
`QT/src/ApiClient.*`	HTTP API 客户端
`QT/src/AttendanceTypes.h`	考勤记录、统计、时间段结构体
`QT/src/CryptoUtils.*`	AES 解密工具
`QT/src/RecordListModel.*`	考勤记录模型
`QT/src/StatisticsListModel.*`	统计模型
`QT/src/TimeSlotListModel.*`	时间段模型
`QT/src/MappingListModel.*`	姓名/班级映射模型
`QT/src/FaceListModel.*`	人脸管理模型
`QT/CMakeLists.txt`	Qt/CMake 构建配置
`QT/android/`	Android Gradle 配置和图标
`QT/assets/`	桌面端图标

3. 技术栈

分类	内容
语言	C++17、QML
UI	Qt Quick、Qt Quick Controls 2
Qt 模块	Core、Gui、Qml、Quick、QuickControls2、Network
构建系统	CMake 3.16+
样式	`QQuickStyle::setStyle("Basic")`
Android 文字渲染	`NativeTextRendering`
本地配置	`QSettings`、`QStandardPaths::AppDataLocation`

4. 应用基础信息

位置：QT/main.cpp

项	值
ApplicationName	`人脸识别考勤系统`
ApplicationVersion	`3.0.0`
OrganizationName	`STM32 Face Recognition`
主 QML	`qrc:/qml/Main.qml`
默认窗口大小	`1560 x 920`
PC 最小窗口	`900 x 620`
Android 最小窗口	`360 x 560`

5. 页面结构

Qt 管理端是单窗口应用，共 5 个页面：

页面	作用
考勤记录	查看、筛选、导出、清空记录
统计分析	按时间范围统计学生签到情况
配置中心	服务端地址、签到时间段、名称映射
人脸管理	查看照片、绑定学号、删除人脸
关于	系统说明、版本和作者信息

PC 宽屏显示左侧导航栏；窄屏和 Android 显示顶部/底部更紧凑的导航布局。

6. 网络访问规则

Qt 端的服务端地址默认是：

http://127.0.0.1:8082

用户可在“配置中心”修改服务端地址。保存后写入本地 QSettings：

server/url

ApiClient::buildUrl 会在地址后自动拼接 /api，例如：

服务端地址: http://127.0.0.1:8082
传入 endpoint: /v1/system/health
实际请求: http://127.0.0.1:8082/api/v1/system/health

所有请求都会带：

X-Api-Token: <Token>
Accept: application/json

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

$env:ATTENDANCE_API_TOKEN="你的Token"

网络超时：

5000 ms

7. 启动流程

Qt 启动后：

main.cpp 创建 QGuiApplication。
设置应用图标、应用名、版本号、组织名。
Android 下启用原生文字渲染。
创建 AppController。
AppController 读取本地服务端地址、映射配置、时间段配置。
ApiClient 设置当前服务端地址。
启动自动重连状态并执行健康检查。
QML 载入 Main.qml。
QML 通过上下文对象 appController 调用 C++。

8. 自动重连

如果健康检查失败，AppController 会进入重连状态。

9. 考勤记录页

功能：

显示服务端记录。
显示总记录数、今日记录数、当前筛选结果数。
按班级筛选。
按学号筛选。
按姓名关键字筛选。
按日期范围筛选。
导出当前筛选结果。
清空服务端所有记录。

记录加载默认请求：

GET /api/v1/attendance/records?limit=1000&offset=0

注意：当前 Qt 统计和筛选主要基于已加载的记录。如果服务端超过 1000 条，界面统计不一定覆盖全部历史记录。

10. 筛选规则

筛选在 Qt 本地完成。

支持：

筛选项	说明
班级	`class_id` 匹配
学号	`student_id` 匹配
姓名	映射姓名或原始 name 包含关键字
日期	全部、今天、最近 7 天、最近 30 天、指定日期

姓名显示优先级：

如果学生映射里有该学号，显示映射姓名。
否则显示服务端记录中的 name。
如果都没有，则显示原始学号。

班级显示优先级：

如果班级映射里有该 class_id，显示映射班级名。
否则显示 class_id。

11. 记录导出

导出 CSV 文件时会写入：

# 考勤记录导出
# 导出时间: yyyy-MM-dd HH:mm:ss
# 记录总数: N
签到时间,班级编号,班级名称,学号,姓名,置信度,状态

字段会做 CSV 转义，包含逗号、双引号、换行时会自动加引号并转义。

12. 统计分析页

统计页基于当前加载记录在本地计算。

支持时间范围：

今天。
最近 7 天。
最近 30 天。
本月。
自定义开始和结束日期。

统计指标：

指标	含义
统计学生数	当前范围内出现过的学生数量
统计记录数	当前范围内记录数量
总签到次数	每个学生在范围内的记录数量
今日签到	每个学生今天的记录数量
最后签到时间	每个学生最新一条记录时间
平均置信度	每个学生记录的平均 confidence

导出字段：

考勤统计报表,<范围>
学号,姓名,总签到次数,今日签到,最后签到时间,平均置信度

13. 配置中心

配置中心包含三块：

服务端地址。
时间段配置。
名称映射配置。

13.1 服务端地址

字段示例：

http://27.106.113.205:8082

按钮：

按钮	作用
保存地址	写入 `QSettings`，并立即切换 `ApiClient` 的服务端
测试连接	请求 `/api/v1/system/health`

13.2 时间段配置

时间段格式：

{
  "name": "上午签到",
  "start_time": "08:00",
  "end_time": "09:30",
  "enabled": true
}

当前默认时间段为空。第一次使用时需要手动新增。

按钮：

按钮	作用
展开/收起	展示或隐藏时间段列表
新增时段	打开新增对话框
清空时段	清空本地时间段并保存同步到服务端
从服务器同步/同步	从服务端读取时间段；服务端为空数组时也会清空本地时间段
保存时间段/保存	保存到本地并上传服务端

本地文件：

timeslot_config.json

如果本地文件中刚好是旧版本四个默认时间段，当前代码会自动迁移为空配置。

13.3 名称映射配置

学生映射：

{
  "20240001": "张三"
}

班级映射：

{
  "1": "软件工程一班"
}

本地文件：

mapping_config.json

14. 人脸管理页

人脸管理页把三类数据合并展示：

服务端照片列表。
服务端已有学生 ID。
服务端 face_id 到学生 ID 映射。

如果服务端已经把照片从原始 face_id 文件名重命名为学号文件名，Qt 仍会把已有映射中的原始 face_id 展示出来，保存时保留这类真实映射，并跳过未编辑的“ID 等于学号”的默认占位项。

用户可以：

刷新人脸库。
为每张照片填写真实学号。
保存映射。
删除人脸。
删除人脸时选择是否同时删除该学生的考勤记录。

照片下载流程：

Qt 获取照片 ID 列表。
对每个 ID 请求 /api/v1/faces/photos/<id>。
下载成功后保存到本地缓存目录：

<AppDataLocation>/face_photos/<id>.jpg

QML 使用本地 file URL 显示图片。

15. 关于页面

关于页显示：

系统用途。
功能范围。
毕业设计说明。
作者和版权信息。
仓库地址。
演示账号信息。

这些文本在 QT/qml/Main.qml 中。

16. PC 和 Android 适配

当前 QML 中有这些布局断点：

属性	条件	用途
`compactLayout`	`width < 1460`	PC 紧凑布局
`denseLayout`	`width < 1380`	更密集显示
`narrowLayout`	`width < 1280`	表格列裁剪
`slimLayout`	`width < 1040`	隐藏侧边栏，使用移动导航
`phoneLayout`	PC 小于 560，Android 小于 640	手机布局

Android 特殊处理：

最小窗口宽度是 360。
最小窗口高度是 560。
字体使用 sans-serif。
粗体权重降低为 Font.Medium。
使用原生文字渲染，减少中文粗体重影。

配置页卡片现在使用内容自适应高度，避免按钮遮挡。

17. 本地持久化

Qt 使用两类本地持久化。

17.1 QSettings

保存服务端地址：

server/url

17.2 AppDataLocation 文件

文件	内容
`timeslot_config.json`	时间段配置
`mapping_config.json`	学生姓名和班级名称映射
`face_photos/*.jpg`	下载后的人脸照片缓存

18. 构建方式

18.1 Qt Creator

打开 Qt Creator。
打开 QT/CMakeLists.txt。
选择 Desktop Qt 6.x 或 Android Kit。
等待 CMake 配置完成。
构建 apprewrite_qt。
桌面端直接运行；Android 端部署到设备或模拟器。

18.2 命令行示例

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 安装位置调整。

19. 常见问题

现象	可能原因	处理
测试连接失败	服务端没启动、地址错、Token 不一致	检查服务端健康接口和 `ATTENDANCE_API_TOKEN`
页面按钮重叠	旧版固定高度导致内容被裁切	当前已改为自适应高度
Android 文字发虚/重影	字体渲染方式问题	当前 Android 使用原生渲染和中等粗体
人脸照片不显示	下载失败、本地缓存路径无效、服务端无照片	刷新人脸库，看服务端 `faces/`
统计数量少于服务端总量	Qt 默认只拉取 1000 条记录	增加分页或服务端统计接口
时间段为空导致无法签到	当前默认就是空配置	在配置中心新增时间段并保存
保存映射后 K210 没变化	K210 尚未同步或 WiFi 不通	等待同步或检查 K210 日志

11 KiB Raw Blame History Unescape Escape