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>

.env.example

@@ -49,6 +49,7 @@ WINE_MAX_TIMEOUT_SECONDS=1800
 INITIAL_ADMIN_EMAIL=admin@example.com
 INITIAL_ADMIN_USERNAME=admin
 INITIAL_ADMIN_PASSWORD=change-me-strong-password
+DEBUG_MODE=true
 POSTGRES_DB=fquiz
 POSTGRES_USER=fquiz
 POSTGRES_PASSWORD=fquiz

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)

api/tests/test_debug_mode.py

@@ -0,0 +1,59 @@
+"""Test debug mode configuration and exception handling."""
+from unittest.mock import patch
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from app.core.config import Settings, get_settings
+from app.core.exception_handlers import global_exception_handler
+
+
+def test_debug_mode_default_enabled():
+    """Test that debug_mode defaults to True."""
+    settings = Settings()
+    assert settings.debug_mode is True
+
+
+def test_debug_mode_can_be_disabled():
+    """Test that debug_mode can be disabled via environment."""
+    with patch.dict("os.environ", {"DEBUG_MODE": "false"}):
+        settings = Settings()
+        assert settings.debug_mode is False
+
+
+async def test_exception_handler_with_debug_enabled():
+    """Test exception handler includes stacktrace when debug is enabled."""
+    with patch("app.core.exception_handlers.get_settings") as mock_settings:
+        mock_settings.return_value.debug_mode = True
+
+        request = None
+        exc = ValueError("Test error")
+
+        response = await global_exception_handler(request, exc)
+
+        assert isinstance(response, JSONResponse)
+        assert response.status_code == 500
+
+        content = response.body.decode()
+        assert "Test error" in content
+        assert "ValueError" in content
+        assert "stacktrace" in content
+
+
+async def test_exception_handler_with_debug_disabled():
+    """Test exception handler excludes stacktrace when debug is disabled."""
+    with patch("app.core.exception_handlers.get_settings") as mock_settings:
+        mock_settings.return_value.debug_mode = False
+
+        request = None
+        exc = ValueError("Test error")
+
+        response = await global_exception_handler(request, exc)
+
+        assert isinstance(response, JSONResponse)
+        assert response.status_code == 500
+
+        content = response.body.decode()
+        assert "Test error" in content
+        assert "ValueError" in content
+        assert "stacktrace" not in content

api/verify_debug_mode.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Verify debug mode configuration and exception handler."""
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "app"))
+
+from app.core.config import get_settings
+
+def main():
+    settings = get_settings()
+
+    print("Configuration Verification:")
+    print(f"  debug_mode: {settings.debug_mode}")
+    print(f"  api_name: {settings.api_name}")
+    print(f"  api_version: {settings.api_version}")
+
+    # Test exception handler import
+    try:
+        from app.core.exception_handlers import global_exception_handler
+        print("\n✓ Exception handler imported successfully")
+    except ImportError as e:
+        print(f"\n✗ Failed to import exception handler: {e}")
+        return 1
+
+    # Test main app import
+    try:
+        from app.main import app
+        print("✓ Main app imported successfully")
+
+        # Check if exception handler is registered
+        exception_handlers = app.exception_handlers
+        if Exception in exception_handlers:
+            print("✓ Global exception handler is registered")
+        else:
+            print("✗ Global exception handler is NOT registered")
+            return 1
+    except ImportError as e:
+        print(f"✗ Failed to import main app: {e}")
+        return 1
+
+    print("\n✓ All checks passed!")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())