SellWeight 启动页问题修复汇总

文档信息

一、背景与最终结论

上述代码问题已分三批完成修复。最终启动流程能够区分首次初始化和已初始化设备，网络失败时不再以模态弹框锁死页面；人员、人脸及客屏任务具备明确的成功、失败、降级和释放路径。

当前没有已知的启动页代码遗留。由于本地环境不具备米果三合一终端和百度人脸授权硬件，离线授权、摄像头识别、主屏触摸和客屏显示仍需真机验收。

二、问题、修复方案与批次总表

2.1 启动交互与状态控制

编号	发现的问题	影响	修复方案	批次	状态
S-01	无网请求失败后显示模态弹框	弹框拦截触摸，启动页无法继续操作	改为启动页内恢复操作区，提供“重新同步”和“前往设置”	第一批	已修复
S-02	首次初始化与已初始化设备使用同一无网处理	已有本地数据的设备无法正常离线启动	引入 StartupNetworkPolicy，区分远程同步、离线继续和等待首次同步	第一批	已修复
S-03	配置不完整跳转设置后仍继续执行同步	产生无效请求、重复页面和状态竞争	跳转设置后立即返回，并统一配置完整性检查	第一批	已修复
S-04	启动请求和页面跳转缺少防重复状态	连续回调或点击可能产生并发请求、重复跳转	增加同步中和已跳转状态保护	第一批	已修复
S-05	网络恢复后缺少页面内反馈	用户不知道可以继续初始化	监听网络状态，在恢复区提示网络已恢复并允许主动重试	第一批	已修复
S-06	人脸初始化失败沿用人员同步失败降级	可能重新进入离线流程并形成失败循环	人脸失败使用独立恢复入口	第三批	已修复
S-07	已初始化设备离线点击重试仍被“必须联网”拦截	本地人脸初始化失败后无法离线重试	引入 StartupRetryPolicy，离线重试本地运行时	第三批	已修复

2.2 人员同步与数据一致性

编号	发现的问题	影响	修复方案	批次	状态
D-01	批量同步在工作线程直接回调页面	存在线程安全和 UI 异常风险	数据库任务保留在单线程，页面回调统一切换主线程	第一批	已修复
D-02	部分人员保存失败仍返回整体成功	可能写入错误初始化标记	使用 BatchSyncResult 统计结果，任一失败即走失败分支	第一批	已修复
D-03	批量同步无法取消	页面退出后仍可能继续保存和回调	增加取消、中断检查和回调有效性保护	第一批	已修复
D-04	更新人员时使用可能变化的数值 ID	本地可能残留重复人员	使用稳定业务 UUID 定位和替换记录	第一批	已修复
D-05	接口返回体和错误信息缺少空值保护	异常响应可能空指针	对响应、数据体、错误对象和文案增加兜底	第一批	已修复

2.3 人脸数据与离线初始化

编号	发现的问题	影响	修复方案	批次	状态
F-01	人员同步后又调用旧接口全量下载人脸数据	重复请求、重复写库、启动变慢	复用人员同步保存的特征，只加载本地库与索引	第二批	已修复
F-02	已初始化设备离线启动时直接进入首页	人脸运行时可能未加载	离线复用本地授权并加载本地模型与人脸库	第三批	已修复
F-03	initPush() 可能早于识别模型完成	FaceSearch 为空时后台空指针	按识别模型、注册模型、数据库、索引顺序初始化并增加空值保护	第三批	已修复
F-04	人脸更新回调线程不统一	页面可能在后台线程更新 UI	回调统一投递主线程并支持解除	第一批	已修复
F-05	人脸失败自动重启或退出	用户无法恢复，可能形成循环	改为可恢复状态，保留重试和设置入口	第一批	已修复
F-06	在线与离线人脸初始化边界不明确	离线设备可能错误发起在线激活	在线执行激活，离线复用已有授权文件	第三批	已修复

2.4 生命周期与异步任务

编号	发现的问题	影响	修复方案	批次	状态
L-01	人员同步网络请求没有取消句柄	页面销毁后可能收到迟到回调	透传 Disposable，启动页统一释放	第二批	已修复
L-02	人脸在线激活无法阻止旧页面回调	可能推进已销毁启动页	返回可取消句柄并使用 Application Context	第三批	已修复
L-03	模型管理器持有页面 Context 且无法释放	页面销毁后仍可能收到结果	使用 Application Context，增加 release()	第三批	已修复
L-04	人脸数据库线程无法只取消任务	可能泄漏线程或误清空全局数据	管理独立执行器，增加不清空数据的 cancel()	第三批	已修复
L-05	启动资源未完全统一释放	旧页面仍可能跳转或持有资源	统一清理网络、批处理、激活、模型、数据库、延迟任务和客屏	第一至三批	已修复

2.5 客屏、权限与通用弹框

编号	发现的问题	影响	修复方案	批次	状态
U-01	客屏使用 TYPE_APPLICATION_OVERLAY	依赖悬浮窗权限并可能影响触摸	改为标准 Presentation，删除悬浮窗权限	第二批	已修复
U-02	首页恢复时可能重复创建客屏	多个实例和窗口泄漏	创建前检查状态，页面销毁主动释放	第二批	已修复
U-03	设备类型使用数字魔法值	硬件分支难维护	统一使用 DeviceTypeUtils 具名常量	第一、二批	已修复
U-04	NewSingleTipPop 缺少无参构造	系统恢复 Fragment 失败	增加无参构造，文案写入 arguments	第二批	已修复
U-05	未知设备弹框恢复后监听丢失	确认按钮不执行退出	保存请求标识，由重建后的 Activity 处理动作	第三批	已修复
U-06	Manifest 存在重复权限	配置噪声和构建警告	删除重复权限及不再需要的悬浮窗权限	第二批	已修复

三、分批修复过程

3.1 第一批：无网交互、同步正确性和基础生命周期

第一批优先解决直接阻断用户操作的故障，并修复人员同步链路中的数据正确性问题。

• 页面内恢复操作区替换无网失败模态弹框。
• 建立首次初始化、已初始化、有网、无网四类决策。
• 修复配置分支穿透、重复请求和重复跳转。
• 批量同步回调切回主线程，部分失败不再误报成功。
• 支持批处理取消，增加空值与生命周期保护。
• 按人员 UUID 更新本地记录。
• 人脸失败不再自动杀进程重启。

批次记录：2026-09-01-启动页无网与同步流程修复.md/html。

3.2 第二批：重复人脸请求、网络取消和客屏权限

• 移除旧人脸接口的第二次全量下载。
• 人员同步请求返回并释放 Disposable。
• 客屏切换为标准 Presentation。
• 防止重复创建客屏并在销毁时释放。
• 设备类型改用具名常量。
• 提示弹框增加无参构造和可恢复 arguments。

批次记录：2026-09-01-启动页生命周期与客屏第二批修复.md/html。

3.3 第三批：离线人脸闭环和 SDK 生命周期

• 已初始化设备离线启动时加载本地人脸运行时。
• 在线、离线采用不同的人脸初始化策略。
• 调整模型、注册模型、数据库和索引顺序。
• 人脸失败使用独立恢复状态，避免失败循环。
• 激活、模型、数据库任务使用 Application Context 并支持释放。
• 未知设备弹框使用稳定请求标识恢复业务动作。

批次记录：2026-09-01-启动页离线人脸与生命周期第三批修复.md/html。

四、修复后的启动状态矩阵

本地初始化	网络	人脸支付	启动行为	最终结果
未完成	无网	任意	停留启动页，展示重新同步与设置入口	页面可触摸，不进入不完整业务
未完成	有网	关闭	全量同步人员数据	成功后进入首页
未完成	有网	开启	全量同步、在线激活并加载本地人脸	全部成功后进入首页
已完成	无网	关闭	跳过远程同步，使用本地业务数据	进入首页
已完成	无网	开启	跳过远程同步和在线激活，加载本地运行时	成功进入首页；失败停留恢复区
已完成	有网	关闭	增量同步人员数据	成功进入首页；失败使用本地数据
已完成	有网	开启	增量同步并初始化人脸运行时	成功进入首页；人脸失败停留恢复区

五、关键实现文件

• LaunchActivity.java 与三个 startup/*Policy.java
• BatchCustomerSyncManager.java、BatchSyncResult.java
• CallBackObserver.java、RetrofitClient.java
• ActivationFaceSDK.java、InitFaceModelManager.java、InitFaceDBApiManager.java、FaceSDKManager.java
• NewSingleTipPop.java、activity_launch.xml

六、测试与验证证据

6.1 TDD 过程

• 第一批策略类和批量结果类先测试红灯，随后转绿。
• 第二批人脸初始化策略测试先红后绿。
• 第三批双参数人脸策略和重试策略先编译失败，实现后转绿。

6.2 最终自动化验证

JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew \
  :app:testDebugUnitTest :app:assembleDebug \
  --rerun-tasks --console=plain

• BUILD SUCCESSFUL
• 92 个 Gradle 任务执行完成
• 20 个单元测试，失败 0、错误 0、跳过 0
• git diff --check 通过
• Debug APK：app/build/outputs/apk/debug/app-debug.apk

6.3 已覆盖的策略场景

• 首次初始化与已初始化设备的有网、无网决策。
• 人脸开启、关闭以及在线、离线初始化。
• 在线重试、离线本地重试和首次初始化等待网络。
• 批量人员同步全部成功、部分失败和空结果统计。

七、真机验收清单

• ☐ 首次安装且无网：启动页可触摸，重新同步和设置按钮可用。
• ☐ 已初始化且无网、人脸关闭：能够直接进入首页。
• ☐ 已初始化且无网、人脸开启：本地授权、模型和人脸库加载成功。
• ☐ 同步过程中断网：不弹出阻断触摸的模态弹框。
• ☐ 网络恢复后重新同步：只产生一次请求和一次跳转。
• ☐ 人脸初始化失败：停留恢复区，不自动重启、不形成循环。
• ☐ 启动过程中进入设置或退出：迟到回调不再跳转旧页面。
• ☐ 米果客屏正常显示，主屏触摸和系统栏层级正常。
• ☐ 首页反复前后台切换：不重复创建客屏。

八、已知边界与非阻断项

• 旧版人脸依赖仍输出 D8 stack-map 警告，但 Debug 构建成功，该警告不是本次引入。
• 其他业务页面仍可能使用运行期弹框监听，属于全应用治理，不影响启动页恢复链路。
• 未经真机验证前，不将离线授权、摄像头识别和双屏显示标记为硬件验收通过。

九、本次修复形成的可复用能力

这里的“能力”只统计已经落到 SellWeight 代码、测试或明确接入约束中的内容。仅有经验描述、尚未解耦的代码，不标记为“可直接复用组件”。

9.1 能力清单与成熟度

能力编号	能力名称	SellWeight 代码证据	后续项目可以直接使用的内容	当前复用级别	使用边界
C-01	启动网络决策能力	StartupNetworkPolicy、对应测试	由网络和首次同步状态得到远程同步、离线继续、等待首次同步	可直接迁移	新项目必须定义自己的首次同步完成标记
C-02	启动失败恢复决策能力	StartupRetryPolicy、对应测试	区分在线重同步、离线重载本地运行时、等待网络	可直接迁移	首次安装不能绕过联网初始化
C-03	人脸在线/离线初始化决策能力	StartupFaceInitializationPolicy、对应测试	决定跳过人脸、加载本地运行时或在线激活后加载	可直接迁移	适用于沿用百度人脸授权与本地模型的项目
C-04	批量同步完整性判定能力	BatchSyncResult、BatchCustomerSyncManager、对应测试	只有失败数为 0 且成功数等于总数才允许启动成功	可直接迁移核心模型	跨项目需替换人员保存和人脸同步适配器
C-05	可操作的非模态启动恢复能力	activity_launch.xml、showRecoveryActions()、retryStartupSync()	失败后保留状态、重新同步和设置入口，页面始终可触摸	项目内已复用，跨项目需适配 UI	首次初始化失败不能静默进入首页
C-06	人员与人脸特征单链路落库能力	CustomerSyncManager、BatchCustomerSyncManager	以 customerUuid 同步业务库和人脸库，取消重复全量下载	同数据模型项目可复用	接口必须已经返回人脸特征等字段
C-07	百度人脸运行时有序初始化能力	initializeFaceRuntime()、initModel()、initRegisterModel()、initDBApi()	固定识别模型、注册模型、本地库、内存索引的初始化顺序	同 SDK 项目可复用	更换 SDK 时只能复用顺序约束
C-08	启动异步任务生命周期托管能力	CompositeDisposable、各管理器的 cancel()/release()、isActivityUsable()	统一停止网络、批处理、激活、模型、数据库、延迟跳转和客屏回调	项目内组合能力	尚未抽成统一任务注册器，新增任务必须人工登记
C-09	双屏终端无悬浮窗客屏能力	TYPE_MIGUO_ALL_IN_ONE、DefaultPresentation、客屏创建与释放逻辑	使用标准 Presentation 绑定第二块 Display，无悬浮窗权限	同类双屏设备可复用	硬件识别需逐机型适配并真机验收

9.2 后续项目的直接接入顺序

1. 先复制三个纯策略类及四个单元测试：StartupNetworkPolicy、StartupRetryPolicy、StartupFaceInitializationPolicy、BatchSyncResult。
2. 定义首次初始化完成标记。只有人员落库成功且启用的人脸运行时初始化成功后才写入；SellWeight 对应 Constants.FIRST_INIT_FINISH_TAG。
3. 接入页面内恢复区，分别处理首次初始化必须联网、已初始化可离线和人脸运行时失败，禁止重新引入网络失败模态弹框。
4. 批量同步保留结果统计、单线程、主线程回调和取消语义，替换新项目的数据适配实现。
5. 百度人脸项目按当前初始化顺序接入；接口已经携带特征时，不再调用旧人脸全量下载接口。
6. 为每个异步动作登记取消或释放方法，页面销毁时集中调用，回调前统一检查 Activity 是否可用。
7. 双屏页面只使用标准 Presentation 和真实第二块 Display，设备类型使用具名常量，销毁时必须 dismiss()。
8. 复用第四节状态矩阵和第七节真机清单验收，不能只验证有网启动。

9.3 暂时不能宣称为通用组件的部分

• 纯策略类和 BatchSyncResult 尚未发布为公共 Android Library，当前仍是带测试复制或后续抽取公共模块。
• BatchCustomerSyncManager 依赖 SellWeight 的人员、数据库、人脸库和资源类，不是通用批处理框架。
• 人脸初始化依赖百度 SDK 静态状态、FaceApi 和项目内两套模型管理器，只适合同技术栈项目。
• 异步释放尚无统一任务注册接口，新增任务仍需人工加入 onDestroy()。
• 米果真机触摸、离线授权、摄像头和客屏显示尚未完成硬件验收，不能标记为跨设备验证完成。

9.4 项目级沉淀结论

本次最有价值的沉淀不是“无网时不弹框”这一条修复，而是形成了 SellWeight 的启动容错基线：纯策略决定动作、初始化标记控制离线边界、页面内恢复替代网络模态阻塞、同步结果必须完整、百度人脸在线与离线分流、所有异步资源随页面释放、双屏使用标准 Presentation。

C-01 至 C-04 已有独立类和单元测试，可作为后续同类项目的首批迁移资产；C-05 至 C-09 已在 SellWeight 形成代码闭环，但跨项目使用必须按表中依赖和硬件边界适配。

十、最终验收结论

启动页相关代码问题已完成三批修复，自动化测试与 Debug 打包通过。原始故障“无网失败弹框导致整个页面无法触摸”已经从交互机制上移除，并补齐了人员同步、人脸离线初始化、异步生命周期和客屏窗口的关联风险。

本次及三个修复批次均未执行 Git 暂存、提交或推送。