传输加密

02_K210识别端文档.md

@@ -169,21 +169,25 @@ UNKNOWN
 POST /api/v1/faces/photos/1
 ```
 
-## 10. 人脸映射同步
+## 10. 人脸档案同步
 
-新增人脸后，K210 只知道它是 `ID:1`，不知道真实学号。管理员需要在 Qt 管理端把 `1` 映射成学号：
+新增人脸后，K210 只知道它是 `ID:1`，不知道真实学号。管理员需要在 Qt 管理端把 `1` 绑定到学号，服务端通过 `/api/v1/face_profiles` 保存人脸档案：
 
 ```json
 {
-  "mappings": {
-    "1": "20240001"
-  }
+  "face_profiles": [
+    {
+      "face_id": "1",
+      "student_id": "20240001",
+      "status": "active"
+    }
+  ]
 }
 ```
 
 K210 同步后会：
 
-1. 拉取服务端 `face_mappings`。
+1. 拉取服务端 `face_profiles`。
 2. 修改本地 `face_mapping.txt`。
 3. 保持 `recordftr.txt` 中的原始 `ID:<face_id>` 不变。
 4. 识别成功后先取原始 `face_id`，再通过 `face_mapping.txt` 转成真实学号发送给 STM32。
@@ -215,9 +219,14 @@ GET /api/v1/sync/state?client=k210&last_version=<本地版本>
   "version": 5,
   "changed": true,
   "state": {
-    "face_mappings": {
-      "1": "20240001"
-    },
+    "face_profiles": [
+      {
+        "face_id": "1",
+        "student_id": "20240001",
+        "status": "active",
+        "has_photo": true
+      }
+    ],
     "pending_delete": ["1"],
     "delete_tasks": [
       {
@@ -256,15 +265,15 @@ Qt 删除会在服务端创建待删除任务。K210 同步后删除本地人脸
 
 ## 14. K210 常用接口
 
+K210 与服务端之间的业务 JSON 请求和响应使用 AES-128-CBC + PKCS#7 + Base64。`esp_http_get` 会请求加密响应并在本地解密，`esp_http_post_json` 会先加密 JSON 请求体再发送。人脸照片 JPEG 仍按 `image/jpeg` 原始二进制上传，避免在 K210/ESP8266 分块传输中引入过高内存占用。
+
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
 | `POST` | `/api/v1/faces/photos/<face_id>` | 上传 JPEG 照片 |
 | `GET` | `/api/v1/faces/photos` | 查询服务端已有照片 |
-| `GET` | `/api/v1/faces/mappings` | 拉取人脸 ID 到学号映射 |
-| `GET` | `/api/v1/faces/pending-delete` | 拉取待删除列表 |
-| `POST` | `/api/v1/faces/delete-ack` | 删除同步确认 |
-| `GET` | `/api/v1/sync/state?client=k210&last_version=N` | 推荐统一同步 |
-| `POST` | `/api/v1/sync/ack` | 推荐统一同步确认 |
+| `GET` | `/api/v1/face_profiles` | 拉取人脸档案与学号绑定关系 |
+| `GET` | `/api/v1/sync/state?client=k210&last_version=N` | 统一拉取人脸档案、删除任务与同步版本 |
+| `POST` | `/api/v1/sync/ack` | 统一同步确认 |
 | `GET` | `/api/v1/sync/request` | 查询 Qt/服务端是否请求同步 |
 | `POST` | `/api/v1/sync/request/ack` | 确认收到同步请求 |
 
@@ -277,7 +286,7 @@ Qt 删除会在服务端创建待删除任务。K210 同步后删除本地人脸
 | 添加人脸失败 | 没检测到陌生人脸、SD 卡不可写、照片保存失败 | 检查光照、SD 卡和日志 |
 | Qt 看不到照片 | 上传队列未完成、服务端地址不一致、Token 错误 | 看 K210 `[PHOTO]`、`[NET]`、`[ESP]` 日志 |
 | 删除后仍识别 | K210 尚未同步或 ACK 失败 | 等待同步，检查 `/api/v1/sync/state` |
-| 发给 STM32 的还是 `ID:1` | 映射没有保存或 K210 未同步 | Qt 保存映射后触发同步 |
+| 发给 STM32 的还是 `ID:1` | 人脸档案没有保存或 K210 未同步 | Qt 保存人脸档案后触发同步 |
 
 ## 16. 修改配置时要注意
 
@@ -285,4 +294,4 @@ Qt 删除会在服务端创建待删除任务。K210 同步后删除本地人脸
 2. K210 的 WiFi 配置和 STM32 可以相同，也可以不同，但都要能访问服务端。
 3. K210 侧照片上传使用自己的 ESP8266，不依赖 STM32 的 ESP8266。
 4. K210 本地 SD 卡数据很重要，删除或格式化 SD 卡会丢失本地人脸特征。
-5. 如果重新录入人脸，原 face_id 可能变化，需要重新在 Qt 管理端设置映射。
+5. 如果重新录入人脸，原 face_id 可能变化，需要重新在 Qt 管理端设置人脸档案绑定关系。