heros/build-templates/wechatgame/cloud_functions/cocos_cloud/README.md

微信云函数游戏数据管理系统

📁 文件结构

cocos_cloud/
├── index.js           # 主云函数文件
├── user_init_data.js  # 新用户初始化数据配置
└── README.md          # 说明文档

🎮 功能特性

1. 数据结构管理

• 平级数据存储: 所有游戏数据字段与用户基本信息平级存储
• 版本控制: 支持数据结构版本管理和自动升级
• 数据验证: 完整的数据结构和类型验证
• 默认值管理: 集中管理新用户初始化数据

2. 支持的命令

命令	功能	说明
login	用户登录	返回完整的用户和游戏数据
load	加载游戏数据	获取用户的所有游戏数据
save	保存游戏数据	支持增量更新，自动合并数据
reset	重置游戏数据	恢复为默认初始值
backup	创建数据备份	在独立集合中创建备份记录
version	查看版本信息	检查数据版本兼容性
upgrade	强制升级数据	手动触发数据结构升级

📊 数据结构

用户数据库结构 (cocos_users 集合)

{
  _id: "用户ID",
  _openid: "微信OpenID", 
  regist_time: "注册时间戳",
  init_time: "初始化时间戳",
  last_save_time: "最后保存时间",
  data_version: "数据版本号",
  
  // 游戏数据字段（与基本信息平级）
  data: {
    score: 0,           // 游戏分数
    mission: 1,         // 当前关卡
    gold: 100,          // 金币
    diamond: 100,       // 钻石
    meat: 0,            // 肉类资源
    exp: 0,             // 升级经验
    ghstone: 0,         // 绿色英雄石
    bhstone: 0,         // 蓝色英雄石
    phlestone: 0,       // 紫色英雄石
    rhstone: 0,         // 红色英雄石
    herocard: 0,        // 英雄卡
    ckey: 0,            // 铜钥匙
    skey: 0,            // 银钥匙
    gkey: 0             // 金钥匙
  },
  fight_heros: {
    0: 5001,            // 出战位置1
    1: 5005,            // 出战位置2
    2: 0,               // 出战位置3（空）
    3: 0,               // 出战位置4（空）
    4: 0                // 出战位置5（空）
  },
  heros: {
    5001: { uuid: 5001, lv: 1, exp: 0, star: 1, power: 100 },
    5005: { uuid: 5005, lv: 1, exp: 0, star: 1, power: 120 },
    5007: { uuid: 5007, lv: 1, exp: 0, star: 1, power: 90 }
  },
  items: {
    1001: 0,            // 生命药水
    1002: 0,            // 魔法药水
    1003: 0,            // 力量药水
    // ... 更多道具
  },
  tals: {
    1001: 0,            // 攻击强化
    1002: 0,            // 防御强化
    1003: 0,            // 生命强化
    // ... 更多天赋
  },
  equips: {
    1001: 0,            // 武器
    1002: 0,            // 头盔
    1003: 0,            // 胸甲
    // ... 更多装备
  }
}

备份数据库结构 (game_backups 集合)

{
  user_id: "用户ID",
  openid: "微信OpenID",
  data: { /* 基础游戏数据 */ },
  fight_heros: { /* 出战英雄配置 */ },
  heros: { /* 英雄属性数据 */ },
  items: { /* 道具数据 */ },
  tals: { /* 天赋数据 */ },
  equips: { /* 装备数据 */ },
  backup_time: "备份时间戳",
  original_save_time: "原始保存时间"
}

🚀 使用示例

客户端调用示例

1. 用户登录

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'login' }
}).then(res => {
  console.log('登录成功:', res.result);
  // res.result.data 包含完整的用户和游戏数据
});

2. 保存游戏数据

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: {
    cmd: 'save',
    data: {
      data: { gold: 1000, diamond: 50 },
      fight_heros: { 0: 5001, 1: 5005 },
      heros: { 5001: { lv: 10, exp: 100 } },
      items: { 1001: 5 }
    }
  }
});

3. 加载游戏数据

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'load' }
}).then(res => {
  const gameData = res.result.data;
  console.log('游戏数据:', gameData);
});

4. 检查版本信息

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'version' }
}).then(res => {
  console.log('版本信息:', res.result.data);
  if (res.result.data.compatibility.needsUpgrade) {
    console.log('需要升级数据');
  }
});

5. 创建数据备份

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'backup' }
}).then(res => {
  console.log('备份成功:', res.result.data.backup_id);
});

🔧 配置管理

修改默认数据

编辑 user_init_data.js 文件中的常量：

// 修改默认金币数量
const DEFAULT_GAME_DATA = {
  // ...
  gold: 200,  // 从100改为200
  // ...
};

// 添加新英雄
const DEFAULT_HEROS = {
  // 现有英雄...
  5008: { uuid: 5008, lv: 1, exp: 0, star: 1, power: 110 }
};

版本升级

当数据结构发生变化时，更新版本号：

// 在 user_init_data.js 中
const DATA_VERSION = "1.1.0";  // 从1.0.0升级到1.1.0

📈 版本控制

版本号格式

• MAJOR.MINOR.PATCH (如: 1.2.3)
• MAJOR: 重大结构变更，不向后兼容
• MINOR: 新增字段，向后兼容
• PATCH: 数值调整，完全兼容

自动升级机制

• 用户登录时自动检查版本兼容性
• 如需升级，自动合并新的默认数据
• 保留用户的现有数据，只补充缺失字段

🛡️ 错误处理

错误码说明

• 200: 成功
• -1: 操作失败
• -2: 未知命令
• -3: 数据结构无效
• -4: 用户创建/获取失败
• -5: 系统错误

日志记录

• 新用户创建日志
• 数据版本升级日志
• 错误操作日志
• 性能监控日志

🔍 调试和监控

查看用户数据版本

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'version' }
});

强制升级用户数据

wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'upgrade' }
});

📝 注意事项

1. 数据备份: 重要操作前建议创建备份
2. 版本兼容: 升级数据结构时注意向后兼容性
3. 性能优化: 大量数据操作时注意性能影响
4. 安全验证: 所有输入数据都经过严格验证
5. 错误处理: 完善的错误处理和日志记录

🚀 部署说明

1. 将整个 cocos_cloud 文件夹上传到微信云开发
2. 在微信开发者工具中部署云函数
3. 确保数据库权限配置正确
4. 测试各项功能是否正常工作

---

版本: 1.0.0
更新时间: 2024年
维护者: 游戏开发团队