AIDishRecognition 摄像头唯一标识与持久化设计说明

1. 核心结论

摄像头配置必须把以下三类信息分开管理：

1. 持久化标识：用于保存“客户选择的是哪一台摄像头”。当前实现使用十进制 VID_PID，例如 1374_41357。
2. 客户显示名称：用于设置页下拉选择。当前显示“产品名称（厂商名称）”，例如“MC-500U（XC-TECH）”。
3. 运行时地址：用于本次启动期间真正打开设备，包括 Android USB deviceId、/dev/videoN 和 Camera2 ID。这些值可能在设备重启后变化，不能作为持久化唯一标识。

在当前 FY-3576SE 上，三台摄像头的 VID/PID 均不相同，因此可以稳定区分。程序重启或设备重启后，只要摄像头仍然连接且应用数据未被清除，就会按照保存的 VID/PID 恢复原选择。

2. 标题字段和用途

3. 当前设备摄像头清单

以下为 2026-09-03 在 FY-3576SE 上的设备快照：

历史设备记录中，MC-500U 与 USB2.0_CAM1 曾分别对应 /dev/video28、/dev/video0，与本次启动正好互换。这证明 V4L2 和 Camera2 编号只是运行时地址，写死映射会在重启后选错摄像头。

4. 当前持久化数据模型

4.1 菜品识别摄像头

菜品摄像头的选择和分辨率都跟随稳定标识保存。因此，同一台摄像头重启后即使获得不同的 Android deviceId，仍能读取原来的选择和分辨率。

4.2 人脸识别摄像头

face_camera_id 虽然也写入配置，但它不是摄像头身份主键。真正的持久化依据是 face_uvc_camera_id；程序每次根据当前硬件拓扑重新得到新的 Camera2 ID。

5. 保存与恢复流程

5.1 用户保存选择

客户选择“产品名称（厂商名称）”
              ↓
程序读取该 UsbDevice 的 vendorId、productId
              ↓
生成稳定标识 VID_PID
              ↓
菜品相机写入 usb_camera
人脸相机写入 face_uvc_camera_id
              ↓
分辨率等参数按稳定标识或业务配置单独保存

5.2 程序重新启动

1. 从 SharedPreferences 读取已保存的稳定标识。
2. 枚举当前连接的 USB/UVC 摄像头。
3. 根据每台设备的 vendorId、productId 重新生成稳定标识。
4. 找到与已保存标识一致的设备并恢复菜品或人脸角色。
5. 如果保存的是旧格式，先执行兼容迁移，再继续匹配。

5.3 整机重新启动

设备重启后，USB deviceId、V4L2 节点和 Camera2 ID 都允许变化。恢复过程如下：

读取 face_uvc_camera_id
          ↓
扫描 /sys/class/video4linux/video*/device
          ↓
从视频节点追溯 USB 父设备，读取 VID/PID
          ↓
建立 VID_PID → 主 V4L2 节点映射
          ↓
读取 Camera2 中 hardware level = EXTERNAL 的相机 ID
          ↓
推导且校验唯一、一致的 Camera2/V4L2 编号偏移
          ↓
生成本次启动的 face_camera_id

当前设备表现为 Camera2 ID 与主 V4L2 节点存在统一偏移，例如 /dev/video0 → 100、/dev/video2 → 102、/dev/video28 → 128。程序通过当次枚举结果推导这个偏移，不再把 100、102、128 与具体型号写死绑定。

6. 旧配置兼容与迁移

旧版菜品配置曾使用 deviceId_VID_PID，例如 1004_1374_41357。新版读取时取最后两段并规范化为 1374_41357。

如果发现旧分辨率键 fbl_旧ID，程序会把值复制到新的 dish_camera_resolution_{VID_PID}。旧键暂不删除，便于升级过渡和问题回溯。

7. 不同场景下的预期行为

8. 客户可读名称设计

设置页不直接显示 1374_41357 之类的内部标识，当前采用“产品名称（厂商名称）”。

• MC-500U（XC-TECH）
• USB 2.0 Camera（Sonix Technology Co., Ltd.）
• USB2.0_CAM1（Sonix Technology Co., Ltd.）

产品名称或厂商名称缺失时，界面使用“USB 摄像头”等兜底文案。名称只服务于客户识别，不参与底层唯一性判断。

9. 同型号双摄的增强方案

9.1 当前边界

9.2 推荐唯一标识优先级

1. 可靠序列号优先：VID + PID + serialNumber。只在序列号非空、非通用占位值且在当前设备列表中唯一时使用。
2. USB 物理端口兜底：VID + PID + physicalPort。摄像头必须固定插在指定接口；换口后提示重新绑定。
3. VID/PID 仅作型号级标识：只能用于当前不存在重复 VID/PID 的场景。

usb:1374:41357:sn:SN00151
usb:3141:25440:port:1-1.6.1

9.3 同型号设备的界面名称

USB 2.0 Camera（Sonix · 尾号0001）
USB 2.0 Camera（Sonix · USB口1）
USB 2.0 Camera（Sonix · USB口2）

还可以增加客户自定义别名，例如“菜品台上方”“人脸支付屏”。别名只作为显示属性，底层仍保存稳定绑定标识。

10. 冲突与安全策略

• 菜品识别和人脸识别不能选择同一台摄像头。
• 设置阶段发现冲突时立即提示，并恢复原选项，不保存错误配置。
• 已保存设备不在线时不自动改选其他摄像头，避免业务角色悄悄错位。
• 人脸摄像头无法推导出唯一且一致的 Camera2 映射时，清空本次运行的 Camera2 ID，不猜测、不打开其他相机。
• 产品名称、厂商名称、Camera2 ID 和 /dev/videoN 都不能单独作为长期身份依据。

11. 代码职责映射

12. 当前验证状态

• 稳定标识规范化、旧格式兼容、稳定分辨率键和动态映射共 11 项摄像头单元测试通过。
• 已覆盖“当前节点顺序”和“重启后节点互换”两种映射测试。
• 包含本次摄像头修改的 Debug APK 曾构建成功。
• 当前工作区另有并发菜单响应结构调整，最新全项目构建被该范围的旧字段引用阻断；不属于摄像头实现错误。
• 新 APK 尚未覆盖安装到 FY-3576SE，因此完整的程序重启和整机重启闭环仍需实机验收。

13. 实机验收清单

13.1 程序重启

• 分别设置菜品摄像头、人脸摄像头及其分辨率。
• 完全结束应用进程后重新打开。
• 确认设置页选项、菜品预览、人脸预览和支付人脸画面均保持原设备。

13.2 整机重启

• 保持三台摄像头连接并重启 FY-3576SE。
• 记录重启后的 /dev/videoN 和 Camera2 ID。
• 即使运行时编号发生变化，也应确认菜品、人脸角色没有互换。

13.3 异常场景

• 拔掉已保存的摄像头后进入设置页，应提示设备不可用，不能自动切换到其他摄像头。
• 插回摄像头并重新枚举后，应恢复对原稳定标识的匹配。
• 尝试让菜品和人脸选择同一设备，应立即拦截且不覆盖原配置。

14. 最终规则摘要

1. 持久化保存稳定身份，不保存运行时地址。
2. 当前设备使用 VID/PID，可以覆盖程序重启、设备重启和枚举顺序变化。
3. V4L2 与 Camera2 ID 每次启动重新解析，不维护型号到编号的硬编码表。
4. 界面展示产品名和厂商名，技术标识只供程序内部使用。
5. 同 VID/PID 双摄必须升级为序列号或物理端口绑定，不能把 VID/PID 误认为所有场景下的单机唯一编号。
6. 失联或映射不明确时停止自动选择，提示客户处理，避免打开错误摄像头。