shanxia2.0/docs/superpowers/specs/2026-09-26-mp-version-status-design.md

微信小程序版本可见性与更新状态（方案 C 一期）

日期：2026-09-26
适用范围：miniprogram/utils/mpUpdate.js、miniprogram/pages/workbench/workbench.vue
前置：docs/superpowers/specs/2026-09-26-mp-weixin-force-update-design.md
决策：展示微信发版号 + UpdateManager 状态文案（已是最新 / 有新版本…）

---

1. 目标

1. 用户在主界面「工作台」能看见当前代码包版本与环境（正式 / 体验 / 开发）。
2. 能明确看到检查结果文案：已是最新 或 有新版本（下载中 / 待重启）。
3. 不引入后端版本接口（一期）；强制重启行为保持不变。

2. 非目标

• 后端「最新版本号 / 最低可用版本」比对
• 启动页全屏版本横幅
• 改变 showCancel: false 强制重启策略
• 用 package.json 的 version 冒充微信发版号

3. 数据来源

字段	来源	说明
version	uni.getAccountInfoSync().miniProgram.version	仅正式版有值；开发/体验常为空
envVersion	同上 .envVersion	release / trial / develop
是否有更新	UpdateManager.onCheckForUpdate → hasUpdate	正式版 CDN 结果；有延迟
下载就绪	onUpdateReady	已有强制弹窗，行上文案同步为「待重启」
失败	onUpdateFailed	已有失败弹窗

4. 状态机（UI）

status	行内文案片段	触发
unsupported	开发版/体验版 · 无正式更新流	envVersion !== 'release'
checking	检查中…	用户点击或主动检查开始
latest	已是最新	hasUpdate === false
downloading	有新版本（下载中）	hasUpdate === true 且尚未 ready
ready	有新版本，点此重启	onUpdateReady
failed	更新失败	onUpdateFailed
idle	（正式版初始可显示「点此检查更新」）	尚未收到 check 回调

展示行格式（正式版）：

版本 {version} · 正式版 · {状态文案}

版本为空时用 —。

5. 交互

1. 「工作台」页 onShow：刷新 account 信息，并调用 checkMpUpdate()（沿用 30s 防抖）。
2. 点击版本行：checkMpUpdate({ force: true, fromUser: true })
   
   • 若已 ready：直接再次拉起强制重启弹窗 / applyUpdate
     
   • 若 unsupported：toast 说明开发/体验无正式更新流
     
   • 检查结束且 latest：toast「已是最新」
     
   • downloading：toast「发现新版本，正在下载」
3. onUpdateReady：仍强制 Modal「立即重启」；状态置 ready。

6. 模块 API（mpUpdate.js）

• getMpAccountInfo() → { version, envVersion, envLabel, isRelease }
• getMpUpdateSnapshot() → { status, ...account }
• subscribeMpUpdate(listener) → unsubscribe
• checkMpUpdate(options?) — 扩展现有导出；App.vue 调用方式兼容（无参）

7. UI 落点

• 仅 pages/workbench/workbench.vue：标题「山峡化工工作台」正下方展示版本行（绿色 Header 内）。
• 常态：半透明白字，不抢标题。
• 需更新（downloading / ready / failed）：大麦黄底条 + 加粗文案；ready 另显「立即更新」按钮样式并轻微脉冲，便于点按。
• 不改 app-env-badge；不落在 pages/mine/mine.vue。

8. 已知限制

1. 发版后 CDN 未同步时，可能短暂显示「已是最新」。
2. 微信不会因多次 getUpdateManager 立刻重复拉 CDN；force 主要绕过本地 30s 入口防抖并刷新 UI 状态。
3. 开发版/体验版无法用本能力验收「已是最新」。

9. 验收

1. 正式版「工作台」可见 版本 x.x.x · 正式版 · …。
2. 无更新时检查后文案为「已是最新」，用户点击有 toast。
3. 有更新时先「下载中」，就绪后弹窗 +「点此重启」。
4. 开发/体验版不假装最新，文案为无正式更新流。
5. App 冷/热启动强制更新行为与既有设计一致。