# 性能优化快速应用指南

## 📋 优化文件清单

已创建以下优化文件：

1. ✅ `lib/main_optimized.dart` - 启动优化
2. ✅ `lib/utils/image_decoder.dart` - 图片解码优化
3. ✅ `lib/utils/memory_monitor.dart` - 内存监控
4. ✅ `lib/play/board_play_optimized.dart` - 游戏页面优化
5. ✅ `lib/models/download_optimized.dart` - 下载管理优化
6. ✅ `PERFORMANCE_OPTIMIZATION_REPORT.md` - 完整优化报告
7. ✅ `MEMORY_OPTIMIZATION_GUIDE.md` - 内存优化指南

---

## 🚀 第一阶段：快速修复（2-4小时）

### 步骤 1: 应用启动优化 (1小时)

**目标**: 解决 Slow cold start rate 34.33%

**操作**:
```bash
# 1. 备份原文件
cp lib/main.dart lib/main_backup.dart

# 2. 应用优化
# 将 lib/main_optimized.dart 的内容复制到 lib/main.dart
```

**关键改动**:
- ✅ 移除 `main()` 函数中的 `await`
- ✅ 异步初始化 Firebase 和 Persistence
- ✅ 添加加载界面和错误处理

**验证**:
```dart
// 在 main.dart 中添加性能监控
void main() {
  final stopwatch = Stopwatch()..start();
  
  runApp(MyApp());
  
  print('App started in ${stopwatch.elapsedMilliseconds}ms');
}
```

---

### 步骤 2: 图片解码优化 (1.5小时)

**目标**: 解决 ANR rate 1.52%

**操作**:
```dart
// 1. 确保 image_decoder.dart 已存在（已创建）

// 2. 在 board_play.dart 中导入
import 'package:puzzleweave/utils/image_decoder.dart';

// 3. 替换 _init() 方法中的图片解码代码
// 找到这段代码:
ui.Image image = await itemLoader.getImageBySize(...);
final ByteData cardData = await rootBundle.load(...);
final ui.Codec cardCodec = await ui.instantiateImageCodec(...);

// 替换为:
final imageBytes = await itemLoader.ensureDataLoaded();
final cardData = await rootBundle.load(...);

final images = await ImageDecoder.decodeImages(
  bytesList: [imageBytes, cardData.buffer.asUint8List()],
  targetWidths: [bestImageSize.width.round(), bestCardImageSize.width.round()],
  targetHeights: [bestImageSize.height.round(), bestCardImageSize.height.round()],
);

final image = images[0];
final cardImage = images[1];
```

**验证**:
```dart
// 添加日志查看解码时间
final stopwatch = Stopwatch()..start();
final images = await ImageDecoder.decodeImages(...);
_log.info('Image decode took ${stopwatch.elapsedMilliseconds}ms');
```

---

### 步骤 3: 内存清理优化 (1.5小时)

**目标**: 解决 Crash rate 2.96% 和 LMK rate 0.84%

**操作**:

**3.1 在 board_play.dart 中添加资源清理**:
```dart
class _BoardPlayState extends State<BoardPlay> {
  Timer? _resourceCleanupTimer;
  
  // 添加这个方法
  void _cleanupBoardResources() {
    if (board != null) {
      _log.info('Cleaning up board resources');
      board!.dispose();
      board = null;
    }
  }
  
  // 修改 _onSuccess() 方法
  void _onSuccess() {
    // ... 现有代码
    
    // ✅ 添加这行
    _scheduleResourceCleanup();
  }
  
  // 添加这个方法
  void _scheduleResourceCleanup() {
    _resourceCleanupTimer?.cancel();
    _resourceCleanupTimer = Timer(Duration(seconds: 2), () {
      if (mounted) {
        _cleanupBoardResources();
      }
    });
  }
  
  // 修改 dispose() 方法
  @override
  void dispose() {
    // ✅ 在最前面添加
    _resourceCleanupTimer?.cancel();
    
    // ✅ 在最后添加
    _cleanupBoardResources();
    
    super.dispose();
  }
}
```

**3.2 在 data.dart 中增强缓存清理**:
```dart
void workDone(ListItem item, {Duration? timeSpent}) {
  // ... 现有代码
  
  _clearCompletedItemCache(item);
  
  // ✅ 添加内存清理
  _clearDownloadItemFromMemory(item);
}

// ✅ 添加这个方法
void _clearDownloadItemFromMemory(ListItem item) {
  if (item is RemoteItem) {
    try {
      final url = ApiHelper.imageUri(item.id, 'high');
      final downloadItem = Download()._cache[url];
      if (downloadItem != null) {
        _log.info('Clearing download item from memory: ${item.id}');
        downloadItem.data = null; // 清空数据
        Download()._cache.remove(url);
      }
    } catch (e) {
      _log.warning('Failed to clear download item: $e');
    }
  }
}
```

---

## 🎯 第二阶段：深度优化（4-6小时）

### 步骤 4: 启用内存监控 (1小时)

**操作**:
```dart
// 1. 在 main.dart 的 _MyAppState 中添加
@override
void initState() {
  super.initState();
  _initializeAsync();
  
  // ✅ 启动内存监控
  MemoryMonitor().startMonitoring(
    interval: Duration(seconds: 30),
    onHighMemory: () {
      _log.warning('High memory detected');
    },
    onCriticalMemory: () {
      _log.severe('Critical memory, forcing cleanup');
    },
  );
}
```

---

### 步骤 5: 应用下载优化 (2小时)

**操作**:
参考 `lib/models/download_optimized.dart`，将优化应用到 `lib/models/download.dart`

**关键改动**:
1. 添加 `_lastAccessTime` 和 `_cleanupTimer`
2. 添加 `clearData()` 方法
3. 添加 `_scheduleCleanup()` 方法
4. 修改 `ensureDataLoaded()` 方法

---

### 步骤 6: 优化 Board 资源管理 (1小时)

**操作**:
```dart
// 在 board.dart 的 dispose() 方法中
dispose() {
  if (_isDisposed) return;
  _isDisposed = true;
  
  _log.info('Disposing board resources');
  
  // ✅ 按内存占用大小顺序释放
  try {
    image.dispose();
    _log.info('Image disposed');
  } catch (e) {
    _log.warning('Failed to dispose image: $e');
  }
  
  try {
    backgroundPicture?.dispose();
    backgroundPicture = null;
  } catch (e) {
    _log.warning('Failed to dispose background picture: $e');
  }
  
  try {
    cardPicture?.dispose();
    cardPicture = null;
  } catch (e) {
    _log.warning('Failed to dispose card picture: $e');
  }
  
  // 清空 pieces
  for (var piece in pieces) {
    piece.path = null;
    piece.outLinePath = null;
    piece.innerLinePath = null;
    piece.group = null;
  }
  pieces.clear();
  backupGroups.clear();
  
  boardNotifier.dispose();
}
```

---

## ✅ 验证清单

完成优化后，请验证以下指标：

### 性能指标
- [ ] 冷启动时间 < 2秒 (中端设备)
- [ ] 进入游戏页面 < 500ms
- [ ] 拖动碎片流畅 (60fps)
- [ ] 连续玩10关后内存 < 150MB

### 测试步骤
```dart
// 1. 添加性能日志
class _BoardPlayState {
  @override
  void initState() {
    super.initState();
    MemoryMonitor.logMemoryUsage('BoardPlay init');
  }
  
  @override
  void dispose() {
    MemoryMonitor.logMemoryUsage('BoardPlay dispose (before)');
    _cleanupBoardResources();
    MemoryMonitor.logMemoryUsage('BoardPlay dispose (after)');
    super.dispose();
  }
}

// 2. 运行测试
// - 启动应用，记录启动时间
// - 进入游戏，记录加载时间
// - 完成10关，记录内存变化
// - 检查日志中的内存数据
```

### 日志示例
```
优化前:
[BoardPlay init] Memory: 120.5 MB
[Level complete] Memory: 145.2 MB
[BoardPlay dispose (before)] Memory: 145.0 MB
[BoardPlay dispose (after)] Memory: 144.2 MB  ❌ 只释放了 0.8MB

优化后:
[BoardPlay init] Memory: 120.5 MB
[Level complete] Memory: 145.2 MB
[BoardPlay dispose (before)] Memory: 125.5 MB
[BoardPlay dispose (after)] Memory: 105.8 MB  ✅ 释放了 19.7MB
```

---

## 📊 预期效果

| 指标 | 优化前 | 优化后 | 改善 |
|------|--------|--------|------|
| Crash rate | 2.96% | <1.0% | **-66%** |
| ANR rate | 1.52% | <0.3% | **-80%** |
| LMK rate | 0.84% | <0.2% | **-76%** |
| Slow cold start | 34.33% | <12% | **-65%** |
| 内存占用 | 150MB+ | <100MB | **-33%** |

---

## 🐛 常见问题

### Q1: 编译错误 "Undefined name 'Platform'"
**A**: 添加导入 `import 'dart:io';`

### Q2: 编译错误 "Undefined name 'ImageDecoder'"
**A**: 确保 `lib/utils/image_decoder.dart` 文件存在并正确导入

### Q3: 内存监控不工作
**A**: 确保在 Android/iOS 平台运行，Web 平台不支持

### Q4: 图片解码超时
**A**: 检查网络连接，或增加超时时间：
```dart
await ImageDecoder.decodeImages(
  // ...
  timeout: Duration(seconds: 60), // 增加超时
);
```

---

## 📞 需要帮助？

如果遇到问题，请提供：
1. 错误日志
2. 设备信息（Android/iOS版本，内存大小）
3. 复现步骤

---

## 🎉 完成！

完成所有步骤后，请：
1. 运行完整测试
2. 检查性能指标
3. 提交到测试环境
4. 收集用户反馈

预计优化后，Google Play 的性能指标将在 1-2 周内显著改善。