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

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

## 总体思路
采用“配置中心 + 启动校验 + 缓存兜底 + 失效提示”的方案：
1. 小程序启动时请求配置中心接口获取最新配置。
2. 校验小程序版本、API版本、WebView版本一致性。
3. 校验失败则提示退出重启；通过则写入缓存并使用配置。
4. 配置接口不可用时使用缓存，缓存失效则提示退出重启。

## 配置中心接口
- 方法: `GET`
- 路径: `/api/open/app/config`

### 返回示例
```json
{
  "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` 用于维护提示。