feat(backend): RBAC admin roles + runtime logs service

backend/app/utils/logging_config.py

@@ -6,9 +6,11 @@
 
 import json
 import logging
+import os
 import sys
 from datetime import datetime
-from typing import Any
+from logging.handlers import RotatingFileHandler
+from typing import Any, Optional
 
 
 class JSONFormatter(logging.Formatter):
@@ -51,12 +53,16 @@ class PlainFormatter(logging.Formatter):
         )
 
 
-def setup_logging(level: str = "INFO", json_format: bool = False) -> None:
+def setup_logging(level: str = "INFO", json_format: bool = False, log_dir: Optional[str] = None) -> None:
     """配置日志系统
 
     Args:
         level: 日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
         json_format: 是否使用 JSON 格式输出
+        log_dir: 运行期日志文件目录。若目录存在或可被创建，则在 stdout handler
+                 之外额外写入 <log_dir>/wecom-it-desk.log
+                 （RotatingFileHandler，单文件上限 20MB，保留 5 个备份，复用 JSONFormatter）。
+                 为空 / 不可创建时仅保留 stdout handler，不影响启动。
     """
     log_level = getattr(logging, level.upper(), logging.INFO)
 
@@ -68,7 +74,7 @@ def setup_logging(level: str = "INFO", json_format: bool = False) -> None:
     for handler in root_logger.handlers[:]:
         root_logger.removeHandler(handler)
 
-    # 创建 console handler
+    # 创建 console handler（保持原有 stdout 行为不变）
     console_handler = logging.StreamHandler(sys.stdout)
     console_handler.setLevel(log_level)
 
@@ -81,6 +87,27 @@ def setup_logging(level: str = "INFO", json_format: bool = False) -> None:
     console_handler.setFormatter(formatter)
     root_logger.addHandler(console_handler)
 
+    # 运行期日志文件 handler（独立于 stdout，便于"运行期日志"管理页面读取）
+    # 始终使用 JSONFormatter，保证日志文件为结构化 JSON 行，便于解析与下载。
+    if log_dir:
+        try:
+            os.makedirs(log_dir, exist_ok=True)
+            log_file = os.path.join(log_dir, "wecom-it-desk.log")
+            file_handler = RotatingFileHandler(
+                log_file,
+                maxBytes=20 * 1024 * 1024,  # 单文件上限 20MB
+                backupCount=5,              # 保留 5 个轮转备份
+                encoding="utf-8",
+            )
+            file_handler.setLevel(log_level)
+            file_handler.setFormatter(JSONFormatter())
+            root_logger.addHandler(file_handler)
+        except (OSError, PermissionError) as e:
+            # 目录不可创建 / 不可写：不阻塞启动，仅记录告警，降级为仅 stdout 日志
+            logging.getLogger(__name__).warning(
+                f"无法为运行期日志创建文件 handler（log_dir={log_dir}）: {e}；仅保留 stdout 日志。"
+            )
+
     # 设置第三方库日志级别
     logging.getLogger("uvicorn").setLevel(logging.WARNING)
     logging.getLogger("fastapi").setLevel(logging.WARNING)