🗄️ GiftCall 데이터베이스 설계

📚 목차

📋 설계 개요

완전한 1:N 구조: 하나의 주문에 여러 수신자

전체 구조

gift_orders (1)
    ↓
gift_recipients (N)
    ↓
    ├── recipient_messages (M)
    └── recipient_change_logs (M)

파일 구조

• backend/app/models/gift_models.py - 모델 정의
• backend/app/models/enums.py - Enum 정의
• backend/app/utils/encryption.py - 암호화 관리

🗄️ 테이블 상세

1️⃣ gift_orders (주문)

선물 주문의 기본 정보

• order_number: 주문 번호 (고유)
• sender_phone: 발신자 전화번호 (암호화)
• status: 주문 상태 (pending/in_progress/completed/cancelled)
• total_recipients: 총 수신자 수 (캐시)

2️⃣ gift_recipients (수신자)

각 수신자의 상세 정보 및 배송 상태

• order_id: 주문 ID (FK)
• name: 수신자명 (암호화)
• phone: 전화번호 (암호화)
• address: 주소 (암호화)
• status: 수신자 상태 (12단계)

3️⃣ recipient_messages (소통 이력)

수신자와의 모든 소통 기록

• recipient_id: 수신자 ID (FK)
• message_type: 발신/수신 구분
• message_channel: 카카오톡/SMS/전화/이메일
• content: 메시지 내용

4️⃣ recipient_change_logs (변경 이력)

수신자 정보 변경 추적

• recipient_id: 수신자 ID (FK)
• field_name: 변경된 필드명
• old_value: 이전 값
• new_value: 새 값

📊 상태 관리

12단계 상태: 실제 업무 플로우 반영

연락 단계 (1-4)

• 📋 PENDING: 연락 대기
• 📤 FIRST_CONTACT: 1차 연락
• 📤📤 SECOND_CONTACT: 2차 연락
• 📤📤📤 THIRD_CONTACT: 3차 연락

응답 단계 (5-9)

• 💬 RESPONDED: 응답 받음
• ✅ CONFIRMED: 배송 확정
• ❌ DECLINED: 수령 거부
• ⏰ POSTPONED: 연기 요청
• 📵 UNREACHABLE: 연락 불가

배송 단계 (10-12)

• 🚚 DELIVERED: 배송 완료
• ✅ RECEIVED: 수령 확인
• ❌ FAILED_DELIVERY: 배송 실패

상태 전환 플로우

PENDING → FIRST_CONTACT → SECOND_CONTACT → THIRD_CONTACT
    ↓
RESPONDED
    ↓
    ├── CONFIRMED → DELIVERED → RECEIVED
    ├── DECLINED
    ├── POSTPONED
    └── UNREACHABLE

🔐 보안 및 암호화

개인정보 보호: Fernet (AES-256) 암호화

암호화 대상 필드

• gift_orders.sender_phone: 발신자 전화번호
• gift_recipients.name: 수신자명
• gift_recipients.phone: 전화번호
• gift_recipients.address: 주소
• gift_recipients.delivery_address: 배송 주소

암호화 구현

# Python 프로퍼티로 자동 암복호화
class GiftRecipient(Base):
    _name = Column("name", Text, nullable=False)
    
    @property
    def name(self) -> str:
        return encryption_manager.decrypt_name(self._name)
    
    @name.setter
    def name(self, value: str):
        self._name = encryption_manager.encrypt_name(value)

# 사용 예시
recipient.name = "홍길동"  # 자동 암호화
print(recipient.name)     # 자동 복호화

성능 최적화

• 인덱스: order_id, status, sent_at 등 주요 조회 필드
• 캐시: gift_orders에 통계 필드 (total_recipients, pending_count 등)
• JOIN 최적화: joinedload로 N+1 문제 방지