人脸识别相似度阈值设置设计
版本：V1.0
日期：2026-09-01
Use Case ID：UC-FACE-THRESHOLD-001
状态：Ready
DoR：READY
执行模式：常规 Codex（单仓库、边界明确、可通过定向单元测试和构建验证）
1. 背景、目标与范围
设备当前主流程的人脸识别相似度阈值为 0.70，但设置页无法调整。目标是在“基础设置”的人脸设置区域增加“人脸识别相似度阈值”设置项，让设备管理员可以输入 50～100 的整数并立即用于后续人脸搜索。
In Scope
- 设置项默认显示当前有效值；从未设置时显示并使用
70。
- 设置项只显示数字，例如
70，不追加“分”。
- 点击设置项弹出数字输入框，提示允许范围
50～100、推荐值 80。
- 输入校验通过后持久化并立即刷新设置项。
- 人脸搜索时读取最新配置并转换为 SDK 分值，例如
70 → 0.70。
Out of Scope
- 不修改 RGB 活体阈值
0.60。
- 不修改摄像头、检测超时、镜像、激活或其他设置。
- 不增加后台接口、账号权限或云端同步。
- 不修改人脸特征库、搜索算法和识别结果页面。
2. 参与者、触发与后置条件
| 项目 | 说明 |
|---|
| 主要参与者 | 能进入设备基础设置页的设备管理员 |
| 触发 | 点击“人脸识别相似度阈值”设置项 |
| 前置条件 | 应用已进入基础设置页，MMKV 可正常读写 |
| 成功后置 | 新值持久化，页面立即显示该值，后续人脸搜索按新阈值判断 |
| 失败后置 | 弹框保留，显示校验错误，原阈值和页面显示均不改变 |
3. 页面与交互设计
- 在人脸设置区域复用现有
CustomSettingItemView 增加设置项，标题为“人脸识别相似度阈值”。
- 右侧显示当前有效整数；未保存配置时显示
70，不显示 70分。
- 点击后复用
ValidatedSettingInputPop，预填当前值并提示“请输入 50～100 的整数，推荐 80”。
- 空值、非整数或越界时显示错误并保持弹框打开；合法值保存、关闭弹框并立即刷新。
- 取消或关闭弹框不修改配置。
4. 主流程、分支与异常
| 编号 | 行为 | 页面/数据变化 | 对应验收 |
|---|
| M1 | 进入基础设置页 | 读取保存值；不存在时取 70 | AC-001 |
| M2 | 点击阈值设置项 | 弹框打开并预填当前值 | AC-002 |
| M3 | 输入合法整数并确认 | 保存、关闭弹框、刷新显示 | AC-003 |
| M4 | 发起后续人脸搜索 | 最新整数除以 100 后参与比较 | AC-004 |
| A1@M3 | 取消 | 不保存，保留原值 | AC-005 |
| E1@M3 | 输入为空、非整数或越界 | 提示错误，弹框不关闭，原值不变 | AC-006 |
| R1@E1 | 改为合法值再次确认 | 回到 M3 | AC-003 |
5. 业务规则与工程契约
BR-001：范围为闭区间 [50, 100]，只接受十进制整数。BR-002：没有持久化配置时默认值必须为 70，显示和识别使用同一事实源。BR-003：80 只是推荐值，不是默认值，也不能自动写入。BR-004：设置项只显示整数，不追加“分”或其他单位。BR-005：SDK 阈值按 整数值 / 100.0f 转换。BR-006：每次搜索前读取当前值，保存后无需重启。BR-007：历史或异常越界持久化值读取时限制到合法范围。- 配置类集中维护 MMKV 键、最小值、最大值、默认值和换算比例，避免散落硬编码。
- 性能：只增加本地读取和常数换算；安全：输入在持久化前完成校验。
6. 数据流与实现边界
基础设置页
→ 数字校验弹框
→ FaceRecognitionThresholdConfig / MMKV
→ 设置项刷新
→ FaceSDKManager 每次搜索读取配置
→ 整数除以 100 转为 SDK 阈值
→ 与搜索得分比较
FaceRecognitionThresholdConfig：维护默认值、范围、持久化、校验和 SDK 换算。SetBasicFragment：展示、弹框、错误反馈和保存后刷新。FaceSDKManager：消费最新 SDK 阈值，不负责 UI 或持久化。- 布局与字符串资源：承载设置项和可见文案，不散落业务阈值。
7. 验收标准
| AC | Given | When | Then | 证据 |
|---|
| AC-001 | 从未保存配置 | 打开基础设置 | 显示 70，识别使用 0.70f | 单元测试、代码检查 |
| AC-002 | 当前值为 70 | 点击设置项 | 弹框预填 70，显示范围与推荐值 | 人工 UI 检查 |
| AC-003 | 弹框已打开 | 输入 80 并确认 | 保存、立即显示 80、弹框关闭 | 单元测试、人工 UI 检查 |
| AC-004 | 已保存 80 | 发起下一次人脸搜索 | 使用 0.80f，无需重启 | 单元测试、代码检查 |
| AC-005 | 当前值为 70 | 输入其他值后取消 | 页面和存储仍为 70 | 人工 UI 检查 |
| AC-006 | 当前值为 70 | 输入空值、49、101、小数或非数字 | 提示错误、弹框不关闭、原值不变 | 单元测试、人工 UI 检查 |
| AC-007 | 任意合法值 | 查看设置项 | 只显示数字，不出现“分” | 资源检查、人工 UI 检查 |
| AC-008 | RGB 活体阈值为 0.60 | 完成功能 | 活体判定配置和逻辑未改变 | 差异检查 |
8. 测试矩阵
| Test ID | 层级 | 覆盖对象 | 预期 |
|---|
| UT-001 | 单元测试 | 默认值 | 返回 70，SDK 值为 0.70f |
| UT-002 | 单元测试 | 合法边界 | 50、70、80、100 合法 |
| UT-003 | 单元测试 | 非法边界 | 49、101 被拒绝 |
| UT-004 | 单元测试 | SDK 换算 | 50 → 0.50f、80 → 0.80f、100 → 1.00f |
| UT-005 | 单元测试 | 异常存储值 | 读取值被限制到合法范围 |
| BUILD-001 | 构建 | Android 工程 | 受影响模块编译通过 |
| MANUAL-001 | 人工 UI | 展示、弹框、取消、错误、保存 | 与 AC-001～AC-007 一致 |
| DIFF-001 | 差异检查 | 活体阈值和无关逻辑 | 未改动 RGB 活体阈值和无关设置 |
9. 风险、兼容与回滚
- 阈值越高越严格，可能增加拒识；弹框标注推荐值，最终由管理员决定。
100 可能很难通过，但属于已确认范围，不额外缩小。- 回滚代码时删除新增入口和动态读取即可恢复固定阈值；遗留 MMKV 键不影响旧版本。
- 当前源码仓存在用户未提交修改；实施时只改必需文件并逐项检查差异。
10. 待确认项与追踪
- P0 待确认项：无。用户已确认默认值为
70，设置成功后才改变。
- 云效关联：当前未提供云效工作项和外部写入授权；本地 Use Case 作为本次实现事实源，不声称已同步云效。
- 追踪：
UC-FACE-THRESHOLD-001 → 基础设置项/弹框 → MMKV 配置 → FaceSDKManager → BR-001～BR-007 → AC-001～AC-008 → UT/BUILD/MANUAL/DIFF。