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

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

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

assets/script/game/map/MissionCardComp.ts

@@ -1,3 +1,37 @@
+/**
+ * @file MissionCardComp.ts
+ * @description 卡牌系统核心控制器（战斗 UI 层 + 业务逻辑层）
+ *
+ * 职责：
+ *   1. **卡牌分发管理** —— 从卡池抽取 4 张卡，分发到 4 个 CardComp 槽位。
+ *   2. **卡池升级** —— 消耗金币提升卡池等级（poolLv），解锁更高稀有度的卡牌。
+ *   3. **金币费用管理** —— 抽卡费用（refreshCost）、升级费用（CardsUpSet）、
+ *      波次折扣（CARD_POOL_UPGRADE_DISCOUNT_PER_WAVE）的计算与扣除。
+ *   4. **英雄数量上限校验** —— 在 UseHeroCard 事件的 guard 阶段判断是否允许
+ *      再召唤英雄（含合成后腾位的特殊判断 canUseHeroCardByMerge）。
+ *   5. **场上英雄信息面板（HInfoComp 列表）同步** ——
+ *      英雄上场时实例化面板，死亡时移除，定时刷新属性显示。
+ *   6. **特殊卡执行** —— 处理英雄升级卡（SpecialUpgrade）和英雄刷新卡（SpecialRefresh）。
+ *   7. **准备/战斗阶段切换** —— 控制卡牌面板的 展开/收起 动画。
+ *
+ * 关键设计：
+ *   - 4 个 CardComp 通过 cacheCardComps() 映射为有序数组 cardComps[]，
+ *     之后所有分发、清空操作均通过此数组进行。
+ *   - buildDrawCards() 保证每次抽取 4 张，不足时循环补齐。
+ *   - 英雄上限校验（onUseHeroCard）采用 guard/cancel 模式：
+ *     CardComp 发出 UseHeroCard 事件并传入 guard 对象，
+ *     本组件可通过 guard.cancel=true 阻止使用。
+ *   - ensureHeroInfoPanel() 建立 EID → HInfoComp 的 Map 映射，
+ *     支持英雄合成升级后面板热更新。
+ *
+ * 依赖：
+ *   - CardComp —— 单卡槽位
+ *   - HInfoComp —— 英雄信息面板
+ *   - CardSet 模块 —— 卡池配置、抽卡规则、特殊卡数据
+ *   - HeroAttrsComp —— 英雄属性（合成校验 / 升级）
+ *   - MissionHeroCompComp —— 获取合成规则（needCount / maxLv）
+ *   - smc.vmdata.mission_data —— 局内数据（coin / hero_num / hero_max_num）
+ */
 import { mLogger } from "../common/Logger";
 import { _decorator, instantiate, Label, Node, NodeEventType, Prefab, SpriteAtlas, Tween, tween, Vec3 } from "cc";
 import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
@@ -18,7 +52,12 @@ import { MissionHeroCompComp } from "./MissionHeroComp";
 const { ccclass, property } = _decorator;
 
 
-/** 视图层对象 */
+/**
+ * MissionCardComp —— 卡牌系统核心控制器
+ *
+ * 管理 4 个卡牌槽位的抽卡分发、卡池升级、金币费用、
+ * 英雄上限校验、场上英雄信息面板同步以及特殊卡执行。
+ */
 @ccclass('MissionCardComp')
 @ecs.register('MissionCard', false)
 export class MissionCardComp extends CCComp {