⚙️ GiftCall 개발 과정과 기술 선택

📚 목차

🔄 아키텍처 진화

핵심 변화: 실제 업무 요구사항 반영을 위한 완전한 재설계

문제 인식과 해결 과정

새로운 구조 설계

GiftOrder (1) → GiftRecipient (N) → RecipientMessage (M)
                                              → RecipientChangeLog (M)

마이그레이션 과정

실제 업무 시나리오 반영

🗄️ 데이터베이스 설계

설계 원칙: 실제 업무 플로우를 완벽하게 지원하는 데이터 구조

핵심 테이블 구조

12단계 수신자 상태 관리

개인정보 암호화 필드

데이터 볼륨 예상

# 일반적인 주문 (50명 수신자)
GiftOrder: 1건
GiftRecipient: 50건
RecipientMessage: 250건 (수신자당 평균 5회 소통)
RecipientChangeLog: 150건 (수신자당 평균 3회 변경)

# 연간 예상 (100개 주문)
총 데이터: 약 45,100건
저장 용량: 약 500MB (암호화 포함)

성능 최적화

🏗️ 기술 스택

선택 기준: 빠른 개발 + 안정성 + 확장성

최종 기술 구성

개발 환경 구성

# docker-compose.dev.yml 핵심 구성
services:
  postgres:
    image: postgres:15
    ports: ["5433:5432"]  # 충돌 방지
    environment:
      POSTGRES_DB: giftcall_dev
      POSTGRES_USER: giftcall_dev
      POSTGRES_PASSWORD: dev_password_123

  redis:
    image: redis:7-alpine
    ports: ["6380:6379"]  # 충돌 방지

  backend:
    build: ./backend
    ports: ["8001:8000"]
    volumes:
      - ./backend/app:/app/app
      - ./config:/config  # 암호화 키 마운트

  frontend:
    build: ./frontend
    ports: ["3001:3000"]

프로젝트 구조

giftcall/
├── backend/app/
│   ├── models/
│   │   ├── enums.py           # RecipientStatus 등 Enum 정의
│   │   ├── gift_models.py     # 새로운 1:N 구조 모델
│   │   └── models.py          # 기존 모델 (Store, User)
│   ├── routers/
│   │   ├── auth.py           # 공통 인증 모듈
│   │   ├── orders.py         # 기존 주문 API (호환성)
│   │   └── gift_orders.py    # 새로운 GiftCall API
│   ├── services/
│   │   └── gift_service.py   # 비즈니스 로직
│   └── utils/
│       ├── common_auth.py    # 공통 인증 헬퍼
│       └── encryption.py     # 개인정보 암호화
├── frontend/src/
│   ├── views/               # 페이지 컴포넌트
│   ├── components/          # 재사용 컴포넌트
│   └── stores/              # Pinia 상태 관리
├── scripts/
│   ├── manage-db.sh         # DB 관리 도구
│   └── migrate_to_gift_system.py  # 마이그레이션
└── docs/
    └── 05-giftcall-database-schema.md  # DB 문서

🔐 보안 구현

핵심 원칙: 개인정보 보호 최우선 + 다층 보안

개인정보 암호화 시스템

# app/utils/encryption.py
from cryptography.fernet import Fernet
import base64

class EncryptionManager:
    def __init__(self):
        self.key = self._load_or_generate_key()
        self.cipher = Fernet(self.key)
    
    def encrypt_name(self, name: str) -> str:
        """이름 암호화"""
        encrypted = self.cipher.encrypt(name.encode())
        return base64.b64encode(encrypted).decode()
    
    def decrypt_name(self, encrypted_name: str) -> str:
        """이름 복호화"""
        encrypted_data = base64.b64decode(encrypted_name.encode())
        decrypted = self.cipher.decrypt(encrypted_data)
        return decrypted.decode()

# 전역 인스턴스
encryption_manager = EncryptionManager()

JWT + Redis 하이브리드 인증

공통 인증 모듈

# app/utils/common_auth.py
class CommonAuth:
    @staticmethod
    def login(db: Session, username: str, password: str) -> Dict[str, Any]:
        """통합 로그인 처리"""
        user = authenticate_user(db, username, password)
        if not user:
            raise HTTPException(status_code=401, detail="인증 실패")
        
        # JWT 토큰 생성
        access_token = create_access_token(
            data={"sub": user.username}, 
            expires_delta=timedelta(minutes=30)
        )
        
        return {
            "access_token": access_token,
            "token_type": "bearer",
            "user": {
                "id": user.id,
                "username": user.username,
                "role": user.role.value,
                "store_id": user.store_id
            }
        }

# 전역 인스턴스
common_auth = CommonAuth()

권한 기반 접근 제어

환경별 보안 설정

⚙️ 개발 프로세스

방법론: AI 협업 + 점진적 개발 + 철저한 문서화

DB 마이그레이션 과정

# 마이그레이션 실행
./scripts/manage-db.sh migrate

# 실행 내용
1. 기존 테이블 정리 (orders, recipients, sms_logs)
2. 새로운 테이블 생성 (gift_orders, gift_recipients, ...)
3. 기본 데이터 초기화 (점포, 사용자)
4. 결과 검증

공통 인증 모듈 개발

테스트 전략

개발 도구 및 스크립트

# 주요 관리 도구
./scripts/manage-db.sh          # DB 관리 (check, init, migrate)
python test_auth_helper.py      # 인증 테스트
docker-compose -f docker-compose.dev.yml up  # 개발 환경

# 사용 예시
./scripts/manage-db.sh check    # DB 상태 확인
./scripts/manage-db.sh migrate  # 새 시스템으로 마이그레이션
python test_auth_helper.py      # 인증 시스템 테스트

문서화 전략

🚀 다음 단계

목표: 2025년 설날 현장 테스트 준비

개발 로드맵

API 개발 계획

현장 테스트 준비

성공 지표