# 后续优化路线

本文档记录当前项目在“可继续优化但非当前阻塞”的方向，方便后续开发、答辩扩展或二次重构时逐项推进。

## 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 删除任务和设备同步状态表。