547 lines
10 KiB
Markdown
547 lines
10 KiB
Markdown
# 后端接口 Windows 测试命令
|
||
|
||
## 1. 使用前准备
|
||
|
||
本文档用于在 Windows PowerShell 中手动测试服务端接口。
|
||
|
||
默认服务端地址：
|
||
|
||
```powershell
|
||
$BaseUrl = "http://127.0.0.1:8082"
|
||
```
|
||
|
||
默认 Token：
|
||
|
||
```powershell
|
||
$ApiToken = "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"
|
||
```
|
||
|
||
建议先在 PowerShell 中设置：
|
||
|
||
```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`：
|
||
|
||
```powershell
|
||
$BaseUrl = "http://27.106.113.205:8082"
|
||
```
|
||
|
||
## 2. 自动化回归脚本
|
||
|
||
项目已经提供基础回归脚本：
|
||
|
||
```powershell
|
||
cd D:\University\graduation\code\Reconstruct_Qt\server
|
||
.\regression_api_tests.ps1 -BaseUrl "http://127.0.0.1:8082" -ApiToken "atk_nKfVWLhMjL0RGSfRll3R_sdJS6IrIjuV"
|
||
```
|
||
|
||
脚本会检查：
|
||
|
||
1. 健康检查。
|
||
2. 存储状态。
|
||
3. 时间接口。
|
||
4. 同步版本。
|
||
5. K210/STM32 同步状态。
|
||
6. 记录和统计。
|
||
7. 时间段。
|
||
8. 查重。
|
||
9. 今日记录。
|
||
10. 映射。
|
||
11. 照片。
|
||
12. 学生 ID。
|
||
13. 待删除任务。
|
||
14. 同步请求。
|
||
|
||
## 3. 基础连通性
|
||
|
||
### 3.1 健康检查
|
||
|
||
```powershell
|
||
Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/health"
|
||
```
|
||
|
||
不需要 Token。正常应返回 `status = healthy`。
|
||
|
||
### 3.2 带 Token 健康检查
|
||
|
||
```powershell
|
||
Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/health" -Headers $Headers
|
||
```
|
||
|
||
### 3.3 端口连通
|
||
|
||
```powershell
|
||
Test-NetConnection -ComputerName 127.0.0.1 -Port 8082
|
||
```
|
||
|
||
公网服务器：
|
||
|
||
```powershell
|
||
Test-NetConnection -ComputerName 27.106.113.205 -Port 8082
|
||
```
|
||
|
||
### 3.4 检查端口占用
|
||
|
||
```powershell
|
||
netstat -ano | findstr :8082
|
||
```
|
||
|
||
## 4. 系统接口
|
||
|
||
### 4.1 获取服务器时间
|
||
|
||
```powershell
|
||
Invoke-RestMethod -Uri "$BaseUrl/api/v1/system/time" -Headers $Headers
|
||
```
|
||
|
||
返回应包含：
|
||
|
||
```text
|
||
epoch
|
||
server_time
|
||
```
|
||
|
||
### 4.2 查看存储状态
|
||
|
||
```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
|
||
state.time_slots
|
||
```
|
||
|
||
当前默认应为空数组，除非已经在 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 写错。
|
||
|