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

## 1. 项目简介

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

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

默认服务端地址：

```text
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. 当前目录结构

```text
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

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

### 4.3 使用命令行

Windows 示例：

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

Linux 示例：

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

安装到系统路径：

```bash
cmake --install build
```

## 5. 多平台图标配置

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

### 5.1 Windows

Windows exe 图标使用：

```text
assets/favicon.ico
```

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

### 5.2 桌面运行时图标

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

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

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

```text
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` 文件：

```text
cmake/rewrite_qt.desktop.in
```

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

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

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

```text
rewrite_qt
```

### 5.4 Android

Android 启动器图标位于：

```text
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 相关配置：

```cmake
QT_ANDROID_PACKAGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/android"
QT_ANDROID_APP_NAME "人脸识别考勤系统"
QT_ANDROID_APP_ICON "@mipmap/ic_launcher"
```

`QT_ANDROID_APP_NAME` 用于设置 Android 桌面显示名，`QT_ANDROID_APP_ICON` 用于设置启动图标。

## 6. 功能说明

### 6.1 考勤记录

考勤记录页支持：

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

导出的记录 CSV 字段：

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

### 6.2 统计分析

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

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

导出的统计 CSV 字段：

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

### 6.3 配置中心

配置中心包含：

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

默认签到时段：

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

### 6.4 人脸管理

人脸管理页支持：

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

照片访问地址格式：

```text
{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 数组。单条记录示例：

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

### 8.2 统计数据格式

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

### 8.3 签到时段格式

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

### 8.4 映射配置格式

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

### 8.5 人脸映射格式

```json
{
  "mappings": {
    "face_001": "20240001"
  }
}
```

## 9. 本地配置

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

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

应用信息：

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

## 10. 加密响应

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

```text
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 构建流程。