# Qt 管理端 README

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

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

```text
http://127.0.0.1:8082
```

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

### 2.2 默认签到时间段

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

```json
{
  "time_slots": []
}
```

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

### 2.3 API Token

Qt 每个请求都会带：

```text
X-Api-Token: <Token>
```

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

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

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

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

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

## 11. 常见问题

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