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

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/logging-debugging.mdc
+++ b/.cursor/rules/logging-debugging.mdc
@@ -0,0 +1,258 @@
+---
+description: "日志系统和调试规范"
+globs: ["src/tool/log.ts", "**/*.ts"]
+alwaysApply: true
+type: "logging"
+---
+
+# 日志系统和调试规范
+
+## 统一日志接口
+
+### 日志级别定义
+```typescript
+import { debug, info, log, warn, error } from "../tool/log";
+
+/**
+ * 日志级别使用指南:
+ * - debug: 调试信息，仅在开发模式显示
+ * - log: 一般信息输出
+ * - info: 信息性消息，带有特殊图标
+ * - warn: 警告信息，黄色背景
+ * - error: 错误消息，红色背景
+ */
+```
+
+### 日志使用规范
+```typescript
+// ✅ 正确的日志使用
+export class WindowManager {
+    public static showWindow(windowName: string): void {
+        debug(`显示窗口: ${windowName}`);  // 调试信息
+        
+        if (!this._windows.has(windowName)) {
+            warn(`窗口不存在 ${windowName}`);  // 警告
+            return;
+        }
+        
+        try {
+            this.doShowWindow(windowName);
+            log(`窗口 ${windowName} 显示成功`);  // 普通信息
+        } catch (e) {
+            error(`显示窗口失败: ${windowName}`, e);  // 错误信息
+        }
+    }
+}
+```
+
+## 调试模式管理
+
+### 调试开关设计
+```typescript
+// header.ts - 调试配置
+export let KUNPO_DEBUG: boolean = false;
+
+/**
+ * 启用或禁用调试模式
+ * @param enable 是否启用调试模式
+ */
+export function enableDebugMode(enable: boolean): void {
+    if (enable === true) {
+        KUNPO_DEBUG = true;
+        warn("调试模式已开启");
+    } else {
+        KUNPO_DEBUG = false;
+    }
+}
+
+// log.ts - 条件日志输出
+function debug(...args: any[]): void {
+    KUNPO_DEBUG && console.log("kunpo:", ...args);
+}
+```
+
+### 框架配置集成
+```typescript
+interface FrameConfig {
+    /** 开启debug 默认: false */
+    debug?: boolean;
+}
+
+export class CocosEntry extends Component {
+    public getConfig(): FrameConfig {
+        return {
+            debug: true  // 在开发环境设置为 true
+        };
+    }
+    
+    protected start(): void {
+        const config = this.getConfig();
+        enableDebugMode(config.debug);  // 根据配置启用调试
+    }
+}
+```
+
+## 日志格式规范
+
+### 统一前缀格式
+```typescript
+// 所有日志都带有 "kunpo:" 前缀
+function log(...args: any[]) {
+    console.log("kunpo:", ...args);
+}
+
+function debug(...args: any[]): void {
+    KUNPO_DEBUG && console.log("kunpo:", ...args);
+}
+```
+
+### 结构化日志信息
+```typescript
+// ✅ 推荐的日志格式
+debug(`窗口注册 - 窗口名:${name} 包名:${pkg} 组名:${group}`);
+log(`模块初始化完成: ${moduleName}`);
+warn(`资源加载失败: ${resourcePath}`);
+error(`网络请求异常: ${url}`, errorDetails);
+
+// ❌ 避免的日志格式  
+debug("window registered");  // 信息不够具体
+log(window);  // 直接输出对象
+```
+
+## 开发调试工具
+
+### 全局调试接口
+```typescript
+// 暴露调试接口到全局对象
+let _global = globalThis || window || global;
+
+(_global as any)["getKunpoRegisterWindowMaps"] = function () {
+    return _uidecorator.getWindowMaps() as any;
+};
+
+(_global as any)["getKunpoRegisterComponentMaps"] = function () {
+    return _uidecorator.getComponentMaps() as any;
+};
+
+(_global as any)["getKunpoRegisterHeaderMaps"] = function () {
+    return _uidecorator.getHeaderMaps() as any;
+};
+```
+
+### 运行时信息输出
+```typescript
+// 系统信息调试
+private initPlatform(): void {
+    debug(`系统类型: ${sys.os}`);
+    debug(`平台类型: ${PlatformType[Platform.platform]}`);
+    debug(`是否原生: ${Platform.isNative}`);
+    debug(`是否移动端: ${Platform.isMobile}`);
+}
+
+// 模块注册调试
+public static registerUI(): void {
+    for (const { ctor, res } of _uidecorator.getWindowMaps().values()) {
+        debug(`窗口注册 - 窗口名:${res.name} 包名:${res.pkg} 组名:${res.group}`);
+    }
+}
+```
+
+## 错误处理和日志
+
+### Promise 错误处理
+```typescript
+public static showWindow(windowName: string, userdata?: any): Promise<void> {
+    return new Promise((resolve, reject) => {
+        debug(`准备显示窗口: ${windowName}`);
+        
+        this._resPool.loadWindowRes(windowName, {
+            complete: () => {
+                debug(`窗口资源加载完成: ${windowName}`);
+                this.showWindowIm(windowName, userdata);
+                resolve();
+            },
+            fail: (pkgs: string[]) => {
+                error(`窗口资源加载失败: ${windowName}`, pkgs);
+                reject(pkgs);
+            }
+        });
+    });
+}
+```
+
+### 异常捕获和记录
+```typescript
+try {
+    this.doSomethingRisky();
+} catch (error) {
+    // 记录详细的错误信息
+    error(`操作执行失败: ${operation}`, {
+        error: error.message,
+        stack: error.stack,
+        context: this.getContext()
+    });
+    
+    // 根据错误类型决定是否继续执行
+    if (error instanceof CriticalError) {
+        throw error;  // 关键错误需要向上抛出
+    }
+}
+```
+
+## 性能监控日志
+
+### 时间统计
+```typescript
+export class WindowManager {
+    public static showWindow(windowName: string): Promise<void> {
+        const startTime = performance.now();
+        debug(`开始显示窗口: ${windowName}`);
+        
+        return new Promise((resolve) => {
+            this._resPool.loadWindowRes(windowName, {
+                complete: () => {
+                    const loadTime = performance.now() - startTime;
+                    debug(`窗口显示完成: ${windowName}, 耗时: ${loadTime.toFixed(2)}ms`);
+                    resolve();
+                }
+            });
+        });
+    }
+}
+```
+
+### 资源使用监控
+```typescript
+export class WindowResPool {
+    private logResourceUsage(): void {
+        if (KUNPO_DEBUG) {
+            const windowCount = this._windowInfos.size;
+            const headerCount = this._headerInfos.size;
+            debug(`资源池状态 - 窗口: ${windowCount}, 头部: ${headerCount}`);
+        }
+    }
+}
+```
+
+## 调试最佳实践
+
+### 1. 日志分级使用
+- `debug`: 仅开发时需要的详细信息
+- `log`: 系统运行的关键节点信息  
+- `warn`: 可能的问题但不影响运行
+- `error`: 必须处理的错误情况
+
+### 2. 信息完整性
+- 包含足够的上下文信息
+- 记录输入参数和状态
+- 包含时间戳和调用路径
+
+### 3. 性能考虑
+- 避免在日志中进行重度计算
+- 使用条件编译减少生产环境开销
+- 延迟计算日志参数
+
+### 4. 安全性
+- 避免输出敏感信息到日志
+- 在生产环境关闭详细日志
+- 注意日志文件的权限设置