初始化毕业设计项目

2026-05-01 20:29:02 +08:00
commit df5b05e936
158 changed files with 67957 additions and 0 deletions
@@ -0,0 +1,272 @@
+# 后续优化路线
+
+本文档记录当前项目在“可继续优化但非当前阻塞”的方向，方便后续开发、答辩扩展或二次重构时逐项推进。
+
+## 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` 单头文件版本。
+- 文件建议放到：
+
+```text
+server/third_party/json.hpp
+```
+
+- 服务端引用方式：
+
+```cpp
+#include "third_party/json.hpp"
+using json = nlohmann::json;
+```
+
+建议分阶段替换：
+
+1. 替换签到请求体解析：`/api/v1/attendance/checkins`
+2. 替换时间段保存校验：`/api/v1/config/time-slots`
+3. 替换人脸映射保存：`/api/v1/faces/mappings`
+4. 替换同步 ACK 解析：`/api/v1/sync/ack`
+5. 最后替换大型响应构造：`/api/v1/sync/state`
+
+注意事项：
+
+- `nlohmann/json` 不需要额外链接库，只需要头文件。
+- 引入后编译命令通常不变。
+- 不建议一次性替换所有 JSON 逻辑，容易引入新问题。
+
+## 4. 同步版本拆分
+
+当前状态：
+
+- 服务端维护一个全局同步版本。
+- 任何数据变化都会让 Qt、STM32、K210 看到版本变化。
+- 对当前规模足够清晰，也方便调试。
+
+后续可升级为：
+
+```text
+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。
+
+后续可升级为：
+
+```json
+{
+  "task_id": "delete_20260501_0001",
+  "face_id": "1",
+  "student_id": "20210001",
+  "created_at": "2026-05-01 14:30:00",
+  "status": "pending"
+}
+```
+
+收益：
+
+- 删除任务可追踪。
+- 重复删除、重新添加同 ID 时更不容易混淆。
+- 可以在 Qt 端显示待删除任务状态。
+
+建议表结构：
+
+```sql
+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`。
+- 服务端不记录每台设备最后同步到哪个版本。
+
+后续可增加：
+
+```sql
+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. 数据库备份与恢复
+
+当前手动备份命令：
+
+```powershell
+sqlite3.exe attendance.db ".backup attendance_backup.db"
+```
+
+后续可增加：
+
+- 服务端启动时自动备份前一天数据库。
+- Qt 端提供“导出数据库备份”按钮。
+- 文档中增加恢复步骤。
+
+恢复示例：
+
+```powershell
+Copy-Item attendance_backup.db attendance.db
+```
+
+注意：恢复前应先停止服务端，避免写入冲突。
+
+## 8. 配置外部化
+
+当前仍存在部分硬编码配置：
+
+- K210 WiFi 名称和密码。
+- K210 服务端 IP 和端口。
+- STM32 服务端 IP、WiFi、班级 ID。
+- 默认 `X-Api-Token`。
+- AES Key/IV。
+
+建议方向：
+
+- 服务端继续使用环境变量管理：
+
+```text
+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` 数量。
+
+数据来源：
+
+```text
+GET /api/v1/system/storage
+GET /api/v1/sync/version
+```
+
+收益：
+
+- 联调时不用一直看服务端日志。
+- 演示时可以直观看到多端同步状态。
+
+## 10. 自动化测试
+
+当前已有手动 curl 文档：
+
+```text
+docs/06_后端接口Windows测试命令.md
+```
+
+后续可增加脚本化测试，但不要替代手动文档：
+
+- Windows PowerShell 测试脚本。
+- Linux shell 测试脚本。
+- 服务端启动后自动测试 health、storage、records、time-slots、sync/state。
+
+建议先保持手动命令文档为主，因为硬件联调环境经常变化。
+
+## 11. 暂不建议立刻做的优化
+
+以下方向有价值，但当前阶段不建议马上做：
+
+- 删除旧 `/api/...` 兼容层：会降低调试容错，建议答辩后再考虑。
+- 全量重写同步协议：当前全局版本方案已经足够。
+- 把照片二进制直接存 SQLite：会让数据库变大，当前文件系统存照片、SQLite 存元数据更合适。
+- 一次性替换所有 JSON 逻辑：风险高，建议分阶段。
+- 引入复杂权限系统：当前 `X-Api-Token` 已满足演示需求，公网正式部署再细分权限。
+
+## 12. 推荐后续开发顺序
+
+1. 先完成 SQLite 版服务端手动编译和接口验证。
+2. 用 `/api/v1/system/storage` 验证记录、映射、照片、待删除任务数量。
+3. 如需继续提升服务端质量，先引入 `nlohmann/json` 替换请求解析。
+4. 如需继续提升演示体验，再做 Qt 同步状态面板。
+5. 如需继续提升同步严谨性，再做 task_id 删除任务和设备同步状态表。
+