人脸相机稳定性修复记录

变更日期

2026-07-22

问题与根因

• 设备的人脸摄像头由 Camera2 暴露为原始 ID 102，旧配置却按整数保存。
• 设置页能枚举到 102，人脸识别阶段却调用 Camera1 的 Camera.open(102)；Camera1 仅接受逻辑序号，因此报相机 ID 非法。
• 旧实现失败后固定回退 Camera.open(0)。该设备的逻辑序号与原始 Camera2 ID 映射不稳定，可能打开菜品摄像头，也可能打开人脸摄像头，形成“经常调不起来”的表象。
• 设置预览、人脸识别弹窗和支付测试弹窗各自管理相机，异步释放或重试可能影响另一入口的新会话。

修复内容

• 人脸相机 ID 全链路改为字符串，精确使用 Camera2 原始 ID；旧整型配置首次读取时自动迁移，不清空现场设置。
• 设置页只展示 Camera2 实际可用设备。已保存相机不存在时要求重新选择，不再静默回退到其他摄像头。
• 新增统一的人脸相机会话协调器，由设置预览、正式识别和支付测试三个入口按 owner 独占使用。
• 使用 CameraX 同时绑定 Preview 与 ImageAnalysis，将 YUV_420_888 按行跨度、像素跨度转换成百度人脸 SDK 所需的 NV21。
• 相机启动以收到真实首帧为成功条件；首帧超时后按 300ms、800ms、1500ms 有界重试，最终失败时向页面返回明确错误。
• 使用 generation、owner 和 attempt 隔离异步回调，旧页面延迟释放或旧重试不能关闭、覆盖新页面会话。
• 识别倒计时和识别处理从真实首帧后开始，避免把相机启动耗时计入识别超时。

代码范围

• 新增 FaceCameraCoordinator、Nv21Converter、FaceCameraSelectionPolicy。
• 调整 FaceCameraSettings、SettingsCameraFragment、FaceRecognitionPop、FaceRecognitionDialogFragment。
• 三个人脸预览布局统一切换为 CameraX PreviewView。
• 新增相机选择策略和 NV21 转换单元测试。

验证结果

• TDD 红灯：实现前定向测试因缺少选择策略与 NV21 转换类而编译失败。
• TDD 绿灯：FaceCameraSelectionPolicyTest 与 Nv21ConverterTest 全部通过。
• ./gradlew :app:testDebugUnitTest :app:assembleDebug 通过。
• git diff --check 通过。
• Debug APK 通过 adb install -r 覆盖安装，保留了设备数据。
• 旧的整型配置已在设备上迁移为 <string name="face_camera_id">102</string>。
• 设置页真机日志确认 owner=SETTINGS, cameraId=102，CameraService 使用 Camera API 2 打开 ID 102，随后收到 640x480 首帧。
• 修复后验证日志未再出现 input id 102 invalid。
• 支付测试弹窗在该设备上受既有百度人脸 SDK 未授权状态阻断，原生日志为 face instance is not authorized；该现象发生在相机启动之前，不属于本次相机链路回归。

版本控制说明

本次未执行暂存、提交、推送或分支切换；未覆盖项目中与本次修复无关的已有修改。