# WxCloudApi 客户端使用指南

## 📋 概述

`WxCloudApi` 是游戏客户端与微信云函数交互的统一接口层，提供了完整的类型安全和便捷的调用方法。

## 🚀 快速开始

### 1. 初始化
```typescript
// 在游戏启动时初始化云环境
WxCloudApi.init("your-cloud-env-id");
```

### 2. 用户登录
```typescript
// 用户登录，获取完整的游戏数据
const loginResult = await WxCloudApi.login();
if (loginResult.result.code === 200) {
    const userData = loginResult.result.data;
    console.log("用户ID:", userData.user_id);
    console.log("金币:", userData.data.gold);
    console.log("出战英雄:", userData.fight_heros);
}
```

## 🎮 基础游戏数据操作

### 获取游戏数据
```typescript
const gameData = await WxCloudApi.getGameData();
if (gameData.result.code === 200) {
    console.log("当前金币:", gameData.result.data.gold);
    console.log("当前钻石:", gameData.result.data.diamond);
}
```

### 增加金币
```typescript
// 方式1：使用便捷方法
const result = await WxCloudApi.addGold(100);

// 方式2：使用通用方法
const result = await WxCloudApi.addGameDataField('gold', 100);

if (result.result.code === 200) {
    console.log("金币增加成功:", result.result.data);
}
```

### 消耗金币
```typescript
// 消耗金币（会检查是否足够）
const result = await WxCloudApi.spendGold(50);
if (result.result.code === 200) {
    console.log("金币消耗成功");
} else if (result.result.code === -6) {
    console.log("金币不足");
}
```

### 批量更新游戏数据
```typescript
const result = await WxCloudApi.updateGameData({
    gold: 1000,
    diamond: 200,
    exp: 500
}, true); // true表示合并更新
```

## ⚔️ 出战英雄管理

### 获取出战英雄配置
```typescript
const fightHeros = await WxCloudApi.getFightHeros();
if (fightHeros.result.code === 200) {
    console.log("出战配置:", fightHeros.result.data);
    // { 0: 5001, 1: 5005, 2: 0, 3: 0, 4: 0 }
}
```

### 设置出战英雄
```typescript
// 将英雄5007设置到位置2
const result = await WxCloudApi.setFightHero(2, 5007);
if (result.result.code === 200) {
    console.log("设置成功:", result.result.data);
}

// 移除位置2的英雄
await WxCloudApi.setFightHero(2, 0);
```

### 批量更新出战英雄
```typescript
const result = await WxCloudApi.updateFightHeros({
    0: 5001,
    1: 5005,
    2: 5007
});
```

### 交换英雄位置
```typescript
// 交换位置0和位置2的英雄
const result = await WxCloudApi.swapFightHeros(0, 2);
```

### 获取激活的出战英雄
```typescript
const activeHeros = await WxCloudApi.getActiveFightHeros();
if (activeHeros.result.code === 200) {
    const heros = activeHeros.result.data.active_heros;
    heros.forEach(hero => {
        console.log(`位置${hero.position}: 英雄${hero.hero_id}, 等级${hero.hero_data.lv}`);
    });
}
```

## 🦸 英雄管理

### 获取所有英雄
```typescript
const heros = await WxCloudApi.getHeros();
if (heros.result.code === 200) {
    Object.entries(heros.result.data).forEach(([heroId, heroData]) => {
        console.log(`英雄${heroId}: 等级${heroData.lv}, 战力${heroData.power}`);
    });
}
```

### 添加新英雄
```typescript
// 添加英雄（使用默认属性）
const result = await WxCloudApi.addHero(5008);

// 添加英雄（自定义属性）
const result = await WxCloudApi.addHero(5008, {
    lv: 5,
    exp: 1000,
    star: 2,
    power: 150
});
```

### 英雄升级
```typescript
// 升级1级
const result = await WxCloudApi.levelUpHero(5001);

// 升级3级
const result = await WxCloudApi.levelUpHero(5001, 3);

if (result.result.code === 200) {
    console.log("升级成功:", result.result.data);
}
```

### 更新英雄属性
```typescript
// 批量更新
const result = await WxCloudApi.updateHero(5001, {
    lv: 15,
    exp: 2000,
    star: 3
});

// 单个属性更新
const result = await WxCloudApi.setHeroProperty(5001, 'power', 200);
```

### 删除英雄
```typescript
const result = await WxCloudApi.deleteHero(5008);
if (result.result.code === -8) {
    console.log("英雄正在出战中，无法删除");
}
```

## 🎒 库存管理

### 道具操作
```typescript
// 获取所有道具
const items = await WxCloudApi.getItems();

// 添加道具
const result = await WxCloudApi.addItem(1001, 10);

// 消耗道具
const result = await WxCloudApi.consumeItem(1001, 3);

// 获取指定道具数量
const itemInfo = await WxCloudApi.getInventoryItem('items', 1001);
console.log("道具1001数量:", itemInfo.result.data.count);
```

### 天赋操作
```typescript
// 获取所有天赋
const talents = await WxCloudApi.getTalents();

// 添加天赋点
const result = await WxCloudApi.addTalent(1001, 1);

// 消耗天赋点
const result = await WxCloudApi.consumeTalent(1001, 1);
```

### 装备操作
```typescript
// 获取所有装备
const equipments = await WxCloudApi.getEquipments();

// 添加装备
const result = await WxCloudApi.addEquipment(1001, 2);

// 消耗装备
const result = await WxCloudApi.consumeEquipment(1001, 1);
```

### 批量库存操作
```typescript
// 批量更新道具
const result = await WxCloudApi.updateInventory('items', {
    1001: 20,
    1002: 15,
    1003: 10
});

// 获取拥有的道具列表（数量>0）
const ownedItems = await WxCloudApi.getOwnedItems('items');
console.log("拥有的道具:", ownedItems.result.data.owned_items);
```

## 🔐 认证和版本管理

### 检查版本信息
```typescript
const versionInfo = await WxCloudApi.checkVersion();
if (versionInfo.result.code === 200) {
    const compatibility = versionInfo.result.data.compatibility;
    if (compatibility.needsUpgrade) {
        console.log("需要升级数据:", compatibility.message);
        // 可以选择自动升级
        await WxCloudApi.upgradeUserData();
    }
}
```

### 获取用户基本信息
```typescript
const userInfo = await WxCloudApi.getUserInfo();
if (userInfo.result.code === 200) {
    console.log("用户信息:", userInfo.result.data);
}
```

## 🛠️ 错误处理

### 统一错误处理
```typescript
async function handleApiCall<T>(apiCall: Promise<CloudCallFunctionResult<CloudReturnType<T>>>) {
    try {
        const result = await apiCall;
        const response = result.result;
        
        switch (response.code) {
            case 200:
                console.log("操作成功:", response.data);
                return response.data;
                
            case -3:
                console.error("参数错误:", response.msg);
                break;
                
            case -4:
                console.error("用户未找到:", response.msg);
                break;
                
            case -5:
                console.error("系统错误:", response.msg);
                break;
                
            case -6:
                console.error("资源不足:", response.msg);
                break;
                
            default:
                console.error("未知错误:", response.code, response.msg);
        }
    } catch (error) {
        console.error("网络错误:", error);
    }
    return null;
}

// 使用示例
const gameData = await handleApiCall(WxCloudApi.getGameData());
```

### 资源不足处理示例
```typescript
async function trySpendGold(amount: number): Promise<boolean> {
    const result = await WxCloudApi.spendGold(amount);
    const response = result.result;
    
    if (response.code === 200) {
        console.log("金币消耗成功");
        return true;
    } else if (response.code === -6) {
        console.log("金币不足，当前:", response.data?.current, "需要:", response.data?.required);
        // 可以提示用户充值或其他操作
        return false;
    }
    
    console.error("消耗失败:", response.msg);
    return false;
}
```

## 📊 完整游戏流程示例

```typescript
export class GameDataManager {
    // 游戏启动时初始化
    public static async initialize() {
        // 1. 初始化云环境
        WxCloudApi.init("your-cloud-env-id");
        
        // 2. 用户登录
        const loginResult = await WxCloudApi.login();
        if (loginResult.result.code !== 200) {
            console.error("登录失败");
            return false;
        }
        
        const userData = loginResult.result.data;
        console.log("登录成功，用户数据:", userData);
        
        // 3. 检查版本兼容性
        const versionResult = await WxCloudApi.checkVersion();
        if (versionResult.result.data.compatibility.needsUpgrade) {
            console.log("正在升级数据...");
            await WxCloudApi.upgradeUserData();
        }
        
        return true;
    }
    
    // 战斗结算
    public static async settleBattle(rewards: {gold: number, exp: number, items: {[id: number]: number}}) {
        try {
            // 1. 增加金币和经验
            await WxCloudApi.addGold(rewards.gold);
            await WxCloudApi.addGameDataField('exp', rewards.exp);
            
            // 2. 增加道具奖励
            for (const [itemId, count] of Object.entries(rewards.items)) {
                await WxCloudApi.addItem(parseInt(itemId), count);
            }
            
            console.log("战斗结算完成");
            return true;
        } catch (error) {
            console.error("战斗结算失败:", error);
            return false;
        }
    }
    
    // 英雄升级
    public static async upgradeHero(heroId: number, levels: number): Promise<boolean> {
        // 假设每级需要100金币
        const cost = levels * 100;
        
        // 1. 检查金币是否足够
        const spendResult = await WxCloudApi.spendGold(cost);
        if (spendResult.result.code !== 200) {
            console.log("金币不足，无法升级");
            return false;
        }
        
        // 2. 升级英雄
        const upgradeResult = await WxCloudApi.levelUpHero(heroId, levels);
        if (upgradeResult.result.code === 200) {
            console.log("英雄升级成功");
            return true;
        } else {
            // 升级失败，退还金币
            await WxCloudApi.addGold(cost);
            console.error("英雄升级失败");
            return false;
        }
    }
    
    // 设置出战阵容
    public static async setupFightTeam(heroIds: number[]): Promise<boolean> {
        const fightHeros: Partial<FightHeros> = {};
        
        // 最多5个位置
        for (let i = 0; i < Math.min(heroIds.length, 5); i++) {
            fightHeros[i] = heroIds[i];
        }
        
        // 清空剩余位置
        for (let i = heroIds.length; i < 5; i++) {
            fightHeros[i] = 0;
        }
        
        const result = await WxCloudApi.updateFightHeros(fightHeros);
        return result.result.code === 200;
    }
}
```

## 🎯 最佳实践

### 1. 错误处理
- 始终检查返回的 `code` 字段
- 对不同错误码进行相应处理
- 网络错误要有重试机制

### 2. 性能优化
- 批量操作优于多次单独操作
- 合理使用缓存，避免频繁请求
- 关键操作添加加载状态

### 3. 数据一致性
- 重要操作后及时同步本地数据
- 使用乐观锁机制处理并发
- 定期全量同步数据

### 4. 用户体验
- 操作前进行客户端验证
- 提供友好的错误提示
- 重要操作添加确认对话框

---

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