docs: 为游戏地图模块添加详细的代码注释

为游戏地图模块的脚本文件添加全面的注释，说明每个组件的职责、关键设计、依赖关系和使用方式。注释覆盖了英雄信息面板、技能卡槽位管理器、排行榜弹窗、卡牌控制器、背景滚动组件等核心功能模块，提高了代码的可读性和维护性。

同时修复了英雄预制体的激活状态和技能效果预制体的尺寸参数。

assets/script/game/map/VictoryComp.ts

@@ -1,3 +1,23 @@
+/**
+ * @file VictoryComp.ts
+ * @description 战斗结算弹窗组件（UI 视图层）
+ *
+ * 职责：
+ *   1. 在战斗结束时弹出，展示结算信息（得分、奖励）。
+ *   2. 根据传入参数判断是否可复活，切换"下一步"或"复活"按钮。
+ *   3. 计算单局总分并存储到 smc.vmdata.scores.score。
+ *   4. 提供"重新开始"和"退出"两个操作入口。
+ *
+ * 关键设计：
+ *   - onAdded(args) 接收战斗结果参数（victory / rewards / game_data / can_revive）。
+ *   - calculateTotalScore() 根据 ScoreWeights 配置加权计算各项得分。
+ *   - restart() 和 victory_end() 通过分发 MissionEnd / MissionStart 事件驱动游戏状态切换。
+ *
+ * 依赖：
+ *   - smc.vmdata.scores —— 全局战斗统计数据
+ *   - ScoreWeights（ScoreSet）—— 得分权重配置
+ *   - GameEvent.MissionEnd / MissionStart —— 游戏生命周期事件
+ */
 import { _decorator, instantiate, Label ,Prefab,Node} from "cc";
 import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
 import { CCComp } from "../../../../extensions/oops-plugin-framework/assets/module/common/CCComp";
@@ -14,31 +34,48 @@ import { mLogger } from "../common/Logger";
 
 const { ccclass, property } = _decorator;
 
-/** 视图层对象 */
+/**
+ * VictoryComp —— 战斗结算弹窗视图组件
+ *
+ * 通过 oops.gui.open(UIID.Victory, args) 打开。
+ * 展示战斗结果，计算总分，并提供重开 / 退出操作。
+ */
 @ccclass('VictoryComp')
 @ecs.register('Victory', false)
 export class VictoryComp extends CCComp {
+    /** 调试日志开关 */
     debugMode: boolean = false;
+    /** 奖励等级（预留） */
     reward_lv:number=1
+    /** 奖励数量（预留） */
     reward_num:number=2
+    /** 掉落奖励列表 */
     rewards:any[]=[]
+    /** 累计游戏数据（经验 / 金币 / 钻石） */
     game_data:any={
         exp:0,
         gold:0,
         diamond:0
     }
     
-    // 复活相关配置
-    private canRevive: boolean = false; // 是否可以复活（由MissionComp传入）
-    // private reviveCount: number = 0;   // 已复活次数 - 移交 MissionComp 管理
+    // ======================== 复活相关 ========================
 
-    /** 视图层逻辑代码分离演示 */
+    /** 是否可以复活（由 MissionComp 传入，取决于剩余复活次数） */
+    private canRevive: boolean = false;
+
+    /** 加载时隐藏 loading 遮罩 */
     protected onLoad(): void {
         this.node.getChildByName("loading").active=false
-        // this.canRevive = true;
-        // this.reviveCount = 0;
     }
 
+    /**
+     * 弹窗打开时的回调：接收战斗结果参数。
+     *
+     * @param args.victory    是否胜利（当前仅用于标识）
+     * @param args.rewards    掉落奖励列表
+     * @param args.game_data  累计数据 { exp, gold, diamond }
+     * @param args.can_revive 是否可复活
+     */
     onAdded(args: any) {
         this.node.getChildByName("loading").active=false
         mLogger.log(this.debugMode, 'VictoryComp', "[VictoryComp] onAdded",args)
@@ -46,25 +83,24 @@ export class VictoryComp extends CCComp {
             this.game_data=args.game_data
         }
 
-        // // 接收复活参数
-        // if (args.can_revive !== undefined) {
-        //     this.canRevive = args.can_revive;
-        // } else {
-        //     this.canRevive = false; // 默认不可复活
-        // }
-
+        // 根据是否可复活决定按钮显示
         this.node.getChildByName("btns").getChildByName("next").active=!args.can_revive
-        // this.node.getChildByName("btns").getChildByName("alive").active=args.can_revive
 
-        // 只有在不能复活（彻底结算）时才计算总分
-        // if (!this.canRevive) {
-            
-        // }
+        // 计算总分
         this.calculateTotalScore();
     }
 
+    // ======================== 得分计算 ========================
+
     /**
-     * 计算单局总分并更新到 smc.scores.score
+     * 计算单局总分并更新到 smc.vmdata.scores.score。
+     *
+     * 得分维度：
+     *   1. 战斗行为分 —— 暴击次数、连击触发、闪避、格挡、眩晕、冻结
+     *   2. 伤害转化分 —— 总伤害、平均伤害、反伤、暴击伤害
+     *   3. 击杀得分 —— 近战击杀、远程击杀、精英击杀、Boss 击杀
+     *   4. 生存得分 —— 治疗量、吸血量
+     *   5. 资源得分 —— 经验获取、金币获取
      */
     private calculateTotalScore() {
         const s = smc.vmdata.scores;
@@ -98,31 +134,44 @@ export class VictoryComp extends CCComp {
         totalScore += s.exp_total * ScoreWeights.EXP_FACTOR;
         totalScore += s.gold_total * ScoreWeights.GOLD_FACTOR;
 
-        // 更新总分（向下取整）
+        // 取整并存储
         s.score = Math.floor(totalScore);
         mLogger.log(this.debugMode, 'VictoryComp', `[VictoryComp] 结算总分: ${s.score}`);
     }
 
+    // ======================== 操作入口 ========================
 
+    /** 退出战斗：清理数据 → 触发任务结束 → 关闭弹窗 */
     victory_end(){
         this.clear_data()
         oops.message.dispatchEvent(GameEvent.MissionEnd)
         oops.gui.removeByNode(this.node)
     }
+
+    /** 清理运行时数据：解除暂停标志 */
     clear_data(){
         smc.mission.pause=false
     }
-    //看广告双倍
+
+    /** 看广告双倍奖励（预留） */
     watch_ad(){
         return true
     }
+
+    /** 双倍奖励发放（预留） */
     double_reward(){
         
     }
 
+    /**
+     * 重新开始：
+     *   1. 清理数据。
+     *   2. 触发 MissionEnd 事件重置状态。
+     *   3. 显示 loading 遮罩，延迟 0.5 秒后触发 MissionStart。
+     *   4. 关闭弹窗。
+     */
     restart(){
         this.clear_data()
-        // 确保游戏结束事件被触发，以便重置状态
         oops.message.dispatchEvent(GameEvent.MissionEnd)
         this.node.getChildByName("loading").active=true
         this.scheduleOnce(()=>{
@@ -131,6 +180,8 @@ export class VictoryComp extends CCComp {
             oops.gui.removeByNode(this.node)
         },0.5)
     }
+
+    /** 物品展示回调（预留） */
     item_show(e:any,val:any){
         mLogger.log(this.debugMode, 'VictoryComp', "item_show",val)
     }
@@ -138,7 +189,8 @@ export class VictoryComp extends CCComp {
     protected onDestroy(): void {
         mLogger.log(this.debugMode, 'VictoryComp', "释放胜利界面");
     }
-    /** 视图对象通过 ecs.Entity.remove(ModuleViewComp) 删除组件是触发组件处理自定义释放逻辑 */
+
+    /** ECS 组件移除时销毁节点 */
     reset() {
         this.node.destroy()
     }