更新文档

2026-05-01 23:03:42 +08:00
parent 5a31ff2179
commit a32baa96e3
14 changed files with 2799 additions and 1853 deletions
@@ -1,340 +1,546 @@
-# 后端接口 Windows 手动测试命令
+# 后端接口 Windows 测试命令

-当前后端 `server_encrypted.cpp` 只监听 HTTP 端口：
+## 1. 使用前准备

-```text
-8082
-```
+本文档用于在 Windows PowerShell 中手动测试服务端接口。

-以下命令适合在 Windows PowerShell 或 CMD 中复制执行。Windows 下建议使用 `curl.exe`，避免 PowerShell 把 `curl` 解析成别名。
-
-如果后端在本机运行，使用：
-
-```text
-http://127.0.0.1:8082
-```
-
-如果测试公网服务器，替换成：
-
-```text
-https://your-domain.example
-```
-
-下面示例默认使用本机地址。
-
-## 0. 自动化回归脚本
-
-服务端启动后，优先运行脚本化检查：
+默认服务端地址：

 ```powershell
-cd server
-powershell -ExecutionPolicy Bypass -File .\regression_api_tests.ps1 -BaseUrl "http://127.0.0.1:8082" -ApiToken "change-me-token"
+$BaseUrl = "http://127.0.0.1:8082"
 ```

-该脚本覆盖健康检查、存储状态、同步状态、记录、统计、时间段、映射和照片列表等低风险接口。需要真实硬件、真实 AES 正文或真实 JPEG 文件的接口仍按下方手动命令验证。
-
-## 1. 测试端口和服务健康
+默认 Token：

 ```powershell
-curl.exe -i --max-time 8 "http://127.0.0.1:8082/api/v1/system/health"
+$ApiToken = "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"
 ```

-预期能看到 `HTTP/1.1 200 OK` 或类似成功响应。
-
-## 2. 获取服务器时间
+建议先在 PowerShell 中设置：

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/system/time"
+$BaseUrl = "http://127.0.0.1:8082"
+$ApiToken = "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"
+$Headers = @{
+  "X-Api-Token" = $ApiToken
+  "Accept" = "application/json"
+}
 ```

-## 2.0 查看 SQLite 存储状态
+如果服务端运行在公网 IP，例如 `27.106.113.205`：

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/system/storage"
+$BaseUrl = "http://27.106.113.205:8082"
 ```

-重点看：
+## 2. 自动化回归脚本

-```text
-"storage":"sqlite"
-"database":"attendance.db"
-"ok":true
-"quick_check":"ok"
-"records": 考勤记录数量
-"face_photos": 服务端照片数量
-"pending_deletes": K210待删除任务数量
-```
-
-## 2.0.1 查看当前同步版本
+项目已经提供基础回归脚本：

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/sync/version"
+cd D:\University\graduation\code\Reconstruct_Qt\server
+.\regression_api_tests.ps1 -BaseUrl "http://127.0.0.1:8082" -ApiToken "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"
 ```

-## 2.1 统一同步状态：K210
+脚本会检查：
+
+1. 健康检查。
+2. 存储状态。
+3. 时间接口。
+4. 同步版本。
+5. K210/STM32 同步状态。
+6. 记录和统计。
+7. 时间段。
+8. 查重。
+9. 今日记录。
+10. 映射。
+11. 照片。
+12. 学生 ID。
+13. 待删除任务。
+14. 同步请求。
+
+## 3. 基础连通性
+
+### 3.1 健康检查

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/sync/state?client=k210&last_version=0"
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/health"
 ```

-重点看：
+不需要 Token。正常应返回 `status = healthy`。

-```text
-"version": 当前服务端同步版本
-"changed": true/false
-"face_mappings": 人脸ID到学号映射
-"pending_delete": K210需要删除的本地人脸ID
-```
-
-## 2.2 统一同步状态：STM32
+### 3.2 带 Token 健康检查

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/sync/state?client=stm32&last_version=0"
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/health" -Headers $Headers
 ```

-重点看 `time_slots` 是否正确返回。
-
-## 2.3 统一同步状态：Qt
+### 3.3 端口连通

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/sync/state?client=qt&last_version=0"
+Test-NetConnection -ComputerName 127.0.0.1 -Port 8082
 ```

-## 2.4 K210 确认统一同步删除
-
-把 `2` 换成真实已删除成功的人脸 ID。
+公网服务器：

 ```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"client\":\"k210\",\"version\":1,\"deleted\":[\"2\"]}" "http://127.0.0.1:8082/api/v1/sync/ack"
+Test-NetConnection -ComputerName 27.106.113.205 -Port 8082
 ```

-## 3. 获取全部考勤记录
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/attendance/records?limit=1000&offset=0"
-```
-
-后端当前以 `attendance.db` 为准。旧 `attendance_database.csv` 只会在首次启动 SQLite 时作为迁移来源，之后新增记录不会再写回 CSV。
-
-如果本机安装了 `sqlite3.exe`，也可以在服务端运行目录执行：
-
-```powershell
-sqlite3.exe attendance.db "SELECT timestamp,student_id,name,confidence,status,class_id FROM records ORDER BY id DESC LIMIT 10;"
-```
-
-备份当前数据库：
-
-```powershell
-sqlite3.exe attendance.db ".backup attendance_backup.db"
-```
-
-## 4. 获取统计信息
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/attendance/statistics"
-```
-
-## 5. 获取签到时间段
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/config/time-slots"
-```
-
-## 6. 保存签到时间段
-
-用于测试 Qt 端 `/api/v1/config/time-slots` 保存失败的问题。执行后观察后端日志，正常应该显示 `POST body size` 大于 0。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"time_slots\":[{\"name\":\"上午签到\",\"start_time\":\"08:00\",\"end_time\":\"09:30\",\"enabled\":true},{\"name\":\"中午签退\",\"start_time\":\"12:00\",\"end_time\":\"13:00\",\"enabled\":true},{\"name\":\"下午签到\",\"start_time\":\"14:00\",\"end_time\":\"15:00\",\"enabled\":true},{\"name\":\"晚上签退\",\"start_time\":\"17:00\",\"end_time\":\"18:30\",\"enabled\":true}]}" "http://127.0.0.1:8082/api/v1/config/time-slots"
-```
-
-## 7. 检查是否重复签到
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/attendance/duplicates?student_id=1&slot_start=00:00&slot_end=23:59"
-```
-
-## 8. 获取今天指定时间段记录
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/attendance/today?slot_start=00:00&slot_end=23:59"
-```
-
-也可以测试指定签到时间段：
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/attendance/today?slot_start=14:00&slot_end=15:00"
-```
-
-## 9. 获取映射配置
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/config/mappings"
-```
-
-## 10. 保存映射配置
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"student_name_map\":{\"1\":\"ID1\"},\"class_name_map\":{\"1\":\"一班\"}}" "http://127.0.0.1:8082/api/v1/config/mappings"
-```
-
-## 11. 获取人脸照片列表
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/faces/photos"
-```
-
-## 12. 下载指定人脸照片
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" "http://127.0.0.1:8082/api/v1/faces/photos/1" --output "%TEMP%\backend_face_1.jpg"
-```
-
-如果 `face_id=1` 存在，照片会保存到：
-
-```text
-%TEMP%\backend_face_1.jpg
-```
-
-## 13. 上传人脸照片
-
-把 `C:\path\to\face.jpg` 换成真实 jpg 文件路径。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Content-Type: image/jpeg" --data-binary "@C:\path\to\face.jpg" "http://127.0.0.1:8082/api/v1/faces/photos/1"
-```
-
-## 14. 获取人脸 ID 映射
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/faces/mappings"
-```
-
-## 15. 保存人脸 ID 映射
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"mappings\":{\"1\":\"1\"}}" "http://127.0.0.1:8082/api/v1/faces/mappings"
-```
-
-## 16. 获取全部学生 ID
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/faces/student-ids"
-```
-
-## 17. 获取待删除列表
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/faces/pending-delete"
-```
-
-## 18. 确认删除同步完成
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"face_id\":\"1\"}" "http://127.0.0.1:8082/api/v1/faces/delete-ack"
-```
-
-## 19. K210 查询是否需要同步
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" "http://127.0.0.1:8082/api/v1/sync/request"
-```
-
-## 20. 触发 K210 同步
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"sync\":true}" "http://127.0.0.1:8082/api/v1/sync/trigger"
-```
-
-## 21. K210 同步确认
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"ack\":true}" "http://127.0.0.1:8082/api/v1/sync/request/ack"
-```
-
-## 22. 加密签到接口
-
-`/api/v1/attendance/checkins` 需要 STM32 生成的 AES-128-CBC Base64 加密正文。把 `BODY` 替换成真实加密数据。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "X-Encrypted: AES128-CBC" -H "Content-Type: application/octet-stream" --data-binary "BODY" "http://127.0.0.1:8082/api/v1/attendance/checkins"
-```
-
-## 23. 删除单条考勤记录
-
-危险操作，会删除真实数据。执行前把时间和学生 ID 改成要删除的记录。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -X DELETE "http://127.0.0.1:8082/api/v1/attendance/records?timestamp=2026-05-01%2014%3A30%3A38&student_id=1"
-```
-
-## 24. 删除指定人脸
-
-危险操作，只删除人脸信息，不删除考勤记录。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -X DELETE "http://127.0.0.1:8082/api/v1/faces/1"
-```
-
-## 25. 删除指定人脸并删除相关考勤记录
-
-危险操作，会删除人脸和相关记录。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -X DELETE "http://127.0.0.1:8082/api/v1/faces/1?delete_records=true"
-```
-
-## 26. 清空全部考勤记录
-
-危险操作，会清空考勤数据库。
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Content-Type: application/json" -X POST --data-binary "{}" "http://127.0.0.1:8082/api/v1/attendance/records/clear"
-```
-
-## 27. Windows 上检查端口占用
+### 3.4 检查端口占用

 ```powershell
 netstat -ano | findstr :8082
 ```

-如果能看到 `LISTENING`，说明本机有程序正在监听 `8082`。
+## 4. 系统接口

-## 28. Windows 上测试 TCP 端口连通
+### 4.1 获取服务器时间

 ```powershell
-Test-NetConnection 127.0.0.1 -Port 8082
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/time" -Headers $Headers
 ```

-公网服务器测试：
-
-```powershell
-Test-NetConnection 127.0.0.1 -Port 8082
-```
-
-`TcpTestSucceeded : True` 表示 TCP 端口可连通。
-
-## 29. 判断 Qt POST 是否真的发送了请求体
-
-先手动执行这条：
-
-```powershell
-curl.exe -i --max-time 8 -H "X-Api-Token: change-me-token" -H "Accept: application/json" -H "Content-Type: application/json" -X POST --data-binary "{\"time_slots\":[{\"name\":\"下午签到\",\"start_time\":\"14:00\",\"end_time\":\"15:00\",\"enabled\":true}]}" "http://127.0.0.1:8082/api/v1/config/time-slots"
-```
-
-如果后端日志显示：
+返回应包含：

 ```text
-[HTTP] POST body size: xx bytes
+epoch
+server_time
 ```

-说明服务端可以正常接收请求体。
+### 4.2 查看存储状态

-如果 Qt 保存时后端仍显示：
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/storage" -Headers $Headers
+```
+
+用于确认 SQLite、记录数、照片数、待删除任务等。
+
+### 4.3 不带 Token 测试鉴权
+
+```powershell
+try {
+  Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/storage"
+} catch {
+  $_.Exception.Response.StatusCode.value__
+}
+```
+
+正常应该得到 `401`。
+
+## 5. 同步接口
+
+### 5.1 查看当前同步版本
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/version" -Headers $Headers
+```
+
+### 5.2 Qt 同步状态
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/state?client=qt&last_version=0" -Headers $Headers
+```
+
+返回内容包含 Qt 需要的数据，例如记录、统计、时间段、映射、照片和学生 ID。
+
+### 5.3 STM32 同步状态
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/state?client=stm32&last_version=0" -Headers $Headers
+```
+
+重点看：

 ```text
-[HTTP] POST body size: 0 bytes
+state.time_slots
 ```

-说明问题在 Qt 端发送 POST 的方式上。
+当前默认应为空数组，除非已经在 Qt 中保存过时间段。
+
+### 5.4 K210 同步状态
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/state?client=k210&last_version=0" -Headers $Headers
+```
+
+重点看：
+
+```text
+state.face_mappings
+state.pending_delete
+state.delete_tasks
+```
+
+### 5.5 K210 同步 ACK
+
+```powershell
+$Body = @{
+  client = "k210"
+  version = 1
+  deleted = @()
+  task_ids = @()
+}
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/sync/ack" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body ($Body | ConvertTo-Json -Compress)
+```
+
+## 6. 考勤记录接口
+
+### 6.1 获取记录
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/attendance/records?limit=10&offset=0" -Headers $Headers
+```
+
+### 6.2 获取统计
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/attendance/statistics" -Headers $Headers
+```
+
+### 6.3 删除单条记录
+
+先准备参数：
+
+```powershell
+$Timestamp = [uri]::EscapeDataString("2026-05-01 08:10:00")
+$StudentId = [uri]::EscapeDataString("20240001")
+```
+
+删除：
+
+```powershell
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/attendance/records?timestamp=$Timestamp&student_id=$StudentId" `
+  -Method DELETE `
+  -Headers $Headers
+```
+
+### 6.4 清空全部记录
+
+危险操作，会删除全部考勤记录：
+
+```powershell
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/attendance/records/clear" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json"
+```
+
+## 7. 时间段接口
+
+### 7.1 获取时间段
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/config/time-slots" -Headers $Headers
+```
+
+新部署默认应为：
+
+```json
+{
+  "time_slots": []
+}
+```
+
+### 7.2 保存空时间段
+
+```powershell
+$Body = @{
+  time_slots = @()
+}
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/config/time-slots" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body ($Body | ConvertTo-Json -Depth 5 -Compress)
+```
+
+### 7.3 保存一个时间段
+
+```powershell
+$Body = @{
+  time_slots = @(
+    @{
+      name = "上午签到"
+      start_time = "08:00"
+      end_time = "09:30"
+      enabled = $true
+    }
+  )
+}
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/config/time-slots" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body ($Body | ConvertTo-Json -Depth 5 -Compress)
+```
+
+### 7.4 检查重复签到
+
+```powershell
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/attendance/duplicates?student_id=20240001&slot_start=08:00&slot_end=09:30" `
+  -Headers $Headers
+```
+
+### 7.5 获取今日某时间段记录
+
+```powershell
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/attendance/today?slot_start=08:00&slot_end=09:30" `
+  -Headers $Headers
+```
+
+## 8. 名称映射接口
+
+### 8.1 获取映射
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/config/mappings" -Headers $Headers
+```
+
+### 8.2 保存映射
+
+```powershell
+$Body = @{
+  student_name_map = @{
+    "20240001" = "张三"
+  }
+  class_name_map = @{
+    "1" = "软件工程一班"
+  }
+}
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/config/mappings" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body ($Body | ConvertTo-Json -Depth 10 -Compress)
+```
+
+## 9. 人脸照片和映射接口
+
+### 9.1 获取照片列表
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/photos" -Headers $Headers
+```
+
+### 9.2 下载照片
+
+```powershell
+$FaceId = "1"
+Invoke-WebRequest `
+  -Uri "$BaseUrl/api/v1/faces/photos/$FaceId" `
+  -Headers $Headers `
+  -OutFile ".\face_$FaceId.jpg"
+```
+
+如果服务端没有该照片，会返回 404。
+
+### 9.3 上传测试照片
+
+假设当前目录有 `test.jpg`：
+
+```powershell
+$FaceId = "test001"
+$PhotoBytes = [System.IO.File]::ReadAllBytes((Resolve-Path ".\test.jpg"))
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/faces/photos/$FaceId" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "image/jpeg" `
+  -Body $PhotoBytes
+```
+
+### 9.4 获取人脸映射
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/mappings" -Headers $Headers
+```
+
+### 9.5 保存人脸映射
+
+```powershell
+$Body = @{
+  mappings = @{
+    "1" = "20240001"
+  }
+}
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/faces/mappings" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body ($Body | ConvertTo-Json -Depth 5 -Compress)
+```
+
+保存后应提升同步版本，并触发 K210 同步请求。
+
+### 9.6 获取全部学生 ID
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/student-ids" -Headers $Headers
+```
+
+### 9.7 删除人脸
+
+只删除人脸相关信息：
+
+```powershell
+$StudentId = [uri]::EscapeDataString("20240001")
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/faces/$StudentId" `
+  -Method DELETE `
+  -Headers $Headers
+```
+
+删除人脸并删除该学生考勤记录：
+
+```powershell
+$StudentId = [uri]::EscapeDataString("20240001")
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/faces/$StudentId?delete_records=true" `
+  -Method DELETE `
+  -Headers $Headers
+```
+
+## 10. K210 删除同步接口
+
+### 10.1 获取待删除任务
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/pending-delete" -Headers $Headers
+```
+
+返回可能包含：
+
+```text
+pending_delete
+delete_tasks
+```
+
+### 10.2 旧式删除确认
+
+```powershell
+$Body = @{
+  face_id = "1"
+}
+
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/faces/delete-ack" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body ($Body | ConvertTo-Json -Compress)
+```
+
+### 10.3 查询同步请求标志
+
+```powershell
+Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/request" -Headers $Headers
+```
+
+### 10.4 确认同步请求
+
+```powershell
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/sync/request/ack" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json" `
+  -Body '{"ack":true}'
+```
+
+### 10.5 触发 K210 同步
+
+```powershell
+Invoke-RestMethod `
+  -Uri "$BaseUrl/api/v1/sync/trigger" `
+  -Method POST `
+  -Headers $Headers `
+  -ContentType "application/json"
+```
+
+## 11. 加密签到接口说明
+
+STM32 实际上传的是 AES-128-CBC 加密后的 Base64。手动构造比较麻烦，通常不建议用 PowerShell 直接手写。
+
+服务端要求：
+
+```text
+POST /api/v1/attendance/checkins
+X-Api-Token: <Token>
+X-Encrypted: AES128-CBC
+```
+
+明文格式应是：
+
+```json
+{
+  "student_id": "20240001",
+  "name": "张三",
+  "confidence": "0.95",
+  "status": "success",
+  "class_id": "1"
+}
+```
+
+如果只是测试记录列表、统计、配置和同步，不需要手动构造加密签到。
+
+## 12. 常见错误
+
+### 12.1 401 Unauthorized
+
+原因：Token 缺失或不一致。
+
+检查：
+
+```powershell
+$Headers
+```
+
+### 12.2 404 Not Found
+
+原因：
+
+1. 路径写错。
+2. 服务端还没启动新版本。
+3. 照片 ID 不存在。
+
+### 12.3 Invoke-RestMethod 连接失败
+
+检查服务端是否启动：
+
+```powershell
+Test-NetConnection -ComputerName 127.0.0.1 -Port 8082
+```
+
+### 12.4 Qt 能访问，本机命令不能访问
+
+可能 Qt 用的是公网地址，而 PowerShell `$BaseUrl` 还是 `127.0.0.1`。统一服务端地址。
+
+### 12.5 STM32/K210 不能访问，电脑能访问
+
+可能原因：
+
+1. STM32/K210 配置的是公网 IP，本机测的是本地地址。
+2. WiFi 与服务器不在同一网络。
+3. 路由器或服务器防火墙阻止端口。
+4. Token 写错。