# 游戏云函数 API 文档

## 📋 概述

本文档详细说明了游戏云函数的所有可用接口，包括认证、数据管理、英雄系统、库存管理等功能。

## 🏗️ 项目结构

```
cocos_cloud/
├── index.js              # 路由入口文件
├── user_init_data.js     # 用户初始化数据配置
├── modules/              # 功能模块目录
│   ├── auth.js           # 认证模块
│   ├── gameData.js       # 基础游戏数据模块
│   ├── fightHeros.js     # 出战英雄模块
│   ├── heros.js          # 英雄管理模块
│   ├── inventory.js      # 库存管理模块
│   └── response.js       # 响应处理模块
├── README.md             # 项目说明文档
└── API.md               # API接口文档
```

## 🚀 通用调用格式

```javascript
wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: {
    cmd: '命令名',
    // 其他参数...
  }
}).then(res => {
  console.log('调用结果:', res.result);
}).catch(err => {
  console.error('调用失败:', err);
});
```

## 📊 通用响应格式

```javascript
{
  code: 200,                    // 状态码 (200=成功, 负数=错误)
  msg: "Success",              // 响应消息
  data: { /* 返回数据 */ },     // 具体数据
  timestamp: 1234567890,       // 时间戳
  version: "1.0.0",           // 数据版本
  execution_time: 50          // 执行时间(ms)
}
```

## 🔐 认证相关接口

### 1. 用户登录
获取用户完整信息和游戏数据。

```javascript
// 请求
{ cmd: 'login' }

// 响应
{
  code: 200,
  data: {
    user_id: "用户ID",
    openid: "微信OpenID",
    regist_time: 1234567890,
    data: { /* 基础游戏数据 */ },
    fight_heros: { /* 出战英雄配置 */ },
    heros: { /* 英雄属性数据 */ },
    items: { /* 道具数据 */ },
    tals: { /* 天赋数据 */ },
    equips: { /* 装备数据 */ },
    data_version: "1.0.0",
    last_save_time: 1234567890
  }
}
```

### 2. 获取用户信息
获取用户基本信息（不包含游戏数据）。

```javascript
// 请求
{ cmd: 'user_info' }

// 响应
{
  code: 200,
  data: {
    user_id: "用户ID",
    openid: "微信OpenID",
    regist_time: 1234567890,
    init_time: 1234567890,
    data_version: "1.0.0",
    last_save_time: 1234567890
  }
}
```

### 3. 检查版本信息
检查用户数据版本兼容性。

```javascript
// 请求
{ cmd: 'version' }

// 响应
{
  code: 200,
  data: {
    user_version: "1.0.0",
    current_version: "1.1.0",
    compatibility: {
      compatible: true,
      needsUpgrade: true,
      message: "Minor version update available"
    },
    init_time: 1234567890,
    regist_time: 1234567890,
    last_save_time: 1234567890
  }
}
```

### 4. 强制升级数据
手动触发用户数据结构升级。

```javascript
// 请求
{ cmd: 'upgrade' }

// 响应
{
  code: 200,
  data: {
    old_version: "1.0.0",
    new_version: "1.1.0",
    upgrade_time: 1234567890,
    // ... 升级后的完整数据
  }
}
```

## 🎮 基础游戏数据接口

### 1. 获取游戏数据
获取用户的基础游戏数据（金币、钻石、经验等）。

```javascript
// 请求
{ cmd: 'data_get' }

// 响应
{
  code: 200,
  data: {
    score: 0,
    mission: 1,
    gold: 100,
    diamond: 100,
    meat: 0,
    exp: 0,
    // ... 更多字段
  }
}
```

### 2. 更新游戏数据
批量更新基础游戏数据。

```javascript
// 请求
{
  cmd: 'data_update',
  data: {
    gold: 1000,
    diamond: 200,
    exp: 500
  },
  merge: true  // 可选，默认true（合并更新）
}

// 响应
{
  code: 200,
  data: {
    // 更新后的完整数据
  }
}
```

### 3. 增加指定字段
增加某个字段的数值。

```javascript
// 请求
{
  cmd: 'data_add',
  field: 'gold',
  amount: 100
}

// 响应
{
  code: 200,
  data: {
    field: 'gold',
    old_value: 1000,
    new_value: 1100,
    change: 100
  }
}
```

### 4. 消耗指定字段
消耗某个字段的数值（会检查是否足够）。

```javascript
// 请求
{
  cmd: 'data_spend',
  field: 'gold',
  amount: 50
}

// 响应
{
  code: 200,
  data: {
    field: 'gold',
    old_value: 1100,
    new_value: 1050,
    change: -50
  }
}
```

### 5. 设置指定字段
直接设置某个字段的值。

```javascript
// 请求
{
  cmd: 'data_set',
  field: 'mission',
  value: 5
}

// 响应
{
  code: 200,
  data: {
    field: 'mission',
    old_value: 1,
    new_value: 5
  }
}
```

### 6. 重置游戏数据
重置基础游戏数据为默认值。

```javascript
// 请求
{ cmd: 'data_reset' }

// 响应
{
  code: 200,
  data: {
    // 重置后的默认数据
  }
}
```

## ⚔️ 出战英雄接口

### 1. 获取出战英雄配置
获取当前的出战英雄配置。

```javascript
// 请求
{ cmd: 'fight_heros_get' }

// 响应
{
  code: 200,
  data: {
    0: 5001,  // 位置0: 英雄5001
    1: 5005,  // 位置1: 英雄5005
    2: 0,     // 位置2: 空
    3: 0,     // 位置3: 空
    4: 0      // 位置4: 空
  }
}
```

### 2. 设置单个出战英雄
设置指定位置的出战英雄。

```javascript
// 请求
{
  cmd: 'fight_hero_set',
  position: 2,
  hero_id: 5007
}

// 响应
{
  code: 200,
  data: {
    position: 2,
    old_hero_id: 0,
    new_hero_id: 5007
  }
}
```

### 3. 批量更新出战英雄
批量更新多个位置的出战英雄。

```javascript
// 请求
{
  cmd: 'fight_heros_update',
  fight_heros: {
    0: 5001,
    1: 5005,
    2: 5007
  }
}

// 响应
{
  code: 200,
  data: {
    // 更新后的完整出战配置
  }
}
```

### 4. 获取激活的出战英雄
获取当前出战的英雄列表（不包含空位）。

```javascript
// 请求
{ cmd: 'fight_heros_active' }

// 响应
{
  code: 200,
  data: {
    active_heros: [
      {
        position: 0,
        hero_id: 5001,
        hero_data: { /* 英雄详细数据 */ }
      },
      {
        position: 1,
        hero_id: 5005,
        hero_data: { /* 英雄详细数据 */ }
      }
    ],
    total_count: 2
  }
}
```

### 5. 交换出战英雄位置
交换两个位置的英雄。

```javascript
// 请求
{
  cmd: 'fight_heros_swap',
  position1: 0,
  position2: 2
}

// 响应
{
  code: 200,
  data: {
    position1: 0,
    position2: 2,
    hero1_moved_to: 5007,
    hero2_moved_to: 5001
  }
}
```

### 6. 重置出战英雄
重置出战英雄配置为默认值。

```javascript
// 请求
{ cmd: 'fight_heros_reset' }

// 响应
{
  code: 200,
  data: {
    // 重置后的默认配置
  }
}
```

## 🦸 英雄管理接口

### 1. 获取所有英雄
获取用户拥有的所有英雄数据。

```javascript
// 请求
{ cmd: 'heros_get' }

// 响应
{
  code: 200,
  data: {
    5001: { uuid: 5001, lv: 10, exp: 500, star: 2, power: 150 },
    5005: { uuid: 5005, lv: 8, exp: 300, star: 1, power: 120 },
    5007: { uuid: 5007, lv: 1, exp: 0, star: 1, power: 90 }
  }
}
```

### 2. 获取单个英雄
获取指定英雄的详细数据。

```javascript
// 请求
{
  cmd: 'hero_get',
  hero_id: 5001
}

// 响应
{
  code: 200,
  data: {
    uuid: 5001,
    lv: 10,
    exp: 500,
    star: 2,
    power: 150
  }
}
```

### 3. 添加新英雄
添加新英雄到用户库存。

```javascript
// 请求
{
  cmd: 'hero_add',
  hero_id: 5008,
  hero_data: {  // 可选，不提供则使用默认数据
    lv: 1,
    exp: 0,
    star: 1,
    power: 110
  }
}

// 响应
{
  code: 200,
  data: {
    uuid: 5008,
    lv: 1,
    exp: 0,
    star: 1,
    power: 110
  }
}
```

### 4. 更新英雄属性
批量更新英雄的多个属性。

```javascript
// 请求
{
  cmd: 'hero_update',
  hero_id: 5001,
  update_data: {
    lv: 15,
    exp: 800,
    star: 3
  }
}

// 响应
{
  code: 200,
  data: {
    old_data: { /* 更新前的数据 */ },
    new_data: { /* 更新后的数据 */ }
  }
}
```

### 5. 设置英雄单个属性
设置英雄的单个属性值。

```javascript
// 请求
{
  cmd: 'hero_property_set',
  hero_id: 5001,
  property: 'lv',
  value: 20
}

// 响应
{
  code: 200,
  data: {
    hero_id: 5001,
    property: 'lv',
    old_value: 15,
    new_value: 20
  }
}
```

### 6. 英雄升级
英雄升级指定级数。

```javascript
// 请求
{
  cmd: 'hero_levelup',
  hero_id: 5001,
  levels: 3  // 可选，默认1级
}

// 响应
{
  code: 200,
  data: {
    hero_id: 5001,
    property: 'lv',
    old_value: 20,
    new_value: 23
  }
}
```

### 7. 删除英雄
删除指定英雄（会检查是否在出战阵容中）。

```javascript
// 请求
{
  cmd: 'hero_delete',
  hero_id: 5008
}

// 响应
{
  code: 200,
  data: {
    // 被删除的英雄数据
  }
}
```

### 8. 获取拥有的英雄ID列表
获取用户拥有的所有英雄ID。

```javascript
// 请求
{ cmd: 'heros_owned' }

// 响应
{
  code: 200,
  data: {
    hero_ids: [5001, 5005, 5007],
    total_count: 3
  }
}
```

## 🎒 库存管理接口

库存管理接口支持三种类型的数据：
- `items`: 道具
- `tals`: 天赋
- `equips`: 装备

### 1. 获取库存数据
获取指定类型的所有库存数据。

```javascript
// 请求
{
  cmd: 'inventory_get',
  type: 'items'  // 'items', 'tals', 'equips'
}

// 响应
{
  code: 200,
  data: {
    1001: 5,   // 道具1001: 5个
    1002: 3,   // 道具1002: 3个
    1003: 0,   // 道具1003: 0个
    // ...
  }
}
```

### 2. 获取单个物品
获取指定物品的数量。

```javascript
// 请求
{
  cmd: 'inventory_item_get',
  type: 'items',
  item_id: 1001
}

// 响应
{
  code: 200,
  data: {
    item_id: 1001,
    count: 5
  }
}
```

### 3. 添加物品
增加指定物品的数量。

```javascript
// 请求
{
  cmd: 'inventory_item_add',
  type: 'items',
  item_id: 1001,
  count: 10
}

// 响应
{
  code: 200,
  data: {
    item_id: 1001,
    old_count: 5,
    new_count: 15,
    added: 10
  }
}
```

### 4. 消耗物品
消耗指定数量的物品（会检查是否足够）。

```javascript
// 请求
{
  cmd: 'inventory_item_consume',
  type: 'items',
  item_id: 1001,
  count: 3
}

// 响应
{
  code: 200,
  data: {
    item_id: 1001,
    old_count: 15,
    new_count: 12,
    added: -3
  }
}
```

### 5. 设置物品数量
直接设置物品的数量。

```javascript
// 请求
{
  cmd: 'inventory_item_set',
  type: 'items',
  item_id: 1001,
  count: 20
}

// 响应
{
  code: 200,
  data: {
    item_id: 1001,
    old_count: 12,
    new_count: 20
  }
}
```

### 6. 批量更新库存
批量更新多个物品的数量。

```javascript
// 请求
{
  cmd: 'inventory_update',
  type: 'items',
  data: {
    1001: 25,
    1002: 10,
    1003: 5
  },
  merge: true  // 可选，默认true（合并更新）
}

// 响应
{
  code: 200,
  data: {
    // 更新后的完整库存数据
  }
}
```

### 7. 重置库存
重置指定类型的库存为默认值。

```javascript
// 请求
{
  cmd: 'inventory_reset',
  type: 'items'
}

// 响应
{
  code: 200,
  data: {
    // 重置后的默认库存数据
  }
}
```

### 8. 获取拥有的物品
获取数量大于0的物品列表。

```javascript
// 请求
{
  cmd: 'inventory_owned',
  type: 'items'
}

// 响应
{
  code: 200,
  data: {
    owned_items: [
      { item_id: 1001, count: 25 },
      { item_id: 1002, count: 10 },
      { item_id: 1003, count: 5 }
    ],
    total_types: 3
  }
}
```

## 🔄 兼容旧接口

为了保持向后兼容，保留了一些旧接口：

### 1. 加载数据 (兼容)
等同于 `login` 命令。

```javascript
// 请求
{ cmd: 'load' }

// 响应：与login相同
```

### 2. 保存数据 (兼容)
批量保存多种类型的数据。

```javascript
// 请求
{
  cmd: 'save',
  data: {
    data: { gold: 1000, diamond: 200 },
    fight_heros: { 0: 5001, 1: 5005 },
    heros: { 5001: { lv: 10, exp: 500 } },
    items: { 1001: 10, 1002: 5 },
    tals: { 1001: 1 },
    equips: { 1001: 2 }
  }
}

// 响应
{
  code: 200,
  data: {
    results: [
      // 各个模块的保存结果
    ]
  },
  msg: "All data saved successfully"
}
```

## ❌ 错误码说明

| 错误码 | 说明 | 示例 |
|-------|------|------|
| 200 | 成功 | 操作成功完成 |
| -1 | 操作失败 | 数据库更新失败 |
| -2 | 未知命令 | 命令不存在 |
| -3 | 参数错误 | 缺少必需参数或参数格式错误 |
| -4 | 用户未找到 | 用户不存在或创建失败 |
| -5 | 系统错误 | 服务器内部错误 |
| -6 | 资源不足 | 金币、道具等资源不够 |
| -7 | 资源已存在 | 英雄已存在等 |
| -8 | 操作被拒绝 | 英雄正在出战中无法删除等 |

## 📝 使用示例

### 完整的游戏流程示例

```javascript
// 1. 用户登录
wx.cloud.callFunction({
  name: 'cocos_cloud',
  data: { cmd: 'login' }
}).then(res => {
  console.log('用户登录成功:', res.result.data);
  
  // 2. 增加金币
  return wx.cloud.callFunction({
    name: 'cocos_cloud',
    data: {
      cmd: 'data_add',
      field: 'gold',
      amount: 100
    }
  });
}).then(res => {
  console.log('金币增加成功:', res.result.data);
  
  // 3. 添加新英雄
  return wx.cloud.callFunction({
    name: 'cocos_cloud',
    data: {
      cmd: 'hero_add',
      hero_id: 5008
    }
  });
}).then(res => {
  console.log('英雄添加成功:', res.result.data);
  
  // 4. 设置出战英雄
  return wx.cloud.callFunction({
    name: 'cocos_cloud',
    data: {
      cmd: 'fight_hero_set',
      position: 2,
      hero_id: 5008
    }
  });
}).then(res => {
  console.log('出战英雄设置成功:', res.result.data);
}).catch(err => {
  console.error('操作失败:', err);
});
```

## 🔧 开发调试

### 1. 启用调试日志
在开发环境中，云函数会输出详细的调试日志：

```javascript
// 请求日志
[data_add] Request from oxxx: { field: 'gold', amount: 100 }

// 响应日志
[data_add] Response (45ms): 200 gold updated successfully
```

### 2. 性能监控
每个响应都包含 `execution_time` 字段，显示接口执行时间。

### 3. 版本管理
使用 `version` 命令检查数据版本兼容性，确保客户端和服务端数据结构一致。

---

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