AI SDK Unified Readiness Gate Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将银歌 AI 插件、初始化、强制升级和真实激活状态统一收口，在 AI 业务放行前完成可靠检查，并按已确认规则引导未激活用户进入设置或返回主页。

Architecture: AiSdkManager 维护单例 SDK 会话和统一就绪状态，提供“服务就绪”和“业务就绪”两层门禁；业务页面通过可复用的 AiReadinessGuard 获得一致弹框与导航行为。设置页激活复用服务门禁，激活成功后重新查询真实状态。

Tech Stack: Android Java、银歌 AI SDK AAR、AndroidX AppCompat、JUnit 4、Gradle 7.4。

Task 1: 建立可测试的状态模型

Files:

• Create: app/src/main/java/com/cpt/aidishrecognition/ai/AiReadyState.java

• Create: app/src/main/java/com/cpt/aidishrecognition/ai/AiReadinessPolicy.java

• Create: app/src/test/java/com/cpt/aidishrecognition/ai/AiReadinessPolicyTest.java

• Step 1: 编写失败测试

覆盖 SUCCESS -> READY、NOT_ACTIVE -> NOT_ACTIVE、插件缺失、强制升级以及未知错误映射。

• Step 2: 运行测试确认失败

Run: ./gradlew :app:testDebugUnitTest --tests com.cpt.aidishrecognition.ai.AiReadinessPolicyTest

Expected: 因目标类型尚未创建而编译失败。

• Step 3: 实现最小状态模型

AiReadinessPolicy 只负责将 SDK code 映射到 AiReadyState，不持有 Android Context 或页面引用。

• Step 4: 运行测试确认通过

Run: ./gradlew :app:testDebugUnitTest --tests com.cpt.aidishrecognition.ai.AiReadinessPolicyTest

Expected: BUILD SUCCESSFUL。

Task 2: 扩展 AiSdkManager 为统一门禁

Files:

• Modify: app/src/main/java/com/cpt/aidishrecognition/ai/AiSdkManager.java

• Step 1: 增加服务门禁与业务门禁接口

提供 ensureServiceReady()、ensureAiReady()、cancelReadyRequests()、invalidateReadyState() 和 markNotActive()。

• Step 2: 增加单次并发与超时控制

同一时刻只执行一次初始化/查询；请求排队，回调前检查 Activity 生命周期；插件安装交互期间不触发普通初始化超时。

• Step 3: 增加初始化后的升级观察窗口

onInitSuccess() 后短暂等待 SDK 的强制升级消息，再放行服务请求或查询激活状态，避免先弹未激活、随后又收到 1010。

• Step 4: 增加真实激活状态查询

在后台线程调用 queryAiActiveStatus()，主线程分发结果；NOT_ACTIVE 同步清除本地激活展示缓存。

• Step 5: 编译验证

Run: ./gradlew :app:compileDebugJavaWithJavac

Expected: BUILD SUCCESSFUL。

Task 3: 设置页激活复用统一服务门禁

Files:

• Modify: app/src/main/java/com/cpt/aidishrecognition/ai/AiDishActivationManager.java

• Modify: app/src/main/java/com/cpt/aidishrecognition/activity/SettingActivity.java

• Modify: app/src/main/java/com/cpt/aidishrecognition/fragment/SettingsBasicFragment.java

• Modify: app/src/main/res/layout/fragment_setting_basic.xml

• Step 1: 移除激活管理器的独立 SDK 初始化回调

激活前调用 ensureServiceReady()；插件未安装或必须升级时返回明确状态；激活成功后调用 ensureAiReady() 二次确认。

• Step 2: 支持从业务页定位激活设置项

SettingActivity 增加来源和目标项参数，基础设置页定位并短暂高亮 AI 激活行。

• Step 3: 回传激活处理结果

从 AI 业务页进入设置时，激活成功回传 RESULT_OK；取消或返回时回传 RESULT_CANCELED。

• Step 4: 编译验证

Run: ./gradlew :app:compileDebugJavaWithJavac

Expected: BUILD SUCCESSFUL。

Task 4: 建立统一业务页面交互守卫

Files:

• Create: app/src/main/java/com/cpt/aidishrecognition/ai/AiReadinessGuard.java

• Modify: app/src/main/res/values/strings.xml

• Step 1: 实现统一检查入口

守卫调用 ensureAiReady()，处理进度提示、重复请求和 Activity 销毁。

• Step 2: 实现统一阻断弹框

未激活：前往设置/返回主页；插件未安装：安装插件/返回主页；必须升级：立即升级/返回主页；其他错误：重试/返回主页。

• Step 3: 实现统一导航

前往设置携带目标项参数；拒绝处理使用 CLEAR_TOP | SINGLE_TOP 返回 MainActivity。

• Step 4: 编译验证

Run: ./gradlew :app:compileDebugJavaWithJavac

Expected: BUILD SUCCESSFUL。

Task 5: 接入三个 AI 业务页面

Files:

• Modify: app/src/main/java/com/cpt/aidishrecognition/activity/DishManagementActivity.java

• Modify: app/src/main/java/com/cpt/aidishrecognition/activity/NewDishLearningActivity.java

• Modify: app/src/main/java/com/cpt/aidishrecognition/activity/DishRecognitionActivity.java

• Step 1: 接入菜品管理页

页面创建后先检查门禁，READY 后才同步菜品与学习数据；设置返回后重新查询；learnDateRivise() 返回 NOT_ACTIVE 时使状态失效并重新提示。

• Step 2: 接入菜品学习页

门禁通过前不启动相机识别和学习请求；删除页面内重复的插件、升级和自动激活处理。

• Step 3: 接入菜品识别页

门禁通过前不提交识别帧；运行中返回 NOT_ACTIVE 时交给统一守卫，不在页面自动提交激活码。

• Step 4: 编译验证

Run: ./gradlew :app:compileDebugJavaWithJavac

Expected: BUILD SUCCESSFUL。

Task 6: 防止校正失败破坏已有学习数据

Files:

• Modify: app/src/main/java/com/cpt/aidishrecognition/utils/DishLearningStore.java

• Modify: app/src/main/java/com/cpt/aidishrecognition/activity/DishManagementActivity.java

• Step 1: 增加临时同步目录支持

远端图片先写入独立临时目录，不提前删除正式目录。

• Step 2: 校正成功后替换正式目录

SDK 校正成功后再切换正式目录；下载、保存或 SDK 校正失败时清理临时目录并保留原数据。

• Step 3: 编译与静态检查

Run: ./gradlew :app:compileDebugJavaWithJavac && git diff --check

Expected: BUILD SUCCESSFUL 且无空白错误。

Task 7: 完整验证与记录

Files:

• Modify: docs/superpowers/specs/2026-07-21-ai-sdk-readiness-gate-design.md

• Modify: docs/superpowers/specs/2026-07-21-ai-sdk-readiness-gate-design.html

• Create: /Users/liang/AndroidStudioProjects/zhct/zhctprompt/work_android/AIDishRecognition/change_records/2026-07-21-ai-sdk-readiness-gate.md

• Create: /Users/liang/AndroidStudioProjects/zhct/zhctprompt/work_android/AIDishRecognition/change_records/2026-07-21-ai-sdk-readiness-gate.html

• Step 1: 运行单元测试和构建

Run: ./gradlew :app:testDebugUnitTest :app:assembleDebug

Expected: BUILD SUCCESSFUL。

• Step 2: 安装到目标设备并验证日志

验证插件未安装、必须升级、未激活、激活成功及运行中 1004 五类路径；日志不得包含激活码。

• Step 3: 更新设计结论和变更记录

同步 Markdown/HTML 文档，记录具体文件、行为、验证命令和遗留的设备侧前置条件。

• Step 4: 最终差异检查

Run: git diff --check && git status --short

Expected: 仅包含本次实现文件和用户原有未相关改动，不执行暂存、提交或推送。

执行状态（2026-07-21）

• Task 1 至 Task 6 已完成。
• Task 7 的单元测试、Debug APK 构建、设计文档与变更记录已完成。
• 目标设备安装与五类交互场景实测未执行，避免在未获得部署确认时变更现场设备；需作为设备验收项继续完成。
• 全程未执行暂存、提交、推送或分支切换。

后续增量：插件更新弹框统一封装（2026-07-21）

• 新增纯状态策略，覆盖查询、下载、下载完成、安装、错误和按钮行为。
• 新增统一更新管理器，复用 SDK 版本查询与下载回调，向页面提供版本信息和进度；下载地址仅在后台使用。
• 新增项目自有弹框，展示版本、更新内容、进度、重试和安装入口，不展示下载地址。
• 插件未安装、强制升级、基础设置激活三类入口全部替换为统一弹框。
• 增加 HTTPS 下载地址校验、下载文件校验和插件 APK 包名校验。
• 安装统一调用目标主板后台安装服务，并结合 SDK 安装广播与主动事件完成就绪门禁复查。
• 使用测试先行方式验证状态策略与下载地址安全规则，并完成全量构建回归。
• 目标设备侧下载、后台安装、安装失败重试和升级成功交互，待获得部署确认后验收。

后续增量：AI 全流程弹框风格统一（2026-07-21）

• 未激活、插件缺失、必须升级和服务异常统一使用项目 NewSingleTipPop。
• AI 门禁检查与基础设置 AI 激活进度直接复用项目 NewSingleTipPop，等待期间隐藏操作区。
• NewSingleTipPop 与插件更新弹框统一使用白色标题栏和黑色标题文字。
• 插件查询、下载、失败、安装弹框统一使用项目宽度、标题分隔线和按钮样式。
• 安装阶段标题切换为“AI算法SDK更新”。
• 目标 FY-3576SE 设备改用主板后台安装服务，不再打开 Android 系统安装器。
• 后台安装完成后校验真实插件版本，并对主板回调与 SDK 广播进行去重。
• 单元测试、Debug APK 构建和静态差异检查通过。
• 目标设备安装新版 APK 后，完成未激活、首次安装、强制升级和安装失败四类视觉验收。