初始化毕业设计项目

docs/02_K210识别端文档.md

@@ -0,0 +1,75 @@
+# K210识别端文档
+
+## 1. 端侧职责
+- 进行人脸检测、特征提取、识别。
+- 通过 UART1 将识别结果实时发送给 STM32。
+- 通过 UART2 驱动 ESP8266，与服务端同步人脸映射与删除任务。
+- 上传新增人脸照片到服务端。
+
+对应入口文件：`k210/main.py`
+
+## 2. 通信链路
+- `UART1`（K210 <-> STM32）：发送识别结果。
+- `UART2`（K210 <-> ESP8266）：HTTP 通信到服务端 `:8082`。
+
+识别结果发送格式（给 STM32）：
+- 已识别：`ID:<id>,NAME:<name>,CONF:<score>`
+- 陌生人：`UNKNOWN`
+
+## 3. 本地数据文件
+- 人脸特征库：`/sd/recordftr.txt`
+- 本地映射缓存：`/sd/face_mapping.txt`
+- 本地同步版本：`/sd/sync_version.txt`
+- 本地人脸照片缓存：`/sd/face_photos/<face_id>.jpg`
+
+## 4. 服务端交互接口
+K210 在脚本中使用 HTTP 访问以下接口：
+- `GET /api/v1/sync/state?client=k210&last_version=<本地版本>`：按版本拉取统一同步状态。
+- `POST /api/v1/sync/ack`：确认已完成删除任务。
+- `GET /api/v1/sync/request`：轮询是否触发同步。
+- `POST /api/v1/sync/request/ack`：确认收到同步请求。
+- `GET /api/v1/faces/photos`：获取服务端已有照片列表，用于判断本地照片是否需要补传。
+- `POST /api/v1/faces/photos/<face_id>`：上传 JPEG 人脸照片。
+
+v1 兼容辅助接口：
+- `GET /api/v1/faces/mappings`
+- `GET /api/v1/faces/pending-delete`
+- `POST /api/v1/faces/delete-ack`
+
+## 5. 启动与运行流程
+1. 初始化摄像头、KPU 模型、LCD、按键中断、串口。
+2. 启动 ESP8266，尝试连接 WiFi。
+3. 启动同步：
+- 读取 `/sd/sync_version.txt`。
+- 请求统一同步状态。
+- 先删除 `pending_delete` 中的人脸特征。
+- 再应用 `face_mappings`。
+- 成功后保存新的同步版本。
+4. 进入主循环：识别 + 绘制 + 向 STM32 上报。
+5. 分时网络任务（避免阻塞识别帧率）：
+- 新增人脸时先把 JPEG 保存到 `/sd/face_photos/`，再加入上传队列。
+- 启动时先获取服务端照片列表，再扫描 `/sd/face_photos/`，只补传服务端缺失的照片；如果服务端不可达，则退回全量加入补传队列。
+- 优先处理照片上传队列，上传失败会保留本地照片并等待下次重试。
+- 然后处理同步任务。
+
+## 6. 按键功能
+在 `k210/main.py` 中定义：
+- 短按：添加人脸。
+- 长按（约2秒）：进入删除单个人脸模式。
+- 超长按（约5秒）：删除全部人脸。
+
+## 7. 当前默认配置（代码内）
+- WiFi：`YOUR_WIFI_SSID / YOUR_WIFI_PASSWORD`
+- 服务端：`127.0.0.1:8082`（部署时改为实际服务端地址）
+- API Token：`change-me-token`（部署时必须修改）
+
+文件位置：`k210/main.py`
+
+## 8. 部署注意事项
+- SD 卡需包含模型文件：
+  - `/sd/FaceDetection.smodel`
+  - `/sd/FaceLandmarkDetection.smodel`
+  - `/sd/FeatureExtraction.smodel`
+- 与 STM32 使用统一学号语义（映射同步后应发送真实学号语义）。
+- 网络任务失败不会阻塞识别主流程，但会影响照片与映射同步时效；本地照片缓存会用于后续补传。
+