云环境和本地调试添加

2025-08-18 17:00:40 +08:00
parent addc61e2a9
commit a824d9a124
155 changed files with 6531 additions and 997 deletions
--- a/build-templates/wechatgame/cloud_functions/cocos_cloud/README.md
+++ b/build-templates/wechatgame/cloud_functions/cocos_cloud/README.md
@@ -0,0 +1,270 @@
+# 微信云函数游戏数据管理系统
+
+## 📁 文件结构
+
+```
+cocos_cloud/
+├── index.js           # 主云函数文件
+├── user_init_data.js  # 新用户初始化数据配置
+└── README.md          # 说明文档
+```
+
+## 🎮 功能特性
+
+### 1. 数据结构管理
+- **平级数据存储**: 所有游戏数据字段与用户基本信息平级存储
+- **版本控制**: 支持数据结构版本管理和自动升级
+- **数据验证**: 完整的数据结构和类型验证
+- **默认值管理**: 集中管理新用户初始化数据
+
+### 2. 支持的命令
+
+| 命令 | 功能 | 说明 |
+|------|------|------|
+| `login` | 用户登录 | 返回完整的用户和游戏数据 |
+| `load` | 加载游戏数据 | 获取用户的所有游戏数据 |
+| `save` | 保存游戏数据 | 支持增量更新，自动合并数据 |
+| `reset` | 重置游戏数据 | 恢复为默认初始值 |
+| `backup` | 创建数据备份 | 在独立集合中创建备份记录 |
+| `version` | 查看版本信息 | 检查数据版本兼容性 |
+| `upgrade` | 强制升级数据 | 手动触发数据结构升级 |
+
+## 📊 数据结构
+
+### 用户数据库结构 (cocos_users 集合)
+```javascript
+{
+  _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 集合)
+```javascript
+{
+  user_id: "用户ID",
+  openid: "微信OpenID",
+  data: { /* 基础游戏数据 */ },
+  fight_heros: { /* 出战英雄配置 */ },
+  heros: { /* 英雄属性数据 */ },
+  items: { /* 道具数据 */ },
+  tals: { /* 天赋数据 */ },
+  equips: { /* 装备数据 */ },
+  backup_time: "备份时间戳",
+  original_save_time: "原始保存时间"
+}
+```
+
+## 🚀 使用示例
+
+### 客户端调用示例
+
+#### 1. 用户登录
+```javascript
+wx.cloud.callFunction({
+  name: 'cocos_cloud',
+  data: { cmd: 'login' }
+}).then(res => {
+  console.log('登录成功:', res.result);
+  // res.result.data 包含完整的用户和游戏数据
+});
+```
+
+#### 2. 保存游戏数据
+```javascript
+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. 加载游戏数据
+```javascript
+wx.cloud.callFunction({
+  name: 'cocos_cloud',
+  data: { cmd: 'load' }
+}).then(res => {
+  const gameData = res.result.data;
+  console.log('游戏数据:', gameData);
+});
+```
+
+#### 4. 检查版本信息
+```javascript
+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. 创建数据备份
+```javascript
+wx.cloud.callFunction({
+  name: 'cocos_cloud',
+  data: { cmd: 'backup' }
+}).then(res => {
+  console.log('备份成功:', res.result.data.backup_id);
+});
+```
+
+## 🔧 配置管理
+
+### 修改默认数据
+编辑 `user_init_data.js` 文件中的常量：
+
+```javascript
+// 修改默认金币数量
+const DEFAULT_GAME_DATA = {
+  // ...
+  gold: 200,  // 从100改为200
+  // ...
+};
+
+// 添加新英雄
+const DEFAULT_HEROS = {
+  // 现有英雄...
+  5008: { uuid: 5008, lv: 1, exp: 0, star: 1, power: 110 }
+};
+```
+
+### 版本升级
+当数据结构发生变化时，更新版本号：
+
+```javascript
+// 在 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`: 系统错误
+
+### 日志记录
+- 新用户创建日志
+- 数据版本升级日志
+- 错误操作日志
+- 性能监控日志
+
+## 🔍 调试和监控
+
+### 查看用户数据版本
+```javascript
+wx.cloud.callFunction({
+  name: 'cocos_cloud',
+  data: { cmd: 'version' }
+});
+```
+
+### 强制升级用户数据
+```javascript
+wx.cloud.callFunction({
+  name: 'cocos_cloud',
+  data: { cmd: 'upgrade' }
+});
+```
+
+## 📝 注意事项
+
+1. **数据备份**: 重要操作前建议创建备份
+2. **版本兼容**: 升级数据结构时注意向后兼容性
+3. **性能优化**: 大量数据操作时注意性能影响
+4. **安全验证**: 所有输入数据都经过严格验证
+5. **错误处理**: 完善的错误处理和日志记录
+
+## 🚀 部署说明
+
+1. 将整个 `cocos_cloud` 文件夹上传到微信云开发
+2. 在微信开发者工具中部署云函数
+3. 确保数据库权限配置正确
+4. 测试各项功能是否正常工作
+
+---
+
+**版本**: 1.0.0  
+**更新时间**: 2024年  
+**维护者**: 游戏开发团队
+