# 宠物模块开发文档

> 宠物模块，宠物属性、技能、战斗、宠物争霸赛

## 1. 宠物系统功能
### 1.1 宠物属性系统
- **品阶体系**：4个品阶（FIRST 60%/SECOND 25%/THIRD 10%/FOURTH 5%）
- **成长属性**：
  - 等级：1-30级
  - 体力值：0-100（每分钟恢复5点）
  - 数值属性：随等级提升而增长
- **喂养机制**：
  - 普通狗粮：提升基础经验
  - 优质狗粮：提供双倍经验

### 1.2 品阶系统
```php
enum PetGrade: string {
    case FIRST = 'FIRST';   // 一品
    case SECOND = 'SECOND'; // 二品
    case THIRD = 'THIRD';   // 三品
    case FOURTH = 'FOURTH'; // 四品
}
```

### 1.3 宠物状态系统
```php
enum PetStatus: int {
    case NONE = 0;      // 未知
    case NORMAL = 1;    // 正常
    case FIGHTING = 2;  // 战斗中
    case DEAD = 3;      // 死亡
}
```

### 1.4 技能系统
| 技能名称    | 消耗体力 | 冷却时间 | 开启条件       | 效果描述               |
|------------|---------|---------|---------------|-----------------------|
| 自动收菜    | 50      | 2小时    | 等级≥5        | 自动收获成熟作物        |
| 自动播种    | 50      | 4小时    | 等级≥10       | 自动补种空闲土地        |
| 灾害防护    | 30      | 6小时    | 等级≥15       | 防止指定类型自然灾害    |

## 2. 数据库设计
### 2.1 数据表概览

| 表名 | 主要功能 | 关键字段 |
|------|---------|---------|
| pet_users | 用户宠物信息 | id, user_id, name, grade, level |
| pet_skills | 技能配置 | id, skill_name, stamina_cost, cool_down |
| pet_skill_logs | 技能使用记录 | id, pet_id, skill_id, used_at |
| pet_remould_logs | 洗髓记录 | id, pet_id, old_grade, new_grade |
| pet_configs | 宠物系统配置 | id, pet_type, grade_probability, feed_effect, display_attributes, numeric_attributes |
| pet_level_configs | 等级配置 | id, level, exp_required, stamina_max, display_attributes, numeric_attributes |
| pet_battle_logs | 战斗记录 | id, pet_id, battle_type, result |
| pet_battle_seasons | 争霸赛赛季 | id, name, start_time, end_time, boss_power |
| pet_battle_teams | 争霸赛队伍 | id, season_id, name, leader_id, total_power |
| pet_battle_team_members | 争霸赛队伍成员 | id, team_id, user_id, pet_id, power |

### 2.2 数据表结构

#### 2.2.1 基础表

```sql

-- 用户宠物表
CREATE TABLE `pet_users` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `name` VARCHAR(20) NOT NULL COMMENT '宠物名称',
  `grade` ENUM('FIRST','SECOND','THIRD','FOURTH') NOT NULL,
  `level` TINYINT UNSIGNED DEFAULT 1,
  `experience` INT UNSIGNED DEFAULT 0,
  `stamina` SMALLINT UNSIGNED DEFAULT 100,
  `status` TINYINT UNSIGNED DEFAULT 1 COMMENT '宠物状态：0未知，1正常，2战斗中，3死亡',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  INDEX idx_user (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 技能配置表
CREATE TABLE `pet_skills` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `skill_name` VARCHAR(50) NOT NULL COMMENT '技能名称',
  `stamina_cost` SMALLINT NOT NULL COMMENT '体力消耗',
  `cool_down` INT COMMENT '冷却时间(秒)',
  `effect_desc` TEXT COMMENT '效果描述',
  `min_level` TINYINT UNSIGNED DEFAULT 1 COMMENT '最低等级要求',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id)
) ENGINE=InnoDB;

-- 宠物配置表
CREATE TABLE `pet_configs` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `pet_type` VARCHAR(50) NOT NULL COMMENT '宠物类型',
  `grade_probability` JSON NOT NULL COMMENT '品阶概率配置',
  `feed_effect` JSON NOT NULL COMMENT '喂养效果配置',
  `max_level` TINYINT UNSIGNED NOT NULL COMMENT '最大等级',
  `stamina_recovery` SMALLINT UNSIGNED NOT NULL COMMENT '体力恢复值/分钟',
  `display_attributes` JSON DEFAULT NULL COMMENT '显示属性配置',
  `numeric_attributes` JSON DEFAULT NULL COMMENT '数值属性配置',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY idx_pet_type (pet_type)
) ENGINE=InnoDB;

-- 宠物等级配置表
CREATE TABLE `pet_level_configs` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `level` TINYINT UNSIGNED NOT NULL COMMENT '等级',
  `exp_required` INT UNSIGNED NOT NULL COMMENT '升级所需经验值',
  `stamina_max` SMALLINT UNSIGNED NOT NULL DEFAULT 100 COMMENT '最大体力值',
  `stamina_recovery_rate` TINYINT UNSIGNED NOT NULL DEFAULT 5 COMMENT '每分钟恢复体力值',
  `unlock_skills` JSON DEFAULT NULL COMMENT '解锁的技能ID列表',
  `display_attributes` JSON DEFAULT NULL COMMENT '等级显示属性配置',
  `numeric_attributes` JSON DEFAULT NULL COMMENT '等级数值属性配置',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY idx_level (level)
) ENGINE=InnoDB;
```

#### 2.2.2 日志表

```sql

-- 技能使用日志表
CREATE TABLE `pet_skill_logs` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `pet_id` BIGINT UNSIGNED NOT NULL,
  `skill_id` INT UNSIGNED NOT NULL,
  `used_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `effect_result` JSON COMMENT '技能使用结果',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  FOREIGN KEY (pet_id) REFERENCES pet_users(id),
  FOREIGN KEY (skill_id) REFERENCES pet_skills(id),
  INDEX idx_pet_skill (pet_id, skill_id)
) ENGINE=InnoDB;

-- 洗髓记录表
CREATE TABLE `pet_remould_logs` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `pet_id` BIGINT UNSIGNED NOT NULL,
  `old_grade` ENUM('FIRST','SECOND','THIRD','FOURTH'),
  `new_grade` ENUM('FIRST','SECOND','THIRD','FOURTH'),
  `remould_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  FOREIGN KEY (pet_id) REFERENCES pet_users(id),
  INDEX idx_pet (pet_id)
) ENGINE=InnoDB;

-- 战斗记录表
CREATE TABLE `pet_battle_logs` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `pet_id` BIGINT UNSIGNED NOT NULL,
  `battle_type` TINYINT UNSIGNED NOT NULL COMMENT '战斗类型：1偷菜，2守护，3争霸赛',
  `opponent_id` BIGINT UNSIGNED COMMENT '对手ID（可为空）',
  `result` TINYINT UNSIGNED NOT NULL COMMENT '战斗结果：0失败，1胜利',
  `reward` JSON COMMENT '战斗奖励',
  `battle_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  FOREIGN KEY (pet_id) REFERENCES pet_users(id),
  INDEX idx_pet (pet_id),
  INDEX idx_battle_time (battle_time)
) ENGINE=InnoDB;
```

#### 2.2.3 争霸赛相关表

```sql

-- 争霸赛赛季表
CREATE TABLE `pet_battle_seasons` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `name` VARCHAR(50) NOT NULL COMMENT '赛季名称',
  `start_time` TIMESTAMP NOT NULL COMMENT '开始时间',
  `end_time` TIMESTAMP NOT NULL COMMENT '结束时间',
  `boss_power` INT UNSIGNED NOT NULL COMMENT 'Boss战力',
  `reward_pool` JSON NOT NULL COMMENT '奖池配置',
  `status` TINYINT UNSIGNED DEFAULT 0 COMMENT '状态：0未开始，1进行中，2已结束',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  INDEX idx_status (status),
  INDEX idx_time (start_time, end_time)
) ENGINE=InnoDB;

-- 争霸赛队伍表
CREATE TABLE `pet_battle_teams` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `season_id` INT UNSIGNED NOT NULL COMMENT '赛季ID',
  `name` VARCHAR(50) NOT NULL COMMENT '队伍名称',
  `leader_id` BIGINT UNSIGNED NOT NULL COMMENT '队长用户ID',
  `total_power` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '队伍总战力',
  `member_count` TINYINT UNSIGNED DEFAULT 0 COMMENT '成员数量',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  FOREIGN KEY (season_id) REFERENCES pet_battle_seasons(id),
  INDEX idx_season (season_id),
  INDEX idx_leader (leader_id)
) ENGINE=InnoDB;

-- 争霸赛队伍成员表
CREATE TABLE `pet_battle_team_members` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `team_id` INT UNSIGNED NOT NULL COMMENT '队伍ID',
  `user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户ID',
  `pet_id` BIGINT UNSIGNED NOT NULL COMMENT '宠物ID',
  `power` INT UNSIGNED NOT NULL COMMENT '战力贡献',
  `join_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  FOREIGN KEY (team_id) REFERENCES pet_battle_teams(id),
  FOREIGN KEY (pet_id) REFERENCES pet_users(id),
  UNIQUE KEY idx_team_user (team_id, user_id),
  INDEX idx_pet (pet_id)
) ENGINE=InnoDB;
```

### 2.3 索引设计

| 表名 | 索引字段 | 索引类型 | 说明 |
| --- | --- | --- | --- |
| pet_users | id | 主键 | 宠物ID主键索引 |
| pet_users | user_id | 普通索引 | 加速用户宠物查询 |
| pet_users | status | 普通索引 | 加速按状态查询宠物 |
| pet_skills | id | 主键 | 技能ID主键索引 |
| pet_skill_logs | pet_id, skill_id | 复合索引 | 加速查询宠物技能使用记录 |
| pet_remould_logs | pet_id | 普通索引 | 加速查询宠物洗髓记录 |
| pet_level_configs | id | 主键 | 等级配置ID主键索引 |
| pet_level_configs | level | 唯一索引 | 确保等级唯一性，加速等级查询 |
| pet_battle_logs | pet_id | 普通索引 | 加速查询宠物战斗记录 |
| pet_battle_logs | battle_time | 普通索引 | 加速按时间查询战斗记录 |
| pet_battle_seasons | status | 普通索引 | 加速按状态查询赛季 |
| pet_battle_seasons | start_time, end_time | 复合索引 | 加速按时间范围查询赛季 |
| pet_battle_teams | season_id | 普通索引 | 加速查询赛季队伍 |
| pet_battle_teams | leader_id | 普通索引 | 加速查询队长创建的队伍 |
| pet_battle_team_members | team_id, user_id | 唯一索引 | 确保用户在一个队伍中只有一个宠物 |
| pet_battle_team_members | pet_id | 普通索引 | 加速查询宠物参与的队伍 |

### 2.4 数据模型关联关系

以下是主要数据模型之间的关联关系：

1. **用户与宠物关系**
   - 用户可以拥有多个宠物，通过 pet_users 表关联
   - 每个宠物只属于一个用户

2. **宠物与技能关系**
   - 宠物可以使用多个技能，通过 pet_skill_logs 表记录使用历史
   - 技能配置在 pet_skills 表中定义

3. **宠物与战斗关系**
   - 宠物可以参与多种战斗，通过 pet_battle_logs 表记录
   - 战斗类型包括偷菜、守护和争霸赛

4. **争霸赛关系链**
   - 赛季(pet_battle_seasons) → 队伍(pet_battle_teams) → 队员(pet_battle_team_members)
   - 每个赛季可以有多个队伍，每个队伍可以有多个队员

### 2.5 宠物等级系统

宠物等级配置表(pet_level_configs)用于定义每个等级的详细信息，包括：

- **升级所需经验**：达到下一级所需的经验值
- **最大体力值**：该等级的体力上限
- **体力恢复速率**：每分钟恢复的体力点数
- **解锁技能**：达到该等级时解锁的技能列表
- **显示属性**：等级相关的UI显示属性，如等级图标、特效等
- **数值属性**：等级相关的游戏数值属性，如攻击力、防御力等

#### 2.5.1 显示属性

宠物配置表(pet_configs)中的显示属性用于定义宠物类型的UI展示相关配置，如：
```json
{
  "icon": "pet_icon_001.png",
  "avatar": "pet_avatar_001.png",
  "animation": "pet_anim_001",
  "ui_color": "#FF5500",
  "description": "一只勤劳的宠物，擅长收集资源"
}
```

#### 2.5.2 数值属性

宠物配置表和等级配置表中的数值属性用于定义宠物的游戏数值相关配置，如：
```json
{
  "base_attack": 10,
  "base_defense": 5,
  "base_speed": 8,
  "harvest_efficiency": 1.2,
  "planting_speed": 1.0,
  "disaster_resistance": 0.8
}
```

通过这些配置表，可以灵活调整宠物成长曲线，平衡游戏难度，并提供丰富的视觉体验和游戏玩法。

## 3. 配置参数
```php
// config/pet.php
return [
    // 宠物基础配置
    'max_level' => 30,                  // 最大等级
    'stamina_recovery' => 5,            // 每分钟恢复体力
    'stamina_max' => 100,               // 最大体力值

    // 技能冷却时间配置（秒）
    'skill_cooltime' => [
        'harvest' => 7200,              // 自动收菜：2小时
        'plant' => 14400,               // 自动播种：4小时
        'protect' => 21600              // 灾害防护：6小时
    ],

    // 洗髓相关配置
    'remould_cost' => [
        'diamond' => 50,                // 洗髓消耗钻石
        'item_id' => 1001               // 洗髓道具ID
    ],

    // 品阶概率配置
    'grade_probability' => [
        'FIRST' => 0.6,                 // 一品阶：60%
        'SECOND' => 0.25,               // 二品阶：25%
        'THIRD' => 0.1,                 // 三品阶：10%
        'FOURTH' => 0.05                // 四品阶：5%
    ],

    // 品阶数值属性加成
    'grade_attribute_bonus' => [
        'FIRST' => 0.1,                 // 一品阶：+10%
        'SECOND' => 0.25,               // 二品阶：+25%
        'THIRD' => 0.5,                 // 三品阶：+50%
        'FOURTH' => 1.0                 // 四品阶：+100%
    ],

    // 争霸赛配置
    'battle_royale' => [
        'min_team_size' => 5,           // 最小队伍人数
        'max_team_size' => 10,          // 最大队伍人数
        'min_power_threshold' => 1000,  // 最低战力要求
        'reward_distribution' => 'top_n' // 奖励分配方式：first_win或top_n
    ]
];
```

## 4. 松狮争霸赛系统
### 4.1 基本规则
- **参与条件**：需5-10人组队，团队战力总和达到Boss战力阈值
- **胜利条件**：
  - 方案1：首支击败Boss队伍获得全部奖池
  - 方案2：前N名队伍按伤害占比瓜分奖池
- **奖池内容**：钻石、高级狗粮、特殊种子

### 4.2 战力系统
- 影响偷菜、守护、争霸赛等玩法结果
- 提升方式：
  - 提升宠物等级（通过数值属性提升战力）
  - 提升品阶（一品阶+10%、二品阶+25%、三品阶+50%、四品阶+100%）
  - 使用特定道具

### 4.3 争霸赛数据结构

争霸赛相关的数据表已在数据库设计章节中详细描述，包括：
- pet_battle_seasons（争霸赛赛季表）
- pet_battle_teams（争霸赛队伍表）
- pet_battle_team_members（争霸赛队伍成员表）

这些表共同构成了争霸赛系统的数据基础，支持赛季管理、队伍组建和成员管理等功能。

## 5. 关键改进
1. **数据完整性**：完善外键约束和索引配置
2. **错误修复**：修正枚举定义中的拼写错误
3. **文档规范**：统一SQL和PHP代码格式
4. **功能完善**：优化洗髓功能设计
5. **结构调整**：移除狗粮库存表，使用物品系统管理狗粮
6. **新增功能**：实现松狮争霸赛战斗逻辑
7. **表名规范**：所有宠物模块相关表统一使用 pet_ 前缀
8. **状态管理**：增加宠物状态系统，支持多种状态转换

## 6. 模块依赖关系
- **物品模块**：宠物系统依赖物品模块管理狗粮和其他消耗品
- **用户模块**：宠物系统需要关联用户信息
- **农场模块**：宠物技能作用于农场系统
- **任务模块**：宠物相关任务需要与任务系统集成
- **Game模块**：宠物模块依赖Game模块的暂存系统来存储和传输宠物变更数据

## 7. 宠物暂存系统

宠物暂存系统是由Game模块提供的一个用于跟踪和记录用户宠物变更的临时存储机制，主要用于优化前端UI更新和提高用户体验。

### 7.1 事件触发

宠物模块在以下情况下触发事件：

- **PetCreatedEvent**：当新宠物被创建时触发
- **PetStatusChangedEvent**：当宠物状态发生变化时触发

### 7.2 数据结构

Game模块使用DTO对象来存储和传输宠物数据：

- **PetCreatedTempDto**：宠物创建临时数据传输对象
- **PetStatusTempDto**：宠物状态变更临时数据传输对象

### 7.3 应用场景

- **宠物获取动画**：当用户获取新宠物时，前端可以显示宠物获取动画
- **宠物状态变更提示**：当宠物状态变化时，前端可以显示变更提示
- **喜养效果展示**：当用户喜养宠物时，前端可以显示经验值和体力值增加的动画效果
- **升级提示**：当宠物经验值达到升级条件时，前端可以显示升级提示

### 7.4 重要属性

宠物模型中的重要属性：

- **experience**（经验值）：宠物的经验值，用于衡量宠物的成长进度。当经验值达到一定阈值时，宠物可以升级。

- **stamina**（体力值）：宠物的体力值，表示宠物可以执行活动的能力。宠物进行某些活动（如战斗、工作等）会消耗体力值，通过喜养等方式可以恢复宠物的体力值。

## 8. 总结

宠物模块是游戏中重要的伙伴系统，为玩家提供了丰富的互动体验和游戏玩法。本文档详细描述了宠物系统的各个方面，包括：

1. **基础功能**：宠物属性系统、品阶系统、状态系统和技能系统
2. **数据库设计**：
   - 所有表名统一使用 pet_ 前缀
   - 数据表分为基础表、日志表和争霸赛相关表
   - 完善的索引设计和外键约束
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模块的暂存系统存储宠物变更数据

通过宠物系统，玩家可以培养自己的宠物伙伴，参与各种游戏活动，增强游戏的趣味性和粘性。系统设计注重数据完整性、性能优化和扩展性，为后续功能迭代提供了良好的基础。