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

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

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

assets/script/game/map/CardController.ts

@@ -1,3 +1,21 @@
+/**
+ * @file CardController.ts
+ * @description 卡牌控制器组件（UI 视图层）
+ *
+ * 职责：
+ *   1. 作为卡牌系统的顶层控制器容器节点对应的脚本。
+ *   2. 管理 "任务主页" 与 "任务中" 两个子界面的激活切换。
+ *   3. 在 ECS 实体挂载后隐藏 loading 遮罩，标志地图加载完毕。
+ *
+ * 设计说明：
+ *   - 本组件挂载在 CardController 预制体根节点上，
+ *     子节点 `mission_home` 与 `mission` 分别对应主页和战斗界面。
+ *   - update 中检查全局暂停 / 结束标志，预留帧逻辑扩展点。
+ *
+ * 依赖：
+ *   - smc.map.MapView.scene.mapLayer —— 获取地图层以隐藏 loading 节点
+ *   - smc.vmdata —— 读取全局游戏状态（game_over / game_pause）
+ */
 import { _decorator,Button,EventHandler,EventTouch,Label,NodeEventType,resources,Sprite,SpriteAtlas,tween,UITransform,v3 } from "cc";
 import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
 import { CCComp } from "../../../../extensions/oops-plugin-framework/assets/module/common/CCComp";
@@ -5,40 +23,74 @@ import { smc } from "../common/SingletonModuleComp";
 import { mLogger } from "../common/Logger";
 const { ccclass, property } = _decorator;
 
-/** 视图层对象 */
+/**
+ * CardControllerComp —— 卡牌系统控制器视图组件
+ *
+ * 负责初始化卡牌界面的顶层布局切换（主页 vs 战斗），
+ * 并在 ECS 实体加入场景时处理 loading 状态。
+ */
 @ccclass('CardControllerComp')
 @ecs.register('CardController', false)
 export class CardControllerComp extends CCComp {
+    /** 是否启用调试日志 */
     @property({ tooltip: "是否启用调试日志" })
     private debugMode: boolean = false;
 
+    /** 触控计时器（预留，可用于长按等交互逻辑） */
     touch_time:number = 0
+    /** 是否正在触控中（预留） */
     in_touch:boolean = false
+    /** 底部背景引用（预留） */
     bbg:any=null
+    /** 底部背景 Y 坐标（预留） */
     bbg_y:number=40
+    /** 卡牌槽位 X 坐标数组（5 个位置，预留） */
     bbg_x:any=[-300,-150,0,150,300]
+
     protected onLoad(): void {
     }
+
+    /**
+     * start：组件启动时打印日志并初始化页面。
+     * 默认显示任务主页（mission_home），隐藏战斗界面（mission）。
+     */
     start() {
         mLogger.log(this.debugMode, 'CardController', "CardControllerComp start",this.node)
         this.page_init()
     }
+
+    /**
+     * onAdded：当本组件对应的 ECS 实体被挂载到场景后触发。
+     * 主要作用：关闭地图层上的 loading 遮罩。
+     * @param args  ECS 实体附加参数
+     */
     onAdded(args:any){
         mLogger.log(this.debugMode, 'CardController', "CardControllerComp onAdded",args)
         smc.map.MapView.scene.mapLayer.node.getChildByName("loading").active=false;
     }
+
+    /**
+     * update：每帧更新。
+     * 若全局标记 game_over 或 game_pause 时直接跳过（预留扩展位）。
+     */
     protected update(dt: number): void {
         if(smc.vmdata.game_over||smc.vmdata.game_pause){
             return
         }
 
     }
+
+    /**
+     * 页面初始化：
+     *   - 显示任务主页（mission_home）
+     *   - 隐藏任务战斗界面（mission）
+     */
     page_init(){
         this.node.getChildByName("mission_home").active=true;
         this.node.getChildByName("mission").active=false;
     }
  
-        /** 视图对象通过 ecs.Entity.remove(ControllerComp) 删除组件是触发组件处理自定义释放逻辑 */
+    /** ECS 组件移除时销毁节点 */
     reset() {
         this.node.destroy();
     }