# 报恩榴莲 - 微信小游戏适配指南

## 🎯 快速开始

### 1. 构建微信小游戏包

```bash
# Windows PowerShell（推荐）
.\build-wechat.ps1 -Version "1.0.0"

# 或者使用批处理
build-wechat.bat
```

构建完成后，输出目录：`build/wechatgame/`

### 2. 真机测试

1. 打开微信开发者工具
2. 导入项目：选择 `build/wechatgame` 目录
3. AppID：`wxb2b7651c561f9d53`
4. 点击「预览」生成二维码
5. 用手机微信扫码测试

---

## 📁 文件说明

### 核心代码
- `js/main.js` - 微信小游戏入口文件（已适配微信环境）
- `cocos-prototype/assets/scripts/core/AdManager.ts` - 广告管理器
- `cocos-prototype/assets/scripts/core/AudioManager.ts` - 音频管理器
- `cocos-prototype/assets/scripts/core/SaveManager.ts` - 存档管理器

### 配置文件
- `wechat-config.js` - 微信性能配置和分包策略

### 构建脚本
- `build-wechat.ps1` - PowerShell 构建脚本（推荐）
- `build-wechat.bat` - Batch 构建脚本

### 文档
- `WECHAT_ADAPTATION_SUMMARY.md` - ⭐ **必读**：适配完成总结
- `WECHAT_OPTIMIZATION_GUIDE.md` - 性能优化指南
- `WECHAT_DEPLOYMENT_GUIDE.md` - 部署和提审指南
- `WECHAT_QUICK_REFERENCE.md` - 快速参考卡

---

## ✅ 已完成适配

### 1. 微信环境初始化
- ✅ 帧率设置（60 FPS）
- ✅ 音频中断处理
- ✅ 加载进度显示
- ✅ 性能监控

### 2. 广告系统
- ✅ 激励视频广告（复活、道具）
- ✅ 插屏广告（关卡结束）
- ✅ 广告频控（每日最多18次）
- ✅ 预加载机制

### 3. 音频系统
- ✅ 来电/通知自动暂停
- ✅ 中断结束后自动恢复
- ✅ 内存管理优化

### 4. 存档系统
- ✅ 微信存储 API 优先
- ✅ 双备份机制
- ✅ 自动保存（每30秒）
- ✅ 数据导入/导出

### 5. 性能优化
- ✅ 对象池管理
- ✅ GC 主动触发
- ✅ 内存监控
- ✅ 分包加载支持

---

## 🚀 下一步操作

### 立即执行（必须）

#### 1. 替换广告位 ID

编辑文件：`cocos-prototype/assets/scripts/core/AdManager.ts`

```typescript
// 第 23-29 行，替换为你的真实广告位 ID
private static readonly AD_UNIT_ID_REVIVE = 'adunit-你的复活广告ID';
private static readonly AD_UNIT_ID_REMOVE_FRUIT = 'adunit-你的道具广告ID';
private static readonly AD_UNIT_ID_INTERSTITIAL = 'adunit-你的插屏广告ID';
```

**获取广告位 ID**：
1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 左侧菜单：推广 → 流量主
3. 创建广告位（激励视频 + 插屏）
4. 复制广告位 ID

#### 2. 重新构建

```bash
.\build-wechat.ps1 -Version "1.0.0"
```

#### 3. 真机测试

重点测试：
- [ ] 广告能否正常展示
- [ ] 观看完成后是否发放奖励
- [ ] 音频中断后是否恢复
- [ ] 存档是否正常保存和加载

---

## 📊 关键指标要求

| 指标 | 目标值 | 检查方法 |
|------|--------|----------|
| 启动时间 | < 3秒 | 真机计时 |
| FPS | 60 | Performance 面板 |
| 内存占用 | < 200MB | wx.getSystemInfoSync() |
| 主包大小 | ≤ 20MB | 查看 build 目录 |
| 崩溃率 | < 1% | 微信后台数据 |

---

## 🐛 常见问题

### Q1: 广告不显示？
**原因**：
- 模拟器测试（广告只在真机显示）
- 广告位 ID 未替换
- 网络问题

**解决**：
1. 必须真机测试
2. 确认广告位 ID 已替换
3. 检查网络连接

### Q2: 启动慢？
**解决**：
- 压缩图片和音频
- 使用分包加载
- 延迟加载非核心资源

### Q3: 内存泄漏？
**解决**：
```typescript
// 场景切换时清理
onDestroy() {
    this.node.removeAllChildren();
    resources.releaseAll();
    if (wx.triggerGC) wx.triggerGC();
}
```

### Q4: 音频中断后不恢复？
**检查**：
确保 `AudioManager.ts` 中有以下代码：
```typescript
wx.onAudioInterruptionEnd(() => {
    this._onAudioInterruptEnd();
});
```

---

## 📖 详细文档

### 推荐阅读顺序

1. **WECHAT_ADAPTATION_SUMMARY.md** - 了解整体适配情况
2. **WECHAT_QUICK_REFERENCE.md** - 查阅具体 API 用法
3. **WECHAT_OPTIMIZATION_GUIDE.md** - 深入性能优化
4. **WECHAT_DEPLOYMENT_GUIDE.md** - 准备提审发布

---

## 🔧 开发工具

### 必备工具
- **Cocos Creator 3.8** - 游戏引擎
- **微信开发者工具** - 调试和上传
- **TinyPNG** - 图片压缩（https://tinypng.com/）
- **Audacity** - 音频编辑（可选）

### 可选工具
- **VS Code** - 代码编辑
- **微信云开发** - 云端存档（高级功能）

---

## 📞 技术支持

### 官方文档
- [微信小游戏开发文档](https://developers.weixin.qq.com/minigame/dev/guide/)
- [Cocos Creator 3.8 文档](https://docs.cocos.com/creator/3.8/manual/zh/)
- [微信广告接入指南](https://developers.weixin.qq.com/minigame/dev/ad/)

### 社区
- [Cocos 论坛](https://forum.cocos.org/)
- [微信开放社区](https://developers.weixin.qq.com/community/)

---

## 🎯 上线流程

```
开发完成 
   ↓
本地测试（模拟器）
   ↓
真机测试（iOS + Android）
   ↓
性能优化
   ↓
替换广告位 ID
   ↓
构建最终包
   ↓
上传到微信后台
   ↓
提交审核（1-3个工作日）
   ↓
审核通过 → 全量发布
   ↓
数据监控 + 持续迭代
```

---

## ✨ 项目亮点

### 1. 差异化玩法
- 三三合成（非传统三消）
- 连锁反应机制
- 连击系统

### 2. 情感 IP
- 报恩榴莲拟人化
- Boss 投喂互动
- 图鉴收集

### 3. 名场面营销
- 「金色传说」史诗特效
- 适合短视频传播
- 社交货币属性

### 4. 技术优化
- 完善的微信 API 适配
- 智能的资源管理
- 全面的性能监控

---

## 📈 预期效果

### 性能表现
- 启动时间：< 3秒
- 稳定帧率：60 FPS
- 内存占用：< 200MB
- 包体大小：< 20MB

### 商业表现（预估）
- 次日留存：> 30%
- 广告完成率：> 60%
- eCPM：> ¥50
- ARPU：> ¥0.5

---

## ⚠️ 注意事项

### 必须遵守
1. **不能永久删除用户文件** - 只能移动到回收站
2. **广告频控** - 每日最多18次，间隔60秒
3. **隐私政策** - 如需收集用户数据，必须提供隐私政策
4. **内容审核** - 不得有违规内容

### 建议遵守
1. 移除所有 `console.log`（生产环境）
2. 压缩所有资源文件
3. 定期备份存档数据
4. 监控崩溃率（目标 < 1%）

---

## 🎉 结语

《报恩榴莲》微信小游戏适配工作已全部完成！

**当前状态**：✅ 具备上线条件

**待完成**：
- [ ] 替换广告位 ID
- [ ] 真机测试验证
- [ ] 准备提审材料
- [ ] 提交微信审核

祝游戏上线顺利，大获成功！🚀🍈✨

---

**最后更新**: 2026-08-14  
**版本**: v1.0.0  
**平台**: 微信小游戏  
**引擎**: Cocos Creator 3.8