人脸识别统一入口二期实施计划

• 计划日期：2026-09-01

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

• 当前分支：fix_pay_by_face

• 一期基础：FaceRecognitionRuntime + FaceRecognitionSession + FaceRecognitionPop

• 状态：代码实施与自动验证完成，真机待验

1. 二期目标

在一期白屏修复和识别生命周期封装稳定边界上，统一 7 个业务页面打开人脸识别弹框的方式：

• 统一弹框 Tag、参数组装和创建位置。

• 防止快速连续点击重复创建弹框。

• Activity 不可用或 Fragment 状态已保存时安全拒绝展示。

• 统一记录调用场景和展示结果。

• 保持 7 个页面原业务监听器、支付、核验和订单逻辑不变。

• 保持 FaceRecognitionPop 当前 UI、重试、确认、取消和自动关闭交互不变。

2. 实施边界

• Launcher 不持有 Activity、Fragment、View、请求或业务监听器。

• Launcher 不调用支付、核验、订单清空或页面刷新接口。

• Request 只描述场景、金额、副屏预览、确认文案和弹框 Tag。

• 每个页面仍负责自己的成功、结束和取消回调。

• MainActivity 仍负责菜单订单和副屏显示收尾。

• 不修改 Runtime、Session 和 Pop 的一期业务契约。

• 不在本期引入 FaceIdentity 或重写 SDK User。

• 不在本期改造 DialogFragment 参数恢复机制。

3. 目标调用链

7 个业务页面
    │ FaceRecognitionRequest + 原业务监听器
    ▼
FaceRecognitionLauncher
    │ 生命周期门禁 / 统一 Tag / 防重复展示
    ▼
FaceRecognitionPop
    ▼
FaceRecognitionSession
    ▼
FaceRecognitionRuntime

4. 新增组件

4.1 FaceRecognitionRequest

统一参数：

• scene：调用场景。

• orderAmount：当前页面显示金额。

• secondaryPreview：菜单消费可选副屏预览。

• confirmText：国信消费和订单核验的确认按钮文案。

• dialogTag：特殊页面自定义弹框 Tag。

空金额和空场景使用安全默认值，请求不保存 Context 或业务回调。

4.2 FaceRecognitionScene

定义 7 个业务场景：

• MENU_CONSUMPTION

• FREE_CONSUMPTION

• FREE_NO_KEYBOARD_CONSUMPTION

• QUOTA_CONSUMPTION

• QUOTA_NO_KEYBOARD_CONSUMPTION

• GUOXIN_FACE_PAY

• ORDER_VERIFY

场景只用于入口区分和日志，不参与支付业务判断。

4.3 FaceRecognitionLaunchGate

纯 Java 门禁统一判断：

• 宿主不可用：拒绝展示。

• Fragment 状态已保存：拒绝展示。

• 相同 Tag 弹框已存在：不重复创建。

• 宿主正常且没有现有弹框：允许展示。

4.4 FaceRecognitionLauncher

Launcher 负责：

• 获取 FragmentManager。

• 选择默认或页面自定义 Tag。

• 执行门禁判断。

• 统一创建和配置 FaceRecognitionPop。

• 返回结构化 LaunchResult。

• 记录场景和展示结果日志。

LaunchResult：

• SHOWN

• ALREADY_SHOWN

• HOST_UNAVAILABLE

• STATE_SAVED

• INVALID_REQUEST

前两个结果表示已有活动弹框负责后续回调，其他结果表示没有活动弹框。

5. 页面迁移映射

5.1 MainActivity

• 场景：菜单消费。

• 继续传递当前总金额。

• 有副屏时继续传递原副屏预览 View。

• Launcher 拒绝展示且没有活动弹框时隐藏副屏人脸区域。

• 原支付回调和菜单订单处理不变。

5.2 自由和定额消费页面

涉及：

• FreeActivity

• FreeNoKeyboardActivity

• QuotaActivity

• QuotaNoKeyboardActivity

迁移规则：

• 继续传递当前显示金额。

• 原 paymentIndex 设置和业务回调保留。

• Launcher 拒绝展示且没有活动弹框时恢复 paymentIndex，避免再次支付被锁定。

5.3 GuoxinFacePayActivity

• 保留独立弹框 Tag。

• 保留“去消费”确认文案。

• 保留原国信人脸支付接口和参数。

5.4 OrderVerifyActivity

• 使用默认弹框 Tag。

• 保留“去核销”确认文案。

• 保留原订单核验接口和参数。

6. 测试驱动任务

任务 1：展示门禁测试

• 宿主不可用。

• Fragment 状态已保存。

• 重复弹框存在。

• 正常允许展示。

任务 2：展示结果测试

• SHOWN 和 ALREADY_SHOWN 表示活动弹框存在。

• 其余拒绝结果表示没有活动弹框。

任务 3：请求参数测试

• 缺省金额为空字符串。

• 缺省场景为 UNKNOWN。

• 显式业务场景保持不变。

任务 4：静态业务边界检查

• 7 个页面均调用 Launcher。

• 页面内直接 new FaceRecognitionPop() 为 0。

• Launcher 内弹框构造位置为 1。

• 7 个业务监听器继续存在。

• Launcher 不包含支付、核验或订单清空调用。

7. 自动验证结果

执行：

JAVA_HOME=/Users/liang/Library/Java/JavaVirtualMachines/corretto-1.8.0_482/Contents/Home \
sh ./gradlew :app:testDebugUnitTest :app:assembleDebug

结果：

• BUILD SUCCESSFUL。

• Debug 单元测试 49 个。

• 失败 0，错误 0，跳过 0。

• Debug APK 构建成功。

• Launcher 和 Request 新增 8 个单元测试。

• 7 个页面、7 个 Launcher 调用点、7 个场景映射。

• 页面直接构造 0 个，Launcher 统一构造 1 个。

• Launcher 业务接口调用 0 个。

8. 真机待验

• 7 个页面快速连续点击入口，只出现一个弹框。

• 菜单消费单屏和双屏金额、预览、关闭收尾保持原样。

• 自由和定额消费在生命周期拒绝展示后仍可再次支付。

• 国信消费确认文案和支付接口保持原样。

• 订单核验确认文案和核验接口保持原样。

• 成功、重试、超时、取消、模型异常交互保持原样。

• 弹框关闭后立即再次点击能够重新打开。

9. 完成定义

二期代码落地完成条件为：统一入口实现、7 个页面迁移、原业务回调未改、自动测试和 Debug 构建通过、独立变更记录已沉淀。硬件摄像头、双屏和真实支付或核验仍必须通过真机验收后才能判定整体交付完成。