# 新增功能模块 / 模块重构

> 适用场景：新增模块、重大模块重构、核心架构能力演进。
> 不适用场景：小接口或轻量功能变更，请使用“功能变更”模板。

## 基本信息

- 模块 ID：Module-20260109-0001
- 模块名称: SxLog 轻量日志系统
- 状态：已完成（历史记录；本次仅归档，未重新验证）
- 类型：新增模块
- 所属系统 / 子系统: StellarX / Logging / Diagnostics
- 版本 / 分支: v3.0.0 / master
- 环境: Windows x64 / Visual Studio 2022 / Debug、Release / 控制台模式
- 负责人: Ysm-04（历史实现）

## 背景与目标

- 背景: Canvas、TabControl、Table 以及快照重绘链路逐渐复杂，仅依靠断点难以还原事件、重绘和状态变化顺序。
- 当前痛点:
  - 缺少统一的日志级别、Tag 过滤和输出渠道。
  - 分散日志难以控制噪声，也难以保存为可回放证据。
  - 协作和对外输出需要中英文文本选择能力。
- 目标:
  - 提供统一日志入口和宏封装。
  - 支持级别控制、Tag 白名单/黑名单、控制台输出、文件输出和按大小滚动。
  - 提供 `SX_T` / `SxT` 双语文本选择以及作用域耗时记录。
- 非目标：[可选]
  - 不负责字符编码转换。
  - 不依赖 WinAPI 调试输出通道，不引入第三方日志库。
  - 不保证高频同步 I/O 场景下无性能影响。

## 模块边界

- 职责:
  - `SxLogger` 负责配置、过滤、格式化与 Sink 分发。
  - `ConsoleSink`、`FileSink` 负责具体输出。
  - `SxLogLine` 通过 RAII 完成流式拼接和行提交。
  - `SxLogScope` 记录作用域耗时。
- 不负责什么:
  - 不负责日志采集服务、网络上报、结构化查询或跨进程聚合。
  - 不对业务敏感信息进行脱敏。
- 外部依赖:
  - C++ 标准库的流、文件、互斥量、原子变量和时间工具。
  - `setGBK()` 面向 Windows 控制台环境。
- 对外能力 / API:
  - `SxLogger::Get()`、`setMinLevel()`、`setTagFilter()`、`clearTagFilter()`。
  - `enableConsole()`、`enableFile()`、`disableFile()`。
  - `setLanguage()`、`setGBK()`。
  - `SX_LOG_TRACE`、`SX_LOGD/I/W/E/F`、`SX_TRACE_SCOPE`、`SX_T` / `SxT`。
- 关键数据 / 状态:
  - `SxLogConfig` 保存级别、格式、Tag 策略以及文件配置。
  - Logger 单例持有配置和 Sink；语言选择使用原子状态。

## 设计说明

- 核心流程:
  1. 日志宏先调用 `shouldLog()` 判断级别、Tag 和可用 Sink。
  2. 命中条件时构造 `SxLogLine` 并进行流式拼接。
  3. `SxLogLine` 析构时提交完整日志行。
  4. `SxLogger::logLine()` 在互斥保护下格式化并分发给控制台和文件 Sink。
- 关键对象 / 类关系:
  - `SxLogger`：中心配置与分发器。
  - `ILogSink`：输出目标抽象。
  - `ConsoleSink` / `FileSink`：具体输出实现。
  - `SxLogLine` / `SxLogScope`：调用端 RAII 辅助对象。
- 生命周期:
  - Logger 为进程内单例；Sink 随配置启用或关闭。
  - 日志行对象只在命中过滤条件时短暂存在，并在析构时提交。
- 事件 / 渲染 / 数据流：[按模块类型填写]
  - 调用点 -> 宏短路 -> 日志行拼接 -> Logger 过滤/格式化 -> Sink 输出。
- 关键不变量:
  - `shouldLog()` 返回 false 时不应构造日志行或执行字符串拼接。
  - 单条日志必须作为整体写出，不能被其他线程插入破坏。
  - 语言切换只选择文本，不进行编码转换。
  - 未启用任何 Sink 时应直接短路。
- 降级 / 回退策略：[可选]
  - 将最低级别设为 Off，或关闭控制台和文件 Sink。
  - 必要时通过编译期开关关闭日志宏。

## 实现与影响

- 关键实现点:
  - Tag 过滤使用适合少量 Tag 的线性查找。
  - 文件输出支持追加和按字节阈值滚动。
  - 输出阶段使用互斥量保证行级串行；语言状态使用原子变量。
- 涉及文件 / 类 / 函数:
  - 历史路径：`include/StellarX/SxLog.h`
  - 历史路径：`src/SxLog.cpp`
  - `SxLogger`、`SxLogConfig`、`ILogSink`、`ConsoleSink`、`FileSink`、`SxLogLine`、`SxLogScope`
- 兼容性影响:
  - 新增独立模块，不改变既有控件公共 API；调用方可选择是否接入。
- 性能影响:
  - 未命中过滤条件时由宏短路降低开销。
  - 命中时存在格式化、互斥和 I/O 成本；高频 Trace 输出可能成为瓶颈并快速增大日志文件。
- 风险点:
  - 文件权限、文件占用或滚动重命名失败可能影响持续写入。
  - 控制台代码页差异可能导致中文显示不一致。
  - 日志内容如果包含敏感数据，需要由调用方自行控制。

## 测试与验证

- 测试范围:
  - 日志级别、Tag 白名单/黑名单、控制台和文件输出、文件滚动、语言切换、不可写路径。
- 验证步骤:

1. 启用控制台并依次输出不同级别，检查格式、级别和语言文本。
2. 启用文件输出，验证追加写、Tag 过滤以及不可写路径的返回值。
3. 使用较小的滚动阈值持续输出，检查旧文件重命名和新文件续写。

- 验证结果:
  - PDF 给出了上述测试方案，但“验证证据”仍是待填占位内容，没有附带日志、截图或性能数据。
  - 本次只确认模块源码、公共接口、提交和发布记录存在，未重新执行运行时测试。
- 已知限制 / 遗留问题：[可选]
  - 同步互斥和文件 I/O 不适合无约束的高频热路径。
  - `setGBK()` 只调整终端解释输出的方式，不进行字符串编码转换。

## 落地信息

- 关联功能变更 ID：[可选]
- 关联 BUG / Fix：[可选]
- Commit: `5cb59b36525cde93de83313551296c6458694110`
- PR：[可选]
- 发布版本：[可选] v3.0.0
- 相关文档：[可选]
  - `StellarX功能_模块变更.pdf` 第 24-28 页。
  - 历史 `CHANGELOG.md` 的 v3.0.0 条目。