yzfh/bishe-QT

Fork 0

T

yzfh ebc49d1ac6 PC 端完成

2026-04-30 22:45:57 +08:00

android/res

PC 端完成

2026-04-30 22:45:57 +08:00

assets

PC 端完成

2026-04-30 22:45:57 +08:00

cmake

PC 端完成

2026-04-30 22:45:57 +08:00

qml

PC 端完成

2026-04-30 22:45:57 +08:00

src

PC 端完成

2026-04-30 22:45:57 +08:00

.gitignore

PC 端完成

2026-04-30 22:45:57 +08:00

CMakeLists.txt

PC 端完成

2026-04-30 22:45:57 +08:00

main.cpp

PC 端完成

2026-04-30 22:45:57 +08:00

README.md

PC 端完成

2026-04-30 22:45:57 +08:00

README.md

人脸识别考勤系统 Qt 客户端说明文档

1. 项目简介

本项目是基于 Qt 6 Quick/QML 开发的人脸识别考勤系统客户端，用于连接考勤服务端，完成考勤记录查看、筛选导出、统计分析、签到时段配置、学生和班级名称映射、人脸照片映射管理等功能。

程序入口为 main.cpp。启动后创建 QGuiApplication 和 AppController，并将 AppController 通过 QML 上下文属性 appController 暴露给 qml/Main.qml。界面由 QML 实现，业务逻辑、网络请求、数据模型、配置保存和 CSV 导出由 C++ 实现。

默认服务端地址：

http://27.106.113.205:8082

2. 技术栈

语言：C++17、QML
框架：Qt 6.2 或更高版本
Qt 模块：Core、Gui、Qml、Quick、QuickControls2、Network
构建系统：CMake 3.16 或更高版本
加密处理：AES-128-CBC，相关代码位于 src/CryptoUtils.cpp

3. 当前目录结构

rewrite_qt/
├── CMakeLists.txt
├── README.md
├── main.cpp
├── android/
│   └── res/
│       ├── mipmap-mdpi/ic_launcher.png
│       ├── mipmap-hdpi/ic_launcher.png
│       ├── mipmap-xhdpi/ic_launcher.png
│       ├── mipmap-xxhdpi/ic_launcher.png
│       └── mipmap-xxxhdpi/ic_launcher.png
├── assets/
│   ├── favicon.ico
│   ├── favicon-16x16.png
│   ├── favicon-32x32.png
│   ├── favicon-48x48.png
│   ├── favicon-64x64.png
│   ├── favicon-128x128.png
│   ├── favicon-192x192.png
│   └── favicon-256x256.png
├── cmake/
│   ├── app_icon.rc.in
│   └── rewrite_qt.desktop.in
├── qml/
│   └── Main.qml
└── src/
    ├── ApiClient.h/.cpp
    ├── AppController.h/.cpp
    ├── AttendanceTypes.h
    ├── CryptoUtils.h/.cpp
    ├── FaceListModel.h/.cpp
    ├── MappingListModel.h/.cpp
    ├── RecordListModel.h/.cpp
    ├── StatisticsListModel.h/.cpp
    ├── TimeSlotListModel.h/.cpp
    └── crypto/tiny_aes.hpp

4. 构建与运行

4.1 环境要求

需要安装：

Qt 6.2+
CMake 3.16+
支持 C++17 的编译器，例如 MSVC、MinGW、Clang 或 GCC

Android 构建还需要配置 Qt for Android、Android SDK、Android NDK 和 JDK。

4.2 使用 Qt Creator

打开项目根目录下的 CMakeLists.txt。
选择合适的 Qt Kit，例如 Desktop Qt 6.x 或 Android Qt 6.x。
重新配置 CMake。
构建并运行目标 apprewrite_qt。

4.3 使用命令行

Windows 示例：

cmake -S . -B build -DCMAKE_PREFIX_PATH=D:/Qt/6.10.0/mingw_64
cmake --build build

Linux 示例：

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x/gcc_64
cmake --build build

安装到系统路径：

cmake --install build

5. 多平台图标配置

项目已经配置为多平台使用同一套应用图标。

5.1 Windows

Windows exe 图标使用：

assets/favicon.ico

CMake 会在 Windows 构建时根据 cmake/app_icon.rc.in 生成资源文件，并把图标嵌入到可执行文件中。

5.2 桌面运行时图标

main.cpp 会设置应用窗口图标：

QIcon appIcon(QStringLiteral(":/assets/favicon.ico"));

同时会加入多尺寸 PNG 作为回退资源：

assets/favicon-256x256.png
assets/favicon-192x192.png
assets/favicon-128x128.png
assets/favicon-64x64.png
assets/favicon-48x48.png
assets/favicon-32x32.png
assets/favicon-16x16.png

这些图标文件会被加入 Qt 资源系统，路径前缀为 :/assets/...。

5.3 Linux

Linux 安装时会生成 .desktop 文件：

cmake/rewrite_qt.desktop.in

并把不同尺寸的 PNG 安装到：

share/icons/hicolor/{size}x{size}/apps/rewrite_qt.png

.desktop 文件中使用的图标名为：

rewrite_qt

5.4 Android

Android 启动器图标位于：

android/res/mipmap-mdpi/ic_launcher.png
android/res/mipmap-hdpi/ic_launcher.png
android/res/mipmap-xhdpi/ic_launcher.png
android/res/mipmap-xxhdpi/ic_launcher.png
android/res/mipmap-xxxhdpi/ic_launcher.png

对应尺寸：

目录	尺寸
`mipmap-mdpi`	48x48
`mipmap-hdpi`	72x72
`mipmap-xhdpi`	96x96
`mipmap-xxhdpi`	144x144
`mipmap-xxxhdpi`	192x192

CMake 中 Android 相关配置：

QT_ANDROID_PACKAGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/android"
QT_ANDROID_APP_ICON "@mipmap/ic_launcher"

QT_ANDROID_APP_ICON 需要 Qt 6.9 或更高版本。当前 Qt 6.10 可正常使用。

6. 功能说明

6.1 考勤记录

考勤记录页支持：

查看总记录数、今日记录数、已加载记录数和当前筛选结果数。
按班级、学号、姓名关键字筛选。
按今天、最近 7 天、最近 30 天或指定日期范围筛选。
导出当前筛选结果为 CSV。
清空服务端全部考勤记录。

导出的记录 CSV 字段：

签到时间,班级编号,班级名称,学号,姓名,置信度,状态

6.2 统计分析

统计页基于已加载记录在本地计算，支持：

今天、最近 7 天、最近 30 天、本月等快捷范围。
自定义统计日期范围。
按学生汇总签到次数、今日签到次数、最后签到时间和平均置信度。
导出统计结果为 CSV。

导出的统计 CSV 字段：

学号,姓名,总签到次数,今日签到,最后签到时间,平均置信度

6.3 配置中心

配置中心包含：

服务端地址配置和连接测试。
签到时段新增、编辑、删除、启用和禁用。
学号到姓名的映射。
班级编号到班级名称的映射。

默认签到时段：

名称	开始时间	结束时间	默认状态
上午签到	08:00	09:30	启用
中午签退	12:00	13:00	启用
下午签到	14:00	15:00	启用
晚上签退	17:00	18:30	启用

6.4 人脸管理

人脸管理页支持：

从服务端同步人脸照片 ID。
从服务端同步所有学生 ID。
展示人脸照片和绑定状态。
为人脸 ID 绑定真实学号。
保存人脸 ID 与学号映射。
删除指定人脸信息，可选择同时删除该学生的考勤记录。

照片访问地址格式：

{serverUrl}/api/face_photo/{id}?ts={timestamp}

ts 参数用于避免缓存导致照片不刷新。

7. 核心模块

文件	说明
`main.cpp`	初始化应用、设置应用信息和图标、加载 QML
`qml/Main.qml`	主界面和用户交互
`src/AppController.*`	应用业务中枢，连接 QML、模型和网络客户端
`src/ApiClient.*`	HTTP API 客户端
`src/ListModel.`	暴露给 QML 的列表模型
`src/AttendanceTypes.h`	业务数据结构
`src/CryptoUtils.*`	AES-128-CBC 解密工具
`src/crypto/tiny_aes.hpp`	AES 底层实现

8. 服务端 API

客户端会把服务端地址与 /api 前缀拼接后访问接口。

方法	路径	用途
`GET`	`/api/records?limit={limit}&offset={offset}`	获取考勤记录
`GET`	`/api/statistics`	获取总数、今日数和服务端时间
`POST`	`/api/clear`	清空全部记录
`DELETE`	`/api/record?timestamp={timestamp}&student_id={studentId}`	删除单条记录
`GET`	`/api/timeslots`	获取签到时段
`POST`	`/api/timeslots`	保存签到时段
`GET`	`/api/mapping_config`	获取学生和班级映射
`POST`	`/api/mapping_config`	保存学生和班级映射
`GET`	`/api/face_id_mapping`	获取人脸 ID 到学号映射
`POST`	`/api/face_id_mapping`	保存人脸 ID 到学号映射
`GET`	`/api/face_photos`	获取照片 ID 列表
`GET`	`/api/all_student_ids`	获取所有学生 ID
`GET`	`/api/face_photo/{id}`	获取人脸照片
`DELETE`	`/api/face/{studentId}`	删除人脸信息
`DELETE`	`/api/face/{studentId}?delete_records=true`	删除人脸信息并删除相关考勤记录
`GET`	`/api/health`	健康检查

8.1 考勤记录格式

/api/records 解密后应返回 JSON 数组。单条记录示例：

{
  "timestamp": "2026-04-24 08:10:23",
  "student_id": "20240001",
  "name": "张三",
  "confidence": 0.9821,
  "status": "success",
  "class_id": "1"
}

8.2 统计数据格式

{
  "total": 120,
  "today": 8,
  "server_time": "2026-04-24 10:30:00"
}

8.3 签到时段格式

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

8.4 映射配置格式

{
  "student_name_map": {
    "20240001": "张三"
  },
  "class_name_map": {
    "1": "软件工程一班"
  }
}

8.5 人脸映射格式

{
  "mappings": {
    "face_001": "20240001"
  }
}

9. 本地配置

应用会保存以下本地状态：

服务端地址：QSettings，键名为 server/url。
映射配置：QStandardPaths::AppDataLocation/mapping_config.json。
签到时段配置：QStandardPaths::AppDataLocation/timeslot_config.json。

应用信息：

ApplicationName: 人脸识别考勤系统
ApplicationVersion: 3.0.0
OrganizationName: STM32 Face Recognition

10. 加密响应

/api/records 和 /api/statistics 请求会带上：

X-Encrypted-Response: true

客户端期望服务端返回 Base64 编码的 AES-128-CBC 密文。

解密参数位于 src/CryptoUtils.cpp：

算法：AES-128-CBC
Padding：PKCS#7
Key：2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c
IV：00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f

11. 常见问题

11.1 修改图标后没有变化

先重新运行 CMake 配置，再重新构建。Windows 资源管理器可能缓存 exe 图标，可以尝试换构建目录、改输出文件名或重启资源管理器。

11.2 启动后没有数据

检查服务端地址是否正确，并在配置中心点击连接测试。如果服务端不可达，状态栏会显示错误信息。

11.3 姓名或班级显示不正确

在配置中心维护学生姓名映射和班级名称映射，然后保存。保存后记录列表和统计结果会重新计算。

11.4 人脸照片不显示

检查 /api/face_photos 是否返回照片 ID，并确认 /api/face_photo/{id} 可以访问。

11.5 Android 图标不生效

确认使用 Qt 6.9 或更高版本，并重新配置 Android Kit。图标资源位于 android/res/mipmap-*，CMake 使用 QT_ANDROID_APP_ICON "@mipmap/ic_launcher" 指定启动图标。

12. 维护建议

构建目录已从项目中清理，后续重新构建时由 Qt Creator 或 CMake 自动生成。
如果服务端记录量超过 1000 条，需要扩展分页加载逻辑。
如果服务端加密参数变化，需要同步修改 src/CryptoUtils.cpp。
如果要发布桌面版本，建议使用 Qt 部署工具收集运行时依赖。
如果要发布 Android 版本，建议补充签名配置和 release 构建流程。

Languages

C++ 51.9%

QML 44.9%

CMake 1.5%

PowerShell 1.2%

C 0.5%

README.md Unescape Escape

人脸识别考勤系统 Qt 客户端说明文档

1. 项目简介

2. 技术栈

3. 当前目录结构

4. 构建与运行

4.1 环境要求

4.2 使用 Qt Creator

4.3 使用命令行

5. 多平台图标配置

5.1 Windows

5.2 桌面运行时图标

5.3 Linux

5.4 Android

6. 功能说明

6.1 考勤记录

6.2 统计分析

6.3 配置中心

6.4 人脸管理

7. 核心模块

8. 服务端 API

8.1 考勤记录格式

8.2 统计数据格式

8.3 签到时段格式

8.4 映射配置格式

8.5 人脸映射格式

9. 本地配置

10. 加密响应

11. 常见问题

11.1 修改图标后没有变化

11.2 启动后没有数据

11.3 姓名或班级显示不正确

11.4 人脸照片不显示

11.5 Android 图标不生效

12. 维护建议

README.md