@kkarum/framework 2.3.18 → 2.3.20

package/docs/ERROR_HANDLING.md

@@ -0,0 +1,233 @@
+# Error Handling
+
+本文档定义框架内业务错误处理、异步失败、资源失败和生命周期清理规范。
+
+## 日志
+
+统一使用 `FW.Log`：
+
+```ts
+FW.Log.debug("message");
+FW.Log.warn("warning", data);
+FW.Log.error("error", error);
+FW.Log.request("request", msg);
+FW.Log.response("response", msg);
+FW.Log.send("socket send", msg);
+FW.Log.receive("socket receive", msg);
+FW.Log.system("system", msg);
+```
+
+发布构建中框架会关闭 console 输出。业务代码不要自行覆盖 console。
+
+## FrameworkBase.invoke
+
+异步业务方法优先用 `invoke()`：
+
+```ts
+const result = await this.invoke(
+  FW.Entry.resMgr.loadAssetData(asset),
+  "loadAssetData",
+);
+
+if (!result) {
+  return;
+}
+```
+
+`invoke()` 会：
+
+- 记录开始和结束时间。
+- 上报到 `performanceMgr`。
+- 慢操作输出 warn。
+- 捕获异常并输出结构化错误。
+- 返回 `undefined`。
+
+调用方必须处理 `undefined`。
+
+## Promise 错误
+
+使用 `FW.Entry.promiseMgr.execute()` 时设置合理超时：
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute(resolveWork, {
+  timeout: 10000,
+  retryCount: 3,
+  retryInterval: 2,
+  retryCondition: (error, count) => true,
+});
+```
+
+取消：
+
+```ts
+proxy.abort("layer closed");
+```
+
+批量结果不会直接抛出所有错误，而是返回：
+
+```ts
+{
+  success: [{ id, value }],
+  failed: [{ id, reason }],
+  cancelled: [id]
+}
+```
+
+## 资源加载失败
+
+资源加载统一走 `FW.Entry.resMgr`。可注册拒绝处理器：
+
+```ts
+FW.Entry.resMgr.registerRejectHandler({
+  loadBundleHandler(error, bundleName) {
+    FW.Log.error("load bundle failed", bundleName, error);
+  },
+  loadResHandler(error, path) {
+    FW.Log.error("load resource failed", path, error);
+  },
+});
+```
+
+加载失败时：
+
+- 不继续操作节点。
+- 不调用 `getAsset()` 兜底。
+- UI 应显示空态、重试按钮或关闭弹窗。
+- Codex 不应通过修改框架资源管理器绕过错误。
+
+## Layer 错误
+
+`FWLayerManager.openAsync()` 失败时会：
+
+- 设置状态为 loading/opening。
+- 失败后移除状态。
+- 清理失败的 Layer 注册。
+- 抛出错误。
+
+业务调用：
+
+```ts
+try {
+  await FW.Entry.layerMgr.openAsync({ type: RewardLayerController });
+} catch (error) {
+  FW.Log.error("open reward layer failed", error);
+}
+```
+
+`openSync()` 失败通常返回 `undefined`，调用方必须判断。
+
+## Socket 错误
+
+Socket 错误处理在 `Handle` 中实现：
+
+```ts
+onError(msg: any) {
+  FW.Log.error("socket error", msg);
+}
+
+onTimeout() {
+  FW.Entry.evtMgr.dispatch("SOCKET_TIMEOUT");
+}
+
+onWeakNetWork() {
+  FW.Entry.evtMgr.dispatch("SOCKET_WEAK_NETWORK");
+}
+
+onClose() {
+  FW.Entry.evtMgr.dispatch("SOCKET_CLOSED");
+}
+```
+
+框架会处理：
+
+- 心跳发送。
+- 弱网检测。
+- 心跳超时重连。
+- 最大重连次数。
+- 协议轮询清理。
+
+业务不要重复实现底层重连循环。
+
+## 事件清理
+
+LayerController 销毁时，框架会调用：
+
+```ts
+FW.Entry.timeMgr.unSchedule(this);
+FW.Entry.evtMgr.targetOff(this);
+this.layer?.unscheduleAllCallbacks();
+this.layer?.node?.stopAllActions();
+this.layer?.node?.destroy();
+```
+
+普通对象或非 Layer 组件必须自行清理：
+
+```ts
+onDestroy() {
+  FW.Entry.evtMgr.targetOff(this);
+  FW.Entry.timeMgr.unSchedule(this);
+}
+```
+
+UI 事件使用 `uiMgr.register()` 后，可用：
+
+```ts
+FW.Entry.uiMgr.unRegisterTarget(target);
+```
+
+## 定时器清理
+
+创建定时器时传 target：
+
+```ts
+FW.Entry.timeMgr.schedule(this.tick, 1, cc.macro.REPEAT_FOREVER, this);
+```
+
+销毁时：
+
+```ts
+FW.Entry.timeMgr.unSchedule(this);
+```
+
+禁止使用无 target 的长期定时器，除非它属于全局系统并有明确 tag。
+
+## 空值和节点有效性
+
+操作 Cocos 节点前检查：
+
+```ts
+if (!cc.isValid(node)) {
+  FW.Log.warn("node invalid");
+  return;
+}
+```
+
+`FW.Entry.uiMgr.find()` 找不到节点会返回 `null` 并打印 warn。业务代码要处理：
+
+```ts
+const button = this.find("ConfirmButton", this.layer.node);
+if (!button) return;
+```
+
+## 错误边界
+
+推荐分层处理：
+
+- 网络层：解析、连接、超时错误。
+- Logic：业务失败和重试。
+- Data：不抛 UI 错误。
+- LayerController：展示失败状态、关闭或重试。
+
+不要让底层错误直接导致 UI 生命周期中断且没有日志。
+
+## Codex 错误处理清单
+
+生成代码时必须检查：
+
+- 每个 `await` 的失败路径是否可接受。
+- `invoke()` 返回 `undefined` 时是否处理。
+- `openSync()` 返回空是否处理。
+- 节点查找失败是否处理。
+- 事件和定时器是否随 target 清理。
+- 资源路径是否来自 `AssetConfig`。
+- Socket 错误是否在 `Handle` 中有入口。

package/docs/ERROR_HANDLING.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "a955657c-a1bb-4b4a-b218-f17ff5649eb3",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs/FRAMEWORK_API.md

@@ -0,0 +1,414 @@
+# Framework API
+
+本文档记录业务开发最常复用的框架 API。除非维护框架本身，不要直接修改 `assets/framework`。
+
+## 全局入口
+
+### `FW.Entry`
+
+常用属性：
+
+| 属性 | 用途 |
+| --- | --- |
+| `bundleName` | 当前业务 bundle 名 |
+| `scene` | 当前 `FW.Scene` |
+| `resMgr` | 资源和 bundle 管理 |
+| `layerMgr` | Layer 打开、关闭、栈、队列 |
+| `uiMgr` | UI 事件、节点查找 |
+| `evtMgr` | 框架事件总线 |
+| `timeMgr` | 定时器和 update |
+| `promiseMgr` | 可取消/超时/重试 Promise |
+| `socketMgr` | Socket 连接 |
+| `objectMgr` | 对象池 |
+| `taskMgr` | 分帧任务 |
+| `languageMgr` | 多语言 |
+| `performanceMgr` | 性能采样 |
+| `utils` | 通用工具 |
+
+方法：
+
+```ts
+FW.Entry.getComponent<T>(identifier): T
+FW.Entry.getComponents<T>(identifier?): T[]
+FW.Entry.launchScene(bundleName, forceRelease?)
+FW.Entry.register({ bundleName, sceneName, depend, autoRelease })
+FW.Entry.unRegister(...)
+FW.Entry.getDepend(bundleName): string[]
+FW.Entry.update(dt)
+FW.Entry.restart()
+```
+
+## 依赖容器
+
+### `FW.Framework`
+
+```ts
+FW.Framework.register({
+  bundleName,
+  logic,
+  data,
+  config,
+  sender,
+  handle,
+});
+
+FW.Framework.unRegister(...)
+FW.Framework.getComponent<T>(ClassOrKey)
+FW.Framework.getComponents<T>(BaseClass)
+FW.Framework.addRegistry(bundleName, RegistryClass)
+FW.Framework.createRegistry(bundleName)
+FW.Framework.destroyRegistry(bundleName)
+FW.Framework.restart()
+```
+
+绑定 key 规则：`${bundleName}${FW.SystemDefine.FWBindTag.*}`。
+
+业务代码通常通过 `FW.Entry.getComponent()` 间接使用，不直接操作容器。
+
+## 基类
+
+### `FW.FrameworkBase`
+
+继承者：
+
+- `FW.Logic`
+- `FW.Data`
+- `FW.Service`
+- `FW.Sender`
+- `FW.Handle`
+- `FWManager`
+- `FW.LayerController`
+
+可用方法：
+
+```ts
+this.entry
+this.getLogic<T>()
+this.getData<T>()
+this.getConfig<T>()
+this.getSender<T>()
+this.getHandle<T>()
+this.initializeDependencies()
+await this.invoke(promise, "operationName")
+```
+
+自动注入依赖依赖类名约定：
+
+- `*Logic`
+- `*Data`
+- `*Config` 或 `*AssetConfig`
+- `*Sender` 或 `*SocketSender`
+- `*Handle` 或 `*SocketHandle`
+
+类名还必须包含 bundle 名。例如 bundle 为 `shop`，推荐 `ShopLogic`、`ShopData`。
+
+## Registry
+
+### `FW.Registry`
+
+```ts
+abstract readonly bundleName: string;
+readonly autoRelease?: boolean;
+readonly sceneName?: string;
+readonly depend?: string[];
+readonly logic?: FW.Newable<FW.Logic>;
+readonly data?: FW.Newable<FW.Data>;
+readonly config?: FW.Newable<FW.AssetConfig>;
+readonly sender?: FW.Newable<FW.Sender>;
+readonly handle?: FW.Newable<FW.Handle>;
+register(): void;
+unRegister(): void;
+```
+
+注册表用于把 bundle 元信息和业务组件交给框架。bundle 加载/释放会自动调用。
+
+## Layer API
+
+### `FW.Entry.layerMgr`
+
+```ts
+openAsync<Ctr>({ type, parent?, position?, args? }): Promise<Ctr>
+openSync<Ctr>({ type, parent?, position?, args? }): Ctr
+close(ctr): Promise<Ctr>
+closeFromStack(count?)
+closeFromLayerName(name | name[])
+displayLayer(ctr)
+hideLayer(ctr)
+removeAllChildren(node)
+clear()
+openDebug()
+getLayerMap()
+```
+
+`LayerOpenArgs`：
+
+```ts
+type LayerOpenArgs = {
+  type: new () => FW.LayerController;
+  parent?: cc.Node;
+  position?: { x: number; y: number };
+  args?: any;
+};
+```
+
+### `FW.LayerController`
+
+业务控制器必须实现：
+
+```ts
+renderOrder: FW.SystemDefine.FWLayerRenderOrder;
+layerType: FW.SystemDefine.FWLayerType;
+layer: FW.Layer;
+layerAssetProperty: FW.AssetProperty;
+autoRelease: boolean;
+isRepeatOpen: boolean;
+```
+
+生命周期：
+
+```ts
+initialize()
+onInit(...args)
+onLoad()
+onStart()
+onEnable()
+onDisable()
+onUpdate(dt)
+onLateUpdate(dt)
+onClose()
+onDestroy()
+destroy()
+```
+
+便捷方法：
+
+```ts
+find(path, referenceNode)
+findComponent<T>(path, referenceNode, type)
+registerEvent(args)
+cc(targetNode, cb, responseInterval?, eventName?)
+fw(eventName, cb, target?, responseInterval?)
+pauseEvent()
+resumeEvent()
+hide()
+display()
+close()
+```
+
+## 资源 API
+
+### `FW.AssetProperty`
+
+```ts
+type AssetProperty = {
+  resourceId?: number;
+  bundle?: string;
+  path: string;
+  type?: typeof cc.Asset;
+  cb?: (asset: FW.AssetData | FW.AssetData[]) => void;
+  progress?: (finish: number, total: number, item: cc.AssetManager.RequestItem) => void;
+  user?: string;
+  autoRelease?: boolean;
+  priorityLoaded?: boolean;
+};
+```
+
+### `FW.Entry.resMgr`
+
+```ts
+loadBundle(bundleName): Promise<cc.AssetManager.Bundle>
+getBundle(bundleName): cc.AssetManager.Bundle
+releaseBundle(bundleName): void
+hasBundle(bundleName): boolean
+
+loadAssetData<T>(assetProperty): Promise<FW.AssetData>
+loadAsset<T>(assetProperty, texture?): Promise<T>
+getAssetData<T>(assetProperty, texture?): FW.AssetData
+getAsset<T>(assetProperty, texture?): T
+preLoad(assetProperty | assetProperty[])
+loadDir(assetProperty): Promise<FW.AssetData[]>
+loadRemote<T>(url, options?): Promise<T>
+loadSpineDataFromRemote({ img, ske, atlas, bin? }): Promise<sp.SkeletonData>
+releaseAsset(assetProperty): void
+hasAsset(assetProperty): boolean
+registerRejectHandler(listener): void
+```
+
+纹理注意：默认 `Texture2D` 会转换为 `SpriteFrame`。需要原始纹理时传 `texture: true`。
+
+## 事件 API
+
+### `FW.Entry.evtMgr`
+
+```ts
+register(eventName, cb, target, options?)
+registerOnce(eventName, cb, target, options?)
+dispatch(eventName, ...args)
+unRegister(eventName, target)
+eventOff(eventName)
+targetOff(target)
+targetPause(target)
+targetResume(target)
+has(eventName, target)
+getListenerCount(eventName)
+```
+
+`options`：
+
+```ts
+{
+  priority?: FW.SystemDefine.FWPriorityOrder;
+  intercept?: boolean;
+  once?: boolean;
+}
+```
+
+### `FW.Entry.uiMgr`
+
+```ts
+register({ target?, CCEvent?, FWEvent? })
+find(path, rootNode): cc.Node | null
+pauseEvent(target)
+resumeEvent(target)
+unRegisterEvent(args)
+unRegisterTarget(target)
+unRegisterAll()
+hasRegister(eventName, target)
+buttonEnable(target)
+buttonDisable(target)
+```
+
+## Time API
+
+```ts
+FW.Entry.timeMgr.schedule(cb, intervalSeconds?, repeat?, target?, tag?)
+FW.Entry.timeMgr.scheduleOnce(cbOrTime?, timeOrTargetOrTag?, targetOrTag?)
+FW.Entry.timeMgr.update(cb, tagOrTarget?, target?)
+FW.Entry.timeMgr.pauseSchedule(tag | id | target)
+FW.Entry.timeMgr.resumeSchedule(tag | id | target)
+FW.Entry.timeMgr.unSchedule(tag | id | target)
+FW.Entry.timeMgr.onUpdate(dt)
+```
+
+返回的 `TimerSchedule` 支持：
+
+```ts
+unSchedule()
+pauseSchedule()
+resumeSchedule()
+promise? // scheduleOnce
+```
+
+## Promise API
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute(executor, {
+  reason,
+  timeout,
+  retryCount,
+  retryInterval,
+  retryCondition,
+});
+
+proxy.id
+proxy.promise
+proxy.status
+proxy.abort(reason?)
+proxy.addAbortEventListener(listener)
+```
+
+批量：
+
+```ts
+FW.Entry.promiseMgr.all([proxy1, proxy2], options)
+FW.Entry.promiseMgr.cancel(id, reason?)
+FW.Entry.promiseMgr.cancelMultiple(ids, reason?)
+FW.Entry.promiseMgr.cancelAll(reason?)
+FW.Entry.promiseMgr.getStatus(id)
+FW.Entry.promiseMgr.getAllStatus()
+FW.Entry.promiseMgr.getActiveCount()
+FW.Entry.promiseMgr.clearCompletedPromise()
+```
+
+## Socket API
+
+### `FW.Entry.socketMgr`
+
+```ts
+createSocket(tag, address, sender, handle, config): Promise<FW.Socket>
+getSocket(tag?): FW.Socket
+getSocketMap(): Map<string, FW.Socket>
+closeSocket(socket)
+closeAll()
+pauseMessageHandle()
+resumeMessageHandle()
+```
+
+### `FW.Sender`
+
+```ts
+sendHeart?()
+onHeart?(msg): Promise<boolean>
+onBeforeSendingMessage?(msg): Promise<FW.SocketMessage>
+getProtocolKey?(msg): string
+send(msg)
+```
+
+### `FW.Handle`
+
+```ts
+onMessage(msg): void
+onBeforeReceivingMessage?(msg): Promise<FW.SocketMessage>
+onHeart?(msg): Promise<boolean>
+getProtocolKey?(msg): string
+onOpen?()
+onClose?()
+onError?(msg)
+onTimeout?()
+onWeakNetWork?()
+```
+
+## Object Pool API
+
+```ts
+const pool = await FW.Entry.objectMgr.createObjectPool(prefabOrNodeOrAsset, parent, tagOrType?)
+FW.Entry.objectMgr.getObjectPool(tag)
+FW.Entry.objectMgr.destroyObjectPool(tag)
+FW.Entry.objectMgr.getPoolStats()
+FW.Entry.objectMgr.clearAllPools()
+```
+
+`FW.ObjectPool`：
+
+```ts
+get(...args): FW.ObjectProperty
+put(node | component | uniqueId)
+puts(array)
+findObjectProperty(node | component | uniqueId)
+isEmpty()
+getEnableObjectMap()
+getDisableObjectMap()
+getAllObjectMap()
+onDestroy()
+```
+
+池对象组件继承 `FW.Object`，实现 `onInit()`、`onGet()`、`onPut()`、`onDestroy()`。
+
+## 装饰器
+
+全局装饰器由 `initializeFramework()` 挂到 `globalThis`：
+
+```ts
+@FWPropertyNode({ path? })
+@FWPropertyNodes(...paths)
+@FWPropertyComponent(ComponentClass, childName?, mute?)
+@FWPropertyComponents(ComponentClass, childName?)
+@PerformanceMonitor(operationName?)
+@FWDeprecated(description?)
+@FWSocketAutoProcessPause()
+@FWSocketAutoProcessResume()
+@AutoRegisterCCEvent(nodePath, eventName?)
+@AutoRegisterFWEvent(eventName)
+```
+
+装饰器会改写 `onLoad` 或方法 descriptor。使用时必须确认目标类生命周期和路径稳定。

package/docs/FRAMEWORK_API.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "66b8acf8-acdf-43e2-a401-8b9afa24b01c",
+  "importer": "markdown",
+  "subMetas": {}
+}