o2o-castad-backend/app/lyric/schemas/lyric.py

"""
Lyric API Schemas

이 모듈은 가사 관련 API 엔드포인트에서 사용되는 Pydantic 스키마를 정의합니다.

사용 예시:
    from app.lyric.schemas.lyric import (
        LyricStatusResponse,
        LyricDetailResponse,
        LyricListItem,
    )
    from app.utils.pagination import PaginatedResponse

    # 라우터에서 response_model로 사용
    @router.get("/lyric/{task_id}", response_model=LyricDetailResponse)
    async def get_lyric(task_id: str):
        ...

    # 페이지네이션 응답 (공통 스키마 사용)
    @router.get("/songs", response_model=PaginatedResponse[SongListItem])
    async def list_songs(...):
        ...
"""

from datetime import datetime
from typing import Optional

from pydantic import BaseModel, ConfigDict, Field


class GenerateLyricRequest(BaseModel):
    """가사 생성 요청 스키마

    Usage:
        POST /lyric/generate
        Request body for generating lyrics.

    Example Request:
        {
            "task_id": "0694b716-dbff-7219-8000-d08cb5fce431",
            "customer_name": "스테이 머뭄",
            "region": "군산",
            "detail_region_info": "군산 신흥동 말랭이 마을",
            "language": "Korean"
        }
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "task_id": "0694b716-dbff-7219-8000-d08cb5fce431",
                "customer_name": "스테이 머뭄",
                "region": "군산",
                "detail_region_info": "군산 신흥동 말랭이 마을",
                "language": "Korean",
            }
        }
    )

    task_id: str = Field(
        ..., description="작업 고유 식별자 (이미지 업로드 시 생성된 task_id)"
    )
    customer_name: str = Field(..., description="고객명/가게명")
    region: str = Field(..., description="지역명")
    detail_region_info: Optional[str] = Field(None, description="상세 지역 정보")
    language: str = Field(
        default="Korean",
        description="가사 출력 언어 (Korean, English, Chinese, Japanese, Thai, Vietnamese)",
    )


class GenerateLyricResponse(BaseModel):
    """가사 생성 응답 스키마

    Usage:
        POST /lyric/generate
        Returns the generated lyrics.

    Note:
        실패 조건:
        - ChatGPT API 오류
        - ChatGPT 거부 응답 (I'm sorry, I cannot, I can't, I apologize 등)
        - 응답에 ERROR: 포함
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "success": True,
                "task_id": "0694b716-dbff-7219-8000-d08cb5fce431",
                "lyric": "인스타 감성의 스테이 머뭄\n군산 신흥동 말랭이 마을에서\n여유로운 하루를 보내며\n추억을 만들어가요",
                "language": "Korean",
                "error_message": None,
            }
        }
    )

    success: bool = Field(..., description="생성 성공 여부")
    task_id: Optional[str] = Field(None, description="작업 고유 식별자 (uuid7)")
    lyric: Optional[str] = Field(None, description="생성된 가사 (성공 시)")
    language: str = Field(..., description="가사 언어")
    error_message: Optional[str] = Field(None, description="에러 메시지 (실패 시, ChatGPT 거부 응답 포함)")


class LyricStatusResponse(BaseModel):
    """가사 상태 조회 응답 스키마

    Usage:
        GET /lyric/status/{task_id}
        Returns the current processing status of a lyric generation task.
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "task_id": "0694b716-dbff-7219-8000-d08cb5fce431",
                "status": "completed",
                "message": "가사 생성이 완료되었습니다.",
            }
        }
    )

    task_id: str = Field(..., description="작업 고유 식별자")
    status: str = Field(..., description="처리 상태 (processing, completed, failed)")
    message: str = Field(..., description="상태 메시지")


class LyricDetailResponse(BaseModel):
    """가사 상세 조회 응답 스키마

    Usage:
        GET /lyric/{task_id}
        Returns the generated lyric content for a specific task.
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "id": 1,
                "task_id": "0694b716-dbff-7219-8000-d08cb5fce431",
                "project_id": 1,
                "status": "completed",
                "lyric_prompt": "고객명: 스테이 머뭄, 지역: 군산...",
                "lyric_result": "인스타 감성의 스테이 머뭄\n군산 신흥동 말랭이 마을에서\n여유로운 하루를 보내며\n추억을 만들어가요",
                "created_at": "2024-01-15T12:00:00",
            }
        }
    )

    id: int = Field(..., description="가사 ID")
    task_id: str = Field(..., description="작업 고유 식별자")
    project_id: int = Field(..., description="프로젝트 ID")
    status: str = Field(..., description="처리 상태")
    lyric_prompt: str = Field(..., description="가사 생성 프롬프트")
    lyric_result: Optional[str] = Field(None, description="생성된 가사")
    created_at: Optional[datetime] = Field(None, description="생성 일시")


class LyricListItem(BaseModel):
    """가사 목록 아이템 스키마

    Usage:
        Used as individual items in paginated lyric list responses.
    """

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "id": 1,
                "task_id": "0694b716-dbff-7219-8000-d08cb5fce431",
                "status": "completed",
                "lyric_result": "인스타 감성의 스테이 머뭄\n군산 신흥동 말랭이 마을에서...",
                "created_at": "2024-01-15T12:00:00",
            }
        }
    )

    id: int = Field(..., description="가사 ID")
    task_id: str = Field(..., description="작업 고유 식별자")
    status: str = Field(..., description="처리 상태")
    lyric_result: Optional[str] = Field(None, description="생성된 가사 (미리보기)")
    created_at: Optional[datetime] = Field(None, description="생성 일시")