Merge pull request #63 from kookmin-sw/feature/#60-refactor

[#60][BE] 백엔드 코드 리팩토링

Author: syeon111

backend/app/ai/main.py

@@ -7,6 +7,7 @@
 from app.core.auth.csrf import verify_csrf
 from app.core.auth.dependencies import get_current_user_id
 from app.core.config import settings
+from app.core.schemas.health import HealthResponse
 
 app = FastAPI(title="Poco AI Orchestrator")
 
@@ -28,8 +29,8 @@
 
 
 @app.get("/health")
-def health() -> dict:
-    return {"ok": True, "service": "ai"}
+def health() -> HealthResponse:
+    return HealthResponse(ok=True, service="ai")
 
 
 # Lambda B entrypoint

backend/app/ai/routers/steps.py

@@ -1,44 +1,46 @@
 from uuid import UUID
 
-from fastapi import APIRouter, Depends
-from sqlalchemy.orm import Session
+from fastapi import Depends
 from fastapi import status as http_status
+from sqlalchemy.orm import Session
 
 from app.ai.services import step_service
+from app.core.api.route import EnvelopeRouter
 from app.core.database import get_db
+from app.core.schemas.step import (
+    NotionTemplateResponse,
+    StepAcceptResponse,
+    StepDetailResponse,
+    StepGenerateResponse,
+)
 
-router = APIRouter()
-
-
-def _ok(data):
-    return {"status": "success", "data": data}
+router = EnvelopeRouter()
 
 
 @router.post("/steps/{step_id}/generate", status_code=http_status.HTTP_201_CREATED)
-def generate_steps(step_id: UUID, db: Session = Depends(get_db)) -> dict:
+def generate_steps(
+    step_id: UUID, db: Session = Depends(get_db)
+) -> StepGenerateResponse:
     """현재 Step 기반으로 다음 후보 Step 3개를 AI로 생성."""
-    response = step_service.generate_steps(db, step_id)
-    return _ok(response)
+    return step_service.generate_steps(db, step_id)
+
 
 @router.post("/steps/{step_id}/accept", status_code=http_status.HTTP_200_OK)
-def accept_step(step_id: UUID, db: Session = Depends(get_db)) -> dict:
-    response = step_service.accept_step(db, step_id)
-    return _ok(response)
+def accept_step(step_id: UUID, db: Session = Depends(get_db)) -> StepAcceptResponse:
+    return step_service.accept_step(db, step_id)
+
 
 @router.get("/steps/{step_id}", status_code=http_status.HTTP_200_OK)
-def get_step_detail(step_id: UUID, db: Session = Depends(get_db)) -> dict:
-    response = step_service.get_step_detail(db, step_id)
-    return _ok(response)
+def get_step_detail(step_id: UUID, db: Session = Depends(get_db)) -> StepDetailResponse:
+    return step_service.get_step_detail(db, step_id)
 
 
 @router.post(
     "/steps/{step_id}/notion-template", status_code=http_status.HTTP_201_CREATED
 )
-def create_notion_template(step_id: UUID) -> dict:
+def create_notion_template(step_id: UUID) -> NotionTemplateResponse:
     """Required Step의 Notion 템플릿 페이지 생성 — TODO: Notion API 연동."""
-    return _ok(
-        {
-            "notion_page_id": "placeholder",
-            "notion_page_url": "https://notion.so/placeholder",
-        }
+    return NotionTemplateResponse(
+        notion_page_id="placeholder",
+        notion_page_url="https://notion.so/placeholder",
     )

backend/app/ai/services/orchestrator.py

@@ -2,8 +2,7 @@
 
 from app.core.aws.bedrock import bedrock_runtime
 from app.core.config import settings
-from app.core.schemas.bedrock import AcceptPayload, GeneratePayload, SidePanelPayload
-
+from app.core.schemas.step import AcceptRequest, GenerateRequest, SidePanelRequest
 
 
 def _invoke_claude(prompt: str) -> str:
@@ -30,8 +29,11 @@ def _invoke_claude(prompt: str) -> str:
 {"is_current_required_step_completed": true 또는 false}
 """
 
-def call_accept(payload: AcceptPayload) -> dict:
-    message = ACCEPT_PROMPT + "\n\n" + json.dumps(payload.model_dump(), ensure_ascii=False)
+
+def call_accept(request: AcceptRequest) -> dict:
+    message = (
+        ACCEPT_PROMPT + "\n\n" + json.dumps(request.model_dump(), ensure_ascii=False)
+    )
     raw = _invoke_claude(message)
     return json.loads(raw)
 
@@ -46,11 +48,14 @@ def call_accept(payload: AcceptPayload) -> dict:
 """
 
 
-def call_generate(payload: GeneratePayload) -> dict:
-    message = GENERATE_PROMPT + "\n\n" + json.dumps(payload.model_dump(), ensure_ascii=False)
+def call_generate(request: GenerateRequest) -> dict:
+    message = (
+        GENERATE_PROMPT + "\n\n" + json.dumps(request.model_dump(), ensure_ascii=False)
+    )
     raw = _invoke_claude(message)
     return json.loads(raw)
 
+
 SIDE_PANEL_PROMPT = """\
 당신은 소프트웨어 개발 방법론 전문가입니다.
 아래 데이터를 바탕으로 사용자가 클릭한 Step에 대한 멘토링과 용어 사전을 생성하세요.
@@ -71,7 +76,11 @@ def call_generate(payload: GeneratePayload) -> dict:
 """
 
 
-def call_side_panel(payload: SidePanelPayload) -> dict:
-    message = SIDE_PANEL_PROMPT + "\n\n" + json.dumps(payload.model_dump(), ensure_ascii=False)
+def call_side_panel(request: SidePanelRequest) -> dict:
+    message = (
+        SIDE_PANEL_PROMPT
+        + "\n\n"
+        + json.dumps(request.model_dump(), ensure_ascii=False)
+    )
     raw = _invoke_claude(message)
-    return json.loads(raw)
+    return json.loads(raw)