---
kind: logging_system
name: 后端日志系统（Winston 双输出）
category: logging_system
scope:
    - '**'
source_files:
    - backend/src/config/logger.js
    - backend/logs/app.log
    - backend/src/app.js
---

## 1. 使用的系统与框架
- 后端采用 Winston 作为统一日志框架，通过 backend/src/config/logger.js 创建全局 logger 实例并导出。
- 前端未引入独立日志库，主要依赖浏览器控制台与网络请求拦截器进行调试。

## 2. 核心文件与位置
- backend/src/config/logger.js — Winston 初始化、格式与传输配置
- backend/logs/app.log — 应用运行期日志落盘文件
- backend/src/app.js — 启动阶段 DB 建表、服务监听等关键流程的日志埋点
- 各路由/配置模块（如 routes/auth.js、config/redis.js）按需 require('./config/logger') 使用

## 3. 架构与约定
- 单例 logger：所有模块共享同一 Winston logger 实例，避免重复配置。
- 输出目标：同时写入 Console 和 File，文件路径固定为 backend/logs/app.log，编码 UTF-8。
- 时间戳格式：YYYY-MM-DD HH:mm:ss。
- 日志级别：默认 level 为 info，业务中广泛使用 info/warn/error，未见 debug 级别使用。
- 结构化字段：通过 printf 将 message 与 meta 对象拼接成一行文本；meta 存在时以 JSON 字符串追加在消息末尾。
- 数据库层日志：Sequelize 在开发环境开启 SQL 语句打印到 console，生产环境关闭。
- 历史兼容痕迹：早期日志中存在 Python 风格（sqlalchemy.engine.Engine、__main__）记录，说明项目曾混用 Python 组件，当前 Node 端已统一到 Winston。

## 4. 开发者应遵循的规则
- 统一从 ./config/logger 引入 logger，不要直接调用 console.log 输出业务日志。
- 优先使用 logger.info 记录正常业务流程，logger.warn 记录可恢复异常或降级场景，logger.error 记录错误堆栈或失败原因。
- 需要附带上下文信息时，以第三个参数传入对象（会被序列化为 JSON 附加到行尾），便于后续解析。
- 敏感信息（密码、token、完整请求体）不应直接写入日志，必要时脱敏后再记录。
- 如需新增日志输出目标（如按天分片、接入远程收集），应在 backend/src/config/logger.js 中集中扩展 transports，保持全局一致。