@kkarum/framework 2.3.19 → 2.3.20

package/README.md

@@ -1,5 +1,29 @@
 # Framework
 
+## AI 工具使用约定
+
+Codex / AI 工具生成本项目业务代码时必须遵守：
+
+- 获取 `AssetProperty` 使用点访问：`FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer`，不要使用 `["ShopLayer"]`。
+- `LayerController` 不查找节点或组件；节点/组件引用定义在对应 `FW.Layer` 中，节点用 `FWPropertyNode`，组件用 `FWPropertyComponent`，变量名与节点名一致。
+- 默认不要在业务层调用 `invoke()`，除非用户明确要求。
+- 新增业务 bundle 必须提供 `FW.Registry` 注册表，并在文件末尾调用 `FW.Framework.addRegistry()`；`bundleName` 和 `addRegistry()` 的 key 必须一致，统一使用小写 bundle 名。
+
+Registry 示例：
+
+```ts
+import { RegisterAssetConfig } from "../config/RegisterAssetConfig";
+import { RegisterLogic } from "../logic/RegisterLogic";
+
+export class RegisterRegistry extends FW.Registry {
+  bundleName = "register";
+  logic: FW.Newable<FW.Logic> = RegisterLogic;
+  config: FW.Newable<FW.AssetConfig> = RegisterAssetConfig;
+}
+
+FW.Framework.addRegistry("register", RegisterRegistry);
+```
+
 `assets/framework` 是面向 Cocos Creator 2.x 的自写业务框架，核心目标是把业务模块、UI Layer、资源、事件、网络、定时器、对象池和异步流程统一到 `FW` 全局命名空间下管理。
 
 本 README 只做快速总览。详细开发规范请阅读 `assets/framework/docs/` 下的文档。

package/docs/CODEX_GUIDE.md

@@ -1,5 +1,73 @@
 # Codex Guide
 
+## AI 生成代码强制规则
+
+以下规则优先级高于本文档中的旧示例。Codex 或其他 AI 工具为本项目生成业务代码时必须遵守：
+
+1. 获取 `AssetProperty` 必须使用点访问，不要使用字符串下标访问。
+
+```ts
+// 推荐
+return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer;
+
+// 禁止
+return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab["ShopLayer"];
+```
+
+2. `LayerController` 不要查找节点或组件，不要调用 `find()` / `findComponent()` 做 UI 引用缓存。
+   UI 节点和组件引用必须定义在对应 `FW.Layer` 组件中，并使用 `FWPropertyNode` / `FWPropertyComponent` 装饰器。变量名默认必须与节点名一致。
+
+```ts
+@ccclass
+export class ShopLayer extends FW.Layer {
+  @FWPropertyNode()
+  BtnClose: cc.Node = null;
+
+  @FWPropertyComponent(cc.Label)
+  TitleLabel: cc.Label = null;
+}
+
+export class ShopLayerController extends FW.LayerController {
+  private bindEvents() {
+    const layer = this.layer as ShopLayer;
+    this.cc(layer.BtnClose, this.onCloseClick);
+  }
+}
+```
+
+3. 业务层默认不要调用 `invoke()`。除非用户明确要求统一性能记录、错误包装或可恢复异步流程，否则直接 `await` 业务方法、网络方法或资源方法。
+
+```ts
+// 推荐
+await FW.Entry.getComponent(ShopLogic).buyGoods(goodsId);
+
+// 仅在用户明确要求时使用
+await this.invoke(FW.Entry.getComponent(ShopLogic).buyGoods(goodsId), "buyGoods");
+```
+
+4. 新增业务 bundle 必须提供 `FW.Registry` 注册表，并在文件末尾调用 `FW.Framework.addRegistry()`。`bundleName` 与 `addRegistry()` 的 bundle key 必须完全一致，统一使用小写 bundle 名。
+
+```ts
+import { RegisterAssetConfig } from "../config/RegisterAssetConfig";
+import { RegisterLogic } from "../logic/RegisterLogic";
+
+export class RegisterRegistry extends FW.Registry {
+  bundleName = "register";
+  logic: FW.Newable<FW.Logic> = RegisterLogic;
+  config: FW.Newable<FW.AssetConfig> = RegisterAssetConfig;
+}
+
+FW.Framework.addRegistry("register", RegisterRegistry);
+```
+
+规则：
+
+- `Registry` 类名使用业务名 + `Registry`，例如 `RegisterRegistry`。
+- `bundleName` 使用小写业务 bundle 名，例如 `"register"`。
+- `logic/data/config/sender/handle` 字段必须显式声明为对应 `FW.Newable<...>` 类型。
+- `FW.Framework.addRegistry("register", RegisterRegistry)` 必须与 `bundleName` 完全一致。
+- 只声明实际存在的业务组件，不要为了占位声明空的 Data/Sender/Handle。
+
 本文档是 Codex 在本项目中新增、修改业务功能时必须优先参考的工作规范。
 
 ## 首要约束

package/docs/FRAMEWORK_USAGE.md

@@ -1,5 +1,38 @@
 # Framework Usage
 
+## AI 工具使用约定
+
+Codex / AI 工具生成业务代码时必须遵守：
+
+- `AssetConfig` 资源读取使用点访问，例如 `preLoad.prefab.ShopLayer`；不要使用 `preLoad.prefab["ShopLayer"]`。
+- `LayerController` 不负责查找节点和组件。节点使用 `FWPropertyNode`、组件使用 `FWPropertyComponent`，统一定义在对应 `FW.Layer` 组件中，变量名与节点名一致。
+- `invoke()` 默认不在业务层使用。只有用户明确要求性能记录、错误包装或特殊异步治理时才调用。
+- 新增业务 bundle 必须提供 `FW.Registry` 注册表，并在文件末尾调用 `FW.Framework.addRegistry()`。`bundleName` 与 `addRegistry()` 的 bundle key 必须完全一致，统一使用小写 bundle 名。
+
+示例：
+
+```ts
+@ccclass
+export class ShopLayer extends FW.Layer {
+  @FWPropertyNode()
+  BtnClose: cc.Node = null;
+
+  @FWPropertyComponent(cc.Label)
+  TitleLabel: cc.Label = null;
+}
+
+export class ShopLayerController extends FW.LayerController {
+  get layerAssetProperty(): FW.AssetProperty {
+    return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer;
+  }
+
+  onInit() {
+    const layer = this.layer as ShopLayer;
+    this.cc(layer.BtnClose, this.onCloseClick);
+  }
+}
+```
+
 本文档给出业务开发时的实际用法和推荐流程。
 
 ## 基本规则
@@ -30,22 +63,26 @@ assets/<bundle>/
 注册类示例：
 
 ```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;
+import { RegisterAssetConfig } from "../config/RegisterAssetConfig";
+import { RegisterLogic } from "../logic/RegisterLogic";
+
+export class RegisterRegistry extends FW.Registry {
+  bundleName = "register";
+  logic: FW.Newable<FW.Logic> = RegisterLogic;
+  config: FW.Newable<FW.AssetConfig> = RegisterAssetConfig;
 }
+
+FW.Framework.addRegistry("register", RegisterRegistry);
 ```
 
+注册规则：
+
+- `Registry` 类名使用业务名 + `Registry`，例如 `RegisterRegistry`。
+- `bundleName` 使用小写业务 bundle 名，例如 `"register"`。
+- `FW.Framework.addRegistry("register", RegisterRegistry)` 必须与 `bundleName` 完全一致。
+- `logic/data/config/sender/handle` 字段必须显式声明为对应 `FW.Newable<...>` 类型。
+- 只声明实际存在的业务组件，不要为了占位声明空的 Data/Sender/Handle。
+
 业务组件命名必须包含 bundle 名，并以 `Logic/Data/Config/Sender/Handle` 结尾。`FrameworkBase.initializeDependencies()` 会按类名推断 bundle 和组件类型。
 
 ## Logic
@@ -59,17 +96,15 @@ export class ShopLogic extends FW.Logic {
   }
 
   async refreshGoods() {
-    return this.invoke(
-      this.getSender<ShopSender>().sendGetGoods(),
-      "refreshGoods",
-    );
+    return this.getSender<ShopSender>().sendGetGoods();
   }
 }
 ```
 
 规范：
 
-- 异步流程用 `this.invoke()` 包装。
+- 默认直接 `await` 或 `return` 异步业务方法，不使用 `this.invoke()`。
+- 只有用户明确要求性能记录、错误包装或特殊异步治理时才使用 `this.invoke()`。
 - 业务数据写入 `this.getData<ShopData>()`。
 - UI 通知用 `FW.Entry.evtMgr.dispatch()`。
 - 不直接加载 prefab 打开 UI，应调用 `FW.Entry.layerMgr`。

package/docs/UI_DEVELOPMENT_GUIDE.md

@@ -1,5 +1,40 @@
 # UI Development Guide
 
+## AI 生成 UI 代码规则
+
+以下规则用于约束 Codex / AI 工具生成 UI 相关代码，并覆盖本文档中的旧示例：
+
+- `LayerController` 中不要查找节点或组件，不要使用 `find()` / `findComponent()` 缓存 UI 引用。
+- 节点引用写在对应 `FW.Layer` 组件中，使用 `@FWPropertyNode()`，变量名与节点名一致。
+- 组件引用写在对应 `FW.Layer` 组件中，使用 `@FWPropertyComponent(ComponentClass)`，变量名与节点名一致。
+- `layerAssetProperty` 返回资源时使用点访问：`preLoad.prefab.ShopLayer`，不要写 `preLoad.prefab["ShopLayer"]`。
+- 默认不要在 Controller 或业务层调用 `invoke()`，除非用户明确要求。
+
+推荐结构：
+
+```ts
+@ccclass
+export class ShopLayer extends FW.Layer {
+  @FWPropertyNode()
+  BtnClose: cc.Node = null;
+
+  @FWPropertyComponent(cc.Label)
+  TitleLabel: cc.Label = null;
+}
+
+export class ShopLayerController extends FW.LayerController {
+  get layerAssetProperty(): FW.AssetProperty {
+    return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer;
+  }
+
+  onInit() {
+    const layer = this.layer as ShopLayer;
+    this.cc(layer.BtnClose, this.onCloseClick);
+    layer.TitleLabel.string = "Shop";
+  }
+}
+```
+
 本文档定义基于本框架开发 UI 的标准做法。
 
 ## UI 类型

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkarum/framework",
-  "version": "2.3.19",
+  "version": "2.3.20",
   "description": "cocoscreator 2.x mvc framework",
   "main": "index.js",
   "keywords": [