refactor(logging): 完善日志系统实现和API设计

- 为ConsoleLogger添加完整的XML文档注释
- 实现GodotLogger中缺失的日志级别方法
- 统一Fatal方法签名，支持异常参数传递
- 为NullLogger添加完整的方法注释
- 修复LoggerFactory中的文件路径处理逻辑
- 移除日志示例中对架构阶段的直接访问
- 添加全局日志记录器创建功能

GFramework.Core/logging/ConsoleLogger.cs

@@ -1,6 +1,3 @@
-using System;
-using System.IO;
-
 namespace GFramework.Core.logging;
 
 /// <summary>
@@ -35,6 +32,10 @@ public sealed class ConsoleLogger : ILog
     /// <summary>
     /// 记录日志消息
     /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <param name="message">日志消息</param>
+    /// <param name="exception">异常信息（可选）</param>
+    /// <param name="context">上下文信息（可选）</param>
     public void Log(LogLevel level, string message, Exception? exception = null, object? context = null)
     {
         if (!IsEnabled(level))
@@ -61,6 +62,8 @@ public sealed class ConsoleLogger : ILog
     /// <summary>
     /// 检查指定日志级别是否启用
     /// </summary>
+    /// <param name="level">要检查的日志级别</param>
+    /// <returns>如果启用则返回true，否则返回false</returns>
     public bool IsEnabled(LogLevel level) => level >= _minLevel;
 
     /// <summary>
@@ -68,6 +71,11 @@ public sealed class ConsoleLogger : ILog
     /// </summary>
     public LogLevel MinLevel => _minLevel;
 
+    /// <summary>
+    /// 使用颜色写入日志消息
+    /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <param name="message">要写入的消息</param>
     private void WriteColored(LogLevel level, string message)
     {
         var originalColor = Console.ForegroundColor;
@@ -82,7 +90,12 @@ public sealed class ConsoleLogger : ILog
         }
     }
 
-    private ConsoleColor GetColor(LogLevel level)
+    /// <summary>
+    /// 根据日志级别获取对应的颜色
+    /// </summary>
+    /// <param name="level">日志级别</param>
+    /// <returns>对应的控制台颜色</returns>
+    private static ConsoleColor GetColor(LogLevel level)
     {
         return level switch
         {
@@ -96,7 +109,12 @@ public sealed class ConsoleLogger : ILog
         };
     }
 
-    private string FormatContext(object context)
+    /// <summary>
+    /// 格式化上下文对象为字符串
+    /// </summary>
+    /// <param name="context">上下文对象</param>
+    /// <returns>格式化后的字符串</returns>
+    private static string FormatContext(object context)
     {
         return context switch
         {
@@ -108,21 +126,54 @@ public sealed class ConsoleLogger : ILog
     }
 
     // 快捷方法实现
+
+    /// <summary>
+    /// 记录信息级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Info(string msg, object? ctx = null)
         => Log(LogLevel.Info, msg, null, ctx);
 
+    /// <summary>
+    /// 记录错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">异常信息（可选）</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Error(string msg, Exception? ex = null, object? ctx = null)
         => Log(LogLevel.Error, msg, ex, ctx);
 
+    /// <summary>
+    /// 记录调试级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Debug(string msg, object? ctx = null)
         => Log(LogLevel.Debug, msg, null, ctx);
 
+    /// <summary>
+    /// 记录跟踪级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Trace(string msg, object? ctx = null)
         => Log(LogLevel.Trace, msg, null, ctx);
 
+    /// <summary>
+    /// 记录警告级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">上下文信息（可选）</param>
     public void Warn(string msg, object? ctx = null)
         => Log(LogLevel.Warning, msg, null, ctx);
 
-    public void Fatal(string msg, object? ctx = null)
+    /// <summary>
-        => Log(LogLevel.Fatal, msg, null, ctx);
+    /// 记录致命错误级别日志
-}
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">异常信息（可选）</param>
+    /// <param name="ctx">上下文信息（可选）</param>
+    public void Fatal(string msg,Exception? ex = null, object? ctx = null)
+        => Log(LogLevel.Fatal, msg, ex, ctx);
+}

GFramework.Core/logging/ILog.cs

@@ -66,6 +66,7 @@ public interface ILog
     /// 记录致命错误级别日志
     /// </summary>
     /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
     /// <param name="ctx">日志上下文信息（可选）</param>
-    void Fatal(string msg, object? ctx = null);
+    void Fatal(string msg, Exception? ex = null,object? ctx = null);
 }

GFramework.Core/logging/ILoggerFactory.cs

@@ -11,5 +11,11 @@ public interface ILoggerFactory
     /// <param name="category">日志类别，用于区分不同的日志源</param>
     /// <returns>返回指定类别的日志记录器实例</returns>
     ILog Create(string category);
+    
+    /// <summary>
+    /// 创建全局日志记录器实例
+    /// </summary>
+    /// <returns>返回全局日志记录器实例</returns>
+    ILog CreateGlobalLogger();
 }
 

GFramework.Core/logging/LoggerFactory.cs

@@ -1,6 +1,3 @@
-using System;
-using System.Collections.Generic;
-
 namespace GFramework.Core.logging;
 
 /// <summary>
@@ -65,13 +62,13 @@ public class LoggerFactory : ILoggerFactory
         try
         {
             var level = _config.GetCategoryLevel(category);
-            var directory = System.IO.Path.GetDirectoryName(_config.LogFilePath);
+            var directory = Path.GetDirectoryName(_config.LogFilePath);
-            if (!string.IsNullOrEmpty(directory) && !System.IO.Directory.Exists(directory))
+            if (!string.IsNullOrEmpty(directory) && !Directory.Exists(directory))
             {
-                System.IO.Directory.CreateDirectory(directory);
+                Directory.CreateDirectory(directory);
             }
 
-            var writer = new System.IO.StreamWriter(_config.LogFilePath!, append: true);
+            var writer = new StreamWriter(_config.LogFilePath!, append: true);
             return new ConsoleLogger(category, level, writer, useColors: false);
         }
         catch
@@ -125,7 +122,7 @@ public class LoggerFactory : ILoggerFactory
         public void Warn(string msg, object? ctx = null)
             => Log(LogLevel.Warning, msg, null, ctx);
 
-        public void Fatal(string msg, object? ctx = null)
+        public void Fatal(string msg,Exception? ex = null, object? ctx = null)
-            => Log(LogLevel.Fatal, msg, null, ctx);
+            => Log(LogLevel.Fatal, msg, ex, ctx);
     }
 }

GFramework.Core/logging/LoggingExample.cs

@@ -3,6 +3,7 @@ using GFramework.Core.logging;
 using GFramework.Core.system;
 using GFramework.Core.model;
 using GFramework.Core.events;
+using GFramework.Core.utility;
 
 namespace GFramework.Core.Examples;
 
@@ -100,8 +101,6 @@ public class LoggingExample
         // 创建示例架构
         var architecture = ExampleArchitecture.Instance;
         
-        Console.WriteLine($"架构当前阶段: {architecture.CurrentPhase}");
-        
         // 注册组件（会自动记录日志）
         architecture.RegisterSystem(new ExampleSystem());
         architecture.RegisterModel(new ExampleModel());

GFramework.Core/logging/NullLogger.cs

@@ -21,11 +21,47 @@ internal sealed class NullLogger : ILog
     /// <returns>始终返回 false，表示所有日志级别都被禁用</returns>
     public bool IsEnabled(LogLevel level) => false;
 
-    // 快捷方法实现（空实现）
+    /// <summary>
+    /// 记录信息级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Info(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Error(string msg, Exception? ex = null, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录调试级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Debug(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录跟踪级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Trace(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录警告级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
     public void Warn(string msg, object? ctx = null) { }
-    public void Fatal(string msg, object? ctx = null) { }
+
+    /// <summary>
+    /// 记录致命错误级别日志
+    /// </summary>
+    /// <param name="msg">日志消息</param>
+    /// <param name="ex">相关异常对象（可选）</param>
+    /// <param name="ctx">日志上下文信息（可选）</param>
+    public void Fatal(string msg,Exception? ex = null, object? ctx = null) { }
 }

GFramework.Godot/logging/GodotLogger.cs

@@ -49,31 +49,31 @@ public sealed class GodotLogger : ILog
 
     public void Info(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Info, msg, null, ctx);
     }
 
     public void Error(string msg, Exception? ex = null, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Error, msg, ex, ctx);
     }
 
     public void Debug(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Debug, msg, null, ctx);
     }
 
     public void Trace(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Trace, msg, null, ctx);
     }
 
     public void Warn(string msg, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Warning, msg, null, ctx);
     }
 
-    public void Fatal(string msg, object? ctx = null)
+    public void Fatal(string msg,Exception? ex = null, object? ctx = null)
     {
-        throw new NotImplementedException();
+        Log(LogLevel.Fatal, msg, ex, ctx);
     }
 }