更新 wiki

.qoder/repowiki/knowledge/zh/_index.yaml

@@ -3,7 +3,7 @@ schema_version: 1
 locale: zh-CN
 branch: main
 nodes_managed: true
-exported_at: "2026-07-22T01:18:52Z"
+exported_at: "2026-07-24T07:31:48Z"
 modules:
     "":
         dir_name: 音频设备管理后台（前后端全栈）
@@ -13,12 +13,3 @@ modules:
         children: []
         depends_on: []
         related_to: []
-    writings:
-        dir_name: Luxsin CMS 软著操作手册生成
-        title: Luxsin CMS 软著操作手册生成
-        scope:
-            - writings/
-        source_files: []
-        children: []
-        depends_on: []
-        related_to: []

.qoder/repowiki/knowledge/zh/后端日志系统（Winston 双输出）/后端日志系统（Winston 双输出）.md

@@ -10,36 +10,28 @@ source_files:
     - backend/src/app.js
 ---
 
-## 1. 使用的框架与工具
-- 后端采用 **winston** 作为统一日志库，通过 `backend/src/config/logger.js` 集中创建 logger 实例并导出。
-- 前端（frontend / frontend_v2）未发现统一的日志框架，业务代码中未引入 winston/pino/bunyan 等 Node 端日志库；前端主要依赖浏览器控制台或无日志输出。
+## 1. 使用的系统与框架
+- 后端采用 Winston 作为统一日志框架，通过 backend/src/config/logger.js 创建全局 logger 实例并导出。
+- 前端未引入独立日志库，主要依赖浏览器控制台与网络请求拦截器进行调试。
 
 ## 2. 核心文件与位置
-- `backend/src/config/logger.js`：winston 初始化、格式定义、传输层配置。
-- `backend/logs/app.log`：默认文件输出路径，所有进程运行期日志均追加写入该单文件。
-- `backend/src/app.js`：应用入口，负责在启动阶段调用 `logger.info/error` 记录数据库建表、服务监听地址等关键生命周期事件。
-- 各模块通过 `require('./config/logger')` 复用同一 logger 实例，如 `routes/auth.js`、`config/redis.js` 等。
+- 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. 架构与约定
-- **全局单例**：仅通过 `src/config/logger.js` 暴露一个 winston logger，所有模块直接 require 使用，避免重复创建。
-- **输出目标（transports）**：
-  - Console：标准输出，便于容器化环境收集 stdout。
-  - File：固定路径 `backend/logs/app.log`，UTF-8 编码，不区分级别，全部写入同一个文件。
-- **日志格式**：自定义 `printf` 模板，形如：
-  ```
-  YYYY-MM-DD HH:mm:ss - level - message [meta JSON]
-  ```
-  当传入 meta 对象时，会以 JSON 字符串拼接在消息末尾，用于携带结构化字段（如用户名、模型 id、S3 路径等）。
-- **日志级别策略**：logger 默认 level 为 `info`，即 info/warn/error 会输出，debug 被过滤。业务中广泛使用 `logger.info` 记录业务流程，`logger.warn` 记录登录失败等非致命异常，`logger.error` 记录错误堆栈或外部依赖异常。
-- **第三方库日志**：Sequelize 的 SQL 日志在开发环境下通过 `logging: (msg) => console.log(msg)` 直接走 console，生产环境关闭，避免污染 app.log。
+- 单例 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. 开发者应遵循的规则
-- **统一入口**：新增日志必须通过 `const logger = require('../config/logger')` 获取，禁止直接使用 `console.log` 输出业务日志。
-- **级别选择**：
-  - `info`：记录关键业务流程节点（用户登录、数据创建/更新/删除、外部请求结果摘要等）。
-  - `warn`：记录可恢复异常或降级场景（登录失败、外部接口 404、缓存未命中等）。
-  - `error`：记录导致功能失败的异常及错误信息。
-- **结构化字段**：需要附加上下文时，以第三个参数传入对象，例如 `logger.info('Model created', { id, brand_name, name })`，最终会被序列化为 JSON 拼接到消息后。
-- **敏感信息**：不要在日志中输出密码、token、完整请求体等敏感内容；如需记录请求详情，请脱敏后再传入 meta。
-- **文件轮转**：当前未配置 winston 的文件轮转策略，长期运行会导致 `app.log` 持续增长；后续如需扩展可在 transports 中添加 `maxsize`/`maxFiles` 等选项。
-- **前端侧**：前端工程未集成统一日志方案，若需在前端埋点，建议在后端提供专用 `/api/log` 接口或通过独立日志 SDK 上报，避免混入业务响应。
+- 统一从 ./config/logger 引入 logger，不要直接调用 console.log 输出业务日志。
+- 优先使用 logger.info 记录正常业务流程，logger.warn 记录可恢复异常或降级场景，logger.error 记录错误堆栈或失败原因。
+- 需要附带上下文信息时，以第三个参数传入对象（会被序列化为 JSON 附加到行尾），便于后续解析。
+- 敏感信息（密码、token、完整请求体）不应直接写入日志，必要时脱敏后再记录。
+- 如需新增日志输出目标（如按天分片、接入远程收集），应在 backend/src/config/logger.js 中集中扩展 transports，保持全局一致。