# 项目总文档

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