feat: [FL-184] 添加调试模式配置以返回异常堆栈跟踪

- 在配置文件中添加 debug_mode 参数，默认值为 true
- 创建全局异常处理器，当 debug_mode 开启时返回 stacktrace 信息
- 在 .env.example 中添加 DEBUG_MODE 配置项说明
- 新增测试文件验证调试模式功能

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>

api/app/core/config.py

@@ -74,6 +74,8 @@ class Settings(BaseSettings):
     initial_admin_username: str = "管理员"
     initial_admin_password: str | None = None
 
+    debug_mode: bool = True
+
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",

api/app/core/exception_handlers.py

@@ -0,0 +1,22 @@
+import traceback
+from fastapi import Request, status
+from fastapi.responses import JSONResponse
+
+from .config import get_settings
+
+
+async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    settings = get_settings()
+
+    error_response = {
+        "detail": str(exc),
+        "type": type(exc).__name__,
+    }
+
+    if settings.debug_mode:
+        error_response["stacktrace"] = traceback.format_exc()
+
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content=error_response,
+    )

api/app/main.py

@@ -6,6 +6,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from .api.router import api_router
 from .core.config import get_settings
 from .core.database import SessionLocal, init_db
+from .core.exception_handlers import global_exception_handler
 from .services.scheduled_task_service import seed_default_scheduled_tasks
 
 settings = get_settings()
@@ -47,4 +48,6 @@ def health() -> dict[str, str]:
         "version": settings.api_version,
     }
 
+app.add_exception_handler(Exception, global_exception_handler)
+
 app.include_router(api_router)