XtGameKit/openspec/changes/port-rok-hero-bag-system/specs/hero-system/spec.md

ADDED Requirements

Requirement: Hero Entity 数据模型

系统 MUST 为每个英雄实例提供一个 Hero 实体，挂在玩家的 HeroComponent 下。每个 Hero 实体 MUST 持有以下基础字段：英雄 configId、当前等级、当前经验、当前星级、当前升星经验、招募时间、击杀数、技能等级数组（5 个槽位）、当前天赋页索引、3 套天赋树数据、8 个装备槽引用。

Scenario: 创建一个新英雄

• WHEN 服务端处理 C2G_SummonHero 成功后
• THEN 在玩家 HeroComponent 下创建一个新的 Hero Entity，等级初始为 1、经验为 0、星级为 configId 对应 HeroConfig 的 initStar、所有技能等级为 1、装备槽为空
• AND 新 Hero Entity 的 Id 是分布式唯一 ID
• AND 服务端 MUST 推送 Hero_HeroInfo 给客户端

Scenario: 查询英雄数据

• WHEN 客户端通过 HeroComponent.GetHero(heroId) 查询
• THEN 返回对应 Hero Entity；若不存在返回 null

Requirement: 英雄招募

玩家 MUST 能通过消耗碎片道具招募一个新英雄。招募 MUST 满足以下条件：碎片数量 >= HeroConfig.getItemNum；玩家未达到当前英雄招募上限（HeroConfig.getLimit）；玩家未已持有该英雄（每个英雄唯一）。

Scenario: 招募成功

• WHEN 玩家碎片足够且未持有该英雄
• AND 客户端发送 C2G_SummonHero { configId }
• THEN 服务端扣除 HeroConfig.getItemNum 数量的对应碎片
• AND 创建新 Hero Entity
• AND 返回 R2C_SummonHero { error: 0, hero: HeroInfo }
• AND 推送 Item_ItemInfo 同步碎片数量变化

Scenario: 碎片不足招募失败

• WHEN 玩家碎片数量 < HeroConfig.getItemNum
• THEN 服务端 MUST 拒绝并返回 R2C_SummonHero { error: ItemNotEnough }
• AND 不扣道具、不创建英雄

Scenario: 重复招募已有英雄

• WHEN 玩家已持有该 configId 的英雄
• THEN 服务端 MUST 拒绝并返回 R2C_SummonHero { error: HeroAlreadyOwned }

Requirement: 英雄经验升级

玩家 MUST 能消耗经验道具提升英雄等级。系统 MUST 强制以下约束：等级上限受当前星级约束（Hero.level <= StarConfig.starLimit）；经验溢出 MUST 顺延到下一级；满级时溢出经验 MUST 被丢弃。

Scenario: 单次升级

• WHEN 玩家发送 C2G_HeroAddExp { heroId, itemId, count }
• AND 玩家拥有足够道具，且英雄未到星级限定等级
• THEN 服务端按 ItemConfig.exp * count 累加经验
• AND 经验超过 HeroLevelConfig.exp 时升级（可连升）
• AND 推送更新后的 Hero_HeroInfo + Item_ItemInfo

Scenario: 满级丢弃溢出

• WHEN 英雄已达星级等级上限
• THEN 服务端 MUST 拒绝升级请求或保持经验不增长，返回相应错误码

Requirement: 英雄升星

玩家 MUST 能消耗"升星材料"道具提升英雄星级。每次提交 MUST 累加升星经验 Hero.starExp，达到阈值后升星，并提供"幸运暴击"机制（按 HeroStarExpConfig.lucky 概率多算经验）。

Scenario: 升星积累经验

• WHEN 玩家发送 C2G_HeroStarUp { heroId, itemId, count }
• THEN 服务端按 HeroStarExpConfig.exp 计算经验值，乘以幸运系数
• AND 累加到 Hero.starExp
• AND 若 starExp >= HeroStarConfig.starExpRequired 则 star += 1，starExp -= 该阈值

Scenario: 满星拒绝

• WHEN Hero.star >= HeroConfig.star（最大星级）
• THEN 服务端 MUST 拒绝升星请求并返回 StarMaxLevel

Requirement: 英雄技能升级

每个英雄 MUST 有 5 个技能槽（前 4 个初始解锁、第 5 个需觉醒解锁）。玩家 MUST 能消耗指定材料按等级升级单个技能；技能等级 MUST 受 HeroSkillConfig.maxLevel 上限约束。

Scenario: 升级第 1-4 技能

• WHEN 玩家发送 C2G_HeroSkillUp { heroId, skillIndex } 且 skillIndex ∈ [0,3]
• AND 拥有 HeroSkillLevelConfig.costItem（按英雄稀有度选择不同 costItem 字段）
• THEN 服务端扣道具，技能等级 +1
• AND 推送 Hero_HeroInfo 更新

Scenario: 升级第 5 技能要求觉醒

• WHEN 玩家发送 C2G_HeroSkillUp { heroId, skillIndex: 4 }
• AND Hero.isAwakening == false
• THEN 服务端 MUST 拒绝并返回 NeedAwakening

Requirement: 英雄觉醒

玩家 MUST 在前 4 个技能全部满级时才能觉醒英雄。觉醒后 Hero.isAwakening = true，解锁第 5 个技能（initial level = 1）。

Scenario: 觉醒成功

• WHEN 玩家发送 C2G_HeroAwake { heroId }
• AND Hero 前 4 个技能都达到 HeroSkillConfig.maxLevel
• AND 玩家拥有觉醒材料道具
• THEN 服务端扣道具，设置 Hero.isAwakening = true，第 5 技能等级置 1
• AND 推送 Hero_HeroInfo

Scenario: 觉醒前置不满足

• WHEN 前 4 个技能未全部满级
• THEN 拒绝并返回 SkillNotMaxBeforeAwake

Requirement: 天赋树

每个英雄 MUST 有 3 套天赋页（pageIndex 0/1/2），玩家 MUST 能：当前页学习/升级单个天赋；切换当前页（消耗道具或钻石）；重置某一页天赋（返还点数）。

Scenario: 学习天赋

• WHEN 玩家发送 C2G_TalentUp { heroId, pageIndex, talentNodeId }
• AND 当前天赋页剩余点数 >= 该节点消耗
• AND 满足前置节点依赖（HeroTalentDefine 中定义）
• THEN 服务端扣减剩余点数，节点等级 +1
• AND 推送 Hero_HeroInfo 更新 talentTrees[pageIndex]

Scenario: 切换天赋页

• WHEN 玩家发送 C2G_ChangeTalentIndex { heroId, targetIndex }
• THEN 服务端按规则扣消耗（道具或钻石）
• AND 更新 Hero.talentIndex = targetIndex

Scenario: 重置天赋

• WHEN 玩家发送 C2G_ResetTalent { heroId, pageIndex }
• THEN 服务端清空该页所有节点等级
• AND 返还消耗的点数（或按规则按比例返还道具）

Requirement: 英雄属性与战力计算

系统 MUST 提供英雄"总战力"计算，等于：baseScore + levelScore + skillScore + talentScore + equipScore。每个分项 MUST 可独立计算：

• baseScore = HeroConfig.score
• levelScore = HeroLevelConfig(rareGroup, lv).score
• skillScore = 5 个技能各自 HeroSkillEffectConfig(skillId, level).score 之和
• talentScore = 已学习天赋节点 score 之和
• equipScore = 已穿戴装备的属性折算 score（由 equipment-system 提供接口）

Scenario: 计算单个英雄战力

• WHEN 客户端调用 HeroExtensions.GetPower(hero)
• THEN 返回 5 个分项之和

Scenario: 计算所有英雄总战力

• WHEN 客户端调用 HeroComponentExtensions.GetTotalPower()
• THEN 返回所有 Hero Entity 的战力之和

Requirement: 英雄排序与筛选

客户端 MUST 提供英雄排序能力，支持以下排序类型：Rare（稀有度）/ Star（星级）/ Level（等级）/ Power（战力）/ Recomend（推荐分）。排序 MUST 输出三个分组：已拥有 / 可召唤（碎片够但未招募）/ 未集齐。

Scenario: 按战力排序已拥有列表

• WHEN 客户端调用 HeroComponentExtensions.GetHerosBySort(SortType.Power)
• THEN 返回 (ownedList, canSummonList, fragmentList) 三个列表
• AND ownedList 按战力降序排列
• AND canSummonList 包含所有 碎片数 >= getItemNum && !已拥有 && !达到招募上限 的英雄

Requirement: 英雄红点

系统 MUST 提供以下红点接口（基于 cn.etetet.yiuireddot 包）：

• 有英雄可招募
• 有英雄有技能可升级（道具足够升满）
• 有英雄装备可升级
• 有英雄天赋有剩余点数

Scenario: 检测可招募英雄红点

• WHEN 客户端访问 HeroComponentExtensions.GetCanSummonHeroCount()
• THEN 返回当前可立即招募的英雄数量

Scenario: 检测可升级技能红点

• WHEN 客户端访问 HeroComponentExtensions.GetCanSkillUpHeroCount()
• THEN 返回当前任一英雄存在"道具足够升一级且未满级"的技能时计数 + 1

Requirement: 客户端英雄数据同步

客户端 HeroComponent MUST 持有服务端推送的全部英雄数据快照。任何 Hero_HeroInfo 推送 MUST：若 heroId 已存在则更新；若不存在则创建新缓存。

Scenario: 全量同步（登录后）

• WHEN 玩家登录成功，服务端发送 Hero_HeroInfoList { heroes }
• THEN 客户端 HeroComponent 清空旧缓存
• AND 为每个 HeroInfo 创建客户端 Hero Entity 缓存
• AND 触发 OnHeroListUpdated 事件

Scenario: 增量同步

• WHEN 服务端推送 Hero_HeroInfo { hero }
• THEN 客户端找到对应缓存并更新
• AND 触发 OnHeroUpdated(heroId) 事件