日志系统 — SLF4J + Logback + TLog 链路追踪与 AOP 操作日志

---
kind: logging_system
name: 日志系统 — SLF4J + Logback + TLog 链路追踪与 AOP 操作日志
category: logging_system
scope:
    - '**'
source_files:
    - chr/src/main/resources/logback-spring.xml
    - factorydata/src/main/resources/logback-spring.xml
    - production/src/main/resources/logback-spring.xml
    - biz/src/main/java/com/lvcc/biz/aspect/LogAspect.java
---

## 1. 使用的框架与工具
- **SLF4J + Logback**：所有微服务模块统一通过 SLF4J API 记录日志，由 Logback 实现输出。
- **TLog（yomahub.tlog）**：在 factorydata、production、sales 等模块中引入 `com.yomahub.tlog.core.enhance.bytes.AspectLogEnhance`，并通过自定义的 `AspectLogbackAsyncAppender` 实现异步输出与链路 traceId 透传。
- **AOP 切面**：`biz` 模块提供 `LogAspect`，基于 `@LogExecution` 注解对方法入参、耗时、异常进行统一记录；同时通过 `@Log` 注解将用户操作持久化到 `SysLog` 表。

## 2. 核心文件与位置
- 各服务独立 Logback 配置：
  - `chr/src/main/resources/logback-spring.xml`
  - `factorydata/src/main/resources/logback-spring.xml`
  - `production/src/main/resources/logback-spring.xml`
- AOP 日志切面：`biz/src/main/java/com/lvcc/biz/aspect/LogAspect.java`
- TLog 增强入口（示例）：`factorydata/src/main/java/com/lvcc/factorydata/FactorDataApplication.java`、`production/src/main/java/com/lvcc/production/ProductionApplication.java`、`sales/src/main/java/com/lvcc/sales/SalesApplication.java`

## 3. 架构与约定
- **输出目标**：每个服务均定义 console、file_info（INFO）、file_error（ERROR）、http_trace（HTTP 跟踪）四个 Appender，按级别分离文件。
- **滚动策略**：使用 `SizeAndTimeBasedRollingPolicy`，按天滚动并按大小切割，保留 15 天，单文件最大 100MB。
- **异步输出**：INFO 日志通过 AsyncAppender（或 TLog 的 `AspectLogbackAsyncAppender`）异步写入，队列深度默认 256，避免阻塞业务线程。
- **日志格式**：
  - 控制台彩色模式：`%d{yyyy-MM-dd HH:mm:ss.SSS} | %highlight(%-5level) | %boldYellow(%thread) | %boldGreen(%logger) | %msg%n`
  - 文件模式：`%d{yyyy-MM-dd HH:mm:ss.SSS} %contextName [%thread] %-5level %logger{36} - %msg%n`
- **根日志级别**：console 根 level 为 debug，file 根 level 为 info，error 单独一个 root。
- **链路追踪**：通过 TLog 注入 traceId，并在 httptrace 日志中体现，便于跨服务请求追踪。
- **操作日志**：`LogAspect` 拦截 `@Log` 注解方法，收集用户名、IP、耗时、数据源等信息写入 `SysLog` 表；`@LogExecution` 则打印结构化方法调用日志（含参数 JSON、耗时、异常）。

## 4. 开发者应遵循的规则
- **统一使用 SLF4J**：通过 `@Slf4j` 注解获取 logger，禁止直接使用 `System.out` 或 `printStackTrace`。
- **合理选择日志级别**：DEBUG 用于调试信息，INFO 用于关键业务流程，WARN 表示潜在问题，ERROR 记录异常及堆栈。
- **敏感信息脱敏**：日志中不得直接输出密码、token、身份证号等敏感字段，必要时使用工具类脱敏。
- **结构化日志**：优先使用占位符 `{}` 而非字符串拼接，确保日志可被 ELK/日志平台解析。
- **操作日志标注**：对外暴露的 Controller/Service 方法如需审计，添加 `@Log` 注解；需要方法级性能监控时添加 `@LogExecution`。
- **不要自定义 Appender**：新增日志输出点应复用现有 file_info / file_error / http_trace Appender，避免分散配置。
- **TraceId 透传**：依赖 TLog 自动注入 traceId，跨服务调用时保持上下文传递，便于全链路排查。