feat: 完善后端 API OpenAPI 文档与统一错误响应 schema

server/src/app/main.py

@@ -1,19 +1,41 @@
-from __future__ import annotations
-
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
 from app.api.router import api_router
 from app.core.config import get_settings
 from app.core.logging import get_logger, setup_logging
+from app.core.openapi import API_DESCRIPTION, OPENAPI_TAGS
 from app.middleware.logging import AccessLogMiddleware
+from app.schemas.common import RootStatusRead
 from app.services.agent_foundation import prepare_agent_foundation
 from app.services.employee import prepare_employee_directory
 from app.services.knowledge import prepare_knowledge_library
-
-
-def create_app() -> FastAPI:
-    settings = get_settings()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    settings = get_settings()
+    logger = get_logger("app.main")
+
+    prepare_employee_directory()
+    prepare_agent_foundation()
+    prepare_knowledge_library()
+    logger.info(
+        "Server ready - host=%s port=%s prefix=%s",
+        settings.app_host,
+        settings.app_port,
+        settings.api_v1_prefix,
+    )
+    yield
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
 
     setup_logging(
         level=settings.log_level,
@@ -26,11 +48,14 @@ def create_app() -> FastAPI:
         "Starting %s (env=%s, debug=%s)", settings.app_name, settings.app_env, settings.app_debug
     )
 
-    app = FastAPI(
-        title=settings.app_name,
-        debug=settings.app_debug,
-        version="0.1.0",
-    )
+    app = FastAPI(
+        title=settings.app_name,
+        debug=settings.app_debug,
+        version="0.1.0",
+        description=API_DESCRIPTION,
+        openapi_tags=OPENAPI_TAGS,
+        lifespan=lifespan,
+    )
 
     app.add_middleware(AccessLogMiddleware)
 
@@ -45,23 +70,17 @@ def create_app() -> FastAPI:
 
     app.include_router(api_router, prefix=settings.api_v1_prefix)
 
-    @app.get("/", tags=["root"])
-    def root() -> dict[str, str]:
-        return {"message": f"{settings.app_name} is running"}
-
-    @app.on_event("startup")
-    def _on_startup() -> None:
-        prepare_employee_directory()
-        prepare_agent_foundation()
-        prepare_knowledge_library()
-        logger.info(
-            "Server ready - host=%s port=%s prefix=%s",
-            settings.app_host,
-            settings.app_port,
-            settings.api_v1_prefix,
-        )
-
-    return app
+    @app.get(
+        "/",
+        tags=["root"],
+        response_model=RootStatusRead,
+        summary="服务根检查",
+        description="用于快速确认后端服务进程已经启动。",
+    )
+    def root() -> RootStatusRead:
+        return RootStatusRead(message=f"{settings.app_name} is running")
+
+    return app
 
 
 app = create_app()