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

server/src/app/api/v1/endpoints/health.py

@@ -5,12 +5,18 @@ from sqlalchemy import text
 
 from app.core.config import get_settings
 from app.db.session import get_engine
+from app.schemas.common import HealthCheckRead
 
 router = APIRouter(prefix="/health")
 
 
-@router.get("")
-def health_check() -> dict[str, object]:
+@router.get(
+    "",
+    response_model=HealthCheckRead,
+    summary="服务健康检查",
+    description="检查服务基础状态，并在系统初始化完成后验证数据库连通性。",
+)
+def health_check() -> HealthCheckRead:
     settings = get_settings()
     database_ok = False
     database_error = None
@@ -23,12 +29,12 @@ def health_check() -> dict[str, object]:
         except Exception as exc:  # pragma: no cover - runtime connectivity branch
             database_error = str(exc)
 
-    return {
-        "status": "ok" if database_ok else "degraded",
-        "database": {
+    return HealthCheckRead(
+        status="ok" if database_ok else "degraded",
+        database={
             "configured": settings.setup_completed,
             "ok": database_ok,
             "error": database_error,
         },
-        "redis": {"configured": bool(settings.redis_url), "enabled": bool(settings.redis_url)},
-    }
+        redis={"configured": bool(settings.redis_url), "enabled": bool(settings.redis_url)},
+    )