人脸相机 UVC 与支付 Camera2 对应方案

1. 方案状态

• 日期：2026-07-24
• 目标版本：fix_face_mamera 当前工作区
• 状态：已落地并完成真机回归
• 设备：FY-3576SE

2. 问题与根因

“设置 → 相机设置”中的人脸相机使用 UVC 枚举、切换和预览，保存的是 UVC VID/PID；人脸支付及支付测试仍通过 CameraX/Camera2 获取帧，读取 Camera2 ID。

两条链路使用不同的相机标识，原实现只保存 UVC ID，没有同步支付链路读取的 Camera2 ID，因此设置页虽然能正确预览，支付时仍可能打开旧相机或错误相机。

3. 对应关系

通过设备 sysfs 的 USB VID/PID、/dev/videoN 节点以及 Camera2 外部相机编号规则完成物理核验：

当前设备的 Camera2 外部相机 ID 为 100 + video 节点编号。

4. 落地设计

4.1 设置页双键保存

用户选择人脸相机时同时保存：

• face_uvc_camera_id：供设置页 UVC 预览和再次进入页面时恢复选择。
• face_camera_id：供人脸支付及支付测试的 CameraX/Camera2 链路使用。

4.2 启动自动迁移

应用启动时根据已保存的 face_uvc_camera_id 重新计算并同步 face_camera_id。已有安装不需要用户重新进入设置页选择，相机对应关系即可自动修正。

4.3 兼容与保护

• 同时兼容稳定 UVC ID（如 3141_25440）和旧的带 USB deviceId 格式（如 1007_3141_25440）。
• 尚未保存 UVC 相机时保留旧 Camera2 配置，避免升级后破坏原有设置。
• 已保存非空 UVC ID 但无法映射时清空 Camera2 ID，避免支付误开其他摄像头。
• 正式支付继续复用现有 CameraX 人脸帧处理链路，不改人脸识别算法。

5. 代码范围

• app/src/main/java/com/cpt/aidishrecognition/utils/FaceCameraIdMapping.java
• app/src/main/java/com/cpt/aidishrecognition/utils/FaceCameraSettings.java
• app/src/main/java/com/cpt/aidishrecognition/application/CptApplication.java
• app/src/test/java/com/cpt/aidishrecognition/utils/FaceCameraIdMappingTest.java

6. 验收结果

• 三组固定硬件映射、旧格式兼容、未知设备保护的单元测试：通过。
• 完整 :app:testDebugUnitTest：通过。
• 完整 :app:assembleDebug：通过。
• 完整构建共执行 94 个任务，结果 BUILD SUCCESSFUL。
• 真机选择 USB2.0_CAM1 后保存 face_uvc_camera_id=11391_19040、face_camera_id=100。
• 真机选择 USB 2.0 Camera 后保存 face_uvc_camera_id=3141_25440、face_camera_id=102。
• 应用启动时已验证可将历史错配的 Camera2 ID 自动纠正。
• 多次切换后人脸相机预览正常，无 Java 或 UVC 原生崩溃。

7. 边界与后续

本映射以当前 FY-3576SE 的固定 USB 拓扑为准。如果硬件型号、USB 接口或内核视频节点分配发生变化，需要重新核验 /dev/videoN 并更新映射表。