AI SDK 统一就绪门禁设计

1. 目标

为菜品管理、菜品学习、菜品识别等依赖银歌 AI SDK 的业务建立统一的前置检查，确保只有在“插件可用、SDK 初始化成功、设备真实已激活”后才进入具体业务。

本设计解决以下问题：

• 页面在 SDK 异步初始化完成前直接调用 AI 接口。
• 插件未安装、插件必须升级、设备未激活等状态由不同页面重复处理。
• 本地 SETTING_AI_DISH_ACTIVATED 与 SDK 真实状态不一致时仍可能放行业务。
• DishManagementActivity 将 SDK 的具体失败统一显示为“学习数据校正失败”。
• 校正前先清理本地学习图片，后续 SDK 失败时可能造成文件和特征库不一致。

2. 已确认的产品规则

1. 检查顺序固定为：插件可用性、SDK 初始化、插件强制升级状态、SDK 真实激活状态、具体业务。
2. DishManagementActivity 在门禁通过前不请求菜品及学习数据，不执行校正。
3. 设备未激活时弹出不可通过点击外部区域关闭的提示框。
4. 用户选择“前往设置”时，进入基础设置并定位 AI 菜品识别激活项。
5. 用户拒绝处理或选择“返回主页”时，明确返回 MainActivity。
6. 从设置页返回后必须重新查询 SDK 真实激活状态，不能仅相信页面返回值或本地缓存。
7. 不在业务页面自动使用保存的激活码激活；激活由用户在设置页主动完成。

3. 方案选择

采用在 AiSdkManager 中建设统一“AI 就绪门禁”的方案。

不采用以下方案：

• 仅在 DishManagementActivity 增加判断：会继续保留学习页和识别页的重复逻辑。
• 在应用启动页全局阻断：会影响设置、订单查询等不依赖 AI 的功能。

4. 就绪条件与状态模型

AI 业务真正可用必须同时满足：

插件已安装
+ 插件版本不要求强制升级
+ SDK 服务初始化成功
+ queryAiActiveStatus() 返回已激活
= READY

统一状态定义：

enum AiReadyState {
    IDLE,
    INITIALIZING,
    CHECKING_ACTIVE,
    READY,
    NOT_ACTIVE,
    PLUGIN_NOT_INSTALLED,
    UPGRADE_REQUIRED,
    INIT_TIMEOUT,
    SERVICE_ERROR
}

SETTING_AI_DISH_ACTIVATED 只作为设置页展示缓存，不能作为业务放行依据。业务放行以本次 SDK 会话中的 queryAiActiveStatus() 结果为准。

5. 总体流程

进入 AI 业务页面
  -> 请求统一门禁 ensureAiReady()
  -> 初始化 SDK 服务
  -> SDK 回调插件未安装：提示安装，拒绝则返回主页
  -> SDK 回调必须升级：提示升级，拒绝则返回主页
  -> SDK 初始化成功：调用 queryAiActiveStatus()
  -> 已激活：状态置为 READY，继续业务
  -> 未激活：提示前往设置，拒绝则返回主页
  -> 设置页激活成功返回：使旧状态失效并重新执行完整门禁

不能在插件未安装时先查询激活状态，因为激活状态由插件服务提供；插件服务不可用时，查询结果不可信。

6. AiSdkManager 设计

6.1 对外接口

public interface ReadyCallback {
    void onReady(@NonNull YingeoAiSDK sdk);

    void onBlocked(
            @NonNull AiReadyState state,
            @NonNull String message
    );
}

public void ensureAiReady(
        @NonNull Activity activity,
        @NonNull ReadyCallback callback
);

public void invalidateReadyState();

public void markNotActive(@Nullable String message);

public AiReadyState getReadyState();

页面只消费统一结果，不再自行组合初始化、插件、升级和激活判断。

6.2 单次并发机制

同一时间只允许一次初始化或激活状态查询：

• 首个调用启动检查。
• 后续调用加入等待回调列表。
• 检查成功或失败后统一通知全部等待者。
• 页面销毁后移除对应回调，禁止向已销毁页面弹框。

6.3 初始化处理

1. 调用 initAiService()。
2. 收到 onInitSuccess() 后再查询激活状态。
3. 收到 SDK_PLUGIN_NOT_INSTALL，进入 PLUGIN_NOT_INSTALLED。
4. 收到 PLUGIN_MUST_UPGRADE，进入 UPGRADE_REQUIRED。
5. 初始化超过 10 秒且没有进入插件安装交互时，进入 INIT_TIMEOUT。
6. 用户正在安装或升级插件时暂停普通初始化超时；安装完成后重新开始初始化计时。

6.4 激活状态查询

SDK 初始化成功后，在后台线程调用 queryAiActiveStatus()：

• 返回 SUCCESS：状态置为 READY。
• 返回 NOT_ACTIVE：状态置为 NOT_ACTIVE，同步写入本地 ACTIVATED=false。
• 返回空值或未知错误：状态置为 SERVICE_ERROR，保留 SDK 原始错误信息。

所有页面回调切回主线程。

6.5 状态失效

以下情况必须清除 READY：

• 应用进程重新启动。
• 插件安装或升级完成。
• SDK 服务断开或重新初始化。
• 激活码发生变化。
• 设置页激活失败。
• 任意 AI 业务接口返回 NOT_ACTIVE。
• 显式调用 unInitAiService()。

7. DishManagementActivity 流程

7.1 页面启动

当前的启动顺序需要由：

初始化 SDK -> 注册监听 -> 立即 syncDishList()

调整为：

初始化页面 -> 注册监听 -> ensureAiReady()
                         -> READY 后 syncDishList()

门禁检查期间：

• 显示“正在检查 AI 服务状态”。
• 禁用同步、数据校正、删除学习图片和进入学习页等业务入口。
• 不请求菜品列表、菜单列表或学习图片列表。
• 不清理本地学习图片。

7.2 门禁成功

onReady() 后：

1. 关闭就绪检查提示。
2. 启用业务按钮。
3. 执行现有菜品及学习数据同步。
4. 下载和保存完成后执行 learnDateRivise()。

7.3 运行中状态失效

即使门禁曾通过，learnDateRivise() 仍需处理 NOT_ACTIVE：

1. 调用 markNotActive()。
2. 停止后续处理，不自动重试。
3. 显示未激活弹框。
4. 用户完成设置后重新从完整同步流程开始。

8. 未激活弹框与导航

提示文案：

AI 菜品识别设备尚未激活，暂时无法进行菜品学习和数据校正。
请前往设置页填写激活码并完成激活。

按钮：

• 前往设置
• 返回主页

行为：

• 禁止点击弹框外部关闭。
• 返回键等同于“返回主页”，不能留在不可用页面。
• “前往设置”携带目标页签与目标设置项参数进入 SettingActivity。
• “返回主页”使用 CLEAR_TOP | SINGLE_TOP 打开 MainActivity，随后结束当前页面。

9. 设置页集成

SettingActivity 使用专用流程参数进入激活处理：

EXTRA_AI_DISH_ACTIVATION_FLOW = true;

该流程固定展示基础设置，并向 SettingsBasicFragment 传递定位参数。基础设置页收到参数后：

• 自动切换到基础设置。
• 定位或高亮 AI 菜品识别激活项。
• 用户输入激活码后执行现有激活流程。
• 激活前仍先完成插件初始化与强制升级检查。
• 激活成功后调用 queryAiActiveStatus() 二次确认。
• 二次确认成功才返回 RESULT_OK。

如果用户取消、激活失败或直接退出设置页，返回 RESULT_CANCELED。

10. 从设置页返回

业务页面使用 Activity Result 接收结果：

• RESULT_OK：调用 invalidateReadyState()，重新执行 ensureAiReady()。
• RESULT_CANCELED：返回主页。
• 即使收到 RESULT_OK，也不得直接执行菜品业务。
• 重新查询仍为未激活时，再次弹框；用户拒绝则返回主页。

不单独依赖普通 onResume()，避免弹框、权限页或屏幕切换造成重复检查。

11. 插件未安装与强制升级

11.1 插件未安装

提示用户安装银歌 AI 插件：

• 安装插件：打开项目统一的插件更新弹框。
• 返回主页：返回 MainActivity。

插件安装成功后重新执行“初始化 -> 版本检查 -> 激活状态查询”。

11.2 插件必须升级

提示当前版本无法继续使用：

• 立即升级：打开项目统一的插件更新弹框。
• 返回主页：返回 MainActivity。

升级完成后旧的初始化和激活缓存全部失效，必须重新走完整门禁。

11.3 统一下载与安装弹框

项目不再直接展示 SDK 内置下载弹框，由 AiPluginUpdateDialog 与 AiPluginUpdateManager 统一承接安装、强制升级和基础设置激活中的插件更新流程：

1. 后台调用 SDK 的版本查询能力获取 AppInfoBean。
2. 弹框展示版本号和更新内容；真实下载地址仅供后台校验与下载，不在界面显示。
3. 下载统一调用 PluginManager.downloadFile()，将 onProgress(int) 映射为 0 至 100 的进度条和百分比。
4. 下载中与正在拉起安装器时禁止取消，避免业务页在插件状态不确定时继续运行。
5. 下载失败可在原弹框重试；下载完成后按钮切换为“立即安装”。
6. 目标设备通过 SmdtManagerNew.sys_doSilentInstallApp() 后台安装，项目弹框在安装阶段 切换为“AI算法SDK更新”，不再展示 Android 系统安装器。
7. 安装完成后同时校验实际已安装包版本，并向统一 SDK 门禁发送安装成功事件；SDK 自身 的包安装广播作为补充，两类事件去重后触发完整门禁复查。

下载前必须校验地址为带有效主机名的 HTTPS URL；下载完成后必须校验文件存在、非空， 且 APK 包名为 com.yingeo.ai.sdk。后台安装前必须确认主板服务可用，安装后必须确认目标 插件版本已生效；任一校验失败均停止流程并在项目弹框显示明确错误。

11.4 弹框风格统一

AI 门禁与插件更新流程的弹框统一复用项目现有视觉基线：固定 common_pop_width、白色圆角 卡片、白色标题栏与黑色标题文字、标题分隔线、灰色正文、左侧次按钮和右侧橙色主按钮。 覆盖范围包括：

• AI 服务检查中。
• 设备未激活。
• 插件未安装。
• 插件必须升级。
• AI 服务异常与重试。
• 插件信息查询、下载进度、下载失败、后台安装和安装完成。
• 基础设置中的 AI 激活进度。

AI 服务检查和基础设置激活中的等待提示直接复用 NewSingleTipPop 与 single_tip_pop_layout.xml，仅隐藏底部操作区，不再维护独立加载弹框或显示系统样式的 圆形进度控件，确保其卡片尺寸、白色标题栏、分隔线和正文排版与项目提示框完全一致。

弹框外部区域均不可关闭；下载中和安装中禁用取消。未激活提示的返回键、返回主页及前往 设置行为不变，插件安装和升级提示在打开下载弹框后继续保留业务阻断。

12. 数据安全

当前校正流程会在 SDK 校正前清理现有学习图片。实施时应改为临时目录准备和成功后替换：

1. 下载远端图片到临时目录。
2. 验证图片数量、编码和文件可读性。
3. 门禁仍为 READY 时执行 SDK 校正。
4. SDK 校正成功后再替换正式学习图片目录。
5. 任一步失败都保留原有正式目录。

这部分与就绪门禁同时实施，避免解决激活问题后仍存在数据破坏风险。

13. 错误映射与日志

页面提示必须区分：

日志至少包含：页面、操作、门禁状态、SDK code、SDK message、耗时和本地数据准备状态。禁止记录激活码。

14. 测试范围

14.1 单元测试

• 初始化成功后才查询激活状态。
• 插件未安装时不查询激活状态。
• 必须升级时不查询激活状态。
• 多个并发请求只触发一次 SDK 检查。
• NOT_ACTIVE 会使 READY 失效。
• 页面注销后不再收到回调。

14.2 页面测试

• 已激活时进入管理页并正常同步。
• 未激活时不请求业务数据并显示弹框。
• 选择返回主页后任务栈正确。
• 选择前往设置后定位到 AI 激活项。
• 设置页激活成功返回后重新检查并开始同步。
• 设置页取消或激活失败后返回主页。
• 插件未安装、必须升级和初始化超时分别显示准确提示。
• 连续点击不会产生多个同步或校正任务。

14.3 数据安全测试

• 图片下载失败时保留原有学习数据。
• SDK 校正返回 1004 时保留原有学习数据。
• 校正成功后正式目录和 SDK 特征库保持一致。

15. 验收标准

1. 所有依赖银歌 AI SDK 的页面统一通过 AiSdkManager.ensureAiReady() 放行业务。
2. 插件未安装时绝不先查询激活状态。
3. 未激活时 DishManagementActivity 不发起菜品学习业务请求。
4. 未激活弹框的“前往设置”和“返回主页”行为符合已确认规则。
5. 设置页返回后以 SDK 真实状态重新校验。
6. 页面不再把 1004、1010 等错误统一显示为“学习数据校正失败”。
7. 并发进入多个 AI 页面不会重复初始化 SDK。
8. 同步或校正失败不会破坏原有可用学习数据。

16. 预计修改范围

• ai/AiSdkManager.java：统一门禁、状态机、并发与状态失效。
• ai/AiDishActivationManager.java：复用统一初始化和插件状态，修正安装期间超时。
• ai/AiPluginUpdatePolicy.java：定义查询、下载、安装状态和按钮行为。
• ai/AiPluginUpdateManager.java：统一版本查询、下载进度、APK 校验与安装回调链。
• ai/AiPluginUpdateDialog.java：统一展示版本、内容、进度、安装状态和重试操作。
• activity/DishManagementActivity.java：门禁后启动业务、弹框和设置页返回处理。
• activity/NewDishLearningActivity.java：移除重复的激活与插件判断，接入统一门禁。
• activity/DishRecognitionActivity.java：接入统一门禁，保留运行中 NOT_ACTIVE 兜底。
• activity/SettingActivity.java、fragment/SettingsBasicFragment.java：目标项导航及激活结果回传。
• DishLearningStore.java：支持临时目录与成功替换。
• strings.xml：补充明确状态和弹框文案。
• dialog_ai_plugin_update.xml 及对应 drawable：统一插件更新弹框界面。
• 对应单元测试与页面验证记录。

17. 风险与边界

• 银歌 SDK 的安装、升级和激活回调可能存在版本差异，实施时以当前 AAR 与设备插件实测结果为准。
• queryAiActiveStatus() 是同步 AIDL 调用，必须避免阻塞主线程。
• 不在本次范围内改造与银歌 AI 无关的人脸 SDK 激活流程。
• 不在业务页面自动提交激活码，避免未经用户确认改变设备授权状态。

18. 实施结果

2026-07-21 已按本设计完成项目落地：

• 建立 AiReadyState、AiReadinessPolicy、AiSdkManager 两层门禁和统一 AiReadinessGuard。
• 基础设置激活改为先检查插件与 SDK 服务，激活成功后再次查询真实激活状态。
• 菜品管理、菜品学习、菜品识别三个页面均在 READY 后启动 AI 业务。
• 未激活提示支持“前往设置”和“返回主页”；弹框返回键与拒绝处理均返回主页。
• 插件安装或升级入口打开后保留阻断弹框，下载或后台安装失败时不会留在无提示的业务页。
• 插件安装、强制升级及基础设置激活中的插件处理已统一使用项目弹框，展示版本信息、 实时进度，并支持失败重试和下载后安装；真实下载地址不在界面显示。
• 下载地址强制使用 HTTPS，安装前校验 APK 包名；目标设备通过主板服务后台安装，安装后 校验真实版本并触发后续门禁复查，不再展示系统安装器。
• AI 检查、未激活、插件缺失、强制升级、异常重试、下载和安装弹框已统一为项目现有风格。
• 学习数据校正使用独立暂存目录；下载或 SDK 校正失败时保留原目录，成功后再原子切换。
• 新增状态映射单元测试；单元测试、Java 编译和 Debug APK 构建已通过。

设备侧插件安装、强制升级和激活交互尚未安装本次 APK 实测，仍需在目标设备上完成五类场景验收。