bishe-STM32/docs/05_项目审查问题清单.md

项目维护、验收与风险清单

1. 文档目的

这份文档用于回答三个问题：

1. 项目目前实现了什么。
2. 验收或答辩时可以从哪些方面说明。
3. 后续维护时有哪些风险和改进方向。

它不是单纯的 bug 列表，而是把功能完整性、稳定性、安全性、易用性和可维护性都列出来。

2. 当前实现状态总览

模块	当前状态	说明
STM32 主控	已实现	接收 K210、考勤判断、加密上传、断线重试、时间段同步
K210 识别	已实现	人脸检测、特征比对、添加/删除、照片上传、映射同步
服务端	已实现	SQLite 存储、HTTP API、Token、AES 解密、统一同步
Qt 管理端	已实现	记录、统计、配置、人脸管理、PC/Android 响应式界面
默认时间段	已改为空	需要管理员在 Qt 中新增
数据导出	已实现	Qt 可导出记录和统计 CSV
自动化 API 回归	已有脚本	server/regression_api_tests.ps1

3. 功能验收清单

3.1 服务端验收

检查项	通过标准
服务可启动	控制台显示监听 8082
健康检查	/api/v1/system/health 返回 healthy
SQLite 初始化	生成或打开 attendance.db
时间接口	/api/v1/system/time 返回 epoch 和 server_time
Token 鉴权	不带 Token 访问受保护接口返回 401
时间段默认	/api/v1/config/time-slots 返回 {"time_slots":[]}
记录接口	/api/v1/attendance/records 返回 JSON 数组
统计接口	/api/v1/attendance/statistics 返回 total、today
照片接口	可列出、上传、下载 JPEG
同步接口	/api/v1/sync/state 按客户端返回不同数据

3.2 Qt 管理端验收

检查项	通过标准
启动界面	Windows 和 Android 都能打开主界面
服务地址	可保存地址并测试连接
配置页布局	PC 和 Android 不出现按钮遮挡
时间段	默认为空，可新增、保存、同步、清空
映射	可新增学生姓名和班级名称映射
记录页	能加载、筛选和导出记录
统计页	能按日期范围统计并导出
人脸管理	能刷新照片、绑定学号、保存映射、删除人脸
自动重连	服务端恢复后能重新同步

3.3 STM32 验收

检查项	通过标准
硬件初始化	OLED、蜂鸣器、LED、串口正常
ESP8266	能连接 WiFi 和服务端
时间同步	能从服务端获取时间或读取 DS1302
时间段同步	能拉取服务端配置，空配置会清空本地时间段
K210 接收	能解析 ID:...,NAME:...,CONF:...
签到判断	置信度、时间段、重复签到逻辑生效
加密上传	服务端能收到并解密保存记录
断线重试	网络断开时记录保留，恢复后同步

3.4 K210 验收

检查项	通过标准
模型加载	三个 .smodel 正常加载
摄像头	LCD 能显示画面，方向正确
人脸识别	已录入人脸能识别，陌生人显示陌生
添加人脸	短按进入添加，确认后写入 SD 卡
删除人脸	长按进入删除，可删除单个或全部
照片上传	新增人脸照片能上传到服务端
映射同步	Qt 保存映射后 K210 本地名称更新
删除同步	Qt 删除后 K210 能删除本地特征并 ACK

4. 数据一致性清单

4.1 Token 一致

这些地方必须一致：

1. 服务端 ATTENDANCE_API_TOKEN 或默认 Token。
2. Qt 环境变量或默认 Token。
3. User/main.c 的 HTTP_API_TOKEN。
4. k210/main.py 的 API_TOKEN。

4.2 服务端地址一致

这些地方要指向同一个服务端：

1. Qt 配置中心的服务端地址。
2. User/main.c 的 HTTP_SERVER_IP 和 HTTP_SERVER_PORT。
3. k210/main.py 的 SERVER_IP 和 SERVER_PORT。

4.3 AES 参数一致

这些文件必须一致：

1. Hardware/Crypto.c
2. server/server_encrypted.cpp
3. QT/src/CryptoUtils.cpp

参数：

Key: 2b 7e 15 16 28 ae d2 a6 ab f7 15 88 09 cf 4f 3c
IV : 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f

4.4 时间段一致

Qt 保存时间段后：

1. 服务端 time_slots 更新。
2. 服务端同步版本提升。
3. STM32 下一次同步拉取到新时间段。
4. STM32 使用新的时间段判断签到。

4.5 人脸映射一致

Qt 保存人脸映射后：

1. 服务端保存 face_mappings。
2. 服务端触发 K210 同步请求。
3. K210 同步后更新 face_mapping.txt。
4. K210 更新 recordftr.txt。
5. K210 发给 STM32 的 ID 变成真实学号。

5. 当前已知限制

5.1 Qt 记录统计基于当前加载记录

Qt 默认请求：

limit=1000&offset=0

如果服务端已有超过 1000 条记录，Qt 本地筛选和统计只覆盖当前加载的这 1000 条。服务端 /statistics 的总数和今日数仍来自数据库。

改进方向：

1. 增加分页。
2. 增加服务端按条件查询。
3. 增加服务端按日期统计接口。

5.2 时间输入缺少强校验

Qt 时间段输入框允许手动输入文本。当前主要依赖 QTime::fromString("HH:mm") 解析。

改进方向：

1. 使用时间选择控件。
2. 保存前校验格式。
3. 检查开始时间必须早于结束时间。
4. 检查时间段重叠。

5.3 K210 JSON 解析仍偏轻量

K210 MicroPython 环境中很多 JSON 解析是手写字符串处理。简单数据够用，但复杂转义字符支持有限。

改进方向：

1. 尽量让服务端返回简单结构。
2. 避免映射 key/value 中出现引号、逗号等复杂字符。
3. 如果固件环境支持，使用 JSON 库。

5.4 STM32 本地缓存容量有限

STM32 本地记录最多 100 条，今日学生缓存最多 50 个 ID。

改进方向：

1. 根据实际班级人数扩大缓存。
2. 增加外部 Flash 或 SD 卡存储。
3. 对已同步记录做更明确的淘汰策略。

5.5 服务端是单文件原生 HTTP 实现

服务端用 socket 手写 HTTP，演示和毕业设计足够直观，但在生产环境上不如成熟 Web 框架。

改进方向：

1. 引入成熟 HTTP 库。
2. 增加结构化日志。
3. 增加配置文件。
4. 增加单元测试。

6. 安全风险和建议

风险	当前状态	建议
默认 Token 写在代码中	存在	部署时用环境变量，并替换 STM32/K210 常量
HTTP 明文传输	存在	公网部署加 HTTPS 反向代理
AES Key/IV 固定	存在	演示可接受，生产应使用更安全的密钥管理
管理接口权限粗粒度	存在	增加用户登录、角色权限
清空记录接口风险高	存在	增加二次确认、审计日志
删除人脸会影响多端	已有同步任务	保留日志，避免误删

7. 答辩或展示可以讲的重点

7.1 多端协同

项目不是单独做一个 UI 或一个识别脚本，而是把嵌入式主控、AI 识别、服务端、桌面/移动管理端串起来。

7.2 安全传输

STM32 上传签到数据不是明文，而是 AES-128-CBC 加密后 Base64 传输。服务端负责解密和校验。

7.3 同步版本机制

服务端维护统一版本号，STM32、K210、Qt 都可以按版本拉取自己需要的数据，减少无意义请求。

7.4 断线容错

STM32 在网络异常时仍能运行，并保留待同步记录；K210 在照片上传失败时保存本地照片并重新排队。

7.5 跨平台管理端

Qt 管理端支持 PC 和 Android，配置页已做响应式布局，避免窄屏按钮遮挡。

7.6 数据可视化和导出

Qt 提供记录筛选、统计分析和 CSV 导出，方便后续汇总考勤数据。

8. 回归测试建议

8.1 每次改服务端后

1. 启动服务端。
2. 运行 server/regression_api_tests.ps1。
3. 手动测试上传时间段为空数组。
4. 手动测试保存人脸映射后同步版本是否变化。
5. 手动测试删除人脸后 pending_delete 是否出现任务。

8.2 每次改 Qt 后

1. 检查 PC 宽屏。
2. 检查 PC 窄屏。
3. 检查 Android 手机宽度。
4. 检查配置中心展开/收起。
5. 检查时间段为空时页面是否正常。
6. 检查保存映射和刷新照片。

8.3 每次改 STM32 后

1. 看调试串口启动日志。
2. 确认 ESP8266 能连 WiFi。
3. 确认能下载时间段。
4. 确认空时间段时不会签到。
5. 配置时间段后再确认能签到。
6. 断开服务端再恢复，检查待同步记录上传。

8.4 每次改 K210 后

1. 确认模型加载。
2. 确认添加人脸写入 SD 卡。
3. 确认照片进入上传队列。
4. 确认服务端能看到照片。
5. 确认 Qt 保存映射后 K210 能同步。
6. 确认 Qt 删除后 K210 能删除并 ACK。

9. 建议后续优化路线

优先级从高到低：

1. 增加 Qt 时间输入校验和重叠检测。
2. 给服务端增加配置文件，减少硬编码。
3. 给服务端增加更完整的自动化测试。
4. 给 Qt 增加记录分页。
5. 给服务端增加按条件查询和统计接口。
6. 把 Token 和 AES 密钥改成部署时配置。
7. 增加 HTTPS 部署说明。
8. 给 STM32 增加更大的离线缓存。
9. 给 K210 使用更稳健的 JSON 解析。
10. 增加服务端日志文件轮转。