2026-09-03 摄像头稳定标识与动态映射变更记录

变更原因

项目原先把 Android 运行期间分配的 USB deviceId 拼入菜品摄像头配置，并将三种 UVC 设备与 Camera2 ID 的关系写死。实际设备重启后，USB 枚举顺序会变化：同一台摄像头可能获得不同的 deviceId 和 /dev/videoN，导致已保存的摄像头配置无法正确恢复，或人脸识别打开了另一台摄像头。

设备核验

FY-3576SE 当前连接 3 台 USB 摄像头，三台设备的 VID/PID 均不相同：

历史记录中的另一轮启动曾出现 MC-500U 与 USB2.0_CAM1 的 V4L2/Camera2 编号互换，证明这些编号只能作为本次启动的运行时地址，不能直接作为持久化唯一标识。

本次变更

• 菜品摄像头和人脸摄像头统一保存十进制 VID_PID 稳定标识，不再保存 Android 运行时 deviceId。
• 兼容旧版 deviceId_VID_PID 配置：首次读取时自动规范化为 VID_PID。
• 菜品摄像头的分辨率配置改为按稳定标识保存，并自动复制旧 fbl_旧ID 配置，避免升级后丢失原分辨率。
• 新增当前启动周期的动态 UVC → Camera2 映射：
  • 从 /sys/class/video4linux/video*/device 追溯 USB 父设备并读取 VID/PID；
  • 每台设备采用最小 V4L2 节点作为主捕获节点；
  • 读取 Camera2 中硬件级别为 EXTERNAL 的相机 ID；
  • 只在所有节点能够得到唯一、一致的编号偏移时接受映射，否则清空运行时 Camera2 ID，拒绝猜测。
• 应用启动、设置页应用人脸配置、人脸支付窗口和人脸识别弹窗开始前都会重新同步当前 Camera2 ID。
• 设置页下拉选项改为“产品名称（厂商名称）”，内部稳定标识不直接展示给客户。
• 已保存的菜品或人脸摄像头当前不在线时，不再静默切换到列表第一项，而是提示重新选择。
• 保留菜品摄像头与人脸摄像头不能选择同一设备的冲突拦截。

测试记录

采用测试先行：

1. 先增加稳定标识迁移、稳定分辨率键、当前拓扑映射、重启后节点互换映射、非法与歧义映射测试。
2. 首次运行因新接口和新类尚未实现而编译失败，确认 RED。
3. 完成实现后定向单元测试通过。

最终验证结果：

• 在并发菜单结构调整进入工作区前执行 ./gradlew :app:assembleDebug：成功，包含本次摄像头修改的 Debug APK 已生成。
• 直接从当前摄像头相关源码隔离编译并运行 3 个测试类：11 项测试全部通过。
• git diff --check：通过。
• 最新一次项目全量 :app:testDebugUnitTest :app:assembleDebug --rerun-tasks 未通过主代码编译：工作区中并发进行的菜单响应结构调整已经移除 dishItemList1 至 dishItemList6，但 DishRecognitionActivity 与 DishMenuManagementActivity 仍引用这些旧字段，共 12 个编译错误；该部分不属于本次摄像头改动，本次未修改或绕过它。

设备侧本次只进行了只读枚举和 sysfs/Camera2 信息核验，未覆盖安装 APK，未修改设备现有配置。安装后的重启恢复、设置页显示和三台摄像头逐台预览仍需实机验收。

已知边界

当前设备的三台摄像头可以用 VID/PID 唯一区分。如果以后同时接入两台完全相同且 VID/PID 相同的摄像头，单独使用 VID/PID 无法唯一标定；后续需优先加入可靠 USB 序列号，缺少序列号时再使用固定 USB 物理端口，并在换口时提示重新绑定。本次映射遇到重复稳定标识或歧义时不会猜测设备。

影响范围

本次仅调整摄像头配置持久化、旧配置迁移、UVC/Camera2 动态映射和设置页名称展示。未修改菜品识别算法、人脸算法、支付接口、激活流程或 Git 历史；工作区中已有的人脸激活相关改动保持原样。