# App Upgrade Plugin - 完整使用指南

## 🚀 快速开始

### 基础用法（一行代码）
```dart
import 'package:app_upgrade_plugin/app_upgrade_plugin.dart';

// 最简单的使用方式
await AppUpgradeSimple.instance.checkUpdate(
  context: context,
  url: 'https://api.example.com/check-update',
);
```

## ⚙️ 配置选项

### 预设配置
```dart
// 开发模式（详细日志+提示信息）
AppUpgradeSimple.instance.configure(UpgradeConfig.development);

// 生产模式（静默检查+性能优化）
AppUpgradeSimple.instance.configure(UpgradeConfig.production);
```

### 自定义配置
```dart
AppUpgradeSimple.instance.configure(UpgradeConfig(
  showNoUpdateToast: true,        // 显示无更新提示
  autoInstall: false,             // 自动安装
  installTimeout: 45,             // 安装检测超时（秒）
  enableDebugLog: true,           // 启用调试日志
  customToast: (message) {        // 自定义Toast
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  },
));
```

## 🎯 使用场景

### 1. 应用启动时检查更新
```dart
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Builder(
        builder: (context) {
          // 应用启动后检查更新
          WidgetsBinding.instance.addPostFrameCallback((_) {
            AppUpgradeSimple.instance.checkUpdate(
              context: context,
              url: 'https://api.example.com/check-update',
            );
          });
          return MyHomePage();
        },
      ),
    );
  }
}
```

### 2. 定期检查更新
```dart
class MyHomePage extends StatefulWidget {
  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  Timer? _updateTimer;

  @override
  void initState() {
    super.initState();
    // 每24小时检查一次更新
    _updateTimer = Timer.periodic(const Duration(hours: 24), (_) {
      AppUpgradeSimple.instance.checkUpdateSilent(
        url: 'https://api.example.com/check-update',
      );
    });
  }

  @override
  void dispose() {
    _updateTimer?.cancel();
    super.dispose();
  }
}
```

### 3. 手动检查更新
```dart
ElevatedButton(
  onPressed: () async {
    await AppUpgradeSimple.instance.checkUpdate(
      context: context,
      url: 'https://api.example.com/check-update',
      params: {
        'userId': currentUserId,
        'channel': releaseChannel,
      },
      onComplete: () {
        print('更新检查完成');
      },
    );
  },
  child: const Text('检查更新'),
)
```

## 🔧 高级功能

### 预下载APK
```dart
// 后台预下载，不显示UI
final filePath = await AppUpgradeSimple.instance.preDownloadApk(
  url: 'https://example.com/app.apk',
  onProgress: (progress) {
    print('下载进度: ${progress.percentage}%');
  },
);
```

### 查找已下载的APK
```dart
final existingApk = await AppUpgradeSimple.instance.findDownloadedApk('1.2.0');
if (existingApk != null) {
  print('找到已下载的APK: $existingApk');
}
```

### 网络状态检查
```dart
final hasNetwork = await AppUpgradeSimple.instance.checkNetworkStatus();
if (!hasNetwork) {
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: const Text('网络错误'),
      content: const Text('请检查网络连接'),
      actions: [
        TextButton(
          onPressed: () => Navigator.of(context).pop(),
          child: const Text('确定'),
        ),
      ],
    ),
  );
}
```

### 清理下载缓存
```dart
// 清理所有下载的APK文件
await AppUpgradeSimple.instance.clearDownloadCache();
```

## 🎨 UI定制

### 自定义Toast
```dart
AppUpgradeSimple.instance.configure(UpgradeConfig(
  customToast: (message) {
    // 使用SnackBar代替Toast
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        backgroundColor: Colors.deepPurple,
        behavior: SnackBarBehavior.floating,
      ),
    );
  },
));
```

### 富文本更新内容
服务器返回的更新内容支持简单的富文本格式：
```
**新功能**
- 添加了[暗黑模式]支持
- 优化了`网络请求`性能
- __修复了已知问题__

**重要更新**
请及时更新到最新版本以获得更好的体验！
```

## 📱 平台支持

### Android
- ✅ APK下载和安装
- ✅ 权限自动处理
- ✅ 多应用商店支持
- ✅ 安装状态智能检测
- ✅ 断点续传
- ✅ 文件校验

### iOS
- ✅ App Store跳转
- ✅ 企业证书分发
- ✅ TestFlight支持

## 🔍 调试和测试

### 启用调试日志
```dart
AppUpgradeSimple.instance.configure(UpgradeConfig.development);
```

### 查看日志输出
```
🔍 检查更新结果: UpgradeInfo(...)
⚡ 应用回到前台，立即检查安装状态
✅ 检测结果: 安装成功
❌ 检测结果: 安装未完成
```

### 测试不同场景
插件内置了测试按钮，可以模拟各种安装场景：
- 模拟安装取消
- 模拟权限拒绝
- 模拟安装超时

## 🛡️ 错误处理

插件提供了完善的错误处理机制：

### 网络错误
- 连接超时
- DNS解析失败
- 服务器错误
- 证书验证失败

### 安装错误
- 权限被拒绝
- APK文件损坏
- 存储空间不足
- 系统版本不兼容

### 自动重试
- 智能检测安装状态
- 多种重试方式
- 用户友好的错误提示

## 📊 最佳实践

### 1. 应用启动检查
```dart
// 推荐：应用启动时静默检查
WidgetsBinding.instance.addPostFrameCallback((_) {
  AppUpgradeSimple.instance.checkUpdateSilent(
    url: 'https://api.example.com/check-update',
  ).then((info) {
    if (info != null && info.hasUpdate) {
      // 发现更新，显示提示
      showUpdateNotification(context, info);
    }
  });
});
```

### 2. 定期检查
```dart
// 推荐：每日检查一次
Timer.periodic(const Duration(days: 1), (_) {
  AppUpgradeSimple.instance.checkUpdateSilent(
    url: 'https://api.example.com/check-update',
  );
});
```

### 3. 用户手动检查
```dart
// 推荐：提供手动检查按钮
ElevatedButton(
  onPressed: () {
    AppUpgradeSimple.instance.checkUpdate(
      context: context,
      url: 'https://api.example.com/check-update',
    );
  },
  child: const Text('检查更新'),
)
```

## 🎯 完整示例

查看 `example/lib/main_enhanced.dart` 获取完整的使用示例，包含所有功能的演示。

## 📝 API文档

### 主要方法

#### `checkUpdate()`
检查并处理应用更新的主要方法。

#### `checkUpdateSilent()`
静默检查更新，不显示UI。

#### `preDownloadApk()`
后台预下载APK文件。

#### `clearDownloadCache()`
清理下载缓存。

#### `checkNetworkStatus()`
检查网络连接状态。

### 配置类

#### `UpgradeConfig`
升级配置类，控制插件的行为。

#### 预设配置
- `UpgradeConfig.development` - 开发模式（详细日志+提示信息）
- `UpgradeConfig.production` - 生产模式（静默检查+性能优化）

---

这个插件现在提供了完整的应用升级解决方案，支持各种使用场景和自定义需求！