play-billing-library-version-upgrade

阶段 0：意图说明

报告操作：继续之前，立即告诉用户：“我将把 Play Billing Library 升级到最新版本。”

阶段 1：发现与情境感知

1. 首要检查（构建版本）：在 build.gradle、build.gradle.kts 或 libs.versions.toml 中找到项目的计费依赖（例如 com.android.billingclient:billing）。
2. 初始编译测试：立即尝试同步并构建项目。
3. 备用发现（有效版本）：
   • 触发条件：仅当构建立即失败时，扫描源代码以查找已弃用的项。
   • 逻辑：存在已弃用的 API，表明“有效版本”——定义为这些特定 API 最后可用时的版本，而非它们引入时的版本。
   • 示例：如果存在 SkuDetails，则将基准视为 PBL v7 或更早版本（无论 build.gradle 中的版本字符串是什么）。
4. 确定目标与路径：访问版本工具或发行说明，以查找最新稳定版本，并根据有效版本基准计算[直接/分步]迁移路径。

• 计算迁移路径：
  • 如果有效版本与目标版本相差不超过 2 个主版本：规划直接迁移。
  • 如果落后超过 2 个主版本：规划分步迁移。每次迁移跨越两个主版本（例如 v4 -> v6 -> v8），直到与目标版本相差不超过两个版本。
• 报告操作：继续之前，告诉用户：“我检测到您实际上使用的是 PBL [Current]，最新版本是 [Target]。我计划采用[直接/分步]迁移路径。”

阶段 2：上下文文档映射与规划

对于迁移路径中的每次主版本升级，必须综合以下内容中的说明：

• 迁移指南（其中 [X] 是目标主版本）。
• 发行重点：相关发行说明中的“弃用”和“破坏性变更”部分。
• 开发者文档：参考你对 Google Play Billing 文档的了解，了解此应用使用的相关功能（例如订阅、一次性商品）。
• 制定计划：找出所需的每项具体代码更改（API 移除、类替换、逻辑调整），并以检查清单的形式列出。

阶段 3：执行说明

报告操作：对于以下每个步骤，请在执行前简要说明将要做什么，并在执行后简要总结完成的工作。

步骤 1：SDK 与环境对齐

• 操作：更新 build.gradle 以满足 SDK 要求（例如，“PBL 9 要求 compileSdk 35”）。
• Gradle 版本：检查新库是否需要更新版本的 Android Gradle Plugin（AGP）或 Kotlin。

步骤 2：基于意图的重构

分析现有代码的意图，而不是单纯进行文本替换。

• 操作：必须遵循 references/migration-logic.md 部分、官方迁移指南，以及阶段 2 中指定的常规文档页面中的所有弃用说明和重构模式。
• 验证：确认已遵循所有文档中的全部步骤，并确保按照参考资料检查清单中的具体说明执行。

步骤 3：顺序验证（仅适用于分步迁移）

1. 升级到迁移路径中的第一个主版本中间版本。
2. 运行 ./gradlew assembleDebug，确认没有遗漏任何中间版本的破坏性变更。
3. 重复上述步骤，直到达到最终目标版本。

第 4 步：最终验证清单

1. 智能清单验证：
2. 打开 references/version-checklist.md，找到 智能版本专属清单。
3. 操作：针对 [检测到的当前版本] 与 [检测到的新版本] 之间的每个版本，使用“在文件中查找”或结构分析，确认代码已处理每一项。
4. 测试：运行所有单元测试和实现测试（./gradlew test）。
5. 干净构建：确认项目可以完成完整的干净构建：./gradlew clean assembleDebug。然后运行 ./gradlew sync 和 ./gradlew build，以便用户可以立即手动测试新版本。

最终报告

向开发者说明“原因”：

• “我将你的 SDK 更新到了 [版本]，因为 PBL [版本] 根据 [文档中的原因] 要求使用该版本。”
• “我删除了你的自定义 retryConnection() 逻辑，因为库现在会通过 enableAutoServiceReconnection() 原生处理此功能。”
• “已成功从 PBL [旧版本] 升级到 PBL [新版本]，并通过单元测试验证。根据对最新库功能和此应用当前功能集的分析，我建议你探索最新版本中的 [新功能]（例如预付费计划或分期付款），因为该功能现已推出，但尚未实现。”