7.8 KiB
7.8 KiB
后续优化路线
本文档记录当前项目在“可继续优化但非当前阻塞”的方向，方便后续开发、答辩扩展或二次重构时逐项推进。
1. 当前架构状态
当前项目已经完成以下核心升级：
- API 已统一到
/api/v1/...，旧/api/...仅作为服务端内部兼容层。 - 服务端使用
attendance.db作为主存储，旧 CSV/JSON 文件仅作为首次迁移来源。 - 服务端维护全局同步版本，Qt、STM32、K210 按
last_version增量同步。 - K210 删除人脸使用待删除任务和 ACK 确认。
- K210 新增人脸照片先保存到本地
/sd/face_photos/，再补传服务端。 - Qt 端照片由
ApiClient携带鉴权头下载并缓存为本地file://地址显示。 - 服务端提供
/api/v1/system/storage和/api/v1/sync/version用于调试存储和同步状态。
结论：当前架构已经适合联调、演示和毕业设计答辩。后续优化以工程质量、稳定性和可维护性为主，不建议在演示前集中大改。
2. 优化优先级
| 优先级 | 方向 | 当前是否建议立即做 | 主要收益 |
|---|---|---|---|
| P1 | 服务端 JSON 解析换成 nlohmann/json |
暂缓 | 降低手写解析风险，提升维护性 |
| P1 | 数据库自动备份与恢复文档 | 可做 | 防止误删或调试破坏数据 |
| P2 | 同步版本按模块拆分 | 暂缓 | 降低无关数据重复同步 |
| P2 | 删除任务 task_id 化 | 暂缓 | 删除同步更严谨，避免 ID 歧义 |
| P2 | 设备同步 ACK 状态表 | 暂缓 | 可追踪每台设备同步进度 |
| P2 | 外部配置文件/环境变量统一管理 | 可做 | 降低硬编码凭据风险 |
| P3 | HTTPS/反向代理部署 | 视部署环境 | 公网安全性更好 |
| P3 | 自动化测试脚本 | 可做 | 回归验证更方便 |
| P3 | Qt 同步状态面板 | 可做 | 调试体验更好 |
3. 服务端 JSON 库化
当前状态：
- 服务端部分请求解析和响应构造仍使用字符串查找和手写 JSON 拼接。
- 已有
jsonEscape()，可以避免大多数响应字符串破坏。 - SQLite 已解决 CSV/多 JSON 文件存储不一致问题。
建议方案：
- 引入
nlohmann/json单头文件版本。 - 文件建议放到：
server/third_party/json.hpp
- 服务端引用方式：
#include "third_party/json.hpp"
using json = nlohmann::json;
建议分阶段替换：
- 替换签到请求体解析：
/api/v1/attendance/checkins - 替换时间段保存校验：
/api/v1/config/time-slots - 替换人脸映射保存：
/api/v1/faces/mappings - 替换同步 ACK 解析：
/api/v1/sync/ack - 最后替换大型响应构造：
/api/v1/sync/state
注意事项：
nlohmann/json不需要额外链接库，只需要头文件。- 引入后编译命令通常不变。
- 不建议一次性替换所有 JSON 逻辑，容易引入新问题。
4. 同步版本拆分
当前状态：
- 服务端维护一个全局同步版本。
- 任何数据变化都会让 Qt、STM32、K210 看到版本变化。
- 对当前规模足够清晰，也方便调试。
后续可升级为：
records_version
config_version
faces_version
delete_tasks_version
收益：
- STM32 只关心
config_version。 - K210 只关心
faces_version和delete_tasks_version。 - Qt 可按模块决定是否刷新记录、配置、照片。
代价：
- 服务端同步响应结构要调整。
- Qt、STM32、K210 都要保存多个版本号。
- 调试复杂度会上升。
建议：当前不急，除非后续记录量明显变大或同步频率变高。
5. 删除任务 task_id 化
当前状态：
- 待删除任务以
face_id列表形式保存。 - K210 删除成功后通过 ACK 返回已删除 ID。
后续可升级为：
{
"task_id": "delete_20260501_0001",
"face_id": "1",
"student_id": "20210001",
"created_at": "2026-05-01 14:30:00",
"status": "pending"
}
收益：
- 删除任务可追踪。
- 重复删除、重新添加同 ID 时更不容易混淆。
- 可以在 Qt 端显示待删除任务状态。
建议表结构：
CREATE TABLE delete_tasks (
task_id TEXT PRIMARY KEY,
face_id TEXT NOT NULL,
student_id TEXT,
status TEXT NOT NULL,
created_at TEXT NOT NULL,
ack_at TEXT
);
建议：如果后续要增强多设备同步审计，再做。
6. 设备同步状态表
当前状态：
- 各设备本地保存自己的
last_version。 - 服务端不记录每台设备最后同步到哪个版本。
后续可增加：
CREATE TABLE device_sync_state (
client TEXT PRIMARY KEY,
last_seen_version INTEGER,
last_ack_version INTEGER,
last_seen_at TEXT
);
收益：
- 可以知道 K210、STM32、Qt 是否长期未同步。
- 服务端可以在
/api/v1/system/storage中显示设备同步状态。 - 方便做 Qt 同步状态面板。
建议：当前不是必须，适合作为后续展示增强。
7. 数据库备份与恢复
当前手动备份命令：
sqlite3.exe attendance.db ".backup attendance_backup.db"
后续可增加：
- 服务端启动时自动备份前一天数据库。
- Qt 端提供“导出数据库备份”按钮。
- 文档中增加恢复步骤。
恢复示例：
Copy-Item attendance_backup.db attendance.db
注意：恢复前应先停止服务端，避免写入冲突。
8. 配置外部化
当前仍存在部分硬编码配置：
- K210 WiFi 名称和密码。
- K210 服务端 IP 和端口。
- STM32 服务端 IP、WiFi、班级 ID。
- 默认
X-Api-Token。 - AES Key/IV。
建议方向：
- 服务端继续使用环境变量管理：
ATTENDANCE_API_TOKEN
ATTENDANCE_CORS_ORIGIN
- K210 可使用
/sd/config.txt保存 WiFi、服务端和 token。 - STM32 可集中放在
User/main.c顶部，并在文档中标记部署必改项。 - Qt 可在设置页保存服务端地址，token 可后续加入设置项。
建议：真实公网部署前必须轮换默认 token、WiFi 密码和 AES Key/IV。
9. Qt 同步状态面板
后续可在 Qt 管理端增加一个调试/状态区域，展示：
- 服务器连接状态。
- 当前服务端同步版本。
- 最近同步时间。
records数量。face_mappings数量。face_photos数量。pending_deletes数量。
数据来源：
GET /api/v1/system/storage
GET /api/v1/sync/version
收益：
- 联调时不用一直看服务端日志。
- 演示时可以直观看到多端同步状态。
10. 自动化测试
当前已有手动 curl 文档：
docs/06_后端接口Windows测试命令.md
后续可增加脚本化测试，但不要替代手动文档：
- Windows PowerShell 测试脚本。
- Linux shell 测试脚本。
- 服务端启动后自动测试 health、storage、records、time-slots、sync/state。
建议先保持手动命令文档为主，因为硬件联调环境经常变化。
11. 暂不建议立刻做的优化
以下方向有价值，但当前阶段不建议马上做：
- 删除旧
/api/...兼容层：会降低调试容错，建议答辩后再考虑。 - 全量重写同步协议：当前全局版本方案已经足够。
- 把照片二进制直接存 SQLite：会让数据库变大，当前文件系统存照片、SQLite 存元数据更合适。
- 一次性替换所有 JSON 逻辑：风险高，建议分阶段。
- 引入复杂权限系统：当前
X-Api-Token已满足演示需求，公网正式部署再细分权限。
12. 推荐后续开发顺序
- 先完成 SQLite 版服务端手动编译和接口验证。
- 用
/api/v1/system/storage验证记录、映射、照片、待删除任务数量。 - 如需继续提升服务端质量，先引入
nlohmann/json替换请求解析。 - 如需继续提升演示体验，再做 Qt 同步状态面板。
- 如需继续提升同步严谨性，再做 task_id 删除任务和设备同步状态表。