@kkarum/framework 2.3.17 → 2.3.19

package/docs/FRAMEWORK_OVERVIEW.md

@@ -0,0 +1,127 @@
+# Framework Overview
+
+本文档说明 `assets/framework` 的整体设计，面向人类开发者、Codex，以及使用 cocos-mcp 做 UI 自动化的 AI 工作流。
+
+## 核心定位
+
+该框架是 Cocos Creator 2.x 项目的业务基础层，统一管理：
+
+- 全局入口：`FW.Entry`
+- 依赖容器：`FW.Framework`
+- Bundle 注册：`FW.Registry`
+- 业务组件：`FW.Logic`、`FW.Data`、`FW.AssetConfig`、`FW.Sender`、`FW.Handle`
+- UI 层级：`FW.Layer`、`FW.LayerController`、`FW.Entry.layerMgr`
+- 资源、事件、时间、Promise、Socket、对象池、语言、任务、性能等管理器
+
+框架启动后会在 `window.FW` 上挂载全局命名空间，并把常用装饰器挂到 `globalThis`。业务代码应通过 `FW.Entry` 和继承基类来使用框架能力。
+
+## 初始化链路
+
+入口函数是 `initializeFramework()`：
+
+1. 创建 `window.FW`。
+2. 注入系统枚举和事件枚举：`FW.SystemDefine`、`FW.EventDefine`。
+3. 挂载核心类和单例：`FW.Framework`、`FW.Entry`、`FW.Log` 等。
+4. 调用 `FW.Framework.initialize()` 初始化 Inversify 容器。
+5. 调用 `FW.Entry.initialize()` 初始化所有管理器。
+
+初始化是幂等的：如果 `FW.Framework` 和 `FW.Entry` 已存在，会直接返回。
+
+## 架构分层
+
+### Framework
+
+`FW.Framework` 负责依赖注入和业务组件生命周期：
+
+- 使用 Inversify `Container`，默认单例。
+- `register(data)` 绑定业务 bundle 的 Logic/Data/Config/Sender/Handle。
+- `getComponent()` 通过类、字符串 key 或当前 `FW.Entry.bundleName` 的命名约定获取组件。
+- `restart()` 会销毁所有组件、重建容器、重新注册已有组件。
+
+### Entry
+
+`FW.Entry` 是所有业务代码的统一入口。常用字段：
+
+- `resMgr`：资源与 bundle。
+- `layerMgr`：UI Layer 打开、关闭、队列、栈。
+- `uiMgr`：节点查找、UI 事件注册、按钮禁用。
+- `evtMgr`：框架事件总线。
+- `timeMgr`：统一定时器和 update。
+- `promiseMgr`：可取消、超时、重试的 Promise。
+- `socketMgr`：Socket 连接管理。
+- `objectMgr`：对象池。
+- `taskMgr`：分帧异步任务。
+- `performanceMgr`：性能统计。
+
+业务代码不要自行 new 管理器，不要绕过 `FW.Entry` 调用底层实现。
+
+### Registry
+
+每个业务 bundle 应有一个继承 `FW.Registry` 的注册类，声明：
+
+- `bundleName`
+- `sceneName`
+- `depend`
+- `autoRelease`
+- `logic`
+- `data`
+- `config`
+- `sender`
+- `handle`
+
+bundle 加载时，`FWBundleManager.load()` 会调用 `FW.Framework.createRegistry(bundleName)?.register()`。bundle 释放时会调用注册表 `unRegister()` 并销毁注册表实例。
+
+### FrameworkBase
+
+`FW.FrameworkBase` 是业务组件和管理器基类，提供：
+
+- `entry` 快捷访问 `FW.Entry`。
+- `getLogic()`、`getData()`、`getConfig()`、`getSender()`、`getHandle()`。
+- 自动依赖注入：根据类名包含的 bundle 名和后缀 `Logic/Data/Config/Sender/Handle` 推断依赖。
+- `invoke(operation, operationName)`：包装异步操作，记录性能，统一错误日志。
+- `onRestart()` 钩子：构造时注册到系统重启事件。
+
+新增业务组件必须继承对应基类，命名必须保留后缀，否则依赖注入可能失败。
+
+## UI 模型
+
+UI 的核心单位是 Layer：
+
+- 预制体节点上挂 `FW.Layer` 或继承组件。
+- 控制器继承 `FW.LayerController`。
+- 控制器通过 `layerAssetProperty` 指向 prefab。
+- 业务通过 `FW.Entry.layerMgr.openAsync({ type, parent, position, args })` 打开。
+
+LayerController 负责业务生命周期、事件绑定、节点查找和关闭。不要在普通组件中自行 `cc.instantiate` 业务弹窗，除非它不是框架 Layer。
+
+## 资源模型
+
+所有业务资源应通过 `FW.AssetConfig` 声明，并通过 `FW.Entry.resMgr` 加载：
+
+- `preLoad`：随 bundle 或依赖优先加载的资源。
+- `demandLoad`：按需加载的资源。
+- `AssetProperty` 至少包含 `path`，通常包含 `bundle` 和 `type`。
+
+`FWResManager` 会递归加载 bundle 依赖，并优先加载 `preLoad` 中 `priorityLoaded: true` 的资源。
+
+## 事件模型
+
+框架事件分两类：
+
+- Cocos 节点事件：通过 `FW.Entry.uiMgr.register()` 或 `LayerController.cc()` 注册。
+- 框架事件：通过 `FW.Entry.evtMgr.register()`、`dispatch()` 或 `LayerController.fw()` 注册。
+
+Layer 销毁时框架会清理控制器的定时器和事件。新增代码应避免直接散落 `node.on`，优先走框架注册。
+
+## Codex 开发原则
+
+Codex 新增业务功能时必须先判断功能属于哪个层：
+
+- 页面、弹窗、常驻面板：新增 `LayerController` 和 prefab。
+- 业务状态或流程：新增或扩展 `Logic`。
+- 可变业务数据：放入 `Data`。
+- 资源地址：放入 `AssetConfig`。
+- 网络协议发送：放入 `Sender`。
+- 网络消息处理：放入 `Handle`。
+
+不要修改 `assets/framework` 内部源码来适配业务需求。优先新增业务 bundle 代码，复用 `FW.Entry` 已提供能力。

package/docs/FRAMEWORK_OVERVIEW.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "abc3993f-769f-4afa-8cae-057e52d49298",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs/FRAMEWORK_PATTERNS.md

@@ -0,0 +1,261 @@
+# Framework Patterns
+
+本文档定义新增业务功能时的推荐模式和禁止事项。Codex 必须优先遵守本文档。
+
+## 模块边界
+
+业务功能按职责拆分：
+
+| 职责 | 放置位置 |
+| --- | --- |
+| 页面/弹窗生命周期 | `FW.LayerController` |
+| 业务流程 | `FW.Logic` |
+| 业务数据 | `FW.Data` |
+| 资源声明 | `FW.AssetConfig` |
+| Socket 发送包装 | `FW.Sender` |
+| Socket 接收分发 | `FW.Handle` |
+| 跨模块事件 | `FW.Entry.evtMgr` |
+| UI 节点事件 | `LayerController.cc()` 或 `registerEvent()` |
+
+禁止把所有逻辑堆进 `LayerController`。控制器只协调 UI、事件和调用 Logic。
+
+## 命名约定
+
+必须保留后缀：
+
+- `<Bundle>Logic`
+- `<Bundle>Data`
+- `<Bundle>AssetConfig`
+- `<Bundle>Sender`
+- `<Bundle>Handle`
+- `<Feature>LayerController`
+
+原因：`FrameworkBase` 根据类名推断 bundle 和组件类型。类名不含 bundle 名或后缀错误会导致 `getLogic()` 等依赖为空。
+
+## 新功能实现步骤
+
+1. 查找现有 bundle 和功能目录，优先复用已有结构。
+2. 如果是新 bundle，新增 Registry、Logic、Data、AssetConfig。
+3. 如果需要 UI，先定义 LayerController，再创建 prefab。
+4. 所有 prefab 资源写入 AssetConfig。
+5. UI 打开走 `FW.Entry.layerMgr.openAsync()`。
+6. 节点事件走 `this.cc()` 或 `registerEvent()`。
+7. 跨模块通知走 `FW.Entry.evtMgr.dispatch()`。
+8. 网络走 Sender/Handle，不在 UI 里直接拼 WebSocket。
+9. 异步和资源错误使用 `invoke()`、`promiseMgr`、`FW.Log`。
+
+## LayerController 模式
+
+推荐：
+
+```ts
+export class RewardLayerController extends FW.LayerController {
+  renderOrder = FW.SystemDefine.FWLayerRenderOrder.POPUP;
+  layerType = FW.SystemDefine.FWLayerType.POPUP_QUEUE;
+  autoRelease = true;
+  isRepeatOpen = false;
+
+  get layerAssetProperty(): FW.AssetProperty {
+    return this.getConfig<RewardAssetConfig>().preLoad.prefab["RewardLayer"] as FW.AssetProperty;
+  }
+
+  onInit(args: RewardArgs) {
+    this.bindNodes();
+    this.bindEvents();
+    this.render(args);
+  }
+
+  private bindNodes() {}
+
+  private bindEvents() {
+    this.cc(this.find("ConfirmButton", this.layer.node), this.onConfirm);
+  }
+
+  private onConfirm = () => {
+    this.close();
+  };
+}
+```
+
+要点：
+
+- `onInit()` 接收 `openAsync({ args })` 传入的数据。
+- 节点查找基于 `this.layer.node`。
+- 不在构造函数里访问节点。
+- `POPUP_QUEUE` 会在已有队列弹窗打开时排队。
+- `PERMANENT` 可用 `hide()`/`display()` 控制透明度和事件。
+
+## Logic/Data 模式
+
+推荐：
+
+```ts
+export class MailLogic extends FW.Logic {
+  async requestMailList() {
+    const msg = await this.invoke(
+      this.getSender<MailSender>().requestMailList(),
+      "requestMailList",
+    );
+    this.getData<MailData>().setMailList(msg.list);
+  }
+}
+```
+
+```ts
+export class MailData extends FW.Data {
+  private list: MailItem[] = [];
+
+  setMailList(list: MailItem[]) {
+    this.list = list || [];
+    FW.Entry.evtMgr.dispatch("MAIL_LIST_CHANGED", this.list);
+  }
+
+  getMailList() {
+    return this.list;
+  }
+}
+```
+
+要点：
+
+- Logic 发起流程。
+- Data 保持状态。
+- UI 监听状态变化。
+
+## 资源模式
+
+所有业务资源用 `AssetProperty` 声明：
+
+```ts
+readonly preLoad = {
+  prefab: {
+    MailLayer: {
+      bundle: "mail",
+      path: "prefab/MailLayer",
+      type: cc.Prefab,
+      priorityLoaded: true,
+      autoRelease: true,
+    },
+  },
+};
+```
+
+使用规则：
+
+- `openSync()` 只用于确定资源已加载的 Layer。
+- 默认使用 `openAsync()`。
+- 资源获取前先加载；`getAsset()` 不会自动加载。
+- 自动释放资源时确认 `autoRelease` 语义。
+
+## 事件模式
+
+节点事件：
+
+```ts
+this.cc(buttonNode, this.onClick, 500);
+```
+
+框架事件：
+
+```ts
+this.fw("MAIL_LIST_CHANGED", this.renderList);
+```
+
+全局注册：
+
+```ts
+FW.Entry.evtMgr.register("PLAYER_LEVEL_UP", this.onLevelUp, this);
+```
+
+清理：
+
+```ts
+FW.Entry.evtMgr.targetOff(this);
+FW.Entry.timeMgr.unSchedule(this);
+```
+
+LayerController 通常由框架销毁流程清理，普通对象必须自己清理。
+
+## 异步模式
+
+推荐用 `invoke()`：
+
+```ts
+const data = await this.invoke(
+  FW.Entry.resMgr.loadAssetData(asset),
+  "loadRewardIcon",
+);
+```
+
+需要取消/超时/重试：
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute(resolveWork, {
+  timeout: 10000,
+  retryCount: 2,
+  retryInterval: 1,
+});
+```
+
+不要吞掉错误。`invoke()` 返回 `undefined` 时调用方必须处理空值。
+
+## 对象池模式
+
+适用于列表项、飘字、特效对象：
+
+```ts
+const pool = await FW.Entry.objectMgr.createObjectPool(prefab, container, "reward_item");
+const item = pool.get(data);
+pool.put(item.node);
+```
+
+池对象继承 `FW.Object`：
+
+```ts
+export class RewardItem extends FW.Object {
+  onInit() {}
+  onGet(args: any[]) {}
+  onPut() {}
+}
+```
+
+## 禁止事项
+
+- 不修改 `assets/framework` 内部代码来实现业务需求。
+- 不在业务代码中 new 框架管理器。
+- 不绕过 `FW.Entry.resMgr` 直接散落 `cc.loader` 或 `cc.assetManager.loadBundle`。
+- 不绕过 `FW.Entry.layerMgr` 手动实例化业务 Layer prefab。
+- 不在 UI 控制器里直接维护网络连接。
+- 不在 `Data` 中操作节点或发起网络请求。
+- 不在构造函数中访问 Cocos 节点。
+- 不使用没有 bundle 名和后缀的业务组件类名。
+- 不直接使用 `setTimeout`/`setInterval` 管理游戏内生命周期定时器。
+- 不让 `node.on` 分散在多个生命周期中且没有清理路径。
+
+## Codex 决策表
+
+当用户要求“新增一个页面”：
+
+- 先创建/定位 prefab。
+- 创建 `LayerController`。
+- `layerAssetProperty` 指向 Config 中的 prefab。
+- 用 cocos-mcp 创建 UI 节点。
+- 用 `cc()` 绑定按钮事件。
+
+当用户要求“新增一个接口”：
+
+- 修改或新增 `Sender` 方法。
+- 在 `Handle.onMessage()` 或协议分发中处理返回。
+- 写入 `Data`。
+- 派发事件通知 UI。
+
+当用户要求“新增列表”：
+
+- 小列表可普通节点。
+- 大列表优先 `FWVirtualViewComponent` 或对象池。
+- item 预制体资源写入 Config。
+
+当用户要求“切场景”：
+
+- 使用 `FW.Entry.launchScene(bundleName, forceRelease?)`。
+- 确认 Registry 中 `sceneName` 已配置。

package/docs/FRAMEWORK_PATTERNS.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "41fff980-7e94-4a19-ad9e-d35b17048068",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs/FRAMEWORK_USAGE.md

@@ -0,0 +1,309 @@
+# Framework Usage
+
+本文档给出业务开发时的实际用法和推荐流程。
+
+## 基本规则
+
+- 所有框架能力从 `FW.Entry` 进入。
+- 业务组件继承框架基类：`FW.Logic`、`FW.Data`、`FW.AssetConfig`、`FW.Sender`、`FW.Handle`、`FW.LayerController`。
+- 每个 bundle 使用 `FW.Registry` 注册自身组件。
+- 异步资源走 `FW.Entry.resMgr`。
+- UI 打开关闭走 `FW.Entry.layerMgr`。
+- 事件绑定走 `LayerController.registerEvent()`、`cc()`、`fw()` 或 `FW.Entry.evtMgr`。
+- 定时器走 `FW.Entry.timeMgr`。
+- 可取消/带重试异步流程走 `FW.Entry.promiseMgr`。
+
+## 新增业务 Bundle
+
+推荐目录结构：
+
+```text
+assets/<bundle>/
+  config/<Bundle>AssetConfig.ts
+  data/<Bundle>Data.ts
+  logic/<Bundle>Logic.ts
+  registry/<Bundle>Registry.ts
+  ui/<Feature>/<Feature>LayerController.ts
+  prefab/<Feature>Layer.prefab
+```
+
+注册类示例：
+
+```ts
+import { FWRegistry } from "../../framework/registry/FWRegistry";
+import { ShopLogic } from "../logic/ShopLogic";
+import { ShopData } from "../data/ShopData";
+import { ShopAssetConfig } from "../config/ShopAssetConfig";
+
+export class ShopRegistry extends FWRegistry {
+  readonly bundleName = "shop";
+  readonly sceneName = "ShopScene";
+  readonly depend = ["common"];
+  readonly autoRelease = true;
+  readonly logic = ShopLogic;
+  readonly data = ShopData;
+  readonly config = ShopAssetConfig;
+}
+```
+
+业务组件命名必须包含 bundle 名，并以 `Logic/Data/Config/Sender/Handle` 结尾。`FrameworkBase.initializeDependencies()` 会按类名推断 bundle 和组件类型。
+
+## Logic
+
+`Logic` 放业务流程，不持有复杂 UI 节点引用。
+
+```ts
+export class ShopLogic extends FW.Logic {
+  initialize() {
+    // 初始化轻量状态，避免在构造阶段访问尚未加载的资源节点。
+  }
+
+  async refreshGoods() {
+    return this.invoke(
+      this.getSender<ShopSender>().sendGetGoods(),
+      "refreshGoods",
+    );
+  }
+}
+```
+
+规范：
+
+- 异步流程用 `this.invoke()` 包装。
+- 业务数据写入 `this.getData<ShopData>()`。
+- UI 通知用 `FW.Entry.evtMgr.dispatch()`。
+- 不直接加载 prefab 打开 UI，应调用 `FW.Entry.layerMgr`。
+
+## Data
+
+`Data` 保存业务状态，避免混入 UI 节点。
+
+```ts
+export class ShopData extends FW.Data {
+  goods: GoodsItem[] = [];
+
+  setGoods(list: GoodsItem[]) {
+    this.goods = list || [];
+    FW.Entry.evtMgr.dispatch("SHOP_GOODS_CHANGED", this.goods);
+  }
+}
+```
+
+规范：
+
+- `Data` 不发起网络请求。
+- `Data` 不操作 Cocos 节点。
+- 对外提供明确方法，不鼓励外部到处直接改字段。
+
+## AssetConfig
+
+资源地址统一放在 Config。
+
+```ts
+export class ShopAssetConfig extends FW.AssetConfig {
+  preLoad: FW.LoadConfig = {
+    prefab: {
+      ShopLayer: {
+        bundle: "shop",
+        path: "prefab/ShopLayer",
+        type: cc.Prefab,
+        priorityLoaded: true,
+        autoRelease: true,
+      },
+    },
+  };
+
+  demandLoad: FW.LoadConfig = {
+    texture: {
+      IconCoin: {
+        bundle: "shop",
+        path: "texture/icon_coin",
+        type: cc.Texture2D,
+      },
+    },
+  };
+}
+```
+
+使用：
+
+```ts
+const cfg = FW.Entry.getComponent<ShopAssetConfig>(ShopAssetConfig);
+const prefab = await FW.Entry.resMgr.loadAsset<cc.Prefab>(
+  cfg.preLoad.prefab["ShopLayer"] as FW.AssetProperty,
+);
+```
+
+## LayerController
+
+UI 控制器示例：
+
+```ts
+export class ShopLayerController extends FW.LayerController {
+  renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+  layerType = FW.SystemDefine.FWLayerType.REPEAT;
+  autoRelease = true;
+  isRepeatOpen = false;
+
+  get layerAssetProperty(): FW.AssetProperty {
+    return this.getConfig<ShopAssetConfig>().preLoad.prefab["ShopLayer"] as FW.AssetProperty;
+  }
+
+  onInit(args?: { tab?: string }) {
+    const closeBtn = this.find("CloseButton", this.layer.node);
+    this.cc(closeBtn, this.onCloseClick);
+    this.fw("SHOP_GOODS_CHANGED", this.renderGoods);
+  }
+
+  private onCloseClick = () => {
+    this.close();
+  };
+
+  private renderGoods = (goods: GoodsItem[]) => {
+    // 更新 UI
+  };
+}
+```
+
+打开：
+
+```ts
+await FW.Entry.layerMgr.openAsync<ShopLayerController>({
+  type: ShopLayerController,
+  args: { tab: "hot" },
+});
+```
+
+## 资源加载
+
+```ts
+const sf = await FW.Entry.resMgr.loadAsset<cc.SpriteFrame>({
+  bundle: "shop",
+  path: "texture/icon_coin",
+  type: cc.Texture2D,
+});
+```
+
+注意：
+
+- 传入 `cc.Texture2D` 时，`FWResManager` 默认会包装成 `cc.SpriteFrame`。
+- 如果只要原始 Texture，使用 `loadAsset(assetProperty, true)`。
+- 同步 `getAsset()` 只能用于已加载资源，否则会报错。
+
+## 事件注册
+
+优先使用控制器便捷方法：
+
+```ts
+this.cc(this.find("BuyButton", this.layer.node), this.onBuyClick);
+this.fw("SHOP_GOODS_CHANGED", this.renderGoods);
+```
+
+复杂事件：
+
+```ts
+this.registerEvent({
+  CCEvent: [{
+    target: buyButton,
+    eventName: cc.Node.EventType.TOUCH_END,
+    responseInterval: 500,
+    cb: this.onBuyClick,
+  }],
+  FWEvent: [{
+    eventName: "SHOP_REFRESH",
+    responseInterval: 200,
+    cb: this.onRefresh,
+  }],
+});
+```
+
+销毁时 LayerController 会清理自身事件，普通对象必须调用 `FW.Entry.evtMgr.targetOff(target)` 或通过框架管理生命周期。
+
+## 定时器
+
+```ts
+const schedule = FW.Entry.timeMgr.scheduleOnce(() => {
+  this.refreshGoods();
+}, 1, this);
+
+FW.Entry.timeMgr.schedule(
+  () => this.tick(),
+  0.5,
+  cc.macro.REPEAT_FOREVER,
+  this,
+  "shop_tick",
+);
+
+FW.Entry.timeMgr.unSchedule(this);
+```
+
+不要直接使用 `setTimeout`、`setInterval` 管理业务定时器。
+
+## Promise
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute<string>((resolve, reject, signal) => {
+  // 异步操作
+  signal.addEventListener("abort", () => {
+    // 清理
+  });
+}, {
+  timeout: 10000,
+  retryCount: 3,
+  retryInterval: 2,
+});
+
+const result = await proxy.promise;
+```
+
+需要取消时：
+
+```ts
+proxy.abort("layer closed");
+```
+
+## Socket
+
+业务 bundle 可注册 `Sender` 和 `Handle`：
+
+```ts
+export class GameSender extends FW.Sender {
+  sendHeart() {
+    this.send(JSON.stringify({ cmd: "heart" }));
+  }
+
+  async onHeart(msg: any) {
+    return JSON.parse(msg).cmd === "heart";
+  }
+
+  async onBeforeSendingMessage(msg: any) {
+    return typeof msg === "string" ? msg : JSON.stringify(msg);
+  }
+
+  getProtocolKey(msg: any) {
+    return JSON.parse(msg).seq;
+  }
+}
+```
+
+```ts
+export class GameHandle extends FW.Handle {
+  async onBeforeReceivingMessage(event: MessageEvent) {
+    return JSON.parse(event.data);
+  }
+
+  onMessage(msg: any) {
+    FW.Entry.evtMgr.dispatch(`SOCKET_${msg.cmd}`, msg);
+  }
+
+  async onHeart(msg: any) {
+    return msg.cmd === "heart";
+  }
+
+  getProtocolKey(msg: any) {
+    return msg.seq;
+  }
+}
+```
+
+创建连接走 `FW.Entry.socketMgr.createSocket()`，不要直接 new `WebSocket`。

package/docs/FRAMEWORK_USAGE.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "6a4c7da4-306c-4eea-9d3b-aa499018e592",
+  "importer": "markdown",
+  "subMetas": {}
+}