atomic-resource-promotion

1. 实验目标与工程要点

这个 Android host 样板只演示更新链路里最危险也最关键的一步：把 staging 资源包安全晋升为 active 版本。

它验证的重点是：

• staging 目录准备完整前，active 目录绝不被写脏
• 切换时先改版本指针，再决定旧版本是否进入 backup
• 晋升失败时要继续保留旧版本服务，而不是半切换半回滚

---

2. 深入原理与生活浅显比喻

2.1 生活浅显比喻

它像商场夜间换展：

• 白天营业区（active）不能边营业边拆墙装修
• 新展区（staging）必须在后台先完全布置好
• 真正切换营业，只能等新展区准备完再一次性开门

2.2 底层原理分析

原子晋升最核心的约束只有一句：业务读路径在任何时刻只能看到一个完整版本。

因此更稳的序列是：

1. 校验 staging 完整
2. 预写新的 activeVersion 指针候选
3. 执行目录级切换 / rename
4. 成功后把旧版本放入 backup
5. 失败则回退指针和目录映射

2.3 方案对比矩阵

方案	通俗比喻	底层原理	保证特性	吞吐性能	运行开销	适用场景
逐文件覆盖 active	边营业边换展台	active 中途暴露半新半旧文件	最弱	中	低	不推荐
staging 完整后原子晋升	后台布展后统一开门	目录切换 + 指针更新	最稳	中	中	离线包、模型、资源包更新
只切指针不备份	换展后旧展立刻丢弃	无回滚保底	中	高	低	低风险更新

---

3. Android / 移动端实战场景与误配事故

3.1 实战场景

• WebView 离线资源包切换
• 端上模型版本升级
• 热更新资源目录激活

3.2 常见误配与事故注意事项

• active 正在读时被直接覆盖，页面白屏
• 版本指针已更新，但 staging 实际未切成功
• backup 没保留，失败后无法回滚

3.3 排障思路

先检查三件事是否一致：

1. activeVersion
2. activeDirName
3. backupVersion

一旦三者不一致，就说明晋升事务没有收好尾。

---

4. 实验源码与运行验证

关键源码

• Activity：AtomicResourcePromotionActivity.kt
• 布局：activity_atomic_resource_promotion.xml

关键参数 / 开关

• simulatePromotionFailure：模拟切换阶段抛错
• backupVersion：保留最近一个可回滚版本

运行方式

cd labs/android/host
./gradlew installDebug

打开 Android Host，进入 资源包原子晋升。

预期控制台运行输出

verify staging_v42 ok
promote staging_v42 -> active
promotion failed, keep active=v41 backup=v40
retry success, active=v42 backup=v41

---

5. 对应知识库文档

• 理论主文档：项目案例：download_service.dart 的下载 / 校验 / 原子更新 / 失败恢复