# 后端接口 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 写错。