🌌 프로젝트명: 삼타로 (SamTaro)

세 장의 타로 카드로 고민을 해결해주는 감성적인 웹 애플리케이션입니다. 사용자의 텍스트 질문과 선택한 타로 카드를 기반으로 GPT API를 호출해 리딩 결과를 제공합니다. 감성적인 UI와 직관적인 UX로 사용자 몰입을 극대화하고자 설계했습니다. (그리고 저 본인이 타로점을 볼 줄 알기도 합니다.)

🗓️ 개발 개요

• 개발 기간: 2025.05.15 ~ 2025.05.22 (1주일)
• 개발 인원: 1인
• 활용 목적: 토이 프로젝트
• 배포 링크: 삼타로(vercel 배포)

🛠️ 기술 스택 및 도입 이유

• HTML / CSS / JavaScript (Vanilla)

  • React 등의 라이브러리나 프레임워크 없이 순수 JS로 전체 상태와 구조를 직접 설계하고 구현함으로써, 기본기와 DOM 제어 능력을 체화하고자 함

• OpenAI GPT API / Tarot API

  • 사용자 질문에 대한 맞춤형 해석을 생성하기 위해 GPT API를 사용
  • 타로 카드 데이터는 Tarot API로부터 구조화된 형태로 받아와 활용 (이미지는 직접 매핑함)

• CSS Animation / Drag Scroll 구현

  • 카드 선택에 몰입감을 더하기 위한 애니메이션을 적용
  • 마우스 및 터치 기반의 드래그 스크롤 기능을 구현하여 직관적 조작 가능

• 기능 기반 모듈 설계 (Vanilla 방식)

  • React를 사용하지 않더라도 기능 단위로 코드를 분리함으로써 재사용성과 가독성을 높이고, 구조적 사고를 연습하기 위함

• Git & GitHub 협업 연습

  • 깃과 깃허브의 용도를 알게된 바를 적용
  • 이슈 템플릿 설정, 기능별로 이슈 나누기
  • 세팅, 기능 추가 등 상황에 따라 나누어 커밋
  • 이슈에 맞추어 브랜치 만들어 작업 후 PR

🧩 원 페이지 방식 채택 이유

• 타로 리딩은 몰입감이 중요한 콘텐츠이므로, 페이지 새로고침 없이 부드럽게 이동하는 구조가 적합하다고 판단함
• switchPage(from, to) 방식으로 DOM element를 제어함으로써 라우트나 페이지 전환 없이 과정을 단계별로 연결함

🔄 사용자 플로우

홈 → 질문 입력 → 카드 선택 (78장 중 3장) → GPT의 결과 해석 → 다시하기 또는 홈 이동

⚙️ 내부 동작 흐름

1. 질문 입력 시 상태(state)에 저장하여 전역 공유
2. 카드 3장 선택 → 카드 정보와 질문을 함께 GPT API에 전달
3. GPT 응답을 받아 결과 페이지에 출력
4. 홈 버튼 클릭 시 전체 상태 초기화 및 랜딩 페이지로 이동 (다시하기 버튼의 경우, 초기화 후 질문 입력 페이지로 이동)

✨ 주요 기능

• 78장의 카드 무작위 렌더링 및 좌우 드래그 지원
• 카드 클릭 시 앞면 공개 (최대 3장까지 선택)
• 질문 입력 후, 카드 3장 선택 완료 후 다음 섹션으로 넘어가는 버튼 활성화
• GPT 기반 텍스트 리딩 결과 출력 (유저의 질문과 카드 선택 결과를 포함한 프롬프트 전송, 응답 받아 출력)
• 다시하기 및 홈으로 이동 기능

🧠 구현 중 겪은 문제 및 해결

• 재사용 필요한 데이터 관리의 어려움 → state.js로 전역적 상태 관리
• 카드 클릭 중 드래그 오작동 → isDragging 상태를 별도로 관리하여 클릭 이벤트와 드래그 이벤트를 분리
• GPT 응답이 너무 길어 가독성 저하 → 의미 중심의 단락화, 줄바꿈 등을 적용해 UX 개선
• 모바일 터치가 되지 않았음 → touchstart, touchmove, touchend 이벤트를 핸들링하여 PC와 동일한 동작 구현
• 결과 버튼 중복 클릭 될 수 있음 → addEventListener에 { once: true } 옵션을 설정, 그 전 removeEventListener도 이용해 다회 클릭 방지 처리
• 페이지 전환 후 스크롤 위치 초기화가 안 됨 → switchPage() 내부에서 scrollTop = 0 처리로 각 페이지 진입 시 항상 최상단부터 시작
• API 응답 지연 시 사용자 혼란 → 로딩 중... UI 요소(#result-loading, #card-loading)로 현재 상태 안내
• 빠른 페이지 전환 시 애니메이션 충돌 → setTimeout 기반 단계 처리로 fade 효과 충돌 방지

📌 향후 개선 가능한 점

• 전반적인 리팩토링, 구조 재설계
• React로 이식해보기, 혹은 SPA와 라우팅 원리를 라이브러리 없이 구현해보기
• GPT 프롬프트를 상황별로 세분화하여 응답 품질 향상
• 질문 히스토리 저장 기능 (로컬 스토리지 또는 백엔드 연동 고려)
• 프리셋 기능 (연애운, 금전운, 오늘의 운세 등)

👩💻 개발자 정보

• 이름: 함서연(Ham Seoyeon)
• 역할: 기획, 디자인, 프론트엔드 개발, API 연동
• 목적: Vanilla JS 기반의 구조적 개발 경험 쌓기, GitHub Issue와 PR 활용하여 체계적으로 프로젝트 관리하기
• 이메일: ina0312@naver.com

📜 라이선스

본 프로젝트는 MIT License를 따릅니다.