# Game模块服务层DTO和Protobuf转换功能增强

**时间**: 2025年06月09日 20:56  
**任务类型**: 功能增强  
**状态**: 已完成

## 任务描述

为Game模块的ConsumeService、ConditionService和RewardService增加获取组的方法，返回DTO对象，并增加消耗组DTO转Protobuf对象Deduct、奖励组DTO转Protobuf对象Reward的转换功能。

## 需求分析

### 核心需求
1. **ConsumeService增加获取消耗组方法**，返回DTO
2. **ConditionService增加获取条件组方法**，返回DTO  
3. **RewardService添加获取奖励组方法**，返回DTO
4. **增加消耗组DTO转Protobuf对象Deduct**
5. **增加奖励组DTO转Protobuf对象Reward**

### 设计目标
- 统一的DTO接口，便于数据传输和处理
- 完整的Protobuf转换支持，满足前端通信需求
- 保持服务层的简洁性和一致性
- 支持灵活的数据获取选项

## 解决方案

### 1. 创建DTO类

#### 1.1 消耗相关DTO
**ConsumeGroupDto** (`app/Module/Game/Dtos/ConsumeGroupDto.php`):
```php
class ConsumeGroupDto
{
    public int $id;
    public string $name;
    public string $code;
    public ?string $description;
    public array $items = []; // ConsumeItemDto[]
    
    public static function fromModel($model, bool $withItems = false): self
}
```

**ConsumeItemDto** (`app/Module/Game/Dtos/ConsumeItemDto.php`):
```php
class ConsumeItemDto
{
    public int $id;
    public int $groupId;
    public int $consumeType;
    public int $targetId;
    public int $param1;
    public int $param2;
    public int $quantity;
    public ?array $extraData;
    
    public static function fromModel($model): self
}
```

#### 1.2 条件相关DTO
**ConditionGroupDto** (`app/Module/Game/Dtos/ConditionGroupDto.php`):
```php
class ConditionGroupDto
{
    public int $id;
    public string $name;
    public string $code;
    public ?string $description;
    public int $logicType;
    public array $items = []; // ConditionItemDto[]
    
    public static function fromModel($model, bool $withItems = false): self
}
```

**ConditionItemDto** (`app/Module/Game/Dtos/ConditionItemDto.php`):
```php
class ConditionItemDto
{
    public int $id;
    public int $groupId;
    public int $conditionType;
    public int $targetId;
    public int $operator;
    public int $value;
    public int $param1;
    public int $param2;
    public ?array $extraData;
    
    public static function fromModel($model): self
}
```

### 2. 增强服务层方法

#### 2.1 ConsumeService增强
```php
/**
 * 获取消耗组信息
 */
public static function getConsumeGroup($consumeGroupCode, bool $withItems = true): ?ConsumeGroupDto

/**
 * 获取消耗组并转换为Protobuf Deduct对象
 */
public static function getConsumeGroupAsDeduct($consumeGroupCode): ?\Uraus\Kku\Common\Deduct
```

#### 2.2 ConditionService增强
```php
/**
 * 获取条件组信息
 */
public static function getConditionGroup($conditionGroupCode, bool $withItems = true): ?ConditionGroupDto
```

#### 2.3 RewardService增强
```php
/**
 * 获取奖励组并转换为Protobuf Reward对象
 */
public static function getRewardGroupAsReward($groupIdOrCode): ?\Uraus\Kku\Common\Reward
```

### 3. 创建Protobuf转换器

#### 3.1 ProtobufConverter类
**文件**: `app/Module/Game/Services/ProtobufConverter.php`

**核心功能**:
- 消耗组DTO转Protobuf Deduct对象
- 奖励组DTO转Protobuf Reward对象
- 单个消耗项/奖励项的Protobuf转换
- 支持复杂的类型映射和参数处理

**主要方法**:
```php
// 消耗组转换
public static function convertConsumeGroupToDeduct(ConsumeGroupDto $consumeGroupDto): Deduct

// 奖励组转换
public static function convertRewardGroupToReward(RewardGroupDto $rewardGroupDto): Reward

// 单项转换
public static function convertConsumeItemToProtobuf(ConsumeItemDto $consumeItemDto)
public static function convertRewardItemToProtobuf(RewardItemDto $rewardItemDto)
```

#### 3.2 支持的Protobuf类型映射

**消耗类型映射**:
- `CONSUME_TYPE::ITEM` → `DeductItem`
- `CONSUME_TYPE::CURRENCY` → `DeductCoin`
- `CONSUME_TYPE::FUND_CONFIG` → `DeductCoin`
- `CONSUME_TYPE::FUND_CONFIGS` → `DeductCoin`

**奖励类型映射**:
- `REWARD_TYPE::ITEM` → `RewardItem`
- `REWARD_TYPE::CURRENCY` → `RewardCoin`
- `REWARD_TYPE::FUND_CONFIG` → `RewardCoin`
- `REWARD_TYPE::FARM_SHRINE` → `RewardGod`
- `REWARD_TYPE::PET` → `RewardPets`
- `REWARD_TYPE::PET_POWER` → `RewardPetPowers`
- `REWARD_TYPE::SKIN` → `RewardSkin`

## 实现特性

### 1. 灵活的数据获取
- 支持通过ID或编码获取组信息
- 可选择是否包含子项（withItems参数）
- 统一的错误处理和日志记录

### 2. 完整的类型支持
- 支持所有现有的消耗类型和奖励类型
- 正确处理参数映射（param1、param2等）
- 支持随机数量范围（minQuantity、maxQuantity）

### 3. 高效的转换逻辑
- 直接从DTO转换为Protobuf，避免重复查询
- 合理的默认值处理
- 类型安全的转换过程

### 4. 便捷的API接口
- 一步到位的Protobuf转换方法
- 保持向后兼容性
- 清晰的方法命名和文档

## 使用示例

### 1. 获取消耗组DTO
```php
// 获取包含消耗项的消耗组
$consumeGroup = ConsumeService::getConsumeGroup(1, true);
if ($consumeGroup) {
    echo "消耗组: {$consumeGroup->name}";
    echo "消耗项数量: " . count($consumeGroup->items);
}
```

### 2. 直接获取Protobuf对象
```php
// 获取消耗组的Protobuf Deduct对象
$deduct = ConsumeService::getConsumeGroupAsDeduct('consume_group_code');

// 获取奖励组的Protobuf Reward对象
$reward = RewardService::getRewardGroupAsReward('reward_group_code');
```

### 3. 获取条件组
```php
// 获取条件组DTO
$conditionGroup = ConditionService::getConditionGroup('condition_code', true);
if ($conditionGroup) {
    echo "逻辑类型: {$conditionGroup->logicType}";
    echo "条件项数量: " . count($conditionGroup->items);
}
```

## 技术优势

### 1. 架构清晰
- DTO层负责数据传输
- Service层提供业务接口
- Converter层处理格式转换
- 职责分离，易于维护

### 2. 类型安全
- 强类型的DTO定义
- 完整的类型检查
- 避免运行时类型错误

### 3. 扩展性强
- 新增类型时只需扩展Converter
- DTO结构易于扩展
- 保持接口稳定性

### 4. 性能优化
- 减少重复的数据库查询
- 高效的对象转换
- 合理的内存使用

## 测试验证

### 1. 功能测试
- 验证所有服务方法正常工作
- 确认DTO数据完整性
- 测试Protobuf转换正确性

### 2. 兼容性测试
- 确保现有功能不受影响
- 验证新旧接口兼容性
- 测试错误处理机制

## 总结

本次功能增强成功为Game模块建立了完整的DTO和Protobuf转换体系：

1. **创建了4个DTO类**，提供统一的数据传输接口
2. **增强了3个Service类**，添加了获取组的方法
3. **创建了ProtobufConverter**，提供完整的Protobuf转换功能
4. **支持所有类型映射**，满足前端通信需求
5. **保持了架构清晰**，便于后续维护和扩展

这次增强为Game模块的服务层提供了更加完善和统一的接口，特别是在Handler层中可以方便地获取DTO并转换为Protobuf格式返回给前端，大大提升了开发效率和代码质量。