# 应用版本更新使用示例

## 功能说明

`useAppUpdate` 提供了完整的应用版本检查和更新功能，支持：

- ✅ 自动获取当前应用版本（原生/Web）
- ✅ 从后端 API 检查最新版本
- ✅ 版本号比较（语义化版本）
- ✅ 强制更新和可选更新
- ✅ 打开应用商店更新页面
- ✅ 国际化支持（中英文）
- ✅ Service Worker 更新（PWA）

## 基础使用

### 1. 在应用启动时检查更新

在 `App.vue` 或主布局组件中：

```vue
<script setup lang="ts">
import { onMounted } from "vue";

const { checkAndPromptUpdate } = useAppUpdate();

onMounted(async () => {
  // 应用启动 3 秒后检查更新
  setTimeout(() => {
    checkAndPromptUpdate();
  }, 3000);
});
</script>
```

### 2. 手动触发检查更新

在设置页面添加"检查更新"按钮：

```vue
<script setup lang="ts">
const {
  isChecking,
  currentVersion,
  checkAndPromptUpdate,
} = useAppUpdate();

async function handleCheckUpdate() {
  await checkAndPromptUpdate();
}
</script>

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>系统设置</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content>
      <ion-list>
        <ion-item button @click="handleCheckUpdate">
          <ion-label>
            <h2>检查更新</h2>
            <p>当前版本: {{ currentVersion }}</p>
          </ion-label>
          <ion-spinner v-if="isChecking" slot="end" />
        </ion-item>
      </ion-list>
    </ion-content>
  </ion-page>
</template>
```

### 3. 自定义更新提示

如果不想使用默认对话框，可以自己处理：

```vue
<script setup lang="ts">
const {
  hasUpdate,
  latestVersion,
  forceUpdate,
  updateMessage,
  checkForUpdate,
  openStoreUpdate,
} = useAppUpdate();

async function checkUpdate() {
  const result = await checkForUpdate();

  if (result.hasUpdate) {
    // 自定义提示逻辑
    if (result.forceUpdate) {
      // 强制更新 - 阻止用户继续使用
      showForceUpdateModal();
    }
    else {
      // 可选更新 - 显示提示但允许跳过
      showOptionalUpdateToast();
    }
  }
}
</script>
```

### 4. 显示版本信息

```vue
<script setup lang="ts">
import { onMounted } from "vue";

const { currentVersion, hasUpdate, getCurrentVersion, checkForUpdate } = useAppUpdate();

onMounted(async () => {
  await getCurrentVersion();
  await checkForUpdate();
});
</script>

<template>
  <ion-item>
    <ion-label>
      <h2>应用版本</h2>
      <p>{{ currentVersion || '获取中...' }}</p>
    </ion-label>
    <ion-badge v-if="hasUpdate" color="danger">
      有更新
    </ion-badge>
  </ion-item>
</template>
```

## API 参考

### 返回值

```typescript
{
  // 状态
  isChecking: Ref<boolean>          // 是否正在检查更新
  hasUpdate: Ref<boolean>            // 是否有新版本
  currentVersion: Ref<string>        // 当前版本号
  latestVersion: Ref<string>         // 最新版本号
  forceUpdate: Ref<boolean>          // 是否强制更新
  updateMessage: Ref<string>         // 更新提示信息
  updateUrl: Ref<string>             // 应用商店链接

  // 方法
  getCurrentVersion(): Promise<string>           // 获取当前版本
  checkForUpdate(): Promise<UpdateResult>        // 检查更新
  checkAndPromptUpdate(): Promise<void>          // 检查并显示提示
  showUpdateDialog(): Promise<void>              // 显示更新对话框
  openStoreUpdate(): Promise<void>               // 打开应用商店
  applyUpdate(): Promise<void>                   // 应用更新
  forceReload(): Promise<void>                   // 强制刷新
}
```

### checkForUpdate 返回类型

```typescript
{
  hasUpdate: boolean              // 是否有更新
  currentVersion: string          // 当前版本
  latestVersion?: string          // 最新版本
  forceUpdate?: boolean           // 是否强制更新
  updateMessage?: string          // 更新说明
  updateUrl?: string              // 更新链接
}
```

## 后端 API 接口

需要后端实现以下接口：

```typescript
// GET /api/app/version
// Query Parameters:
{
  platform: 'ios' | 'android' | 'web'  // 平台类型
  currentVersion: string                // 当前版本号
}

// Response:
{
  version: string                       // 最新版本号
  buildNumber?: number                  // 构建号
  forceUpdate: boolean                  // 是否强制更新
  updateMessage?: string                // 更新说明（多语言）
  updateUrl?: string                    // 下载链接
  minSupportVersion?: string            // 最低支持版本
  releaseDate?: string                  // 发布时间
  releaseNotes?: string[]               // 更新日志
}
```

## 环境变量配置

在 `.env` 文件中添加：

```bash
# 应用版本（可选，如果不设置会从 Capacitor 读取）
VITE_APP_VERSION=1.0.0
```

## 版本号规范

遵循语义化版本规范（Semantic Versioning）：

- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

示例：`1.2.3`

## 注意事项

1. **原生应用更新**：iOS 和 Android 原生应用必须通过应用商店更新，不能绕过
2. **强制更新策略**：谨慎使用强制更新，避免影响用户体验
3. **版本检查频率**：建议应用启动时检查，避免频繁请求
4. **降级处理**：如果后端接口失败，应用仍能正常使用
5. **测试环境**：开发阶段接口返回模拟数据，生产环境需替换为真实 API

## 国际化文本

已添加的翻译键：

```json
{
  "app.update.title": "发现新版本 / New Version Available",
  "app.update.message": "有新版本可用... / A new version is available...",
  "app.update.now": "立即更新 / Update Now",
  "app.update.later": "稍后再说 / Later",
  "app.update.forceUpdate": "发现新版本，需要更新后才能继续使用"
}
```

## 生产环境配置

1. **替换模拟数据**：在 [useAppUpdate.ts](../composables/useAppUpdate.ts#L80-L100) 中取消注释真实 API 调用
2. **配置应用商店链接**：后端返回正确的 App Store / Google Play 链接
3. **设置最低支持版本**：根据实际情况配置 `minSupportVersion`