---
kind: logging_system
name: 后端日志系统 (Winston)
category: logging_system
scope:
    - '**'
source_files:
    - backend/src/config/logger.js
    - backend/src/app.js
    - backend/src/routes/auth.js
    - backend/src/config/database.js
---

## 1. 核心框架与配置
- **框架**: 使用 `winston` 作为后端 Node.js 应用的统一日志框架。
- **配置文件**: `backend/src/config/logger.js` 负责初始化 logger 实例。
- **日志级别**: 默认设置为 `info`，涵盖 info, warn, error 等级别。
- **输出格式**: 
  - 采用自定义的文本格式：`${timestamp} - ${level} - ${message} ${JSON.stringify(meta)}`。
  - 时间戳格式为 `YYYY-MM-DD HH:mm:ss`。
  - 额外元数据（meta）会被序列化为 JSON 字符串附加在消息后。

## 2. 日志输出目标 (Transports)
- **控制台 (Console)**: 所有级别的日志都会输出到标准输出，便于本地开发和容器日志采集。
- **文件 (File)**: 所有日志同时写入 `backend/logs/app.log` 文件。
  - 目录 `logs/` 若不存在会在初始化时自动创建。
  - 目前未配置日志轮转（Log Rotation），长期运行需注意文件大小。

## 3. 使用规范与模式
- **引入方式**: 在各业务模块中通过 `require('../config/logger')` 获取单例 logger。
- **记录模式**:
  - **信息类**: `logger.info('描述性消息')`，如服务启动、用户登录成功、数据库同步完成。
  - **警告类**: `logger.warn('异常但可恢复的情况')`，如登录失败、资源未找到。
  - **错误类**: `logger.error('错误详情')`，通常在 catch 块中记录异常信息 `e.message`。
- **上下文记录**: 建议在 message 中包含关键业务 ID 或参数，例如 `User ${username} logged in` 或 `id=${brandId}`。

## 4. 特殊场景处理
- **数据库日志**: 在 `backend/src/config/database.js` 中，Sequelize 的 SQL 日志仅在开发环境 (`APP_ENV === 'development'`) 下通过 `console.log` 输出，生产环境关闭以避免性能损耗和日志污染。
- **前端日志**: 前端项目 (`frontend/`) 目前未发现统一的日志封装，主要依赖浏览器控制台默认的 `console` 输出。