feat: 实现英雄局外成长系统

1. 新增GameEvent事件枚举HERO_GROWTH_UPDATE
2. 新增英雄局外升级所需碎片配置表
3. 新增英雄局外成长数据持久化与相关工具方法
4. 重构英雄卡片等级逻辑，统一使用局外成长等级
5. 更新英雄设计文档与相关注释

assets/script/game/common/SingletonModuleComp.ts

@@ -33,12 +33,24 @@ export interface GameDate {
     switch_effect?: boolean, // 音效开关
     switch_music?: boolean,  // 音乐开关
     timestamp?: number, // 用于比对本地与云端数据的最新状态
+    /** 英雄局外成长数据：key 为英雄 uuid，value 为成长记录 */
+    hero_growth?: Record<number, HeroGrowthRecord>,
 }
 export interface CloudData {
     openid: string;
     data: GameDate;
 }
 
+/** 英雄局外成长记录 */
+export interface HeroGrowthRecord {
+    /** 英雄模板 uuid（对应 heroSet.HeroInfo 的 key） */
+    uuid: number;
+    /** 当前局外等级（从 1 开始） */
+    lv: number;
+    /** 当前拥有的英雄碎片数量 */
+    fragments: number;
+}
+
 /**
  * 死亡英雄快照：英雄真实死亡时记录，供后续复活机制（重新召唤）消费。
  * 仅记录静态/成长数据，不含战斗内临时状态（buff、CD 等）。
@@ -97,6 +109,8 @@ export class SingletonModuleComp extends ecs.Comp {
             skill: false,   // 购买技能卷轴面板按钮
             shop: false,    // 购买药品面板按钮
         },
+        /** 英雄局外成长数据：记录每个英雄的局外等级与碎片数量 */
+        hero_growth: {} as Record<number, HeroGrowthRecord>,
     }
 
     vmdata: any = {
@@ -302,6 +316,56 @@ export class SingletonModuleComp extends ecs.Comp {
         }
     }
 
+    // ==================== 英雄局外成长 ====================
+
+    /**
+     * 获取英雄局外成长记录；若不存在则初始化并返回
+     * @param uuid 英雄模板 uuid
+     */
+    getHeroGrowth(uuid: number): HeroGrowthRecord {
+        if (!this.data.hero_growth) this.data.hero_growth = {};
+        if (!this.data.hero_growth[uuid]) {
+            this.data.hero_growth[uuid] = { uuid, lv: 1, fragments: 0 };
+        }
+        return this.data.hero_growth[uuid];
+    }
+
+    /**
+     * 获取英雄局外等级（未初始化时返回 1）
+     * @param uuid 英雄模板 uuid
+     */
+    getHeroOuterLv(uuid: number): number {
+        return this.getHeroGrowth(uuid).lv;
+    }
+
+    /**
+     * 增加英雄碎片
+     * @param uuid 英雄模板 uuid
+     * @param count 增加的碎片数量（正数）
+     */
+    addHeroFragments(uuid: number, count: number): void {
+        const growth = this.getHeroGrowth(uuid);
+        growth.fragments = Math.max(0, growth.fragments + count);
+        gameDataSync.markDataDirty();
+        oops.message.dispatchEvent(GameEvent.HERO_GROWTH_UPDATE);
+    }
+
+    /**
+     * 消耗碎片提升英雄局外等级
+     * @param uuid 英雄模板 uuid
+     * @param needFragments 本次升级所需碎片数量（由外部配置表计算）
+     * @returns 是否升级成功
+     */
+    upgradeHero(uuid: number, needFragments: number): boolean {
+        const growth = this.getHeroGrowth(uuid);
+        if (growth.fragments < needFragments) return false;
+        growth.fragments -= needFragments;
+        growth.lv += 1;
+        gameDataSync.markDataDirty();
+        oops.message.dispatchEvent(GameEvent.HERO_GROWTH_UPDATE);
+        return true;
+    }
+
     /**
      * 在游戏载入早期调用，预加载常用图集
      */