绑盘与消费独立运行模式设计

文档信息

1. 背景与结论

当前 StartActivity 实际承担绑盘模式加载：申请相机等权限、检查基础配置、激活人脸 SDK、加载模型、初始化人脸库并同步绑盘人员数据。消费功能则在 ConsumptionActivity 内初始化扫码、订单、一卡通读卡和消费补传等能力。

只增加“是否进入消费页面”开关会把页面导航和设备运行模式混在一起，可能直接跳过某一模式的前置加载。最终方案是引入设备级持久运行模式，并为绑盘、消费建立相互独立的加载链路。

设备配置完成后运行模式相对固定。应用启动、开机自启和崩溃重启均自动进入已配置模式，不再展示功能选择页。绑盘页和消费页均隐藏返回按钮，系统返回键和返回手势也不执行返回。

2. 目标与范围

2.1 目标

• 管理员可在基础设置中选择“绑盘模式”或“消费模式”。
• 新安装和历史升级设备默认保持绑盘模式，避免升级后改变现场行为。
• 两种模式分别执行各自所需的配置校验和初始化，不互相阻塞。
• 设置页返回、正常启动、开机自启和崩溃重启使用同一模式路由规则。
• 业务运行页不能通过标题栏或系统返回操作离开当前模式。

2.2 In Scope

• 设备运行模式枚举、持久化读取和异常值兜底。
• 基础设置中的运行模式选择项。
• 统一启动分发入口。
• 绑盘加载链路和消费加载链路。
• 设置页按运行模式校验并返回对应加载页。
• 绑盘页、消费页返回入口隐藏和系统返回拦截。
• 开机自启、崩溃重启的模式路由兼容。
• 路由、校验和返回行为的自动化测试。

2.3 Out of Scope

• 不修改绑盘、消费的业务协议和服务端 API。
• 不删除 FunctionSelectActivity 及其资源；本期只从正常运行链路移除。
• 不改变管理员密码和长按标题栏进入设置页的方式。
• 不实现远程切换运行模式、定时切换或普通操作员切换。
• 不在消费加载页提前打开 USB 读卡器。

3. 参与者与边界

4. 核心数据与业务规则

4.1 数据对象

新增 DeviceRunMode 枚举：BINDING 为默认绑盘模式，CONSUMPTION 为消费模式。运行模式通过独立 MMKV 键持久化，由枚举集中解析，禁止在页面中散落数字或字符串判断。

4.2 业务规则

• BR-001：未保存运行模式或读取到未知值时，必须回退为 BINDING。
• BR-002：运行模式只能由通过管理员密码进入设置页的管理员修改。
• BR-003：应用的所有冷启动入口必须先经过模式分发器。
• BR-004：绑盘模式只执行绑盘配置校验和初始化；消费模式只执行消费配置校验和初始化。
• BR-005：设置页校验通过后必须进入当前配置模式的加载页，禁止直接跳过加载进入业务页。
• BR-006：绑盘页和消费页均不显示返回按钮；系统返回键、返回手势和 onBackPressed() 均不导航。
• BR-007：模式切换保存后，在设置页点击返回立即生效，后续重启继续使用该模式。
• BR-008：消费读卡器仍由 ConsumptionActivity 管理，消费加载页不得抢占 USB 设备。
• BR-009：FunctionSelectActivity 保留兼容但不得出现在正常业务链路中。

5. 架构设计

5.1 启动路由

应用启动 / 开机自启 / 崩溃重启
              |
              v
     ModeDispatchActivity
        |             |
        | BINDING     | CONSUMPTION
        v             v
  StartActivity   ConsumptionStartActivity
        |             |
        v             v
   HomeActivity   ConsumptionActivity

ModeDispatchActivity 是无业务界面的轻量分发入口。Manifest Launcher、开机广播和崩溃恢复 PendingIntent 最终都进入该入口。

5.2 组件职责

5.3 初始化状态

绑盘和消费分别维护初始化状态。模式分发不根据旧的统一完成标记跳过加载页；加载页只可依据本模式状态决定完整加载、增量检查或快速通过。

6. 分模式加载与校验

6.1 绑盘模式

1. 检查设备型号和绑盘所需权限。
2. 检查公共 API、配对码、终端编号。
3. 检查至少选择一种绑定方式。
4. 启用人脸时检查激活码并初始化模型、人脸库。
5. 准备绑盘人员数据。
6. 进入 HomeActivity。

6.2 消费模式

1. 检查公共 API、配对码、终端编号。
2. 启动只处理本地已有消费结果的非阻塞补传调度。
3. 立即进入 ConsumptionActivity，由业务页按实际需要连接一卡通并打开餐盘读取和 USB 读卡。

消费模式不校验绑定方式、人脸激活、一卡通地址或 AppID，不加载人脸模型，也不执行人员同步。一卡通连接失败不得阻止进入消费页。

6.3 消费公共配置失败

• 公共 API、配对码或终端编号不完整时停留在消费入口并提供进入设置。
• 一卡通连接和人员同步失败不属于消费启动异常，不得阻止进入消费页。

7. 设置页设计

基础设置新增“设备运行模式”，点击后复用现有单选弹窗。设置页的页面按钮、物理返回键和系统返回手势统一调用同一返回方法：读取模式、执行模式专属校验、失败则停留并提示、成功则进入对应加载页并结束设置页。

现有按来源 Activity 和统一初始化标记决定返回目标的逻辑退出正常链路。

8. 页面返回与管理员入口

• HomeActivity 和 ConsumptionActivity 的标题栏都不显示返回布局。
• 两个 Activity 均拦截系统返回且不调用父类返回逻辑。
• 消费交易中和非交易中采用相同的“不返回”结果。
• 两个业务页继续允许长按标题栏 Logo，通过管理员密码进入设置页。
• 设置页返回后重新经过所选模式的加载链路。

9. AI 可执行 Use Case

9.1 触发、前置与后置

• 触发：Android 冷启动，或管理员在设置页修改/确认模式后点击返回。
• 前置：MMKV 可读取；修改模式时已通过管理员密码。
• 成功后置：进入所选模式业务页，未加载另一模式专属资源，业务页无返回入口。
• 失败后置：保持在加载页或设置页，允许重试或修正配置。

9.2 主流程

9.3 分支流程

9.4 异常与恢复流程

10. 验收标准

11. 测试矩阵

12. 非功能、安全与兼容

• 性能：不新增服务端 API 或并发模型；模式分发只做本地读取和路由，不得网络阻塞。
• 稳定性：不得产生重复 Activity、同步任务或硬件占用。
• 安全：模式修改继续受管理员密码保护，不记录密码。
• 数据兼容：历史设备默认绑盘，不删除现有数据。
• 版本回滚：旧版本忽略新增模式键，继续原绑盘链路。
• 权限：消费模式不申请相机权限；USB 权限仍由消费页处理。

13. 风险与控制

14. 待确认项与设计结论

• P0 待确认项：无。
• 云效需求写入：本次未获得明确的云效项目、工作项和写入授权，仅生成本地 AI 可执行 Use Case；不得声称已同步云效。
• 设计结论：采用“持久运行模式 + 统一分发入口 + 双加载页 + 分模式校验 + 业务页禁止返回”的方案。
• 实施前门禁：用户确认本文档后，再生成分步实施计划并进入测试驱动开发。