传输加密

04_Qt管理端文档.md

@@ -12,9 +12,9 @@ Qt 管理端是整个系统的图形化后台。它支持 Windows 桌面端和 A
 6. 导出统计 CSV。
 7. 配置服务端地址和 API Token。
 8. 配置签到时间段。
-9. 配置学号到姓名、学号到班级编号、班级编号到班级名的学生档案映射。
+9. 维护班级信息。
 10. 查看 K210 上传的人脸照片。
-11. 给 K210 face_id 绑定真实学号。
+11. 编辑 K210 face_id 对应的学号、姓名和班级。
 12. 删除人脸信息，并可选择删除相关考勤记录。
 
 ## 2. 相关文件
@@ -26,11 +26,12 @@ Qt 管理端是整个系统的图形化后台。它支持 Windows 桌面端和 A
 | `QT/src/AppController.*` | QML 与 C++ 业务逻辑的中枢 |
 | `QT/src/ApiClient.*` | HTTP API 客户端 |
 | `QT/src/AttendanceTypes.h` | 考勤记录、统计、时间段结构体 |
-| `QT/src/CryptoUtils.*` | AES 解密工具 |
+| `QT/src/CryptoUtils.*` | AES 加解密工具 |
 | `QT/src/RecordListModel.*` | 考勤记录模型 |
 | `QT/src/StatisticsListModel.*` | 统计模型 |
 | `QT/src/TimeSlotListModel.*` | 时间段模型 |
-| `QT/src/MappingListModel.*` | 学生姓名、学生班级归属、班级名称映射模型 |
+| `QT/src/StudentProfileListModel.*` | 学生档案模型 |
+| `QT/src/MappingListModel.*` | 班级信息等键值模型 |
 | `QT/src/FaceListModel.*` | 人脸管理模型 |
 | `QT/CMakeLists.txt` | Qt/CMake 构建配置 |
 | `QT/clear_qt_cache.ps1` | 清理当前 Qt 项目的 Qt Creator/CMake 缓存 |
@@ -71,8 +72,8 @@ Qt 管理端是单窗口应用，共 5 个页面：
 | --- | --- |
 | 考勤记录 | 查看、筛选、导出、清空记录 |
 | 统计分析 | 按时间范围统计学生签到情况 |
-| 配置中心 | 服务端地址、签到时间段、名称映射 |
-| 人脸管理 | 查看照片、绑定学号、删除人脸 |
+| 配置中心 | 服务端地址、签到时间段、班级管理 |
+| 人脸管理 | 查看照片、编辑学号姓名班级、删除人脸 |
 | 关于 | 系统说明、版本和作者信息 |
 
 PC 宽屏显示左侧导航栏；窄屏和 Android 显示顶部/底部更紧凑的导航布局。
@@ -107,6 +108,8 @@ X-Api-Token: <Token>
 Accept: application/json
 ```
 
+除照片 JPEG 下载外，Qt 的业务 JSON 请求和响应统一使用 AES-128-CBC + PKCS#7 + Base64。GET/DELETE 请求要求服务端返回加密响应，POST JSON 会先加密请求体并携带 `X-Encrypted: AES128-CBC`；照片内容仍按 `image/jpeg` 原始二进制显示。
+
 Token 默认值写在 `QT/src/ApiClient.cpp`，也可以通过环境变量覆盖：
 
 ```powershell
@@ -127,7 +130,7 @@ Qt 启动后：
 2. 设置应用图标、应用名、版本号、组织名。
 3. Android 下启用原生文字渲染。
 4. 创建 `AppController`。
-5. `AppController` 读取本地服务端地址、API Token、映射配置、时间段配置。
+5. `AppController` 读取本地服务端地址、API Token、学生档案缓存、班级缓存、人脸档案缓存和时间段配置。
 6. `ApiClient` 设置当前服务端地址和 API Token。
 7. 启动自动重连状态并执行健康检查。
 8. QML 载入 `Main.qml`。
@@ -181,18 +184,18 @@ GET /api/v1/attendance/records?limit=1000&offset=0
 | --- | --- |
 | 班级 | `class_id` 匹配 |
 | 学号 | `student_id` 匹配 |
-| 姓名 | 映射姓名或原始 name 包含关键字 |
+| 姓名 | 学生档案姓名或原始 name 包含关键字 |
 | 日期 | 全部、今天、最近 7 天、最近 30 天、指定日期 |
 
 姓名显示优先级：
 
-1. 如果学生映射里有该学号，显示映射姓名。
+1. 如果学生档案里有该学号，显示档案姓名。
 2. 否则显示服务端记录中的 `name`。
 3. 如果都没有，则显示原始学号。
 
 班级显示优先级：
 
-1. 如果班级映射里有该 `class_id`，显示映射班级名。
+1. 如果班级信息里有该 `class_id`，显示班级名称。
 2. 否则显示 `class_id`。
 
 ## 11. 记录导出
@@ -244,7 +247,7 @@ GET /api/v1/attendance/records?limit=1000&offset=0
 
 1. 服务端地址和 API Token。
 2. 时间段配置。
-3. 名称映射配置。
+3. 班级管理。
 
 ### 13.1 服务端配置
 
@@ -294,37 +297,36 @@ timeslot_config.json
 
 该文件只作为 Qt 管理端本地缓存；服务端当前以 SQLite 中的配置为准。
 
-### 13.3 学生档案映射配置
+### 13.3 班级管理
 
-学号到姓名：
+配置中心只负责班级新建、命名和删除，不再单独提供学生档案编辑页。学生学号、姓名和班级归属在人脸管理页的编辑弹窗中维护。班级信息通过独立接口维护：
+
+```text
+GET /api/v1/classes
+POST /api/v1/classes
+```
+
+请求体示例：
 
 ```json
 {
-  "20240001": "张三"
+  "classes": [
+    {
+      "class_id": "1",
+      "class_name": "软件工程一班"
+    }
+  ]
 }
 ```
 
-学号到班级编号：
+记录列表、班级筛选和导出优先使用学生档案中的班级归属关系；没有配置时才显示设备上传记录中的原始班级编号。
 
-```json
-{
-  "20240001": "1"
-}
-```
+删除班级前，管理端会先检查该班级下是否还有学生；服务端保存班级时也会进行同类校验。
 
-班级编号到班级名称：
-
-```json
-{
-  "1": "软件工程一班"
-}
-```
-
-记录列表、班级筛选和导出优先使用“学号到班级编号”的归属关系；没有配置时才显示设备上传记录中的原始班级编号。
 本地文件：
 
 ```text
-mapping_config.json
+profiles_cache.json
 ```
 
 ## 14. 人脸管理页
@@ -332,17 +334,18 @@ mapping_config.json
 人脸管理页把两类人脸数据合并展示：
 
 1. 服务端照片列表。
-2. 服务端 face_id 到学生 ID 映射。
+2. 服务端人脸档案。
 
-照片 ID 始终使用 K210 原始 `face_id`，例如 `faces/1.jpg`。Qt 只维护 `face_id -> 学号` 的绑定关系，不再把所有已有考勤学生 ID 当成“无照片人脸”展示。
+照片 ID 始终使用 K210 原始 `face_id`，例如 `faces/1.jpg`。Qt 通过 `/api/v1/face_profiles` 维护 `face_id -> 学号` 的绑定关系，并通过 `/api/v1/students` 保存学号、姓名和班级归属，不再把所有已有考勤学生 ID 当成“无照片人脸”展示。
 
 用户可以：
 
 1. 刷新人脸库。
-2. 为每张照片填写真实学号。
-3. 保存映射。
+2. 点击“编辑”打开弹窗，填写真实学号、姓名和班级。
+3. 保存学生档案和人脸档案。
 4. 删除人脸。
-5. 删除人脸时选择是否同时删除该学生的考勤记录。
+5. 修改已有学号前弹窗提示影响范围。
+6. 删除人脸时选择是否同时删除该学生的考勤记录。
 
 照片下载流程：
 
@@ -409,7 +412,7 @@ server/apiToken
 | 文件 | 内容 |
 | --- | --- |
 | `timeslot_config.json` | 时间段配置 |
-| `mapping_config.json` | 学生姓名、学生班级归属和班级名称映射 |
+| `profiles_cache.json` | 学生档案、班级信息和人脸档案的本地缓存 |
 | `face_photos/*.jpg` | 下载后的人脸照片缓存 |
 
 ## 18. 构建方式
@@ -456,4 +459,4 @@ powershell -ExecutionPolicy Bypass -File .\clear_qt_cache.ps1
 | 人脸照片不显示 | 下载失败、本地缓存路径无效、服务端无照片 | 刷新人脸库，看服务端 `faces/` |
 | 统计数量少于服务端总量 | Qt 默认只拉取 1000 条记录 | 增加分页或服务端统计接口 |
 | 时间段为空导致无法签到 | 当前默认就是空配置 | 在配置中心新增时间段并保存 |
-| 保存映射后 K210 没变化 | K210 尚未同步或 WiFi 不通 | 等待同步或检查 K210 日志 |
+| 保存人脸档案后 K210 没变化 | K210 尚未同步或 WiFi 不通 | 等待同步或检查 K210 日志 |