初始化毕业设计项目

2026-05-01 20:29:02 +08:00
commit df5b05e936
158 changed files with 67957 additions and 0 deletions
@@ -0,0 +1,50 @@
+# 项目总文档
+
+## 1. 项目概览
+本项目是“人脸识别考勤系统”多端协同工程，包含：
+- STM32 固件端（设备控制与签到逻辑）
+- K210 识别端（视觉识别与人脸管理）
+- C++ 服务端（加密签到、数据管理、同步控制）
+- Qt 管理端（后台管理与可视化）
+
+## 2. 推荐运行链路
+建议使用以下版本组合：
+1. 服务端：`server/server_encrypted.cpp`（HTTP 8082）
+2. STM32：`User/main.c`（加密上传 + 时间段同步）
+3. K210：`k210/main.py`（识别 + 照片上传 + 同步）
+4. Qt：`QT/AttendanceViewer.pro` 构建的客户端
+
+## 3. 总体架构
+1. K210 识别人脸，经 UART 上报 STM32。
+2. STM32 执行签到策略并加密上传服务端 `POST /api/v1/attendance/checkins`。
+3. 服务端写入 `attendance.db` 并提供管理 API。
+4. 服务端在 SQLite 中维护全局同步版本，作为各端同步的权威版本。
+5. Qt 管理端通过统一同步接口拉取记录/统计、配置、人脸照片和映射。
+6. STM32 与 K210 分别按本地 `last_version` 增量拉取时间段、人脸映射与待删除任务，保持端云一致。
+
+## 4. 文档索引（分端）
+- STM32 固件端：`docs/01_STM32固件端文档.md`
+- K210 识别端：`docs/02_K210识别端文档.md`
+- 服务端：`docs/03_服务端文档.md`
+- Qt 管理端：`docs/04_Qt管理端文档.md`
+- 项目审查问题清单：`docs/05_项目审查问题清单.md`
+- 后续优化路线：`docs/07_后续优化路线.md`
+
+## 5. 各端关键配置位置
+- STM32 网络与班级配置：`User/main.c`
+- K210 WiFi/服务器配置：`k210/main.py`
+- Qt 默认服务地址与 API 封装：`QT/src/ApiClient.cpp`、`QT/src/AppController.cpp`
+- 服务端端口与数据文件：`server/server_encrypted.cpp`
+
+## 6. 一致性要求
+- AES Key/IV 必须在 STM32、服务端、Qt 三端一致。
+- 服务端建议统一使用加密版本，避免接口行为不一致。
+- 各端时间配置需统一时区（当前代码以 UTC+8 逻辑处理）。
+
+## 7. 快速部署顺序
+1. 编译并启动服务端（确认 `:8082` 可访问）。
+2. 启动 Qt，先做 `/api/v1/system/health` 连通性验证。
+3. 烧录 STM32 固件并联网。
+4. 启动 K210 脚本并确认识别/同步正常。
+5. 用 Qt 检查签到记录、照片、映射与删除同步链路。
+