feat: 운세 상세 테이블 생성, 오늘 운세 프롬프트 작성, 오늘 운세 조회 API 생성 (#16)

* feat: 운세 상세 테이블 생성, 오늘 운세 프롬프트 작성, 오늘 운세 조회 API 생성

* feat: hcx call/parsing 실패 시 fallback

---------

Co-authored-by: Gukhee Jo <[email protected]>

Author: 9keyyyy

migrations/env.py

@@ -30,7 +30,7 @@
 # 모든 도메인 모델을 import하여 메타데이터에 포함해야 함
 from src.users.entities.models import User
 from src.lotto.entities.models import LottoStatistics, LottoDraws
-from src.fortune.entities.models import DailyFortuneResource, UserDailyFortuneSummary
+from src.fortune.entities.models import DailyFortuneResource, UserDailyFortuneSummary, UserDailyFortuneDetail
 
 # 모델 메타데이터 설정
 target_metadata = Base.metadata

migrations/versions/926bb28822d1_add_user_daily_fortune_detail_table.py

@@ -0,0 +1,45 @@
+"""add_user_daily_fortune_detail_table
+
+Revision ID: 926bb28822d1
+Revises: de9ee05d86b4
+Create Date: 2025-08-13 21:13:08.667387
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '926bb28822d1'
+down_revision: Union[str, Sequence[str], None] = 'de9ee05d86b4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('user_daily_fortune_detail',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False, comment='운세 상세 기록 고유 ID'),
+    sa.Column('user_id', sa.String(length=255), nullable=False, comment='유저 ID'),
+    sa.Column('fortune_date', sa.Date(), nullable=False, comment='운세 날짜'),
+    sa.Column('fortune_score', sa.Integer(), nullable=False, comment='운세 점수'),
+    sa.Column('fortune_comment', sa.String(length=1000), nullable=False, comment='운세 코멘트'),
+    sa.Column('fortune_details', sa.JSON(), nullable=False, comment='운세 상세 정보 (JSON)'),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.CheckConstraint('fortune_score >= 0 AND fortune_score <= 100', name='ck_fortune_score_range'),
+    sa.CheckConstraint('length(fortune_comment) > 0', name='ck_fortune_comment_len'),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table('user_daily_fortune_detail')
+    # ### end Alembic commands ###

src/common/utils.py

@@ -0,0 +1,8 @@
+from datetime import date, datetime, timezone, timedelta
+
+
+def get_kst_date() -> date:
+    """한국 표준시(KST) 기준으로 오늘 날짜를 반환합니다."""
+    kst_tz = timezone(timedelta(hours=9))
+    kst_now = datetime.now(kst_tz)
+    return kst_now.date()

src/fortune/entities/constants.py

@@ -0,0 +1,12 @@
+"""
+운세 관련 상수 및 샘플 데이터
+"""
+
+# 일일 운세 fallback 샘플 데이터
+DAILY_FORTUNE_FALLBACK_DATA = {
+    "score": 75,
+    "comment": "좋은 기운이 문을 두드리고 있소",
+    "money_fortune": "적은 노력으로 일확천금",
+    "job_fortune": "구직 성공의 기운",
+    "love_fortune": "백억부자 애인 각",
+}

src/fortune/entities/models.py

@@ -1,5 +1,5 @@
 # src/fortune/entities/models.py
-from sqlalchemy import Column, Integer, Date, Enum as SAEnum, String, CheckConstraint, ForeignKey
+from sqlalchemy import Column, Integer, Date, Enum as SAEnum, String, CheckConstraint, ForeignKey, JSON
 from sqlalchemy.orm import relationship
 from src.config.database import Base
 from src.fortune.entities.enums import FortuneType
@@ -26,3 +26,19 @@ class UserDailyFortuneSummary(Base):
     user_id = Column(String(255), ForeignKey("users.id"), nullable=False, comment="유저 ID")
     daily_fortune_resource_id = Column(Integer, ForeignKey("daily_fortune_resources.id"), nullable=False, comment="운세 리소스 ID")
     fortune_date = Column(Date, nullable=False, comment="운세 날짜")
+
+
+class UserDailyFortuneDetail(Base):
+    __tablename__ = "user_daily_fortune_detail"
+
+    id = Column(Integer, primary_key=True, autoincrement=True, comment="운세 상세 기록 고유 ID")
+    user_id = Column(String(255), ForeignKey("users.id"), nullable=False, comment="유저 ID")
+    fortune_date = Column(Date, nullable=False, comment="운세 날짜")
+    fortune_score = Column(Integer, nullable=False, comment="운세 점수")
+    fortune_comment = Column(String(1000), nullable=False, comment="운세 코멘트")
+    fortune_details = Column(JSON, nullable=False, comment="운세 상세 정보 (JSON)")
+
+    __table_args__ = (
+        CheckConstraint("fortune_score >= 0 AND fortune_score <= 100", name="ck_fortune_score_range"),
+        CheckConstraint("length(fortune_comment) > 0", name="ck_fortune_comment_len"),
+    )

src/fortune/entities/schemas.py

@@ -1,6 +1,6 @@
 # src/fortune/entities/schemas.py
 from datetime import date
-from typing import List, Optional
+from typing import List, Optional, Dict
 from src.config.schemas import CommonBase
 from src.fortune.entities.enums import FortuneType
 
@@ -37,4 +37,12 @@ class UserDailyFortuneSummary(CommonBase):
     fortune_date: date
     fortune_type: FortuneType
     image_url: str
-    description: str
+    description: str
+
+class UserDailyFortuneDetail(CommonBase):
+    id: int
+    user_id: str
+    fortune_date: date
+    fortune_score: int
+    fortune_comment: str
+    fortune_details: Dict[str, str]

src/fortune/repository.py

@@ -1,12 +1,17 @@
-# src/fortune/repository.py
 from datetime import date
 from typing import List, Optional, Tuple
+
 from fastapi import Depends
 from sqlalchemy import select, desc, and_
 from sqlalchemy.ext.asyncio import AsyncSession
+
 from src.common.dependencies import get_db_session
-from src.fortune.entities.models import UserDailyFortuneSummary as UserDailyFortuneSummaryModel, DailyFortuneResource as DailyFortuneResourceModel
 from src.fortune.entities.enums import FortuneType
+from src.fortune.entities.models import (
+    UserDailyFortuneSummary as UserDailyFortuneSummaryModel,
+    DailyFortuneResource as DailyFortuneResourceModel,
+    UserDailyFortuneDetail as UserDailyFortuneDetailModel,
+)
 from src.fortune.entities.schemas import UserDailyFortuneSummary
 
 
@@ -19,7 +24,7 @@ async def create_fortune(
         publish_date: date,
         fortune_type: FortuneType,
         image_url: str,
-        description: str
+        description: str,
     ) -> DailyFortuneResourceModel:
         model = DailyFortuneResourceModel(
             publish_date=publish_date,
@@ -28,7 +33,7 @@ async def create_fortune(
             description=description,
         )
         self.session.add(model)
-        await self.session.commit()
+        await self.session.flush()
         await self.session.refresh(model)
         return model  # DB 모델 반환
 
@@ -38,7 +43,7 @@ async def update_fortune(
         publish_date: Optional[date],
         fortune_type: Optional[FortuneType],
         image_url: Optional[str],
-        description: Optional[str]
+        description: Optional[str],
     ) -> DailyFortuneResourceModel:
         model = await self.get_fortune_by_id(resource_id)
         if not model:
@@ -53,7 +58,7 @@ async def update_fortune(
         if description is not None:
             model.description = description
 
-        await self.session.commit()
+        await self.session.flush()
         await self.session.refresh(model)
         return model
 
@@ -62,7 +67,7 @@ async def delete_fortune(self, resource_id: int) -> None:
         if not model:
             raise ValueError("리소스를 찾을 수 없습니다.")
         await self.session.delete(model)
-        await self.session.commit()
+        await self.session.flush()
 
     async def get_fortunes(
         self,
@@ -71,7 +76,9 @@ async def get_fortunes(
         publish_date: Optional[date] = None,
         fortune_type: Optional[FortuneType] = None,
     ) -> Tuple[List[DailyFortuneResourceModel], Optional[int]]:
-        query = select(DailyFortuneResourceModel).order_by(desc(DailyFortuneResourceModel.id))
+        query = select(DailyFortuneResourceModel).order_by(
+            desc(DailyFortuneResourceModel.id)
+        )
 
         conditions = []
         if cursor:
@@ -91,25 +98,32 @@ async def get_fortunes(
         next_cursor = items[-1].id if len(items) == limit else None
         return items, next_cursor
 
-    async def get_fortune_by_id(self, resource_id: int) -> Optional[DailyFortuneResourceModel]:
+    async def get_fortune_by_id(
+        self, resource_id: int
+    ) -> Optional[DailyFortuneResourceModel]:
         return await self.session.get(DailyFortuneResourceModel, resource_id)
 
     async def get_user_daily_fortune_summaries(
-            self, user_id: str, fortune_date: date
+        self, user_id: str, fortune_date: date
     ) -> List[UserDailyFortuneSummary]:
-        query = select(
-            UserDailyFortuneSummaryModel.id,
-            UserDailyFortuneSummaryModel.user_id,
-            UserDailyFortuneSummaryModel.fortune_date,
-            DailyFortuneResourceModel.fortune_type,
-            DailyFortuneResourceModel.image_url,
-            DailyFortuneResourceModel.description
-        ).join(
-            DailyFortuneResourceModel,
-            UserDailyFortuneSummaryModel.daily_fortune_resource_id == DailyFortuneResourceModel.id
-        ).filter(
-            UserDailyFortuneSummaryModel.user_id == user_id,
-            UserDailyFortuneSummaryModel.fortune_date == fortune_date
+        query = (
+            select(
+                UserDailyFortuneSummaryModel.id,
+                UserDailyFortuneSummaryModel.user_id,
+                UserDailyFortuneSummaryModel.fortune_date,
+                DailyFortuneResourceModel.fortune_type,
+                DailyFortuneResourceModel.image_url,
+                DailyFortuneResourceModel.description,
+            )
+            .join(
+                DailyFortuneResourceModel,
+                UserDailyFortuneSummaryModel.daily_fortune_resource_id
+                == DailyFortuneResourceModel.id,
+            )
+            .filter(
+                UserDailyFortuneSummaryModel.user_id == user_id,
+                UserDailyFortuneSummaryModel.fortune_date == fortune_date,
+            )
         )
 
         result = await self.session.execute(query)
@@ -123,7 +137,39 @@ async def get_user_daily_fortune_summaries(
                 fortune_date=summary[2],
                 fortune_type=summary[3],
                 image_url=summary[4],
-                description=summary[5]
+                description=summary[5],
             )
             for summary in summaries
-        ]
+        ]
+
+    async def get_user_daily_fortune_detail(
+        self, user_id: str, fortune_date: date
+    ) -> Optional[UserDailyFortuneDetailModel]:
+        """특정 날짜의 사용자 운세 상세 정보 조회"""
+        query = select(UserDailyFortuneDetailModel).filter(
+            UserDailyFortuneDetailModel.user_id == user_id,
+            UserDailyFortuneDetailModel.fortune_date == fortune_date,
+        )
+        result = await self.session.execute(query)
+        return result.scalar_one_or_none()
+
+    async def create_user_daily_fortune_detail(
+        self,
+        user_id: str,
+        fortune_date: date,
+        fortune_score: int,
+        fortune_comment: str,
+        fortune_details: dict,
+    ) -> UserDailyFortuneDetailModel:
+        """사용자 운세 상세 정보 생성"""
+        model = UserDailyFortuneDetailModel(
+            user_id=user_id,
+            fortune_date=fortune_date,
+            fortune_score=fortune_score,
+            fortune_comment=fortune_comment,
+            fortune_details=fortune_details,
+        )
+        self.session.add(model)
+        await self.session.flush()
+        await self.session.refresh(model)
+        return model