AI SDK 统一就绪门禁变更记录

变更日期

2026-07-21

背景

目标设备日志显示 DishManagementActivity 调用 learnDateRivise() 时返回 code=1004、message=设备未激活，页面此前只展示通用的“学习数据校正失败”。同时，基础设置激活和多个 AI 业务页面各自维护插件、初始化和激活逻辑，容易出现检查顺序不一致及本地激活缓存与 SDK 真实状态不一致。

统一规则

AI 业务统一按以下顺序放行：

1. 检查银歌 AI 插件是否安装。
2. 初始化 SDK 服务。
3. 处理插件必须升级状态。
4. 调用 queryAiActiveStatus() 查询设备真实激活状态。
5. 仅在状态为 READY 时执行菜品同步、学习、识别和数据校正。

本地 SETTING_AI_DISH_ACTIVATED 仅用于设置页展示，不作为业务放行依据。

代码变更

• 新增 AiReadyState 和 AiReadinessPolicy，统一 SDK 状态映射。
• 扩展 AiSdkManager，提供服务就绪与 AI 业务就绪两层门禁、并发请求合并、初始化超时、升级观察窗口和真实激活状态查询。
• 新增 AiReadinessGuard，统一处理检查进度、插件安装、强制升级、未激活、重试和返回主页。
• AiDishActivationManager 改为激活前先通过服务门禁，激活成功后再查询真实激活状态确认结果。
• SettingActivity 和 SettingsBasicFragment 支持从 AI 业务页进入基础设置并定位 AI 菜品激活项；成功返回 RESULT_OK，取消返回 RESULT_CANCELED。
• DishManagementActivity、NewDishLearningActivity、DishRecognitionActivity 均改为门禁成功后启动 AI 业务，并统一处理运行中 NOT_ACTIVE。
• 菜品学习数据全量校正改用独立暂存目录，SDK 校正成功后再切换正式目录，失败时保留原有学习图片。
• 新增状态映射单元测试和对应用户提示文案。

用户交互

• 设备未激活：提示前往设置完成激活，或返回主页。
• 用户拒绝、点击返回主页或在阻断弹框按返回键：返回 MainActivity。
• 设置页激活成功返回：重新执行完整门禁，不直接相信页面结果。
• 插件未安装或必须升级：显示对应安装或升级入口；系统安装流程取消后仍保留阻断弹框。

验证

• AiReadinessPolicyTest 状态映射测试通过。
• Debug Java 编译通过。
• 全量 Debug 单元测试与 Debug APK 构建通过。
• git diff --check 通过。

由于本次未向目标设备安装 APK，插件未安装、必须升级、未激活、激活成功及运行中再次返回 1004 的五类设备交互仍需现场验收。本次新增日志未记录 AI 激活码。

版本控制说明

本次仅完成实现、验证与记录，未执行暂存、提交、推送或分支切换。