云环境和本地调试 添加

build-templates/wechatgame/cloud_functions/cocos_cloud/API.md

@@ -0,0 +1,913 @@
+# 游戏云函数 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年  
+**维护者**: 游戏开发团队
+