bishe-STM32/docs/03_服务端文档.md

服务端文档

1. 推荐服务端版本

当前项目推荐使用：server/server_encrypted.cpp

原因：

• 支持 STM32 上传加密签到数据。
• 支持 Qt 管理端所需管理 API。
• 支持 K210 人脸照片与映射同步相关 API。

2. 端口与数据文件

• HTTP 端口：8082
• SQLite 数据库：attendance.db
• 启动备份目录：backups/
• 日志：运行时生成 attendance.log
• 旧数据迁移来源：attendance_database.csv、timeslots_config.json、mapping_config.json、face_id_mapping.json、pending_delete.json、sync_request.json、sync_version.txt
• 人脸目录：faces/
• 全局同步版本：存储在 attendance.db 的 kv_store 表中。
• 删除任务：存储在 pending_delete 表中，包含 task_id、face_id、student_id、created_at、status、ack_at。
• 设备同步状态：存储在 device_sync_state 表中，用于追踪各端最近同步版本和 ACK 版本。

3. 签到数据链路

1. STM32 调用 POST /api/v1/attendance/checkins 上传 Base64 密文。
2. 服务端按 AES-128-CBC 解密并解析 JSON。
3. 将记录写入 attendance.db 的 records 表（含 class_id 字段）。

4. 核心 API（按模块）

4.1 考勤与统计

• POST /api/v1/attendance/checkins
• GET /api/v1/attendance/records?limit=&offset=
• GET /api/v1/attendance/statistics
• POST /api/v1/attendance/records/clear
• DELETE /api/v1/attendance/records?timestamp=&student_id=
• GET /api/v1/system/health
• GET /api/v1/system/storage
• GET /api/v1/system/time

说明：

• /api/v1/attendance/records 与 /api/v1/attendance/statistics 默认返回明文 JSON；请求头包含 X-Encrypted-Response: true 时返回加密数据。

4.2 时间段与查重

• POST /api/v1/config/time-slots
• GET /api/v1/config/time-slots
• GET /api/v1/attendance/duplicates?student_id=&slot_start=&slot_end=
• GET /api/v1/attendance/today?slot_start=&slot_end=

4.3 映射与照片

• POST /api/v1/config/mappings
• GET /api/v1/config/mappings
• GET /api/v1/faces/photos
• GET /api/v1/faces/photos/<id>
• POST /api/v1/faces/photos/<face_id>
• POST /api/v1/faces/mappings
• GET /api/v1/faces/mappings
• GET /api/v1/faces/student-ids

4.4 统一同步接口（推荐）

• GET /api/v1/sync/state?client=<client>&last_version=<version>
• POST /api/v1/sync/ack
• GET /api/v1/sync/version

说明：

• 服务端是唯一权威状态源。
• 每次签到、清空/删除记录、修改时间段、修改映射、上传照片、删除人脸，服务端都会递增 kv_store.sync_version。
• 设备端保存自己的 last_version，请求时带给服务端。
• 服务端会记录每个 client 的 last_seen_version、last_ack_version 和 last_seen_at，可通过 /api/v1/system/storage 查看。
• 如果版本无变化，服务端返回 changed:false，设备端无需重复解析配置。
• 如果版本有变化，服务端返回 changed:true 和当前客户端需要的状态。
• /api/v1/sync/version 只返回当前版本和服务端时间，适合调试时快速确认同步版本。

客户端示例：

• client=k210：返回 face_mappings 和 pending_delete。
• client=stm32：返回 time_slots 和 server_time。
• client=qt：返回时间段、人脸映射、照片列表、学生ID列表、记录、统计和映射配置。
• client=all：返回全部可同步状态。

K210 删除确认示例：

{
  "client": "k210",
  "version": 12,
  "deleted": ["2", "3"],
  "task_ids": ["2-1770000000", "3-1770000001"]
}

4.5 人脸删除与同步控制

• DELETE /api/v1/faces/<student_id>?delete_records=true
• GET /api/v1/faces/pending-delete
• POST /api/v1/faces/delete-ack
• GET /api/v1/sync/request
• POST /api/v1/sync/request/ack
• POST /api/v1/sync/trigger

说明：这些是 v1 下的兼容控制接口；推荐设备端优先使用统一同步接口，只有手动调试或兼容旧流程时才单独调用。

4.6 旧接口兼容

服务端内部仍保留旧 /api/... 路由兼容层，便于历史程序临时访问；新代码和新文档统一使用 /api/v1/...。

5. 编译与运行

Windows（示例）：

cd server
g++ -o server_encrypted.exe server_encrypted.cpp -lws2_32 -lcrypto -lssl -lsqlite3 -std=c++11
server_encrypted.exe

Linux（示例）：

cd server
g++ -o server_encrypted server_encrypted.cpp -lcrypto -lssl -lsqlite3 -lpthread -std=c++11
./server_encrypted

说明：服务端启动时会自动创建 attendance.db。如果检测到旧 CSV/JSON 文件，会在首次启动时导入；之后以后端 API 和 SQLite 为准。

6. 备份与恢复

服务端启动时如果发现已有 attendance.db，会先复制到 backups/attendance_YYYY-MM-DD_HH-MM-SS.db。备份失败时服务端会停止启动，避免在没有恢复点的情况下继续写入。

恢复步骤：

1. 停止 server_encrypted。
2. 将当前 attendance.db 改名保留，例如 attendance.broken.db。
3. 从 backups/ 选择最近可用备份，复制为 attendance.db。
4. 重新启动服务端，访问 /api/v1/system/storage，确认 ok:true、quick_check:"ok"。

7. 公网部署安全

本机或内网演示可以直接监听 0.0.0.0:8082。公网部署建议：

• 设置 ATTENDANCE_BIND_HOST=127.0.0.1，只让服务端监听本机。
• 使用 Nginx 或 Caddy 终止 HTTPS，并由反向代理转发到 127.0.0.1:8082。
• 配置 HTTPS 后立即轮换 ATTENDANCE_API_TOKEN、设备端 Token 和相关密钥。
• 反向代理层继续限制来源 IP、请求体大小和访问日志脱敏。

8. 自动化回归

服务端启动后可运行：

powershell -ExecutionPolicy Bypass -File .\regression_api_tests.ps1 -BaseUrl "http://127.0.0.1:8082" -ApiToken "change-me-token"

脚本覆盖 health、storage、time、sync、records、statistics、time-slots、mappings、faces 等低风险接口；真实 AES 签到正文和真实照片上传仍保留手动验证。

9. 版本说明

仓库仅保留当前推荐版本：server_encrypted.cpp。旧版实验服务端与测试脚本已清理，避免误部署非鉴权接口。

10. 关键一致性要求

• AES Key/IV 必须与 STM32、Qt 完全一致。
• 若 Qt 无法解析记录，先检查是否误连到非加密版本服务端。

11. 后续优化

服务端当前已经完成 SQLite 主存储、v1 接口、自动备份和统一同步模型。后续需要继续跟踪的风险和优化项已统一记录在 docs/05_项目审查问题清单.md。