feat(game): 重构物品和宠物暂存系统

- 新增 ItemChangeTempDto、PetCreatedTempDto 和 PetStatusTempDto 类用于存储临时数据
- 重构 ItemTemp 和 PetTemp 类，使用新的 DTO 类处理临时数据
- 更新 ItemTempService 和 PetTempService 类，支持新的临时数据结构
- 修改 AppGameProtobufResponseListener 以使用新的临时数据
- 更新相关文档，描述新的暂存系统结构和使用方法

app/Module/AppGame/Listeners/AppGameProtobufResponseListener.php

@@ -5,6 +5,8 @@ namespace App\Module\AppGame\Listeners;
 use App\Module\AppGame\Events\ProtobufResponseEvent;
 use App\Module\AppGame\SessionApp;
 use Illuminate\Support\Facades\Log;
+use Uraus\Kku\Common\DataItem;
+use Uraus\Kku\Common\LastData;
 
 /**
  * AppGame模块Protobuf响应事件监听器
@@ -33,9 +35,39 @@ class AppGameProtobufResponseListener
      */
     public function handle(ProtobufResponseEvent $event): void
     {
+        $lastData = $event->response->getLastData();
+        if(!$lastData){
+            $lastData= new LastData();
+        }
         $user_id = SessionApp::getUserId();
-        $items = \App\Module\Game\Logics\ItemCache::getUserItemChanges($user_id);
+        // 获取用户物品变更临时数据
+        $items = \App\Module\Game\Logics\ItemTemp::getUserItemChanges($user_id);
+        $itemLs = [];
+        foreach ($items as $item){
+            $i = new DataItem();
+            $i->setItemId($item->itemId);
+            $i->setQuantity($item->newQuantity);
+            if($item->instanceId){
+                $i->setInstanceId($item->instanceId);
+            }
 
+            $itemLs[] = $i;
+        }
+        if($itemLs){
+            $lastData->setItems($itemLs);
+        }
+        $pets = \App\Module\Game\Logics\PetTemp::getUserPetStatus($user_id);
 
+        $petLs = [];
+        foreach ($pets as $pet){
+            $p = new \Uraus\Kku\Common\DataPet();
+            $p->setId($pet->petId);
+            $p->setTypeId($pet->newStatus);
+            $p->setLevel($pet->reason);
+            $p->setName($pet->name);
+            $petLs[] = $p;
+        }
+
+        $event->response->setLastData($lastData);
     }
 }

app/Module/Game/Docs/宠物暂存系统.md

@@ -1,5 +1,7 @@
 # 宠物暂存系统
 
+> 最后更新时间：2023年12月
+
 ## 1. 概述
 
 宠物暂存系统是 Game 模块提供的一个用于跟踪和记录用户宠物变更的临时存储机制，主要用于优化前端UI更新和提高用户体验。当用户宠物状态发生变化或新宠物被创建时，系统会将变更信息暂时存储，前端可以通过API获取这些变更信息，从而实现宠物变更的实时反馈。
@@ -13,16 +15,21 @@
 - **PetCreatedEvent**: 宠物创建事件，当新宠物被创建时触发。
 - **PetStatusChangedEvent**: 宠物状态变更事件，当宠物状态发生变化时触发。
 
-### 2.2 监听器（在 Game 模块中实现）
+### 2.2 DTO 类
+
+- **PetCreatedTempDto**: 宠物创建临时数据传输对象，用于存储和传输宠物创建的临时数据。
+- **PetStatusTempDto**: 宠物状态变更临时数据传输对象，用于存储和传输宠物状态变更的临时数据。
+
+### 2.3 监听器（在 Game 模块中实现）
 
 - **PetCreatedListener**: 监听宠物创建事件，并调用逻辑层处理临时数据。
 - **PetStatusChangedListener**: 监听宠物状态变更事件，并调用逻辑层处理临时数据。
 
-### 2.3 逻辑层
+### 2.4 逻辑层
 
 - **PetTemp**: 宠物临时数据逻辑类，负责处理宠物相关事件的临时数据存储逻辑。
 
-### 2.4 服务层
+### 2.5 服务层
 
 - **PetTempService**: 宠物临时数据服务类，提供宠物临时数据相关的服务方法，用于外部调用。
 
@@ -40,31 +47,41 @@
 
 ## 4. 临时数据结构
 
-### 4.1 宠物创建临时数据
+### 4.1 宠物创建临时数据 (PetCreatedTempDto)
 
 ```php
-[
-    'pet_id' => 宠物ID,
-    'name' => 宠物名称,
-    'grade' => 宠物品阶,
-    'level' => 宠物等级,
-    'created_at' => 创建时间戳
-]
+class PetCreatedTempDto
+{
+    public int $petId;        // 宠物ID
+    public string $name;      // 宠物名称
+    public int $grade;        // 宠物品阶
+    public int $level;        // 宠物等级
+    public int $createdAt;    // 创建时间戳
+}
 ```
 
-### 4.2 宠物状态变更临时数据
+### 4.2 宠物状态变更临时数据 (PetStatusTempDto)
 
 ```php
-[
-    'pet_id' => 宠物ID,
-    'old_status' => 旧状态,
-    'new_status' => 新状态,
-    'reason' => 变更原因,
-    'data' => 附加数据,
-    'updated_at' => 更新时间戳
-]
+class PetStatusTempDto
+{
+    public int $petId;        // 宠物ID
+    public int $oldStatus;    // 旧状态
+    public int $newStatus;    // 新状态
+    public string $reason;    // 变更原因
+    public array $data;       // 附加数据
+    public int $updatedAt;    // 更新时间戳
+}
 ```
 
+### 4.3 宠物属性说明
+
+宠物模型中的重要属性：
+
+- **experience**（经验值）：宠物的经验值，用于衡量宠物的成长进度。当经验值达到一定阈值时，宠物可以升级。在喜养操作中，经验值会增加。
+
+- **stamina**（体力值）：宠物的体力值，表示宠物可以执行活动的能力。宠物进行某些活动（如战斗、工作等）会消耗体力值，通过喜养等方式可以恢复宠物的体力值。
+
 ## 5. 临时数据键和过期时间
 
 - **宠物创建临时数据键前缀**：`game:pet:created:`，后接用户ID，如 `game:pet:created:123`。
@@ -78,16 +95,46 @@
 ```php
 $petTempService = new PetTempService();
 $petCreated = $petTempService->getUserPetCreated($userId);
+
+// 使用DTO对象的属性
+$petId = $petCreated[1]->petId;
+$petName = $petCreated[1]->name;
+$petGrade = $petCreated[1]->grade;
 ```
 
-### 6.2 获取用户的宠物状态变更临时数据
+### 6.2 获取用户特定宠物的创建临时数据
+
+```php
+$petTempService = new PetTempService();
+$petCreated = $petTempService->getUserPetCreatedById($userId, $petId);
+
+// 判断宠物是否存在
+$petExists = $petCreated !== null;
+```
+
+### 6.3 获取用户的宠物状态变更临时数据
 
 ```php
 $petTempService = new PetTempService();
 $petStatus = $petTempService->getUserPetStatus($userId);
+
+// 遍历所有宠物状态
+ foreach ($petStatus as $petId => $statusDto) {
+    echo "宠物ID: {$statusDto->petId}, 新状态: {$statusDto->newStatus}\n";
+}
+```
+
+### 6.4 获取用户特定宠物的状态变更临时数据
+
+```php
+$petTempService = new PetTempService();
+$petStatus = $petTempService->getUserPetStatusById($userId, $petId);
+
+// 获取状态变更原因
+$reason = $petStatus ? $petStatus->reason : null;
 ```
 
-### 6.3 清除用户的宠物临时数据
+### 6.5 清除用户的宠物临时数据
 
 ```php
 $petTempService = new PetTempService();
@@ -109,6 +156,8 @@ $petTempService->clearUserAllPetTemp($userId);
 - **宠物状态变更提示**：当宠物状态变化时，前端可以显示变更提示。
 - **宠物列表更新**：当用户宠物列表发生变化时，前端可以实时更新宠物列表界面。
 - **任务进度更新**：当用户完成与宠物相关的任务时，前端可以更新任务进度。
+- **喜养效果展示**：当用户喜养宠物时，前端可以显示经验值和体力值增加的动画效果。
+- **升级提示**：当宠物经验值达到升级条件时，前端可以显示升级提示。
 
 ## 8. 注意事项
 

app/Module/Game/Docs/物品暂存系统.md

@@ -1,5 +1,7 @@
 # 物品暂存系统
 
+> 最后更新时间：2023年12月
+
 ## 1. 概述
 
 物品暂存系统是一个用于跟踪和记录用户物品变更的临时存储机制，主要用于优化前端UI更新和提高用户体验。当用户物品数量发生变化时，系统会将变更信息暂时存储，前端可以通过API获取这些变更信息，从而实现物品变更的实时反馈。
@@ -12,48 +14,53 @@
 
 - **ItemQuantityChanged**: 物品数量变更事件，当用户物品数量发生变化时触发。
 
-### 2.2 监听器
+### 2.2 DTO 类
+
+- **ItemChangeTempDto**: 物品变更临时数据传输对象，用于存储和传输物品变更的临时数据。
+
+### 2.3 监听器
 
 - **ItemQuantityChangedListener**: 监听物品数量变更事件，并调用逻辑层处理暂存。
 
-### 2.3 逻辑层
+### 2.4 逻辑层
 
-- **ItemCache**: 物品暂存逻辑类，负责处理物品变更事件的暂存逻辑。
+- **ItemTemp**: 物品暂存逻辑类，负责处理物品变更事件的暂存逻辑。
 
-### 2.4 服务层
+### 2.5 服务层
 
-- **ItemCacheService**: 物品暂存服务类，提供物品暂存相关的服务方法，用于外部调用。
+- **ItemTempService**: 物品暂存服务类，提供物品暂存相关的服务方法，用于外部调用。
 
-### 2.5 命令
+### 2.6 命令
 
-- **TestItemCacheCommand**: 测试物品暂存命令，用于测试物品变更事件监听和暂存功能。
+- **TestItemTempCommand**: 测试物品暂存命令，用于测试物品变更事件监听和暂存功能。
 
 ## 3. 工作流程
 
 1. **事件触发**：当用户物品数量发生变化时（如获取物品、消耗物品等），系统会触发 `ItemQuantityChanged` 事件。
 
-2. **事件监听**：`ItemQuantityChangedListener` 监听到事件后，会调用 `ItemCache::handleItemQuantityChanged` 方法处理暂存。
+2. **事件监听**：`ItemQuantityChangedListener` 监听到事件后，会调用 `ItemTemp::handleItemQuantityChanged` 方法处理暂存。
 
-3. **数据暂存**：`ItemCache` 类将物品变更数据暂时存储，按用户ID和物品ID进行存储，同一物品多次变更会覆盖之前的数据。
+3. **数据暂存**：`ItemTemp` 类将物品变更数据暂时存储，按用户ID和物品ID进行存储，同一物品多次变更会覆盖之前的数据。
 
-4. **数据获取**：前端或其他模块可以通过 `ItemCacheService` 提供的方法获取用户的物品变更暂存数据。
+4. **数据获取**：前端或其他模块可以通过 `ItemTempService` 提供的方法获取用户的物品变更暂存数据。
 
-5. **数据清理**：当不再需要暂存数据时，可以通过 `ItemCacheService` 提供的方法清除用户的物品变更暂存数据。
+5. **数据清理**：当不再需要暂存数据时，可以通过 `ItemTempService` 提供的方法清除用户的物品变更暂存数据。
 
 ## 4. 暂存数据结构
 
-暂存数据按用户ID进行存储，每个用户的暂存数据是一个关联数组，键为物品ID，值为物品变更数据：
+### 4.1 物品变更临时数据 (ItemChangeTempDto)
 
 ```php
-[
-    'item_id' => 物品ID,
-    'instance_id' => 物品实例ID（单独属性物品）,
-    'old_quantity' => 旧数量,
-    'new_quantity' => 新数量,
-    'change_amount' => 变化量,
-    'user_item_id' => 用户物品记录ID,
-    'updated_at' => 更新时间戳
-]
+class ItemChangeTempDto
+{
+    public int $itemId;         // 物品ID
+    public ?int $instanceId;    // 物品实例ID（单独属性物品）
+    public int $oldQuantity;    // 旧数量
+    public int $newQuantity;    // 新数量
+    public int $changeAmount;   // 变化量
+    public int $userItemId;     // 用户物品记录ID
+    public int $updatedAt;      // 更新时间戳
+}
 ```
 
 ## 5. 暂存键和过期时间
@@ -82,22 +89,34 @@ Event::dispatch($event);
 ### 6.2 获取用户的物品变更暂存数据
 
 ```php
-$itemCacheService = new ItemCacheService();
-$itemChanges = $itemCacheService->getUserItemChanges($userId);
+$itemTempService = new ItemTempService();
+$itemChanges = $itemTempService->getUserItemChanges($userId);
+
+// 使用DTO对象的属性
+foreach ($itemChanges as $itemId => $changeDto) {
+    echo "物品ID: {$changeDto->itemId}, 变化量: {$changeDto->changeAmount}\n";
+}
 ```
 
 ### 6.3 获取用户特定物品的变更暂存数据
 
 ```php
-$itemCacheService = new ItemCacheService();
-$itemChange = $itemCacheService->getUserItemChange($userId, $itemId);
+$itemTempService = new ItemTempService();
+$itemChange = $itemTempService->getUserItemChange($userId, $itemId);
+
+// 判断物品是否存在
+if ($itemChange !== null) {
+    $oldQuantity = $itemChange->oldQuantity;
+    $newQuantity = $itemChange->newQuantity;
+    $changeAmount = $itemChange->changeAmount;
+}
 ```
 
 ### 6.4 清除用户的物品变更暂存数据
 
 ```php
-$itemCacheService = new ItemCacheService();
-$itemCacheService->clearUserItemChanges($userId);
+$itemTempService = new ItemTempService();
+$itemTempService->clearUserItemChanges($userId);
 ```
 
 ## 7. 优势和应用场景
@@ -115,6 +134,7 @@ $itemCacheService->clearUserItemChanges($userId);
 - **物品数量变更提示**：当用户物品数量变化时，前端可以显示变更提示。
 - **背包更新**：当用户背包中的物品发生变化时，前端可以实时更新背包界面。
 - **任务进度更新**：当用户完成与物品相关的任务时，前端可以更新任务进度。
+- **物品消耗效果**：当用户消耗物品时，前端可以显示物品消耗的效果。
 
 ## 8. 注意事项
 

app/Module/Game/Dtos/ItemChangeTempDto.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Module\Game\Dtos;
+
+/**
+ * 物品变更临时数据DTO
+ * 
+ * 用于存储和传输物品变更的临时数据
+ */
+class ItemChangeTempDto
+{
+    /**
+     * 物品ID
+     *
+     * @var int
+     */
+    public int $itemId;
+
+    /**
+     * 物品实例ID（单独属性物品）
+     *
+     * @var int|null
+     */
+    public ?int $instanceId;
+
+    /**
+     * 旧数量
+     *
+     * @var int
+     */
+    public int $oldQuantity;
+
+    /**
+     * 新数量
+     *
+     * @var int
+     */
+    public int $newQuantity;
+
+    /**
+     * 变化量
+     *
+     * @var int
+     */
+    public int $changeAmount;
+
+    /**
+     * 用户物品记录ID
+     *
+     * @var int
+     */
+    public int $userItemId;
+
+    /**
+     * 更新时间戳
+     *
+     * @var int
+     */
+    public int $updatedAt;
+
+    /**
+     * 从数组创建DTO对象
+     *
+     * @param array $data 物品变更数据数组
+     * @return self
+     */
+    public static function fromArray(array $data): self
+    {
+        $dto = new self();
+        $dto->itemId = $data['item_id'];
+        $dto->instanceId = $data['instance_id'];
+        $dto->oldQuantity = $data['old_quantity'];
+        $dto->newQuantity = $data['new_quantity'];
+        $dto->changeAmount = $data['change_amount'];
+        $dto->userItemId = $data['user_item_id'];
+        $dto->updatedAt = $data['updated_at'];
+        return $dto;
+    }
+
+    /**
+     * 转换为数组
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        return [
+            'item_id' => $this->itemId,
+            'instance_id' => $this->instanceId,
+            'old_quantity' => $this->oldQuantity,
+            'new_quantity' => $this->newQuantity,
+            'change_amount' => $this->changeAmount,
+            'user_item_id' => $this->userItemId,
+            'updated_at' => $this->updatedAt,
+        ];
+    }
+}

app/Module/Game/Dtos/PetCreatedTempDto.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace App\Module\Game\Dtos;
+
+/**
+ * 宠物创建临时数据DTO
+ * 
+ * 用于存储和传输宠物创建的临时数据
+ */
+class PetCreatedTempDto
+{
+    /**
+     * 宠物ID
+     *
+     * @var int
+     */
+    public int $petId;
+
+    /**
+     * 宠物名称
+     *
+     * @var string
+     */
+    public string $name;
+
+    /**
+     * 宠物品阶
+     *
+     * @var int
+     */
+    public int $grade;
+
+    /**
+     * 宠物等级
+     *
+     * @var int
+     */
+    public int $level;
+
+    /**
+     * 创建时间戳
+     *
+     * @var int
+     */
+    public int $createdAt;
+
+    /**
+     * 从数组创建DTO对象
+     *
+     * @param array $data 宠物创建数据数组
+     * @return self
+     */
+    public static function fromArray(array $data): self
+    {
+        $dto = new self();
+        $dto->petId = $data['pet_id'];
+        $dto->name = $data['name'];
+        $dto->grade = $data['grade'];
+        $dto->level = $data['level'];
+        $dto->createdAt = $data['created_at'];
+        return $dto;
+    }
+
+    /**
+     * 转换为数组
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        return [
+            'pet_id' => $this->petId,
+            'name' => $this->name,
+            'grade' => $this->grade,
+            'level' => $this->level,
+            'created_at' => $this->createdAt,
+        ];
+    }
+}

app/Module/Game/Dtos/PetStatusTempDto.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace App\Module\Game\Dtos;
+
+/**
+ * 宠物状态变更临时数据DTO
+ * 
+ * 用于存储和传输宠物状态变更的临时数据
+ */
+class PetStatusTempDto
+{
+    /**
+     * 宠物ID
+     *
+     * @var int
+     */
+    public int $petId;
+
+    /**
+     * 旧状态
+     *
+     * @var int
+     */
+    public int $oldStatus;
+
+    /**
+     * 新状态
+     *
+     * @var int
+     */
+    public int $newStatus;
+
+    /**
+     * 变更原因
+     *
+     * @var string
+     */
+    public string $reason;
+
+    /**
+     * 附加数据
+     *
+     * @var array
+     */
+    public array $data;
+
+    /**
+     * 更新时间戳
+     *
+     * @var int
+     */
+    public int $updatedAt;
+
+    /**
+     * 从数组创建DTO对象
+     *
+     * @param array $data 宠物状态变更数据数组
+     * @return self
+     */
+    public static function fromArray(array $data): self
+    {
+        $dto = new self();
+        $dto->petId = $data['pet_id'];
+        $dto->oldStatus = $data['old_status'];
+        $dto->newStatus = $data['new_status'];
+        $dto->reason = $data['reason'];
+        $dto->data = $data['data'];
+        $dto->updatedAt = $data['updated_at'];
+        return $dto;
+    }
+
+    /**
+     * 转换为数组
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        return [
+            'pet_id' => $this->petId,
+            'old_status' => $this->oldStatus,
+            'new_status' => $this->newStatus,
+            'reason' => $this->reason,
+            'data' => $this->data,
+            'updated_at' => $this->updatedAt,
+        ];
+    }
+}

app/Module/Game/Logics/ItemTemp.php

@@ -2,6 +2,7 @@
 
 namespace App\Module\Game\Logics;
 
+use App\Module\Game\Dtos\ItemChangeTempDto;
 use App\Module\GameItems\Events\ItemQuantityChanged;
 use Illuminate\Support\Facades\Log;
 use UCore\Helper\Cache;
@@ -80,13 +81,19 @@ class ItemTemp
      * 获取用户的物品变更临时数据
      *
      * @param int $userId 用户ID
-     * @return array 用户的物品变更数据
+     * @return ItemChangeTempDto[] 用户的物品变更数据
      */
     public static function getUserItemChanges(int $userId): array
     {
         $tempKey = self::TEMP_KEY_PREFIX . $userId;
+        $rawData = Cache::get($tempKey, []);
 
-        return Cache::get($tempKey, []);
+        $result = [];
+        foreach ($rawData as $itemId => $itemData) {
+            $result[$itemId] = ItemChangeTempDto::fromArray($itemData);
+        }
+
+        return $result;
     }
 
     /**
@@ -94,9 +101,9 @@ class ItemTemp
      *
      * @param int $userId 用户ID
      * @param int $itemId 物品ID
-     * @return array|null 物品变更数据，不存在时返回null
+     * @return ItemChangeTempDto|null 物品变更数据，不存在时返回null
      */
-    public static function getUserItemChange(int $userId, int $itemId): ?array
+    public static function getUserItemChange(int $userId, int $itemId): ?ItemChangeTempDto
     {
         $userItemChanges = self::getUserItemChanges($userId);
 

app/Module/Game/Logics/PetTemp.php

@@ -2,6 +2,8 @@
 
 namespace App\Module\Game\Logics;
 
+use App\Module\Game\Dtos\PetCreatedTempDto;
+use App\Module\Game\Dtos\PetStatusTempDto;
 use App\Module\Pet\Events\PetCreatedEvent;
 use App\Module\Pet\Events\PetStatusChangedEvent;
 use Illuminate\Support\Facades\Log;
@@ -131,12 +133,19 @@ class PetTemp
      * 获取用户的宠物创建临时数据
      *
      * @param int $userId 用户ID
-     * @return array 用户的宠物创建数据
+     * @return PetCreatedTempDto[] 用户的宠物创建数据
      */
     public static function getUserPetCreated(int $userId): array
     {
         $tempKey = self::TEMP_KEY_CREATED_PREFIX . $userId;
-        return Cache::get($tempKey, []);
+        $rawData = Cache::get($tempKey, []);
+
+        $result = [];
+        foreach ($rawData as $petId => $petData) {
+            $result[$petId] = PetCreatedTempDto::fromArray($petData);
+        }
+
+        return $result;
     }
 
     /**
@@ -144,9 +153,9 @@ class PetTemp
      *
      * @param int $userId 用户ID
      * @param int $petId 宠物ID
-     * @return array|null 宠物创建数据，不存在时返回null
+     * @return PetCreatedTempDto|null 宠物创建数据，不存在时返回null
      */
-    public static function getUserPetCreatedById(int $userId, int $petId): ?array
+    public static function getUserPetCreatedById(int $userId, int $petId): ?PetCreatedTempDto
     {
         $userPetCreated = self::getUserPetCreated($userId);
         return $userPetCreated[$petId] ?? null;
@@ -156,12 +165,19 @@ class PetTemp
      * 获取用户的宠物状态变更临时数据
      *
      * @param int $userId 用户ID
-     * @return array 用户的宠物状态变更数据
+     * @return PetStatusTempDto[] 用户的宠物状态变更数据
      */
     public static function getUserPetStatus(int $userId): array
     {
         $tempKey = self::TEMP_KEY_STATUS_PREFIX . $userId;
-        return Cache::get($tempKey, []);
+        $rawData = Cache::get($tempKey, []);
+
+        $result = [];
+        foreach ($rawData as $petId => $petData) {
+            $result[$petId] = PetStatusTempDto::fromArray($petData);
+        }
+
+        return $result;
     }
 
     /**
@@ -169,9 +185,9 @@ class PetTemp
      *
      * @param int $userId 用户ID
      * @param int $petId 宠物ID
-     * @return array|null 宠物状态变更数据，不存在时返回null
+     * @return PetStatusTempDto|null 宠物状态变更数据，不存在时返回null
      */
-    public static function getUserPetStatusById(int $userId, int $petId): ?array
+    public static function getUserPetStatusById(int $userId, int $petId): ?PetStatusTempDto
     {
         $userPetStatus = self::getUserPetStatus($userId);
         return $userPetStatus[$petId] ?? null;

app/Module/Game/Services/ItemTempService.php

@@ -2,21 +2,22 @@
 
 namespace App\Module\Game\Services;
 
+use App\Module\Game\Dtos\ItemChangeTempDto;
 use App\Module\Game\Logics\ItemTemp;
 use Illuminate\Support\Facades\Log;
 
 /**
  * 物品临时数据服务类
- * 
+ *
  * 提供物品临时数据相关的服务方法，用于外部调用
  */
 class ItemTempService
 {
     /**
      * 获取用户的物品变更临时数据
-     * 
+     *
      * @param int $userId 用户ID
-     * @return array 用户的物品变更数据
+     * @return ItemChangeTempDto[] 用户的物品变更数据
      */
     public function getUserItemChanges(int $userId): array
     {
@@ -30,15 +31,15 @@ class ItemTempService
             return [];
         }
     }
-    
+
     /**
      * 获取用户特定物品的变更临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @param int $itemId 物品ID
-     * @return array|null 物品变更数据，不存在时返回null
+     * @return ItemChangeTempDto|null 物品变更数据，不存在时返回null
      */
-    public function getUserItemChange(int $userId, int $itemId): ?array
+    public function getUserItemChange(int $userId, int $itemId): ?ItemChangeTempDto
     {
         try {
             return ItemTemp::getUserItemChange($userId, $itemId);
@@ -51,10 +52,10 @@ class ItemTempService
             return null;
         }
     }
-    
+
     /**
      * 清除用户的物品变更临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @return bool 操作是否成功
      */

app/Module/Game/Services/PetTempService.php

@@ -2,21 +2,23 @@
 
 namespace App\Module\Game\Services;
 
+use App\Module\Game\Dtos\PetCreatedTempDto;
+use App\Module\Game\Dtos\PetStatusTempDto;
 use App\Module\Game\Logics\PetTemp;
 use Illuminate\Support\Facades\Log;
 
 /**
  * 宠物临时数据服务类
- * 
+ *
  * 提供宠物临时数据相关的服务方法，用于外部调用
  */
 class PetTempService
 {
     /**
      * 获取用户的宠物创建临时数据
-     * 
+     *
      * @param int $userId 用户ID
-     * @return array 用户的宠物创建数据
+     * @return PetCreatedTempDto[] 用户的宠物创建数据
      */
     public function getUserPetCreated(int $userId): array
     {
@@ -30,15 +32,15 @@ class PetTempService
             return [];
         }
     }
-    
+
     /**
      * 获取用户特定宠物的创建临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @param int $petId 宠物ID
-     * @return array|null 宠物创建数据，不存在时返回null
+     * @return PetCreatedTempDto|null 宠物创建数据，不存在时返回null
      */
-    public function getUserPetCreatedById(int $userId, int $petId): ?array
+    public function getUserPetCreatedById(int $userId, int $petId): ?PetCreatedTempDto
     {
         try {
             return PetTemp::getUserPetCreatedById($userId, $petId);
@@ -51,12 +53,12 @@ class PetTempService
             return null;
         }
     }
-    
+
     /**
      * 获取用户的宠物状态变更临时数据
-     * 
+     *
      * @param int $userId 用户ID
-     * @return array 用户的宠物状态变更数据
+     * @return PetStatusTempDto[] 用户的宠物状态变更数据
      */
     public function getUserPetStatus(int $userId): array
     {
@@ -70,15 +72,15 @@ class PetTempService
             return [];
         }
     }
-    
+
     /**
      * 获取用户特定宠物的状态变更临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @param int $petId 宠物ID
-     * @return array|null 宠物状态变更数据，不存在时返回null
+     * @return PetStatusTempDto|null 宠物状态变更数据，不存在时返回null
      */
-    public function getUserPetStatusById(int $userId, int $petId): ?array
+    public function getUserPetStatusById(int $userId, int $petId): ?PetStatusTempDto
     {
         try {
             return PetTemp::getUserPetStatusById($userId, $petId);
@@ -91,10 +93,10 @@ class PetTempService
             return null;
         }
     }
-    
+
     /**
      * 清除用户的宠物创建临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @return bool 操作是否成功
      */
@@ -111,10 +113,10 @@ class PetTempService
             return false;
         }
     }
-    
+
     /**
      * 清除用户的宠物状态变更临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @return bool 操作是否成功
      */
@@ -131,10 +133,10 @@ class PetTempService
             return false;
         }
     }
-    
+
     /**
      * 清除用户的所有宠物临时数据
-     * 
+     *
      * @param int $userId 用户ID
      * @return bool 操作是否成功
      */

app/Module/Pet/DEV.md

@@ -1,514 +0,0 @@
-# 宠物模块开发计划
-
-## 1. 当前状态分析
-
-宠物模块已经完成了基础框架的搭建，包括：
-
-- 数据库表结构设计和SQL文件生成
-- 基础模型类定义
-- 枚举类定义（PetGrade、PetStatus）
-- 事件类定义（PetBattleEvent、PetLevelUpEvent、PetRemouldEvent、PetSkillUsedEvent、PetStatusChangedEvent）
-- 部分监听器实现（ItemChangedListener、LoginSuccessListener）
-- 后台管理控制器实现
-- 仓库类基础结构
-
-目前模块处于初始阶段，核心业务逻辑尚未实现，包括服务层、逻辑层、验证器等。
-
-## 2. 开发目标
-
-完成宠物模块的核心功能实现，包括：
-
-1. 宠物基础功能：创建、升级、喂养、洗髓
-2. 宠物技能系统：技能解锁、使用、冷却
-3. 与其他模块的集成：物品系统、农场系统、任务系统
-
-注：宠物战斗系统和争霸赛系统暂不开发
-
-## 3. 开发计划
-
-### 3.1 第一阶段：核心服务和逻辑实现（当前）
-
-#### 3.1.1 服务层实现
-
-- [x] **PetService**：对外提供宠物相关服务
-  - [x] 获取用户宠物列表
-  - [x] 创建宠物
-  - [x] 宠物升级
-  - [x] 宠物喂养
-  - [x] 宠物洗髓
-  - [x] 宠物技能使用
-  - [x] 宠物状态管理
-
-#### 3.1.2 逻辑层实现
-
-- [x] **PetLogic**：内部宠物逻辑处理
-  - [x] 宠物创建逻辑
-  - [x] 宠物升级逻辑
-  - [x] 宠物经验计算
-  - [x] 宠物体力恢复
-  - [x] 宠物状态变更
-  - [x] 宠物技能逻辑
-  - [x] 宠物洗髓逻辑
-
-#### 3.1.3 验证器实现
-
-- [x] **PetCreateValidator**：宠物创建验证
-  - [x] 宠物名称验证
-  - [x] 宠物数量限制验证
-
-- [x] **PetLevelUpValidator**：宠物升级验证
-  - [x] 宠物状态验证
-  - [x] 宠物经验验证
-
-- [x] **PetFeedValidator**：宠物喂养验证
-  - [x] 宠物状态验证
-  - [x] 物品类型验证
-
-- [x] **PetRemouldValidator**：宠物洗髓验证
-  - [x] 宠物状态验证
-  - [x] 洗髓道具验证
-
-- [x] **PetSkillUseValidator**：宠物技能使用验证
-  - [x] 技能使用条件验证
-  - [x] 技能冷却验证
-
-- [x] **PetStatusChangeValidator**：宠物状态变更验证
-  - [x] 状态变更规则验证
-
-- [x] **PetFoodValidator**：宠物口粮验证
-  - [x] 根据物品属性判断是否为宠物口粮
-
-### 3.2 第二阶段：事件系统完善
-
-#### 3.2.1 事件系统实现
-
-- [x] **对内监听器**：监听其他模块的事件
-  - [x] **ItemChangedListener**：监听物品变更事件，处理宠物口粮和洗髓道具
-  - [x] **LoginSuccessListener**：监听登录成功事件，处理宠物体力恢复等
-
-- [x] **对外事件**：提供给其他模块监听的事件
-  - [x] **PetStatusChangedEvent**：宠物状态变更事件
-  - [x] **PetLevelUpEvent**：宠物升级事件
-  - [x] **PetRemouldEvent**：宠物洗髓事件
-  - [x] **PetSkillUsedEvent**：宠物技能使用事件
-
-#### 3.2.2 事件注册
-
-- [x] 在PetServiceProvider中注册模块间通信的事件和监听器
-
-### 3.3 第三阶段：宠物技能系统完善
-
-- [ ] **技能效果实现**：实现各种宠物技能效果
-- [ ] **技能解锁机制**：完善技能解锁条件和机制
-- [ ] **技能冷却管理**：优化技能冷却时间管理
-- [ ] **技能使用记录**：完善技能使用记录和统计
-
-### 3.4 第四阶段：与其他模块集成
-
-- [ ] 与物品模块集成：狗粮、洗髓道具等物品处理
-- [ ] 与农场模块集成：宠物技能对农场的影响
-- [ ] 与任务模块集成：宠物相关任务
-
-### 3.5 第五阶段：测试和优化
-
-- [ ] 单元测试编写
-- [ ] 性能优化
-- [ ] 代码重构和优化
-
-## 4. 当前任务
-
-### 4.1 优先实现的功能
-
-1. **宠物技能系统**：完善宠物技能功能
-   - 技能效果实现
-   - 技能解锁机制
-   - 技能冷却管理
-   - 技能使用记录
-
-2. **与农场模块集成**：实现宠物技能对农场的影响
-   - 自动收菜技能
-   - 自动播种技能
-   - 灾害防护技能
-
-3. **与物品模块集成**：完善物品使用效果
-   - 宠物口粮使用效果
-   - 洗髓道具使用效果
-   - 技能道具使用效果
-
-### 4.2 具体实现步骤
-
-1. 完善PetLogic类中的技能效果实现
-2. 实现与农场模块的接口调用
-3. 完善ItemChangedListener，处理更多物品类型
-4. 优化宠物状态管理和事件处理
-5. 添加更多宠物技能类型和效果
-
-## 5. 开发进度跟踪
-
-| 功能模块 | 状态 | 开始日期 | 完成日期 | 备注 |
-|---------|------|---------|---------|------|
-| 数据库设计 | 已完成 | - | - | 包括10个数据表 |
-| 模型定义 | 已完成 | - | - | 包括10个模型类 |
-| 枚举定义 | 已完成 | - | - | PetGrade、PetStatus |
-| 事件定义 | 已完成 | - | - | 5个事件类 |
-| 监听器 | 已完成 | - | - | 已实现5个监听器 |
-| 后台控制器 | 已完成 | - | - | 10个控制器 |
-| 仓库类 | 已完成 | - | - | 10个仓库类 |
-| 服务层 | 已完成 | - | - | 已实现PetService |
-| 逻辑层 | 已完成 | - | - | 已实现PetLogic |
-| 验证器 | 已完成 | - | - | 已实现7个验证器 |
-| 技能系统 | 部分完成 | - | - | 已实现基础功能 |
-| 与其他模块集成 | 部分完成 | - | - | 已实现物品变更监听 |
-
-## 6. 下一步工作计划
-
-1. 完善宠物技能系统
-   - 实现更多技能效果
-   - 优化技能解锁机制
-   - 完善技能冷却管理
-
-2. 加强与农场模块的集成
-   - 实现自动收菜技能
-   - 实现自动播种技能
-   - 实现灾害防护技能
-
-3. 完善与物品模块的集成
-   - 增加更多宠物口粮类型
-   - 增加更多洗髓道具效果
-   - 增加技能道具系统
-
-4. 优化宠物状态管理
-   - 完善状态变更逻辑
-   - 增加状态效果系统
-   - 优化状态变更事件处理
-
-## 7. 注意事项
-
-1. 所有模型类中需要保持无业务逻辑，业务逻辑应放在逻辑层
-2. 服务层类中的所有方法应该是静态方法，对外提供服务
-3. 服务层不负责事务管理，调用方需要自行开启和管理事务
-4. 验证器类应单独实现，不应在模型中进行验证
-5. 事件用于模块间通信，模块内部不应使用事件机制
-6. 宠物模块与物品模块的集成应通过监听物品变更事件实现
-7. 宠物口粮验证应根据物品的pet_power/pet_exp属性判断
-
-## 8. 宠物模块与其他模块的交互
-
-### 8.1 与物品模块的交互
-
-- **监听物品变更事件**：处理宠物口粮、洗髓道具等物品的变更
-- **调用物品服务**：消耗宠物口粮、洗髓道具等物品
-
-### 8.2 与农场模块的交互
-
-- **提供宠物技能服务**：供农场模块调用宠物技能
-- **监听农场事件**：响应农场中的特定事件（如灾害发生）
-
-### 8.3 与任务模块的交互
-
-- **提供宠物状态查询服务**：供任务模块检查宠物相关任务条件
-- **触发任务完成事件**：当宠物达成特定条件时
-
-## 9. 宠物技能系统详细设计
-
-### 9.1 技能类型
-
-1. **自动收菜**：消耗50点体力，冷却2小时，自动收获成熟作物
-2. **自动播种**：消耗50点体力，冷却4小时，自动补种空闲土地
-3. **灾害防护**：消耗30点体力，冷却6小时，防止指定类型自然灾害
-
-### 9.2 技能解锁条件
-
-- **自动收菜**：宠物等级≥5
-- **自动播种**：宠物等级≥10
-- **灾害防护**：宠物等级≥15
-
-### 9.3 技能效果实现
-
-- **自动收菜**：调用农场模块的收获接口
-- **自动播种**：调用农场模块的播种接口
-- **灾害防护**：设置农场模块的灾害防护标志
-
-## 10. 宠物争霸赛系统详细设计
-
-### 10.1 赛季管理
-
-- 赛季创建、开始、结束
-- 奖池设置
-- Boss战力设置
-
-### 10.2 队伍管理
-
-- 队伍创建、解散
-- 成员加入、退出
-- 队伍战力计算
-
-### 10.3 战斗系统
-
-- Boss战斗机制
-- 伤害计算
-- 战斗结果记录
-
-### 10.4 奖励分配
-
-- 首胜奖励模式
-- 伤害占比奖励模式
-- 奖励发放机制
-
-## 11. 宠物喂养系统详细设计
-
-### 11.1 喂养机制
-
-- **普通狗粮**：提供基础经验值
-- **优质狗粮**：提供双倍经验值
-- **特殊狗粮**：提供额外属性加成
-
-### 11.2 喂养效果
-
-- **经验获取**：根据狗粮类型和品质获得不同经验值
-- **体力恢复**：部分狗粮可以恢复宠物体力
-- **状态变更**：喂养过程中宠物状态变为FEEDING
-
-### 11.3 喂养限制
-
-- **冷却时间**：每次喂养后有短暂冷却时间
-- **每日上限**：每日喂养次数有上限
-- **体力消耗**：喂养过程消耗少量体力
-
-## 12. 宠物洗髓系统详细设计
-
-### 12.1 洗髓机制
-
-- **消耗资源**：钻石或特定道具
-- **概率计算**：根据配置的品阶概率进行随机
-- **品阶变更**：可能提升或降低品阶
-
-### 12.2 洗髓效果
-
-- **属性重置**：根据新品阶重新计算属性加成
-- **技能影响**：部分技能可能受品阶影响
-- **外观变化**：不同品阶可能有不同外观
-
-### 12.3 洗髓记录
-
-- **记录保存**：每次洗髓结果记录到pet_remould_logs表
-- **历史查询**：玩家可查看历史洗髓记录
-
-## 13. 宠物战斗系统详细设计
-
-### 13.1 战斗类型
-
-- **偷菜战斗**：宠物参与偷取其他玩家农场作物的战斗
-- **守护战斗**：宠物守护自己农场的战斗
-- **争霸赛战斗**：宠物参与争霸赛的战斗
-
-### 13.2 战力计算
-
-- **基础战力**：根据宠物等级和品阶计算
-- **属性加成**：根据宠物数值属性计算加成
-- **品阶加成**：不同品阶有不同战力加成系数
-- **装备加成**：特殊装备可提供额外战力
-
-### 13.3 战斗结果计算
-
-- **偷菜战斗**：根据攻守双方战力差计算成功率
-- **守护战斗**：根据守护宠物战力计算防御成功率
-- **争霸赛战斗**：根据队伍总战力与Boss战力对比计算伤害
-
-### 13.4 战斗奖励
-
-- **偷菜战斗**：获得作物、经验值
-- **守护战斗**：获得守护奖励、经验值
-- **争霸赛战斗**：根据伤害排名获得奖池奖励
-
-## 14. 宠物模块实现计划
-
-### 14.1 第一周：基础功能实现
-
-| 日期 | 计划任务 | 负责人 |
-|------|---------|-------|
-| 第1天 | 实现PetService基础方法 | - |
-| 第2天 | 实现PetLogic基础逻辑 | - |
-| 第3天 | 实现PetValidator验证器 | - |
-| 第4天 | 实现PetFoodValidator验证器 | - |
-| 第5天 | 完善事件监听器 | - |
-
-### 14.2 第二周：技能系统实现
-
-| 日期 | 计划任务 | 负责人 |
-|------|---------|-------|
-| 第1天 | 实现PetSkillLogic基础逻辑 | - |
-| 第2天 | 实现技能解锁机制 | - |
-| 第3天 | 实现技能冷却管理 | - |
-| 第4天 | 实现技能效果 | - |
-| 第5天 | 与农场模块集成 | - |
-
-### 14.3 第三周：战斗系统实现
-
-| 日期 | 计划任务 | 负责人 |
-|------|---------|-------|
-| 第1天 | 实现PetBattleLogic基础逻辑 | - |
-| 第2天 | 实现战力计算 | - |
-| 第3天 | 实现战斗结果计算 | - |
-| 第4天 | 实现战斗奖励发放 | - |
-| 第5天 | 完善战斗记录 | - |
-
-### 14.4 第四周：争霸赛系统实现
-
-| 日期 | 计划任务 | 负责人 |
-|------|---------|-------|
-| 第1天 | 实现赛季管理 | - |
-| 第2天 | 实现队伍管理 | - |
-| 第3天 | 实现Boss战斗机制 | - |
-| 第4天 | 实现奖励分配 | - |
-| 第5天 | 系统测试与优化 | - |
-
-## 15. 接口设计
-
-### 15.1 服务层接口
-
-```php
-// PetService.php
-class PetService
-{
-    // 获取用户宠物列表
-    public static function getUserPets(int $userId): array;
-
-    // 创建宠物
-    public static function createPet(int $userId, string $name): array;
-
-    // 宠物升级
-    public static function levelUpPet(int $userId, int $petId): array;
-
-    // 宠物喂养
-    public static function feedPet(int $userId, int $petId, int $itemId, int $amount = 1): array;
-
-    // 宠物洗髓
-    public static function remouldPet(int $userId, int $petId, int $itemId = 0): array;
-
-    // 使用宠物技能
-    public static function useSkill(int $userId, int $petId, int $skillId, array $params = []): array;
-
-    // 获取宠物状态
-    public static function getPetStatus(int $userId, int $petId): array;
-
-    // 更新宠物状态
-    public static function updatePetStatus(int $userId, int $petId, int $status, string $reason = ''): bool;
-}
-
-// PetBattleService.php
-class PetBattleService
-{
-    // 获取战斗记录
-    public static function getBattleLogs(int $userId, int $petId, int $page = 1, int $pageSize = 20): array;
-
-    // 发起战斗
-    public static function startBattle(int $userId, int $petId, int $battleType, int $targetId = 0): array;
-
-    // 获取战斗结果
-    public static function getBattleResult(int $battleId): array;
-
-    // 获取当前赛季信息
-    public static function getCurrentSeason(): array;
-
-    // 创建/加入队伍
-    public static function joinTeam(int $userId, int $petId, int $teamId = 0, string $teamName = ''): array;
-
-    // 退出队伍
-    public static function leaveTeam(int $userId, int $petId): bool;
-
-    // 获取队伍信息
-    public static function getTeamInfo(int $teamId): array;
-}
-```
-
-### 15.2 逻辑层接口
-
-```php
-// PetLogic.php
-class PetLogic
-{
-    // 创建宠物
-    public static function createPet(int $userId, string $name): array;
-
-    // 宠物升级
-    public static function levelUpPet(int $petId): array;
-
-    // 计算宠物经验
-    public static function calculateExp(int $petId, int $expGain): array;
-
-    // 恢复宠物体力
-    public static function recoverStamina(int $petId, int $minutes): int;
-
-    // 变更宠物状态
-    public static function changeStatus(int $petId, int $status, string $reason = ''): bool;
-}
-
-// PetSkillLogic.php
-class PetSkillLogic
-{
-    // 检查技能是否解锁
-    public static function checkSkillUnlocked(int $petId, int $skillId): bool;
-
-    // 管理技能冷却
-    public static function manageSkillCooldown(int $petId, int $skillId): array;
-
-    // 执行技能效果
-    public static function executeSkillEffect(int $petId, int $skillId, array $params = []): array;
-}
-```
-
-## 16. 数据结构示例
-
-### 16.1 宠物数据结构
-
-```json
-{
-  "id": 1,
-  "user_id": 1001,
-  "name": "小松狮",
-  "grade": "THIRD",
-  "level": 15,
-  "experience": 2500,
-  "stamina": 85,
-  "status": 1,
-  "created_at": "2023-05-01 10:00:00",
-  "updated_at": "2023-05-05 15:30:00"
-}
-```
-
-### 16.2 技能数据结构
-
-```json
-{
-  "id": 1,
-  "skill_name": "自动收菜",
-  "stamina_cost": 50,
-  "cool_down": 7200,
-  "effect_desc": "自动收获成熟作物",
-  "min_level": 5,
-  "created_at": "2023-05-01 10:00:00",
-  "updated_at": "2023-05-01 10:00:00"
-}
-```
-
-### 16.3 战斗记录数据结构
-
-```json
-{
-  "id": 1,
-  "pet_id": 1,
-  "battle_type": 1,
-  "opponent_id": 2,
-  "result": 1,
-  "reward": {
-    "exp": 100,
-    "items": [
-      {"id": 1001, "amount": 2},
-      {"id": 1002, "amount": 1}
-    ]
-  },
-  "battle_time": "2023-05-05 14:30:00",
-  "created_at": "2023-05-05 14:30:00"
-}
-```

app/Module/Pet/Docs/事件系统.md

@@ -158,14 +158,68 @@
 | useSkill | Farm | 使用宠物技能 | userId, petId, skillId, params | bool |
 | checkPetCondition | Quest | 检查宠物条件 | userId, petId, conditionType | bool |
 
-## 5. 总结
+## 5. 宠物暂存系统
 
-宠物模块通过两种方式与其他模块交互：事件系统和服务调用。
+宠物模块与 Game 模块集成，使用 Game 模块提供的暂存系统来存储和传输宠物变更数据。
+
+### 5.1 事件与暂存系统的关系
+
+宠物模块触发的事件会被 Game 模块的事件监听器捕获，并将相关数据暂存起来：
+
+| 宠物模块事件 | Game 模块监听器 | 暂存数据类型 |
+|------------|-----------------|------------|
+| PetCreatedEvent | PetCreatedListener | PetCreatedTempDto |
+| PetStatusChangedEvent | PetStatusChangedListener | PetStatusTempDto |
+
+### 5.2 暂存数据结构
+
+Game 模块使用 DTO 对象来存储和传输宠物数据：
+
+**PetCreatedTempDto**：宠物创建临时数据传输对象
+```php
+class PetCreatedTempDto
+{
+    public int $petId;        // 宠物ID
+    public string $name;      // 宠物名称
+    public int $grade;        // 宠物品阶
+    public int $level;        // 宠物等级
+    public int $createdAt;    // 创建时间戳
+}
+```
+
+**PetStatusTempDto**：宠物状态变更临时数据传输对象
+```php
+class PetStatusTempDto
+{
+    public int $petId;        // 宠物ID
+    public int $oldStatus;    // 旧状态
+    public int $newStatus;    // 新状态
+    public string $reason;    // 变更原因
+    public array $data;       // 附加数据
+    public int $updatedAt;    // 更新时间戳
+}
+```
+
+### 5.3 应用场景
+
+宠物暂存系统的主要应用场景包括：
+
+- **宠物获取动画**：当用户获取新宠物时，前端可以显示宠物获取动画
+- **宠物状态变更提示**：当宠物状态变化时，前端可以显示变更提示
+- **喜养效果展示**：当用户喜养宠物时，前端可以显示经验值和体力值增加的动画效果
+- **升级提示**：当宠物经验值达到升级条件时，前端可以显示升级提示
+
+## 6. 总结
+
+宠物模块通过三种方式与其他模块交互：事件系统、服务调用和暂存系统。
 
 **事件系统**用于处理非核心业务流程，如通知、日志、统计等。模块发出的事件包括宠物技能使用事件、宠物升级事件、宠物洗髓事件和宠物战斗事件；模块监听的事件包括物品变更事件和登录成功事件。
 
 **服务调用**用于处理核心业务流程，如农场模块调用宠物模块的服务来使用宠物技能。这种方式保持了代码流程的清晰和可控，同时减少了模块间的耦合。
 
+**暂存系统**用于存储和传输宠物变更数据，优化前端UI更新和提高用户体验。宠物模块触发的事件会被 Game 模块捕获，并将相关数据暂存起来，供前端获取和使用。
+
 在开发过程中，应该根据具体需求选择合适的交互方式：
 - 对于核心业务流程，优先使用服务调用
 - 对于非核心业务流程，优先使用事件系统
+- 对于前端实时反馈，使用暂存系统

app/Module/Pet/Events/PetCreatedEvent.php

@@ -9,7 +9,7 @@ use Illuminate\Queue\SerializesModels;
 
 /**
  * 宠物创建事件
- * 
+ *
  * 当新宠物被创建时触发此事件，允许其他系统响应宠物的创建。
  * 此事件可用于记录宠物创建日志、更新用户状态、处理新手引导等。
  */
@@ -41,9 +41,9 @@ class PetCreatedEvent
     /**
      * 宠物品阶
      *
-     * @var PetGrade
+     * @var int
      */
-    public PetGrade $grade;
+    public int $grade;
 
     /**
      * 宠物等级
@@ -58,11 +58,11 @@ class PetCreatedEvent
      * @param int $userId 用户ID
      * @param int $petId 宠物ID
      * @param string $name 宠物名称
-     * @param PetGrade $grade 宠物品阶
+     * @param int $grade 宠物品阶
      * @param int $level 宠物等级
      * @return void
      */
-    public function __construct(int $userId, int $petId, string $name, PetGrade $grade, int $level = 1)
+    public function __construct(int $userId, int $petId, string $name, int $grade, int $level = 1)
     {
         $this->userId = $userId;
         $this->petId = $petId;

app/Module/Pet/README.md

@@ -392,8 +392,42 @@ return [
 - **用户模块**：宠物系统需要关联用户信息
 - **农场模块**：宠物技能作用于农场系统
 - **任务模块**：宠物相关任务需要与任务系统集成
+- **Game模块**：宠物模块依赖Game模块的暂存系统来存储和传输宠物变更数据
 
-## 7. 总结
+## 7. 宠物暂存系统
+
+宠物暂存系统是由Game模块提供的一个用于跟踪和记录用户宠物变更的临时存储机制，主要用于优化前端UI更新和提高用户体验。
+
+### 7.1 事件触发
+
+宠物模块在以下情况下触发事件：
+
+- **PetCreatedEvent**：当新宠物被创建时触发
+- **PetStatusChangedEvent**：当宠物状态发生变化时触发
+
+### 7.2 数据结构
+
+Game模块使用DTO对象来存储和传输宠物数据：
+
+- **PetCreatedTempDto**：宠物创建临时数据传输对象
+- **PetStatusTempDto**：宠物状态变更临时数据传输对象
+
+### 7.3 应用场景
+
+- **宠物获取动画**：当用户获取新宠物时，前端可以显示宠物获取动画
+- **宠物状态变更提示**：当宠物状态变化时，前端可以显示变更提示
+- **喜养效果展示**：当用户喜养宠物时，前端可以显示经验值和体力值增加的动画效果
+- **升级提示**：当宠物经验值达到升级条件时，前端可以显示升级提示
+
+### 7.4 重要属性
+
+宠物模型中的重要属性：
+
+- **experience**（经验值）：宠物的经验值，用于衡量宠物的成长进度。当经验值达到一定阈值时，宠物可以升级。
+
+- **stamina**（体力值）：宠物的体力值，表示宠物可以执行活动的能力。宠物进行某些活动（如战斗、工作等）会消耗体力值，通过喜养等方式可以恢复宠物的体力值。
+
+## 8. 总结
 
 宠物模块是游戏中重要的伙伴系统，为玩家提供了丰富的互动体验和游戏玩法。本文档详细描述了宠物系统的各个方面，包括：
 
@@ -405,10 +439,15 @@ return [
 3. **等级系统**：通过 pet_level_configs 表定义宠物成长曲线和等级特性
 4. **配置参数**：详细的系统配置参数，支持灵活调整游戏平衡性
 5. **争霸赛系统**：团队竞技玩法，增强社交互动和游戏竞争性
+6. **暂存系统**：与 Game 模块集成的宠物暂存系统，提供宠物变更的实时反馈
 
 宠物系统的数据表结构清晰：
 - **基础表**：pet_users、pet_skills、pet_configs、pet_level_configs
 - **日志表**：pet_skill_logs、pet_remould_logs、pet_battle_logs
 - **争霸赛相关表**：pet_battle_seasons、pet_battle_teams、pet_battle_team_members
 
+宠物模块与其他模块的集成：
+- **物品模块**：使用物品模块管理狗粮和洗髓道具
+- **Game模块**：使用Game模块的暂存系统存储宠物变更数据
+
 通过宠物系统，玩家可以培养自己的宠物伙伴，参与各种游戏活动，增强游戏的趣味性和粘性。系统设计注重数据完整性、性能优化和扩展性，为后续功能迭代提供了良好的基础。