添加项目规则;修复几处潜在问题

2025-12-05 20:29:10 +00:00 · 2025-11-27 10:54:14 +08:00
parent 5c800cceeb
commit 4e2726dd1b
23 changed files with 3081 additions and 68 deletions
--- a/.cursor/rules/project-overview.mdc
+++ b/.cursor/rules/project-overview.mdc
@@ -0,0 +1,260 @@
+---
+description: "KunpoCC 项目总体开发规范"
+globs: ["**/*.ts", "**/*.md", "**/*.json"]
+alwaysApply: true
+type: "project-guidelines"
+---
+
+# KunpoCC 项目总体开发规范
+
+## 项目介绍
+
+KunpoCC 是一个基于 Cocos Creator 3.x 的游戏开发框架库，提供了一套完整的游戏开发工具和模块：
+
+- **UI 管理系统**: 基于 FairyGUI 的窗口管理和组件系统
+- **数据绑定系统**: 强类型的响应式数据绑定框架
+- **平台适配**: 微信、支付宝、字节跳动等小游戏平台支持
+- **热更新系统**: 完整的资源热更新解决方案
+- **工具模块**: 时间管理、日志系统、数学工具等实用工具
+
+## 项目结构规范
+
+### 目录组织
+```
+src/
+├── cocos/          # Cocos Creator 适配层
+├── condition/      # 条件管理系统 (红点系统)
+├── data/           # 数据绑定系统
+├── fgui/           # FairyGUI 窗口基类
+├── global/         # 全局工具和配置
+├── hotupdate/      # 热更新系统
+├── interface/      # 通用接口定义
+├── minigame/       # 小游戏平台适配
+├── module/         # 模块基类
+├── tool/           # 工具函数集合
+└── ui/             # UI 管理系统
+```
+
+### 文件命名规范
+- **类文件**: PascalCase (如 `WindowManager.ts`)
+- **接口文件**: 以 `I` 开头 (如 `IWindow.ts`)
+- **工具文件**: 功能描述命名 (如 `log.ts`, `Math.ts`)
+- **装饰器文件**: 以 `Decorator` 结尾 (如 `UIDecorator.ts`)
+
+## 编码规范总览
+
+### 类型系统
+```typescript
+// 严格的 TypeScript 配置
+{
+    "strict": true,
+    "strictNullChecks": false,  // 项目特殊需求
+    "experimentalDecorators": true
+}
+
+// 优先使用接口和泛型
+interface IWindow {
+    _show(userdata?: any): void;
+    _close(): void;
+}
+
+// 使用泛型约束确保类型安全
+public static getWindow<T extends IWindow>(name: string): T | null {
+    return this._windows.get(name) as T;
+}
+```
+
+### 装饰器系统
+```typescript
+// UI 装饰器
+@uiclass("popup", "common", "SettingsWindow")
+export class SettingsWindow extends Window {
+    @uiprop btnClose: GButton;
+    @uiclick private onBtnCloseClick(): void { }
+}
+
+// 数据绑定装饰器
+@data.bindProp(GameData, data => data.level, function(item, value) {
+    this.levelLabel.text = `Level: ${value}`;
+})
+private _levelBinding: any;
+
+// 条件装饰器
+@conditionClass(1001)
+export class LevelCondition extends ConditionBase { }
+```
+
+### 架构模式
+```typescript
+// 单例管理器模式
+export class WindowManager {
+    private static _instance: WindowManager;
+    public static getInstance(): WindowManager { }
+}
+
+// 抽象基类模式
+export abstract class Window extends WindowBase {
+    protected abstract onInit(): void;
+    protected onShow(userdata?: any): void { }
+}
+
+// 适配器模式
+export class CocosAdapter implements IAdapter {
+    public init(): void { }
+}
+```
+
+## 开发流程
+
+### 1. 新增功能模块
+1. 在相应目录创建模块文件
+2. 实现必要的接口和基类
+3. 添加相应的装饰器支持
+4. 编写单元测试
+5. 更新文档和示例
+
+### 2. 窗口开发
+```typescript
+@uiclass("main", "game", "GameWindow")
+export class GameWindow extends Window {
+    @uiprop playerPanel: GComponent;
+    @uiprop settingsBtn: GButton;
+    
+    @uiclick
+    private onSettingsBtnClick(): void {
+        WindowManager.showWindow("SettingsWindow");
+    }
+    
+    protected onInit(): void {
+        // 窗口初始化逻辑
+    }
+}
+```
+
+### 3. 数据系统集成
+```typescript
+class GameData extends DataBase {
+    private _score: number = 0;
+    
+    get score(): number { return this._score; }
+    set score(value: number) {
+        if (this._score !== value) {
+            this._score = value;
+            this.notify('score', value);
+        }
+    }
+}
+```
+
+## 质量保证
+
+### 日志和调试
+```typescript
+import { debug, warn, error, log } from "../tool/log";
+
+// 统一的日志格式
+debug(`窗口注册 - 窗口名:${name} 包名:${pkg}`);
+warn(`资源加载失败: ${resourcePath}`);
+error(`网络请求异常: ${url}`, errorDetails);
+```
+
+### 错误处理
+```typescript
+// Promise 错误处理
+public static showWindow(name: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        try {
+            // 业务逻辑
+            resolve();
+        } catch (error) {
+            error('窗口显示失败', error);
+            reject(error);
+        }
+    });
+}
+```
+
+### 性能优化
+- 使用资源池管理UI资源生命周期
+- 实现批量更新减少频繁触发
+- 及时清理事件监听和数据绑定
+- 使用对象池复用临时对象
+
+## 文档和注释
+
+### JSDoc 规范
+```typescript
+/**
+ * @Author: Gongxh
+ * @Date: 2024-12-07
+ * @Description: 窗口管理类
+ */
+
+/**
+ * 显示指定名称的窗口
+ * @param windowName - 窗口的名称
+ * @param userdata - 可选的用户数据
+ * @returns Promise<void>
+ * @internal - 标记内部方法
+ */
+public static showWindow(windowName: string, userdata?: any): Promise<void> {
+```
+
+### 代码注释原则
+- 公共API必须有完整的JSDoc注释
+- 复杂逻辑添加行内注释说明
+- 内部方法使用 `@internal` 标记
+- 废弃功能使用 `@deprecated` 标记
+
+## 版本管理
+
+### 语义化版本
+- **主版本号**: 不兼容的API修改
+- **次版本号**: 向后兼容的功能性新增
+- **修订号**: 向后兼容的问题修正
+
+### 变更记录
+- 维护 CHANGELOG.md 记录版本变更
+- 每个版本包含新增功能、修复问题、破坏性变更
+- 提供迁移指南帮助用户升级
+
+## 测试规范
+
+### 单元测试
+```typescript
+describe('WindowManager', () => {
+    test('should show window correctly', () => {
+        // 测试逻辑
+    });
+    
+    test('should handle window not found', () => {
+        // 错误处理测试
+    });
+});
+```
+
+### 集成测试
+- 测试模块间的交互
+- 验证装饰器系统的完整性
+- 测试平台适配功能
+
+## 部署和发布
+
+### 构建配置
+```json
+{
+    "scripts": {
+        "build": "rollup -c rollup.config.mjs",
+        "build:all": "npm run build && npm run copy"
+    }
+}
+```
+
+### 发布检查清单
+1. 代码通过所有测试
+2. 文档更新完整
+3. 版本号正确更新
+4. CHANGELOG.md 记录变更
+5. 类型定义文件正确生成
+
+这个规范文档作为项目开发的总体指导，具体的技术细节请参考各个专门的规则文件。