优化android 热更新

README.md

@@ -79,16 +79,18 @@ App 内置自建 OTA 更新器。它只更新 `dist` 中的 HTML、JavaScript、
 ```powershell
 Set-Location web
 npm ci
-npm run ota:package -- --version 1.0.1
+npm run ota:package
 ```
 
-ZIP 会生成到 `.artifacts/app-updates`，根目录直接包含 `index.html`。使用
+ZIP 会生成到 `.artifacts/app-updates`，根目录直接包含 `index.html`，其版本固定取自
+`versions.props` 的 `JiaowuFrontendVersion`（传入 `--version` 时也必须一致）。使用
 SuperAdmin 进入“运维与审计 → App 前端热更新”，上传 ZIP，填写目标平台、通道和
 兼容的原生版本后先保存为草稿，再执行发布。当前 Android 工程的 `versionName` 为
 `1.0`，因此对应更新包的“兼容原生版本”应填写 `1.0`。
 
-App 启动后向 `/api/app-updates/latest` 检查版本，在后台下载并校验服务端提供的
+App 启动、以及从后台回到前台超过 5 分钟后，会向 `/api/app-updates/latest` 检查版本，
-SHA-256，下次启动时切换。新资源若未能成功启动，原生更新器会自动回滚。再次发布
+在后台下载并校验服务端提供的 SHA-256；切到后台或下次启动时切换，并保留当前页面地址。
+新资源若未能成功启动，原生更新器会自动回滚。再次发布
 已归档版本即可回滚正式通道；不同原生版本、Android/iOS、测试/正式通道彼此隔离。
 更新版本元数据和 ZIP 保存在数据库中，部署新服务端版本前必须先执行
 `--migrate-only`。

web/capacitor.config.ts

@@ -13,6 +13,13 @@ const config: CapacitorConfig = {
       autoUpdate: 'off',
       version: '1.0.0',
       appReadyTimeout: 10000,
+      // A 30 MB OTA package can take longer than the plugin default on a
+      // mobile network. Manual checking keeps the UI responsive while this
+      // timeout only governs the native request/download pipeline.
+      responseTimeout: 60,
+      autoDeleteFailed: true,
+      autoDeletePrevious: true,
+      keepUrlPathAfterReload: true,
     },
   },
 }

web/scripts/package-app-update.mjs

@@ -8,15 +8,30 @@ import { ZipArchive } from 'archiver'
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url))
 const webDirectory = path.resolve(scriptDirectory, '..')
 const distDirectory = path.join(webDirectory, 'dist')
-const packageJson = JSON.parse(
-  await readFile(path.join(webDirectory, 'package.json'), 'utf8'),
-)
 const versionIndex = process.argv.indexOf('--version')
-const version =
+const requestedVersion =
-  versionIndex >= 0 ? process.argv[versionIndex + 1] : packageJson.version
+  versionIndex >= 0 ? process.argv[versionIndex + 1] : undefined
+const versionProps = await readFile(path.join(webDirectory, '..', 'versions.props'), 'utf8')
+const version = /<JiaowuFrontendVersion>([^<]+)<\/JiaowuFrontendVersion>/.exec(
+  versionProps,
+ )?.[1]?.trim()
 
-if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(version ?? '')) {
+if (!version) {
-  throw new Error('请使用 --version 1.0.1 指定语义版本。')
+  throw new Error('versions.props 中缺少 JiaowuFrontendVersion。')
+}
+
+if (versionIndex >= 0 && !requestedVersion) {
+  throw new Error('请在 --version 后提供版本号。')
+}
+
+if (requestedVersion && requestedVersion !== version) {
+  throw new Error(
+    `更新包版本必须与 JiaowuFrontendVersion 一致（当前为 ${version}）。`,
+  )
+}
+
+if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(version)) {
+  throw new Error('JiaowuFrontendVersion 必须使用语义版本，例如 1.0.1。')
 }
 
 await stat(path.join(distDirectory, 'index.html')).catch(() => {