# 宠物模块开发计划

## 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"
}
```