docs: rebuild Debug API content

docs/api/XCEngine/Debug/Logger/Logger.md

@@ -6,38 +6,79 @@
 
 **头文件**: `XCEngine/Debug/Logger.h`
 
-**描述**: 定义 `XCEngine/Debug` 子目录中的 `Logger` public API。
+**描述**: 构造日志记录、应用全局过滤并把日志分发到多个 sink。
 
 ## 概述
 
-`Logger.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`Logger` 是 XCEngine 当前日志系统的中心节点。业务代码、测试程序和工具层并不直接操作控制台或文件，而是先把消息交给 `Logger`，再由它把统一格式的 `LogEntry` 分发给已注册的 `ILogSink`。
 
-## 声明概览
+这类设计的好处是：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `Logger` | `class` | 头文件中的公开声明。 |
+- 输出目标可以随运行环境变化，而业务日志调用点保持不变。
+- 全局级别过滤和 category 开关只需要维护一份。
+- 可以在编辑器、命令行测试和文件日志之间复用同一条日志链路。
 
-## 公共方法
+## 生命周期
 
-| 方法 | 描述 |
+- [Get](Get.md) 返回进程级单例。
+- [Initialize](Initialize.md) 只设置初始化标志，不会自动添加默认 sink。
+- [Shutdown](Shutdown.md) 会 `Flush` 所有 sink 并清空 sink 列表。
+- [Log](Log.md) 在第一次被调用时会自动调用 `Initialize`。
+
+推荐做法：
+
+- 在程序启动阶段显式 `Initialize` 并注册 sink。
+- 在受控退出阶段调用 `Shutdown`，避免与其它线程仍在写日志时并发销毁。
+
+## 线程语义
+
+- `AddSink`、`RemoveSink` 和 `Log` 通过内部 `Mutex` 保护 sink 列表访问。
+- `SetMinimumLevel` 和 `SetCategoryEnabled` 当前没有加锁，更适合作为初始化阶段配置，而不是高频热更新开关。
+- `Shutdown` 当前也没有在锁内遍历 sink；应在其它线程不再写日志时调用。
+
+## 所有权
+
+- `AddSink` 接收 `std::unique_ptr<ILogSink>`，所有权转移给 `Logger`。
+- `RemoveSink` 只按裸指针匹配已注册对象；如果调用方未来需要移除某个 sink，必须在移交所有权前保留一份原始指针。
+
+## 宏与便捷接口
+
+- `XE_LOG(category, level, message)` 会把 `__FILE__`、`__LINE__` 和 `__FUNCTION__` 一并传给 `Logger::Log`。
+- `XE_ASSERT(condition, message)` 在条件失败时只记录一条 `Fatal` 级别日志；当前实现不会中断程序、抛异常或触发调试断点。
+- `Verbose`、`Debug`、`Info`、`Warning`、`Error`、`Fatal` 都是 `Log` 的便捷封装，但默认不带源码位置信息。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [Get](Get.md) | 获取相关状态或对象。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [AddSink](AddSink.md) | 添加元素或建立关联。 |
-| [RemoveSink](RemoveSink.md) | 移除元素或解除关联。 |
-| [Log](Log.md) | 公开方法，详见头文件声明。 |
-| [Verbose](Verbose.md) | 公开方法，详见头文件声明。 |
-| [Debug](Debug.md) | 公开方法，详见头文件声明。 |
-| [Info](Info.md) | 公开方法，详见头文件声明。 |
-| [Warning](Warning.md) | 公开方法，详见头文件声明。 |
-| [Error](Error.md) | 公开方法，详见头文件声明。 |
-| [Fatal](Fatal.md) | 公开方法，详见头文件声明。 |
-| [SetMinimumLevel](SetMinimumLevel.md) | 设置相关状态或配置。 |
-| [SetCategoryEnabled](SetCategoryEnabled.md) | 设置相关状态或配置。 |
+| [Get](Get.md) | 获取全局 `Logger` 实例。 |
+| [Initialize](Initialize.md) | 初始化日志系统状态。 |
+| [Shutdown](Shutdown.md) | 刷新并移除所有 sink。 |
+| [AddSink](AddSink.md) | 注册一个新的日志输出目标。 |
+| [RemoveSink](RemoveSink.md) | 根据原始指针移除 sink。 |
+| [Log](Log.md) | 构造 `LogEntry` 并分发到所有 sink。 |
+| [Verbose](Verbose.md) | 发送 `Verbose` 级日志。 |
+| [Debug](Debug.md) | 发送 `Debug` 级日志。 |
+| [Info](Info.md) | 发送 `Info` 级日志。 |
+| [Warning](Warning.md) | 发送 `Warning` 级日志。 |
+| [Error](Error.md) | 发送 `Error` 级日志。 |
+| [Fatal](Fatal.md) | 发送 `Fatal` 级日志。 |
+| [SetMinimumLevel](SetMinimumLevel.md) | 设置全局最小日志级别。 |
+| [SetCategoryEnabled](SetCategoryEnabled.md) | 打开或关闭某个日志分类。 |
+
+## 真实使用位置
+
+当前代码库中，`Logger` 已经被用于：
+
+- 编辑器启动流程，为控制台、编辑器面板和文件同时输出日志。
+- RHI 集成测试，为控制台和文件记录帧调试信息。
+- `RenderDocCapture`、截图工具和资源管理等低层模块的错误与警告输出。
 
 ## 相关文档
 
-- [当前目录](../Debug.md) - 返回 `Debug` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Debug.md)
+- [ILogSink](../ILogSink/ILogSink.md)
+- [ConsoleLogSink](../ConsoleLogSink/ConsoleLogSink.md)
+- [FileLogSink](../FileLogSink/FileLogSink.md)
+- [LogEntry](../LogEntry/LogEntry.md)
+- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)