feat: 初始化零工后端代码

gig-poc/apps/api/app/main.py

@@ -1,6 +1,8 @@
 from contextlib import asynccontextmanager
+from time import perf_counter
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.api.routes import router
@@ -9,6 +11,7 @@ from app.core.logging import configure_logging, logger
 from app.db.base import Base
 from app.db.session import engine
 from app.services.rag.lightrag_adapter import LightRAGAdapter
+from app.services.runtime_state import get_ingest_queue, get_match_queue, get_traffic_guard
 
 
 settings = get_settings()
@@ -18,14 +21,33 @@ configure_logging(settings.log_level)
 @asynccontextmanager
 async def lifespan(_: FastAPI):
     Base.metadata.create_all(bind=engine)
+    get_ingest_queue().start()
+    get_match_queue().start()
     try:
         LightRAGAdapter(settings).ensure_ready()
     except Exception:
         logger.exception("Qdrant initialization skipped during startup")
     yield
+    get_ingest_queue().stop()
+    get_match_queue().stop()
 
 
-app = FastAPI(title=settings.app_name, lifespan=lifespan)
+app = FastAPI(
+    title=settings.app_name,
+    description=(
+        "Gig POC 接口文档。\n\n"
+        "接口分组：系统、抽取、入库、匹配、查询。\n"
+        "完整业务说明请参考项目文档 `docs/API.md`。"
+    ),
+    openapi_tags=[
+        {"name": "系统", "description": "服务与依赖组件状态检查接口"},
+        {"name": "抽取", "description": "自然语言文本抽取为结构化卡片"},
+        {"name": "入库", "description": "结构化岗位/工人数据写入与初始化"},
+        {"name": "匹配", "description": "岗位与工人双向匹配及结果解释"},
+        {"name": "查询", "description": "岗位/工人列表与详情查询"},
+    ],
+    lifespan=lifespan,
+)
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"],
@@ -33,4 +55,23 @@ app.add_middleware(
     allow_methods=["*"],
     allow_headers=["*"],
 )
+
+
+@app.middleware("http")
+async def traffic_guard_middleware(request: Request, call_next):
+    guard = get_traffic_guard()
+    allowed, reason = guard.allow(request.url.path)
+    if not allowed:
+        status_code = 429 if reason == "rate_limited" else 503
+        return JSONResponse(status_code=status_code, content={"detail": reason})
+    start = perf_counter()
+    try:
+        response = await call_next(request)
+    except Exception:
+        guard.record(500, (perf_counter() - start) * 1000)
+        raise
+    guard.record(response.status_code, (perf_counter() - start) * 1000)
+    return response
+
+
 app.include_router(router)