vectorSeek/zsjz-ai @ fc3daa8d0fc41d08a62592f48a81bea001a6ba8f - Gogs

1. 使用的框架与工具

门面：SLF4J（org.slf4j.Logger，通过 LoggerFactory.getLogger(...) 获取实例）。
实现：Logback（Spring Boot 默认），由 ai-server/src/main/resources/logback-spring.xml 配置。
集成方式：Spring Boot 自动装配。logback-spring.xml 仅 include Spring Boot 自带的 defaults.xml 和 console-appender.xml，未自定义 appender / layout / file sink。

2. 关键文件

ai-server/src/main/resources/logback-spring.xml：唯一的 logback 配置，定义 root level = debug，输出到 CONSOLE。
ai-server/src/main/java/com/zsjz/ai/App.java：应用入口，使用 log.info(...) 打印启动与工作空间检查日志。
ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java、LoginRequestFilter.java、LoginResponseFilter.java、GatewayRegistry.java、AdminAuthWebFilter.java：网关侧全部使用 SLF4J 日志。

仓库中不存在其他 logback*.xml 或 logging.properties 类配置文件；唯一匹配 logback-spring.xml|logback.xml 的文件是 docs/design/stability-usability-report.md（文档引用）。

3. 架构与约定

3.1 Logger 实例化模式

所有 Java 类统一采用 SLF4J 静态字段模式：

private static final Logger log = LoggerFactory.getLogger(ClassName.class);

在 ai-server 模块中观察到约 913 处 log.debug/info/warn/error 调用，覆盖 228 个源文件；在 ai-gateway 模块中有约 28 处调用，集中在路由、认证、注册等核心路径。

3.2 日志级别策略

全局根级别：<root level="debug">（logback-spring.xml），即 debug 及以上全部输出到控制台。
业务代码实际使用：主要使用 info 和 error；warn 用于非致命异常场景（如网关白名单拒绝、上游不可用、登录响应过大跳过解析等）；极少使用 debug。
未发现按包名或模块设置不同级别的规则——全仓统一 debug 输出。

3.3 结构化字段与消息格式

不使用任何 JSON 结构化日志框架（无 Jackson、GELF、Logstash Encoder 等）。所有日志为纯文本，参数通过 SLF4J 占位符 {} 拼接。
业务日志普遍使用中文前缀标记模块边界，例如：
- 【数据治理】开始执行数据治理任务, caseId={}, userId={}
- [阶段一] 清理/去重任务执行失败或超时
网关侧错误日志以 requestId 作为上下文标识："[{}] gateway internal error", requestId, error。

3.4 输出目标（Sink）

仅输出到 控制台（CONSOLE appender，来自 Spring Boot 内置 console-appender.xml）。
没有文件 appender、rolling file、异步 appender、外部日志收集器（如 Filebeat、Fluentd、ELK）集成。
因此生产部署需依赖容器 stdout/stderr 或进程管理器进行日志采集。

3.5 前端日志

前端（ai-electron/frontend）未发现统一的 logger 封装；API 层通过 axios 拦截器等处理请求/响应，但没有集中化的前端日志子系统。

4. 约定与约束

约定（观察到的行为）：
- 所有 Java 类通过 LoggerFactory.getLogger(ClassName.class) 获取 SLF4J logger，并以私有静态字段持有。
- 业务日志消息使用中文描述并带 caseId、userId、requestId 等业务键。
- 异常一律以 log.error("...", e) 形式记录堆栈。
约束（被实现强制的规则）：
- 根日志级别固定为 debug（由 logback-spring.xml 声明）。
- 日志输出目标仅为控制台（<appender-ref ref="CONSOLE"/>）。
- 仓库内不存在其他 logback 配置文件，任何新增 sink 或格式化规则必须修改该文件。
- 未引入任何第三方日志编码/收集依赖（pom.xml 中无相关 artifact），因此不能假定存在 JSON 输出或远端投递能力。