bishe-STM32/docs/00_项目总文档.md

项目总文档

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/CMakeLists.txt 构建的客户端

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

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 检查签到记录、照片、映射与删除同步链路。