🆘 SOS: Save Our Special day 🧩

"소중한 날을 구하기 위한 실시간 퍼즐 레이스" ⏱️🏃‍♂️

---

1. 🚀 소개 (Introduction)

SOS: Save Our Special day는 제한 시간 내에 조각난 퍼즐을 맞추고, 실시간으로 기록을 겨루는 경쟁형 퍼즐 웹 애플리케이션입니다. 🎮

본 서비스는 완전한 **독립 구동형 서비스(Self-Contained Service)**로 설계되었습니다. 프론트엔드, 백엔드 API 서버, 데이터베이스(PostgreSQL), 메모리 내 고속 데이터 저장소(Redis)가 하나의 Docker Compose로 묶여 있습니다. 📦 따라서 외부 데이터베이스 구축이나 번거로운 라이브러리 의존성 설치 없이, 명령어 한 줄만으로 로컬이나 클라우드 환경에서 즉시 배포 및 독립 구동이 가능합니다.

---

2. ✨ 주요 기능 (Key Features)

• 🏆 실시간 글로벌 순위표: 퍼즐을 완료하는 즉시 내 기록이 글로벌 순위표에 실시간 반영되어 다른 플레이어들과 실시간 경쟁을 즐길 수 있습니다.
• ⏱️ 긴장감 넘치는 시간 제한 및 💡 스마트 힌트: 60초의 제한 시간 동안 퍼즐을 맞추는 긴장감 속에 어려울 때는 게임당 단 한 번 10초간 원본 이미지를 확인하는 힌트를 쓸 수 있습니다.
• 🔒 1등만을 위한 비밀 메시지: 1등을 차지한 단 한 명에게만 숨겨진 특별한 비밀 메시지가 공개됩니다.
• 📅 개인 도전 이력 및 최고 기록 관리: 내가 도전한 모든 게임 기록(클리어 시간, 날짜)과 개인 최고 기록 대비 현재 성과를 한눈에 볼 수 있도록 제공합니다.
• 🛡️ 부정행위 실시간 감지 및 방지: 비정상적인 매크로나 시각적 조작 시도를 백엔드 유효성 검사로 실시간 감지하여 깨끗한 랭킹 시스템을 유지합니다.
• 🎨 몰입감 높은 인터랙티브 애니메이션: 퍼즐 조작 시의 반응형 피드백과 함께 완료 시 빛나는 글로우 효과 및 폭죽 축하 연출로 뛰어난 시각적 몰입감을 제공합니다. 🎉

---

3. ⚙️ 설치 및 실행 (Getting Started)

📋 의존성 요건 (Prerequisites)

프로젝트를 실행하려면 다음 소프트웨어가 설치되어 있어야 합니다.

• 🐳 Docker & Docker Compose (컨테이너 환경 실행 시 권장)
• 🟢 Node.js v20 이상 & npm (로컬 프론트엔드 개발 시 필요)
• 🐍 Python 3.11 이상 (로컬 백엔드 개발 시 필요)

🔑 환경 변수 설정

실행 전 프로젝트 루트 디렉토리에 .env 파일을 생성해야 합니다. 제공된 .env.example 파일을 복사하여 작성하세요.

cp .env.example .env

Important

게임용 퍼즐 이미지 조각을 동적으로 생성하고 서빙하기 위해 AWS S3 설정(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_BUCKET_NAME)이 반드시 기재되어야 게임 정상 구동이 가능합니다. ☁️

---

🐳 방법 A. Docker Compose로 일괄 실행 (권장)

별도의 의존성 설치 없이 전체 스택(Frontend, Backend, PostgreSQL, Redis)을 일괄 실행합니다.

1. 서비스 빌드 및 백그라운드 실행 🚀

   docker compose up --build -d

2. 구동 확인 🔗
   • 프론트엔드 Web: http://localhost:3000 🌐
   • 백엔드 API: http://localhost:8000/api/v1 ⚡
   • API 문서 (Swagger): http://localhost:8000/api/v1/openapi.json 📖

---

💻 방법 B. 로컬 개발 환경에서 개별 실행

개발 시 코드 핫 리로드(Hot Reload)를 활용하려면 프론트엔드와 백엔드를 로컬에서 직접 구동할 수 있습니다.

1. 🐍 백엔드 (FastAPI) 실행

1. 백엔드 폴더로 이동 후 가상환경 생성 및 패키지 설치:

   cd backend
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt

2. 데이터베이스 준비 및 FastAPI 서버 구동:

   # (선택) .env에서 SQLite를 사용하려면 DATABASE_URL="sqlite+aiosqlite:///./data/sos.db"로 설정
   # Redis가 로컬(localhost:6379)에 기동 중이어야 실시간 랭킹이 올바르게 동작합니다.
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2. ⚛️ 프론트엔드 (Vite + React) 실행

1. 루트 디렉토리로 이동하여 의존성 라이브러리 설치:

   npm install

2. 로컬 개발 서버 구동:

   npm run dev

   구동 완료 시 브라우저에서 http://localhost:5173을 통해 접속합니다. 💻

---

4. ☁️ AWS 추천 구성 (Recommended AWS Deployment)

프로덕션 환경에서 수많은 사용자의 실시간 접속 및 동시 퍼즐 이벤트를 유연하고 안전하게 처리하기 위한 AWS 추천 아키텍처 구성입니다. 🛠️

graph TD
    User([사용자 브라우저]) <--> |Route 53| CloudFront[AWS CloudFront]
    CloudFront --> |정적 에셋 서빙| S3_Static[S3 Static Bucket]
    CloudFront --> |API & WebSocket 요청| ALB[Application Load Balancer]
    ALB --> |HTTPS / WSS| ECS[ECS Fargate: App Container Task]
    ECS --> |비동기 트래픽 & 순위 캐싱| Cache[Amazon ElastiCache Redis]
    ECS --> |영속 사용자 및 기록 저장| RDS[(Amazon RDS PostgreSQL)]
    ECS <--> |퍼즐 이미지 서빙 & Presigned URL| S3_Assets[S3 Game Assets Bucket]

Loading

1. AWS S3 버킷 설정 (Game Assets) 🪣

퍼즐로 조각낼 원본 고화질 이미지를 서빙하기 위해 AWS S3 버킷을 구성합니다. 브라우저에서 이미지 조각을 Canvas에 올바르게 가공하고 CORS 오류를 피하기 위해 버킷에 CORS(Cross-Origin Resource Sharing) 규칙을 필수 설정해야 합니다.

S3 버킷 CORS 구성 예시 JSON: 📄

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": ["ETag", "Content-Type"],
    "MaxAgeSeconds": 3000
  }
]

2. 프로덕션 인프라 추천 사양 🏗️

• 컴퓨팅 (ECS Fargate):
  • API 서버의 비동기 처리 및 WebSocket 연결 유지를 위해 오토스케일링이 적용된 Amazon ECS(Fargate) 구성을 추천합니다.
  • ALB(Application Load Balancer)에서 WebSocket 연결 유지를 위해 세션 스티키니스(Sticky Sessions) 또는 최소 300초 이상의 유휴 제한 시간 설정을 권장합니다.
• 데이터베이스 (RDS PostgreSQL):
  • 사용자 데이터 및 상세 이력 저장을 위해 db.t4g.micro 또는 db.t4g.small 클래스의 PostgreSQL을 사용하여 비용 대비 최적의 성능을 낼 수 있습니다.
• 고속 캐싱 & 랭킹 (ElastiCache for Redis):
  • 글로벌 순위표의 초고속 조회 및 랭킹 갱신(Zset 연산)을 유지하기 위해 최소 사양의 Amazon ElastiCache Serverless(Redis) 또는 cache.t4g.micro 노드를 배치합니다.

---

5. 🗺️ 로드맵 (Roadmap)

• 🌟 다양한 난이도 모드 지원: 기존 4x4 고정 퍼즐에서 3x3(쉬움), 5x5(어려움) 등 사용자 선택 난이도 추가
• 🔑 소셜 로그인 다각화: Google, Apple, Kakao 등 간편 소셜 계정 가입 기능 연동
• 📸 사용자 커스텀 이미지 퍼즐: 본인이 직접 올린 사진으로 퍼즐방을 생성해 친구들과 기록 경쟁을 할 수 있는 개인 맞춤형 퍼즐 모드
• 📱 모바일 터치 감도 및 제스처 최적화: 모바일 브라우저 환경에서의 드래그 앤 드롭 슬라이딩 조작감 개선 및 햅틱 진동 피드백 적용
• 🌐 다국어 지원(i18n): 글로벌 레이서들을 위한 영어, 일어 등 번역 리소스 번들링

---

6. 📄 라이선스 (License)

본 프로젝트는 MIT License에 따라 배포됩니다. 자세한 내용은 프로젝트 내 LICENSE 파일이 생성되면 확인하실 수 있습니다.