2026-07-24 人脸 UVC 相机切换黑屏修复记录

问题现象

在“设置 → 相机设置”中切换人脸识别摄像头后，设备能够成功打开，UVC 原生层也持续收到 640x480 视频帧，但预览区域偶发持续黑屏。

根因

原实现使用 UVCCamera.setPreviewTexture(SurfaceTexture) 绑定预览。该 UVC 库会在方法内部临时创建 Surface，业务层无法持有和释放这个对象。

切换、暂停和页面销毁时，原实现调用 setPreviewTexture(null) 尝试解绑，但库内部会执行 new Surface(null)，直接抛出 IllegalArgumentException: surfaceTexture must not be null。因此旧预览输出面并未按预期解绑和释放。重复切换后，旧输出面可能继续占用同一个 BufferQueue，最终形成“相机有帧但 TextureView 黑屏”的状态。

本次变更

• 新增预览 Surface 租约管理：
  • 同一个有效 SurfaceTexture 只复用一个 Surface。
  • 相机切换、预览暂停、分辨率重配、纹理销毁和控制器释放时，统一释放当前 Surface。
  • 释放后即使还是同一个 SurfaceTexture，下次启动也会创建全新的 Surface。
• 预览绑定改为业务层显式创建 Surface，并调用 setPreviewDisplay(Surface)。
• 预览停止时先调用 setPreviewDisplay(null) 从 UVC 原生层解绑，再调用 Surface.release()。
• 删除所有 setPreviewTexture(null) 清理调用，避免无效解绑和异常。
• 保留原有相机选择、分辨率、旋转、镜像及双向冲突拦截逻辑。

测试记录

采用测试先行：

1. 新增 Surface 租约生命周期测试。
2. 首次运行因租约实现不存在而编译失败，确认 RED。
3. 实现租约管理并接入 UVC 控制器后，定向测试通过。

完整验证：

• ./gradlew :app:testDebugUnitTest :app:assembleDebug --rerun-tasks：成功，94 个任务重新执行。
• git diff --check：通过。
• Debug APK 覆盖安装到 FY-3576SE：成功。
• 在 USB2.0_CAM1 (11391/19040) 与 USB 2.0 Camera (3141/25440) 之间连续往返切换 6 次：
  • 每次均在约 1 秒内恢复预览。
  • 6 张切换后截图的预览区域均检测到有效非黑画面。
• 快速连续切换压力测试后，最终相机正常打开并显示有效画面。
• 修复后日志未再出现 surfaceTexture must not be null、Surface 清理异常、Java 崩溃或 UVC 原生崩溃。

影响范围

本次仅修正公共 UvcCameraController 的预览 Surface 生命周期，并增加对应单元测试。设置页人脸相机预览直接受益；复用该控制器的 UVC 测试页面同样获得规范的 Surface 清理行为。未修改菜品识别算法、人脸识别算法、支付流程、接口协议或 Git 历史。