宠物暂存系统

最后更新时间：2023年12月

1. 概述

宠物暂存系统是 Game 模块提供的一个用于跟踪和记录用户宠物变更的临时存储机制，主要用于优化前端UI更新和提高用户体验。当用户宠物状态发生变化或新宠物被创建时，系统会将变更信息暂时存储，前端可以通过API获取这些变更信息，从而实现宠物变更的实时反馈。

2. 系统架构

宠物暂存系统由以下几个部分组成：

2.1 事件类（来自 Pet 模块）

PetCreatedEvent: 宠物创建事件，当新宠物被创建时触发。只包含userId和petId属性。
PetStatusChangedEvent: 宠物状态变更事件，当宠物状态发生变化时触发。

2.2 DTO 类

PetCreatedTempDto: 宠物创建临时数据传输对象，用于存储和传输宠物创建的临时数据。
PetStatusTempDto: 宠物状态变更临时数据传输对象，用于存储和传输宠物状态变更的临时数据。

2.3 监听器（在 Game 模块中实现）

PetCreatedListener: 监听宠物创建事件，并调用逻辑层处理临时数据。
PetStatusChangedListener: 监听宠物状态变更事件，并调用逻辑层处理临时数据。

2.4 逻辑层

PetTemp: 宠物临时数据逻辑类，负责处理宠物相关事件的临时数据存储逻辑。

2.5 服务层

PetTempService: 宠物临时数据服务类，提供宠物临时数据相关的服务方法，用于外部调用。

3. 工作流程

事件触发：当宠物被创建或状态发生变化时，Pet 模块会触发相应的事件。
事件监听：Game 模块中的监听器监听到事件后，会调用 PetTemp 类的方法处理临时数据。
数据暂存：PetTemp 类将宠物数据临时存储，按用户ID和宠物ID进行存储，同一宠物多次变更会覆盖之前的数据。
数据获取：前端或其他模块可以通过 PetTempService 提供的方法获取用户的宠物临时数据。
数据清理：当不再需要临时数据时，可以通过 PetTempService 提供的方法清除用户的宠物临时数据。

4. 临时数据结构

4.1 宠物创建临时数据 (PetCreatedTempDto)

class PetCreatedTempDto
{
    public int $petId;        // 宠物ID
    public string $name;      // 宠物名称
    public int $grade;        // 宠物品阶
    public int $level;        // 宠物等级
    public int $createdAt;    // 创建时间戳
}

注意：虽然PetCreatedEvent事件只包含userId和petId属性，但在处理事件时，系统会从数据库中获取宠物的完整信息，并填充到PetCreatedTempDto中。

4.2 宠物状态变更临时数据 (PetStatusTempDto)

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。
宠物状态变更临时数据键前缀：game:pet:status:，后接用户ID，如 game:pet:status:123。
临时数据过期时间：默认为3600秒（1小时）。

6. 使用示例

6.1 获取用户的宠物创建临时数据

$petTempService = new PetTempService();
$petCreated = $petTempService->getUserPetCreated($userId);

// 使用DTO对象的属性
$petId = $petCreated[1]->petId;
$petName = $petCreated[1]->name;
$petGrade = $petCreated[1]->grade;

6.2 获取用户特定宠物的创建临时数据

$petTempService = new PetTempService();
$petCreated = $petTempService->getUserPetCreatedById($userId, $petId);

// 判断宠物是否存在
$petExists = $petCreated !== null;

6.3 获取用户的宠物状态变更临时数据

$petTempService = new PetTempService();
$petStatus = $petTempService->getUserPetStatus($userId);

// 遍历所有宠物状态
 foreach ($petStatus as $petId => $statusDto) {
    echo "宠物ID: {$statusDto->petId}, 新状态: {$statusDto->newStatus}\n";
}

6.4 获取用户特定宠物的状态变更临时数据

$petTempService = new PetTempService();
$petStatus = $petTempService->getUserPetStatusById($userId, $petId);

// 获取状态变更原因
$reason = $petStatus ? $petStatus->reason : null;

6.5 清除用户的宠物临时数据

$petTempService = new PetTempService();
$petTempService->clearUserAllPetTemp($userId);

7. 优势和应用场景

7.1 优势

减少数据库查询：通过临时存储宠物变更数据，减少了前端需要查询数据库的次数。
提高用户体验：前端可以实时获取宠物变更信息，提供更好的用户反馈。
优化性能：使用临时存储机制存储数据，减轻了数据库负担，提高了系统性能。
简化前端逻辑：前端只需要获取临时数据，无需自行计算宠物变更。

7.2 应用场景

宠物获取动画：当用户获取新宠物时，前端可以根据临时数据显示宠物获取动画。
宠物状态变更提示：当宠物状态变化时，前端可以显示变更提示。
宠物列表更新：当用户宠物列表发生变化时，前端可以实时更新宠物列表界面。
任务进度更新：当用户完成与宠物相关的任务时，前端可以更新任务进度。
喜养效果展示：当用户喜养宠物时，前端可以显示经验值和体力值增加的动画效果。
升级提示：当宠物经验值达到升级条件时，前端可以显示升级提示。

8. 注意事项

数据过期：临时数据有过期时间，过期后数据会被自动清除。
数据一致性：临时数据可能与数据库不一致，需要定期同步或在关键操作后清除临时数据。
数据大小：临时数据不应过大，否则会占用过多内存。
错误处理：临时数据操作可能失败，需要妥善处理异常情况。

宠物暂存系统.md 6.6 KB Historia Czysty