人脸识别阈值动态配置设计

设计日期：2026-08-31

项目仓库：/Users/liang/AndroidStudioProjects/CusumptionMachine

当前实施分支：fix-menu-dish-list-refresh-crash

背景与现状

消费机的人脸库检索由 app 模块内的 FaceSDKManager 完成。当前生活照、证件照和 RGB+NIR 三种模型的默认识别阈值均为 0.7f，实际判断规则为“检索最高分大于阈值才识别成功”。设置中的整数分值需要除以 100 后传给现有识别逻辑，因此设置值 70 对应 SDK 阈值 0.70f。

registerlibrary 中独立存在人脸注册模块的阈值，本次不调整；活体检测、图像质量和人脸检测置信度也不属于本次范围。

目标

• 在基础设置中增加可点击的“人脸识别阈值”设置项，通过独立输入弹窗修改阈值。
• 可配置范围为 50～100，默认值为 70，保持未配置设备的当前识别行为。
• 修改后无需重启，下一次人脸库检索立即使用新阈值。
• 配置持久化保存，应用重启后继续生效。
• 非法历史配置统一限制到 50～100，避免识别逻辑使用越界值。

方案选择

采用独立的人脸识别阈值输入弹窗，并沿用项目现有输入类弹窗的视觉和交互风格。该方案使阈值输入、校验和回调职责集中，不改造配对码、价格等已有弹窗，避免通用化改造影响其他业务。

未采用原生通用提示框，因为其样式和现有页面不一致；也未复用配对码弹窗，因为两者的校验规则和业务职责不同。

界面设计

设置项放在“基础设置”页面的人脸识别配置区域，紧邻“人脸识别超时间”。设置行包含：

• 标题：“人脸识别阈值”。
• 当前值文本，例如“70分”。
• 进入标识，整行均可点击。

点击设置行后打开独立输入弹窗，弹窗标题为“人脸识别阈值”。输入框仅接受整数，打开时回显当前已设置的阈值并默认全选，方便用户直接替换。输入框下方固定显示提示词：“输入范围是 50~100，推荐 70 以上，80 最优。”

用户点击确认且输入有效时保存配置、刷新设置行当前值并关闭弹窗；点击取消时不修改配置。首次进入设置页时读取已保存值，没有配置时显示 70。界面文案、尺寸和范围通过资源或命名常量维护，不在业务代码中散落硬编码。

组件职责

阈值配置类

• 定义并复用配置键、默认值、最小值和最大值。
• 读取及保存 50～100 的整数分值。
• 对异常值执行边界限制。
• 将整数分值转换为 SDK 使用的 0.50f～1.00f。

该类只负责人脸匹配阈值，不管理活体、质量或注册模块参数。

基础设置页

FragmentBasic 负责展示当前整数分值、响应设置行点击、打开输入弹窗，并在收到有效确认结果后调用阈值配置类保存和刷新显示。设置页不直接操作 BaseConfig 内部字段。

阈值输入弹窗

新增独立弹窗组件，负责回显当前阈值、展示输入范围提示、校验用户输入并通过回调返回有效整数。弹窗不直接保存配置，也不承担人脸识别逻辑。

人脸检索

FaceSDKManager 在每次比较检索最高分之前读取最新 SDK 阈值，并继续使用现有“大于阈值才通过”的判断规则。这样不依赖页面生命周期，也不需要重新初始化人脸模型。

数据流

1. 用户进入基础设置页，配置类读取本地整数分值并限制到 50～100。
2. 设置页显示当前分值。
3. 用户点击设置行，输入弹窗回显当前分值并默认全选。
4. 用户输入整数并点击确认，弹窗校验输入是否处于 50～100。
5. 校验通过后，设置页持久化保存分值、刷新当前值并关闭弹窗。
6. 下一次人脸库检索时，FaceSDKManager 读取最新分值并除以 100。
7. 检索最高分大于转换后的阈值时，继续执行现有用户查询和识别成功流程。

异常处理

• 未保存配置：使用 70。
• 保存值低于 50：按 50 使用。
• 保存值高于 100：按 100 使用。
• 输入为空、不是整数或超出 50～100：不保存、不关闭弹窗，并提示用户输入有效范围。
• 用户取消弹窗：保持原配置和设置页显示不变。
• 设置页销毁或重新创建：从持久化配置恢复，不依赖弹窗状态。
• 调整阈值不会触发人脸模型重载，也不会中断正在运行的其他页面。

测试与验收

自动测试

• 默认值转换：70 转换为 0.70f。
• 最小值边界：小于 50 的配置限制为 50，50 转换为 0.50f。
• 最大值边界：大于 100 的配置限制为 100，100 转换为 1.00f。
• 有效值转换：80 转换为 0.80f。
• 输入校验：空值、非整数、49 和 101 均不能保存；50、70、80 和 100 可以保存。
• 完整执行现有 Debug 单元测试与 Debug APK 构建。

真机验收

• 设置页首次进入显示 70，点击后弹窗输入框回显 70，且输入内容默认全选。
• 输入框下方显示“输入范围是 50~100，推荐 70 以上，80 最优。”。
• 输入 49、101、空值或非整数时不能保存，弹窗保持打开并显示错误提示。
• 修改为 80 后退出并重新进入设置页，仍显示 80；再次打开弹窗时回显 80。
• 修改阈值后不重启应用，下一次识别日志中的阈值立即变化。
• 70 分下原有可识别人脸保持可用；提高阈值后，低于或等于新阈值的检索结果不能通过。
• 人脸注册、活体检测、质量检测和非人脸支付流程不受影响。

交付边界

• 本次只增加消费人脸匹配阈值的动态配置。
• 不调整服务端接口、人员库数据、特征提取模型或人脸注册模块。
• 不改变当前“大于阈值才通过”的业务语义。
• 不执行设备安装、Git 暂存、提交或推送，除非用户后续明确要求。