1

flutter_app/docs/PaymentApi.md

@@ -101,3 +101,21 @@
 - `priceCents` 为整数分，客户端展示 ÷100 转元
 - 展示名由客户端按 `days` 派生「N天」，接口无 label 字段
 - 后端套餐来自 `config.yml` `plans` 节点（静态定价，改价改配置重启生效）
+
+## 7. 版本更新检查
+
+`GET /api/v1/app/update`（**公开接口，无需登录**）在 App 启动时调用（协议层见 `lib/update/update_checker.dart`）。
+
+响应 `data`（无记录时字段为空串，视为无需更新）：
+
+```json
+{
+  "version": "1.1.0",
+  "notes": "修复识别准确率问题"
+}
+```
+
+- **仅 Android 调用**：`UpdateChecker.fetch()` 在非 Android 平台直接返回空（iOS 不做版本下发，用户从 App Store 自行更新）
+- 客户端以「语义化版本号」按数字段比较（`1.10.0 > 1.9.9`），**服务器版本 > 已装版本即强制更新**：弹全屏阻塞页（禁返回，仅「立即更新」），`url_launcher` 打开系统浏览器下载固定地址 `{apiBaseUrl}/download/observer-latest.apk`（后端静态托管，永远是最新 APK）
+- **双版本比较防反复提示**：用户点「立即更新」时把服务器版本号写入本地（`SessionStore.accepted_update_version`）；判定条件是服务器版本 > 已装版本 **或** 服务器版本 > 已接受版本。APK 版本号不递增（每次打的包 versionName 相同）时，已更新完成的手机重启也不会再次弹更新
+- 网络异常/响应异常时静默跳过检查，不阻塞启动