重构与加功能指南

从零加一个功能模块，到给已有模块加字段、加协议、加 UI， 这一页是可以照着做的操作手册。每一步都对应工程里真实存在的文件和命令。

1. 从零加一个功能模块

1.1 目录与文件

模块统一放在 Src/Game/Module/<ModuleName>/，标准四件套：

Src/Game/Module/TowerClimb/
├── TowerClimbController.ts   // 逻辑 + 协议收发（必须）
├── TowerClimbModel.ts        // 服务器数据缓存（有服务器数据才要）
├── TowerClimbConfig.ts       // 配置表加工与索引（有复杂查表才要）
├── TowerClimbDefine.ts       // 枚举、常量、接口（推荐一开始就建）
└── View/                     // UI，一个 Panel/Item 一个文件
    ├── TowerClimbInfoView.ts
    └── TowerClimbStarItem.ts

1.2 注册进三大管理器

光建文件不会被加载，必须在 Creator 里 new 出来并 Add：

// ModelManagerCreator.ts
ModelManager.TowerClimbModel = new TowerClimbModel();
ModelManager.Add(ModelManager.TowerClimbModel);

// ControllerRegisterManager.ts
ControllerHolder.TowerClimbController = new TowerClimbController();
this.Add(ControllerHolder.TowerClimbController);

// ModelManager / ConfigManager —— 可能为 undefined，用处要判空
public static TowerClimbModel: TowerClimbModel | undefined = undefined;

// ControllerHolder —— 断言非空，因为 Controller 生命周期覆盖全程
public static TowerClimbController: TowerClimbController = undefined!;

1.3 顺序很重要

1.4 Controller 骨架

export class TowerClimbController extends UiControllerBase {
    // ① 协议注册：进游戏时一次
    protected override OnRegisterNetEvent(): void {
        Net.Register(ENotifyMessageId.WorldDungeonTowerStarStartSCNotify, this.OnStarStart);
    }
    protected override OnUnRegisterNetEvent(): void {
        Net.UnRegister(ENotifyMessageId.WorldDungeonTowerStarStartSCNotify);
    }

    // ② 事件监听：和上面严格配对
    protected override OnAddEvents(): void {
        EventSystem.Add(EEventName.DungeonStateChange, this.OnDungeonStateChange);
    }
    protected override OnRemoveEvents(): void {
        EventSystem.Remove(EEventName.DungeonStateChange, this.OnDungeonStateChange);
    }

    // ③ 回调用箭头函数属性，否则 this 丢失且无法 Remove
    private readonly OnStarStart = (notify: TowerStarStartSCNotify): void => { ... };

    // ④ 关卡级清理（换关卡）vs 彻底清理（登出）
    protected override OnLeaveLevel(): boolean { /* 清关卡数据、停定时器 */ return true; }
    protected override OnClear(): boolean { /* 清所有 */ return true; }
}

// ❌ this 会丢，而且 Remove 时传的是另一个函数对象，摘不掉
private OnStarStart(notify) { ... }
EventSystem.Add(EEventName.X, this.OnStarStart.bind(this));   // bind 每次产生新对象

// ✅
private readonly OnStarStart = (notify): void => { ... };
EventSystem.Add(EEventName.X, this.OnStarStart);

1.5 需要 Tick 时选对阶段

2. 给已有模块加一个字段

这是最常见的需求。「加一个字段」实际要动 5～7 个地方：

2.1 加事件的两处

// Src/Game/Common/Event/EventDefine.ts —— 第一处：枚举
export const enum EEventName {
    ...
    /** 副本爬塔星级数据变化（开始/单档更新都派发） */
    DungeonTowerStarChange,
}

// 同文件 —— 第二处：签名表（漏了这里编译不过）
export interface IEventMap {
    [EEventName.DungeonTowerStarChange]: () => void;
}

事件名带中文注释，写清「什么时候派发」。 全工程 768+ 个事件，没注释的两周后自己都不知道该不该监听。

3. 加 UI

3.1 控件索引是位置，不是名字

protected override OnRegisterComponent(): void {
    this.ComponentRegisterInfos = [
        [EMainUiTaskType.QuestLayout,      UE.UIItem],   // index 0
        [EMainUiTaskType.QuestItem,        UE.UIItem],   // index 1
        [EMainUiTaskType.PnlTowerStar,     UE.UIItem],   // index 2
        ...
    ];
}

3.2 批量创建子项的标准写法

// prefab 里放一个隐藏的模板 Item，运行时 CopyItem 复制 N 份
private async CreateStarItems(count: number): Promise<void> {
    if (this.IsCreatingStarItems) {      // ① 防重入锁
        this.NeedRefreshAfterCreate = true;  //    记下「创建完再刷一次」
        return;
    }
    this.IsCreatingStarItems = true;
    try {
        for (let i = this.ItemList.length; i < count; i++) {
            const item = await CopyItem(this.Template);   // ② 这里会让出，可能被重入
            this.ItemList.push(item);
        }
    } finally {
        this.IsCreatingStarItems = false;      // ③ finally 里解锁，异常也不会卡死
    }
    if (this.NeedRefreshAfterCreate) {         // ④ 补刷
        this.NeedRefreshAfterCreate = false;
        this.Refresh();
    }
}

4. 用定时器

TimerSystem.Next(cb);                    // 下一帧
TimerSystem.Delay(cb, ms);                // 延迟一次
TimerSystem.Loop(cb, ms, maxLoop);       // 循环 N 次
TimerSystem.Forever(cb, ms);              // 无限循环

5. 加日志

Log.Info(ELogModule.Debug, ELogAuthor.ZZB,
    '传送-HandleLocalPlayerTeleportApplied REVIVE 不接管，交回复活链路',
    ['reason', snap.Reason],
    ['serverMoveVersion', snap.ServerMoveVersion]);

6. 编译与提交

6.1 编译流水线到底做了什么

npm run compile-skip-diagnostic   # 跳过诊断，强制 emit

6.2 命令速查

6.3 项目自定义的 lint 规则

eslint-plugin-rule/ 下的规则是这个项目独有的， 第一次撞上会一头雾水：

6.4 CRLF 与格式

7. 需求边界纪律

8. 提交前完整自查

9. 可复用的十条模式

10. 重构时的判断