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

## 📁 文件结构

```
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年  
**维护者**: 游戏开发团队