wz-golang-server/docs/AppConfigVersionPlan.md

小程序接口与 WebView 版本一致性方案

目标

• 小程序获取接口地址与 WebView 地址。
• 判断版本一致性与可用性。
• 不可用时提示用户退出小程序重新打开。

总体思路

采用“配置中心 + 启动校验 + 缓存兜底 + 失效提示”的方案：

1. 小程序启动时请求配置中心接口获取最新配置。
2. 校验小程序版本、API版本、WebView版本一致性。
3. 校验失败则提示退出重启；通过则写入缓存并使用配置。
4. 配置接口不可用时使用缓存，缓存失效则提示退出重启。

配置中心接口

• 方法: GET
• 路径: /api/open/app/config

返回示例

{
  "app": {
    "minVersion": "1.2.0",
    "latestVersion": "1.3.5",
    "forceUpdate": true
  },
  "api": {
    "baseUrl": "https://api.xxx.com",
    "version": "2026-03-16",
    "minClientVersion": "1.2.0"
  },
  "webview": {
    "baseUrl": "https://m.xxx.com",
    "version": "2026-03-16",
    "minClientVersion": "1.2.0"
  },
  "ttlSeconds": 3600,
  "disabled": false,
  "disableReason": ""
}

字段说明

• app.minVersion: 最低可用小程序版本。
• app.latestVersion: 最新版本号。
• app.forceUpdate: 是否强制更新。
• api.baseUrl: API 入口地址。
• api.version: API 版本号（用于一致性校验）。
• api.minClientVersion: API 允许的最小客户端版本。
• webview.baseUrl: WebView 入口地址。
• webview.version: WebView 版本号（用于一致性校验）。
• webview.minClientVersion: WebView 允许的最小客户端版本。
• ttlSeconds: 配置缓存有效期（秒）。
• disabled: 服务下线开关。
• disableReason: 下线原因。

小程序启动校验流程

1. 小程序 App.onLaunch 请求 /api/open/app/config。
2. 校验顺序：
   • disabled == true → 提示“服务暂不可用，请退出小程序重新打开”。
   • 当前版本 < app.minVersion → 提示强更并阻断。
   • api.version != webview.version → 提示“版本不一致，请退出小程序重新打开”。
   • 当前版本 < api.minClientVersion 或 当前版本 < webview.minClientVersion → 提示强更。
3. 校验通过：
   • 缓存配置（本地 storage）。
   • 全局设置 API baseUrl 与 WebView baseUrl。

缓存与兜底策略

• 配置接口失败：
  • 如果本地缓存存在且未过期 → 使用缓存。
  • 若缓存过期或不存在 → 提示“配置获取失败，请退出小程序重新打开”。

提示文案建议

• 版本不一致：
  • “当前版本不一致，请退出小程序并重新打开以获取最新配置。”
• 服务不可用：
  • “服务暂不可用，请退出小程序重新打开。”
• 配置获取失败：
  • “配置获取失败，请退出小程序重新打开。”

WebView 入口处理

• WebView URL 必须由配置中心下发，避免在客户端写死。
• 进入 WebView 前再次校验缓存是否过期；过期则重新拉取。

前端需要完成的部分

1. 在 App.onLaunch 拉取 /api/open/app/config，并写入本地缓存。
2. 实现版本校验逻辑（app.minVersion、api.version、webview.version、minClientVersion）。
3. 校验失败时弹窗提示，并引导退出小程序重新打开。
4. 缓存过期或接口失败时，优先使用缓存；无缓存则提示退出。
5. WebView 入口统一从配置下发的 webview.baseUrl 拼接跳转。
6. 请求 API 时统一使用配置下发的 api.baseUrl。

可选扩展

• 灰度策略：按用户或设备下发不同配置。
• 公告字段：返回 notice 用于维护提示。