ui 优化

2026-07-14 18:56:13 +08:00
parent 4f10cc1648
commit 003b44e2bd
32 changed files with 1082 additions and 375 deletions
@@ -0,0 +1,40 @@
+---
+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/redis.js
+    - backend/src/services/curveClient.js
+    - backend/src/services/measurementStorage.js
+    - backend/src/services/otaStorage.js
+---
+
+## 1. 使用的系统与框架
+- 后端采用 **Winston** 作为统一的日志框架，通过 `backend/src/config/logger.js` 集中创建并导出单例 logger。
+- 前端未引入独立日志库，调试主要依赖浏览器控制台，无统一前端日志方案。
+
+## 2. 核心文件与包
+- `backend/src/config/logger.js` — Winston 实例定义、格式与传输层配置。
+- `backend/logs/app.log` — 默认文件输出路径，由 Dockerfile / 启动脚本挂载持久化。
+- 各模块通过 `require('../config/logger')` 或同级相对路径引入 logger，如 `routes/auth.js`、`services/*.js`、`config/redis.js` 等。
+
+## 3. 架构与约定
+- **全局级别**：默认 `level: 'info'`，低于 info 的日志被丢弃。
+- **格式化**：时间戳 `YYYY-MM-DD HH:mm:ss` + level + message + 可选 meta JSON；meta 对象会被 `JSON.stringify` 拼接在末尾，便于结构化检索。
+- **双通道输出**：
+  - Console transport：容器标准输出，供 docker-compose / k8s 收集。
+  - File transport：写入 `backend/logs/app.log`，UTF-8 编码。
+- **使用模式**：业务代码直接调用 `logger.info/warn/error(...)`，参数为模板字符串，将关键上下文（用户名、URL、S3 key 等）拼入消息体，而非传递结构化对象。
+- **数据库 SQL 日志**：Sequelize 仅在开发环境启用 `console.log` 输出 SQL，生产环境关闭，避免污染主日志。
+
+## 4. 开发者应遵循的规则
+- 统一从 `../config/logger` 引入 logger，不要直接使用 `console.log` 记录业务事件。
+- 按语义选择级别：正常流程用 `info`，可恢复异常或降级用 `warn`，不可恢复错误用 `error`。
+- 将关键上下文（用户、设备、外部服务 URL、S3 key 等）以字符串形式嵌入 message，保持单行可读；如需结构化字段，可通过第三个参数传入对象，Winston 会自动序列化到末尾。
+- 敏感信息（密码、token）不得写入日志；认证失败仅记录用户名等非敏感字段。
+- 新增模块若需额外文件输出或按级别分片，应在 `config/logger.js` 中扩展 transports，而不是在各处重复创建 logger。