284 lines
9.2 KiB
Markdown
284 lines
9.2 KiB
Markdown
# 项目维护、验收与风险清单
|
|
|
|
## 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`
|
|
|
|
参数：
|
|
|
|
```text
|
|
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 默认请求：
|
|
|
|
```text
|
|
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. 增加服务端日志文件轮转。
|
|
|