yzfh/bishe-STM32

Fork 0

Files

T

yzfh a32baa96e3 更新文档

2026-05-01 23:03:42 +08:00

10 KiB

Raw Blame History

后端接口 Windows 测试命令

1. 使用前准备

本文档用于在 Windows PowerShell 中手动测试服务端接口。

默认服务端地址：

$BaseUrl = "http://127.0.0.1:8082"

默认 Token：

$ApiToken = "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"

建议先在 PowerShell 中设置：

$BaseUrl = "http://127.0.0.1:8082"
$ApiToken = "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"
$Headers = @{
  "X-Api-Token" = $ApiToken
  "Accept" = "application/json"
}

如果服务端运行在公网 IP，例如 27.106.113.205：

$BaseUrl = "http://27.106.113.205:8082"

2. 自动化回归脚本

项目已经提供基础回归脚本：

cd D:\University\graduation\code\Reconstruct_Qt\server
.\regression_api_tests.ps1 -BaseUrl "http://127.0.0.1:8082" -ApiToken "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"

脚本会检查：

健康检查。
存储状态。
时间接口。
同步版本。
K210/STM32 同步状态。
记录和统计。
时间段。
查重。
今日记录。
映射。
照片。
学生 ID。
待删除任务。
同步请求。

3. 基础连通性

3.1 健康检查

Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/health"

不需要 Token。正常应返回 status = healthy。

3.2 带 Token 健康检查

Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/health" -Headers $Headers

3.3 端口连通

Test-NetConnection -ComputerName 127.0.0.1 -Port 8082

公网服务器：

Test-NetConnection -ComputerName 27.106.113.205 -Port 8082

3.4 检查端口占用

netstat -ano | findstr :8082

4. 系统接口

4.1 获取服务器时间

Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/time" -Headers $Headers

返回应包含：

epoch
server_time

4.2 查看存储状态

Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/storage" -Headers $Headers

用于确认 SQLite、记录数、照片数、待删除任务等。

4.3 不带 Token 测试鉴权

try {
  Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/storage"
} catch {
  $_.Exception.Response.StatusCode.value__
}

正常应该得到 401。

5. 同步接口

5.1 查看当前同步版本

Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/version" -Headers $Headers

5.2 Qt 同步状态

Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/state?client=qt&last_version=0" -Headers $Headers

返回内容包含 Qt 需要的数据，例如记录、统计、时间段、映射、照片和学生 ID。

5.3 STM32 同步状态

Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/state?client=stm32&last_version=0" -Headers $Headers

重点看：

state.time_slots

当前默认应为空数组，除非已经在 Qt 中保存过时间段。

5.4 K210 同步状态

Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/state?client=k210&last_version=0" -Headers $Headers

重点看：

state.face_mappings
state.pending_delete
state.delete_tasks

5.5 K210 同步 ACK

$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 获取记录

Invoke-RestMethod -Uri "$BaseUrl/api/v1/attendance/records?limit=10&offset=0" -Headers $Headers

6.2 获取统计

Invoke-RestMethod -Uri "$BaseUrl/api/v1/attendance/statistics" -Headers $Headers

6.3 删除单条记录

先准备参数：

$Timestamp = [uri]::EscapeDataString("2026-05-01 08:10:00")
$StudentId = [uri]::EscapeDataString("20240001")

删除：

Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/attendance/records?timestamp=$Timestamp&student_id=$StudentId" `
  -Method DELETE `
  -Headers $Headers

6.4 清空全部记录

危险操作，会删除全部考勤记录：

Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/attendance/records/clear" `
  -Method POST `
  -Headers $Headers `
  -ContentType "application/json"

7. 时间段接口

7.1 获取时间段

Invoke-RestMethod -Uri "$BaseUrl/api/v1/config/time-slots" -Headers $Headers

新部署默认应为：

{
  "time_slots": []
}

7.2 保存空时间段

$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 保存一个时间段

$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 检查重复签到

Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/attendance/duplicates?student_id=20240001&slot_start=08:00&slot_end=09:30" `
  -Headers $Headers

7.5 获取今日某时间段记录

Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/attendance/today?slot_start=08:00&slot_end=09:30" `
  -Headers $Headers

8. 名称映射接口

8.1 获取映射

Invoke-RestMethod -Uri "$BaseUrl/api/v1/config/mappings" -Headers $Headers

8.2 保存映射

$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 获取照片列表

Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/photos" -Headers $Headers

9.2 下载照片

$FaceId = "1"
Invoke-WebRequest `
  -Uri "$BaseUrl/api/v1/faces/photos/$FaceId" `
  -Headers $Headers `
  -OutFile ".\face_$FaceId.jpg"

如果服务端没有该照片，会返回 404。

9.3 上传测试照片

假设当前目录有 test.jpg：

$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 获取人脸映射

Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/mappings" -Headers $Headers

9.5 保存人脸映射

$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

Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/student-ids" -Headers $Headers

9.7 删除人脸

只删除人脸相关信息：

$StudentId = [uri]::EscapeDataString("20240001")
Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/faces/$StudentId" `
  -Method DELETE `
  -Headers $Headers

删除人脸并删除该学生考勤记录：

$StudentId = [uri]::EscapeDataString("20240001")
Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/faces/$StudentId?delete_records=true" `
  -Method DELETE `
  -Headers $Headers

10. K210 删除同步接口

10.1 获取待删除任务

Invoke-RestMethod -Uri "$BaseUrl/api/v1/faces/pending-delete" -Headers $Headers

返回可能包含：

pending_delete
delete_tasks

10.2 旧式删除确认

$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 查询同步请求标志

Invoke-RestMethod -Uri "$BaseUrl/api/v1/sync/request" -Headers $Headers

10.4 确认同步请求

Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/sync/request/ack" `
  -Method POST `
  -Headers $Headers `
  -ContentType "application/json" `
  -Body '{"ack":true}'

10.5 触发 K210 同步

Invoke-RestMethod `
  -Uri "$BaseUrl/api/v1/sync/trigger" `
  -Method POST `
  -Headers $Headers `
  -ContentType "application/json"

11. 加密签到接口说明

STM32 实际上传的是 AES-128-CBC 加密后的 Base64。手动构造比较麻烦，通常不建议用 PowerShell 直接手写。

服务端要求：

POST /api/v1/attendance/checkins
X-Api-Token: <Token>
X-Encrypted: AES128-CBC

明文格式应是：

{
  "student_id": "20240001",
  "name": "张三",
  "confidence": "0.95",
  "status": "success",
  "class_id": "1"
}

如果只是测试记录列表、统计、配置和同步，不需要手动构造加密签到。

12. 常见错误

12.1 401 Unauthorized

原因：Token 缺失或不一致。

检查：

$Headers

12.2 404 Not Found

原因：

路径写错。
服务端还没启动新版本。
照片 ID 不存在。

12.3 Invoke-RestMethod 连接失败

检查服务端是否启动：

Test-NetConnection -ComputerName 127.0.0.1 -Port 8082

12.4 Qt 能访问，本机命令不能访问

可能 Qt 用的是公网地址，而 PowerShell $BaseUrl 还是 127.0.0.1。统一服务端地址。

12.5 STM32/K210 不能访问，电脑能访问

可能原因：

STM32/K210 配置的是公网 IP，本机测的是本地地址。
WiFi 与服务器不在同一网络。
路由器或服务器防火墙阻止端口。
Token 写错。

10 KiB Raw Blame History Unescape Escape