AI 插件更新弹框统一封装变更记录

变更日期

2026-07-21

背景

银歌 AI SDK 内置的插件安装与升级弹框能够执行下载，但应用层无法统一获取并展示下载地址、实时进度和失败状态。插件未安装、强制升级、基础设置激活中的插件处理也分别调用 SDK 弹框，交互和后续状态复查不便统一维护。

统一方案

• AiPluginUpdatePolicy 定义查询、可下载、下载中、已下载、安装中和失败状态，并集中管理按钮行为、进度边界和是否允许关闭。
• AiPluginUpdateManager 负责版本查询、下载回调、实时进度、下载结果校验和拉起安装器，不持有 Activity 强引用。
• AiPluginUpdateDialog 负责统一展示版本号、更新内容、真实下载地址、进度条、百分比、错误提示、重试和安装操作。
• 插件未安装、插件强制升级及基础设置激活中的插件处理，全部进入同一套弹框和管理器。

下载与安装链路

1. 后台调用 PluginManager.queryAppInfo() 获取最新插件信息。
2. 仅接受带有效主机名的 HTTPS 下载地址。
3. 调用 PluginManager.downloadFile()，通过 onProgress(int) 更新 0 至 100 的实时进度。
4. 下载成功后校验 APK 文件存在、非空，且包名为 com.yingeo.ai.sdk。
5. 用户确认安装后调用 PluginManager.installApp() 拉起系统安装界面。
6. 该安装入口会保留 SDK 的包安装广播监听；收到安装成功事件后重置更新状态，并重新执行 SDK 初始化、版本检查和真实激活状态查询。

下载期间和拉起安装器期间禁止取消弹框；查询或下载失败时保留明确错误提示并支持重试。若用户在系统安装器中取消，重新打开弹框仍可使用已下载 APK 再次安装。

入口替换

• AiReadinessGuard：插件未安装与必须升级提示的确认操作进入统一弹框。
• AiDishActivationManager：基础设置激活前发现插件缺失或必须升级时进入统一弹框。
• AiSdkManager：收到插件安装成功事件后重置下载状态并通知门禁重新检查。
• 项目代码中不再调用 SDK 内置的 showPluginInstallDialog() 或 showPluginUpgradeDialog()。

安全与稳定性

• 下载地址强制为 HTTPS，拒绝非安全地址。
• 下载目录不可用时不启动下载，并提示检查存储空间。
• 安装前验证 APK 文件与目标插件包名，避免安装错误文件。
• 下载状态使用代次标识隔离过期回调，进度去重并限制在 0 至 100。
• 监听器使用弱引用，弹框停止后主动注销，避免持有页面。

测试与验证

采用测试先行方式完成状态策略：

• 在策略类不存在时先建立测试，确认编译失败后实现状态与按钮规则。
• 在 HTTPS 校验方法不存在时先增加安全用例，确认失败后补充实现。
• 策略测试覆盖进度边界、按钮行为、下载中不可关闭以及 HTTPS 地址判断。
• Java 编译、全量 Debug 单元测试、Debug APK 构建和 git diff --check 均纳入最终回归。

本次未向目标设备安装 APK，因此真实下载进度、系统安装器取消/重试、安装成功广播和强制升级完成后的设备交互仍需现场验收。

版本控制说明

本次仅完成实现、验证与记录，未执行暂存、提交、推送或分支切换。用户原有未相关修改保持不变。