오다은
ringpassAdmin

개발 개요

프로젝트명

Ringpass(링패스) — B2B 백오피스 관리자 플랫폼

소개

Ringpass는 숙박·티켓 예약이 가능한 B2C 앱 서비스이며,
본 프로젝트는 가맹점이 상품·예약·정산을 관리하는 가맹 관리자 웹과 본사에서 전체 가맹점을 운영·관리하는 슈퍼 관리자 웹을 구축한 B2B 백오피스 플랫폼입니다.

개발 기간

2025년 4월 ~

기여도

웹 프론트엔드 100%

기술 스택

Routing & Rendering

  • React.js

    React 18 기반 SPA 구조로 관리자 웹 화면을 구성하고, 컴포넌트 단위로 화면을 모듈화하여 재사용성을 높였습니다.

  • React Router DOM

    React Router를 사용해 인증 화면과 서비스 화면을 분리하고, 레이아웃 기반 중첩 라우팅과 ProtectedRoute로 접근 제어를 구현했습니다.

  • Vite

    Vite를 사용하여 빠르게 실행되는 개발 서버(HMR)와 esbuild 기반의 고속 빌드를 활용해 개발 생산성을 높였습니다.

  • TypeScript

    전역 타입 정의와 API 응답 모델을 TypeScript로 관리하여 런타임 오류를 줄이고, 협업 시 코드 가독성과 유지보수성을 강화했습니다.

State Management

  • React Query

    가맹점 정보, 상품 정보 등 서버 상태를 React Query로 관리하며, 데이터 특성에 따라 staleTime을 분리 설정해 캐싱과 실시간성을 균형 있게 조절했습니다.

  • Zustand

    인증 정보, 모달/토스트 노출 상태, 가맹점 ID와 같은 전역 도메인 상태 등을 분리해 관리하여, 가벼운 전역 스토어 구조를 유지했습니다.

  • React Hook Form + Zod

    복잡한 입력 폼(가맹점 등록, 상품 등록 등)을 React Hook Form으로 관리하고, Zod 스키마로 입력값과 API 요청 데이터를 검증하여 성능 최적화와 타입 안전성을 동시에 확보했습니다.

Styling

  • Tailwind CSS

    Tailwind CSS 유틸리티 클래스를 사용하여 관리자 UI를 빠르게 구성하고, 공통 컴포넌트에서도 일관된 디자인 토큰을 적용했습니다.

  • Ringpass Admin Shared UI

    사내 공통 UI 패키지를 별도 라이브러리로 분리해 버튼, 모달, 테이블 등 컴포넌트를 재사용하고, 가맹/슈퍼 관리자 웹의 디자인 일관성을 확보했습니다.

Functional Components & Utilities

  • FullCalendar

    FullCalendar(core / daygrid / interaction)를 사용해 매출·정산 내역 등을 캘린더 형태로 직관적으로 시각화했습니다.

  • React Datepicker

    기간 검색이나 예약일 선택 등 날짜 입력이 필요한 폼에서 사용자가 쉽게 날짜를 선택할 수 있도록 캘린더 UI를 제공했습니다.

  • Swiper

    배너나 카드 리스트 등 스와이프 가능한 영역에 Swiper를 적용해 슬라이드 기반 UI를 구현했습니다.

  • XLSX

    매출·정산·예약 데이터를 XLSX 포맷으로 변환하여 사용자가 엑셀 파일로 다운로드할 수 있도록 처리했습니다.

  • Browser Image Compression

    이미지 업로드 시 브라우저 단에서 용량을 압축해 업로드 속도와 서버 저장 공간을 최적화했습니다.

Testing & Tooling

  • MSW (Mock Service Worker)

    백엔드 개발과 병행하기 위해 MSW로 목 API를 구현하고, 실제 API 호출과 동일한 흐름으로 프론트엔드 기능을 개발·테스트했습니다.

  • ESLint & Prettier

    ESLint와 Prettier, 그리고 prettier-plugin-tailwindcss를 적용해 코드 스타일과 품질을 자동으로 정리하고, 팀 내 일관된 코드 규칙을 유지했습니다.

Deployment

  • GitHub Actions

    사내에서 구축된 AWS S3·CloudFront 환경에 GitHub Actions를 연동하여 자동 빌드·배포 파이프라인을 구성했습니다.

핵심 기능

가맹 관리자 기능

  • 가맹점 기본 정보 관리(주소, 연락처, 업장 정보 등 등록·수정)
  • 숙박·티켓 상품 등록·수정·삭제 및 노출 상태 설정
  • 상품별 가격·수량·옵션 설정 등 판매 정보 관리
  • 예약·주문 조회 및 상태 관리(검색·필터·상세 확인)
  • 매출·정산 내역 조회 및 월별 필터링
  • 이용 후기 조회 및 관리자 댓글 작성
  • 계정 정보 수정, 비밀번호 변경, 탈퇴 신청

슈퍼 관리자 기능

  • 전체 가맹점 목록 조회 및 검색
  • 신규 가맹점 가입 승인·관리
  • 가맹점별 운영 현황 모니터링
  • 가맹점별 매출·정산 지표 확인

프로젝트 아키텍처 & 개발 전략

1. 공통 UI 패키지 구축 및 활용

  • 가맹/슈퍼 관리자 웹이 별도 프로젝트임에도 UI 구조가 동일해, 중복 개발을 줄이기 위해 공통 UI 패키지를 구축했습니다.
  • UI 패키지를 GitHub Packages(Private)로 배포하여 두 프로젝트에서 공통 컴포넌트를 의존성으로 설치해 사용할 수 있도록 구성했습니다.
  • UI 변경 사항은 패키지 버전 업데이트 방식으로 각 관리자 웹에 반영했으며, 공통 UI 패키지를 사용하는 구조 덕분에 전체 서비스의 UI/UX 일관성과 유지보수 효율을 높일 수 있었습니다.

2. Git 기반 버전 관리 및 배포 자동화

  • Git 커밋 컨벤션을 정의해 일관된 형식으로 변경 이력을 관리했으며, 기능 추가·버그 수정·리팩토링 등 작업 유형에 따라 Prefix를 구분해 의도가 드러나는 커밋 메시지를 작성했습니다.
  • 기능 개발은 feature 브랜치에서 진행 후 dev 브랜치로 통합하고, 안정화된 코드는 main 브랜치에 머지하여 운영 환경에 반영하는 흐름으로 구성했습니다.
  • dev / main 브랜치 머지 시 GitHub Actions가 자동으로 빌드·배포를 수행하도록 설정해, 사내에서 구축된 AWS S3·CloudFront 환경과 연동된 배포 자동화를 구현했습니다.
feat      : 기능 추가 (새로운 기능 구현)
fix       : 버그 수정
refactor  : 리팩토링 (기능 변화 없이 코드 구조 개선)
design    : UI 스타일 변경 (CSS 등 화면 요소 수정)
comment   : 주석 추가 또는 변경
style     : 코드 스타일 수정 (세미콜론, 포맷팅 등: 로직 변경 없음)
docs      : 문서 작업 (README, 주석 외 문서 추가/수정/삭제)
test      : 테스트 코드 추가·수정·삭제 (로직 변경 없음)
chore     : 기타 작업 (빌드 설정, 패키지 관리, assets 등)
init      : 초기 프로젝트 설정
rename    : 파일 또는 폴더명 변경/이동 (내용 변경 없음)
remove    : 파일 또는 폴더 삭제만 수행하는 경우

3. React Query 기반 데이터 캐싱 전략

  • 전역 QueryClient를 설정해 데이터 성격에 따라 캐싱 전략을 구분하고, 서버 상태를 중앙에서 일관되게 관리했습니다.
  • 변경 가능성이 낮은 데이터(가맹점 상세, 지자체 정보 등)는 staleTime 1시간, 예약·후기처럼 실시간성이 중요한 데이터는 staleTime 0으로 설정해 데이터 특성에 맞게 캐싱 기준을 구분했습니다.
  • 이를 통해 불필요한 API 재요청은 줄이고, 실시간 반영이 필요한 영역은 즉시 업데이트되도록 균형 있게 설계했습니다.
export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 60, // 1시간
      gcTime: 1000 * 60 * 60, // 1시간
      retry: 1, // 실패 시 1번 재시도
      refetchOnWindowFocus: false, // 창 포커스 시 자동 재요청 방지
    },
    mutations: {
      retry: 0, // 실패 시 재시도 없음
    },
  },
});

4. MSW를 활용한 Mock API 환경

  • 백엔드 API 개발과 병행하기 위해 MSW(Mock Service Worker)로 Mock API를 구축해, 실제 요청 흐름과 동일한 환경에서 프론트엔드 기능을 개발했습니다.
  • 기획 단계에서 정의된 API 스펙을 기반으로 요청·응답 모델을 사전에 설계해 두었으며, 실제 서버가 준비되면 baseURL만 교체해 바로 연동할 수 있도록 구성했습니다.
  • 이를 통해 백엔드 진행 상황과 무관하게 프론트엔드 개발 속도를 유지하고, 초기 개발 안정성과 작업 효율을 높일 수 있었습니다.

5. React Hook Form + Zod 기반 폼 처리

  • 가맹점 등록·상품 등록 등 복잡한 입력 폼을 React Hook Form으로 관리해 불필요한 리렌더링을 최소화하고 폼 상태를 안정적으로 유지했습니다.
  • Zod 스키마를 적용해 입력값과 API 요청 데이터를 검증하여 서버·클라이언트 간 타입 불일치를 예방했습니다.

6. React + Vite 조합으로 프로젝트를 구성

  • 관리자 웹 특성상 SSR이 필요하지 않고 CSR만으로도 충분하다고 판단했습니다.
  • Vite를 사용해 설정을 단순화하고 빠른 빌드·HMR로 초기 개발 속도를 높였습니다.
  • 다만 Next.js에서 제공하는 라우팅·파일 시스템·이미지 최적화 기능이 없기 때문에 page router 구성, 번들 최적화 등의 작업을 직접 처리해야 한다는 점도 함께 경험했습니다.

운영·협업 방식

1. Jira 기반 칸반 보드 운영

  • Jira 칸반 보드를 기반으로 업무를 “해야 할 일 → 진행 → 검수 → 완료” 단계로 시각화해 작업 흐름을 일관되게 관리했습니다.
  • 업무 요청은 Jira에 할 일(Task)로 등록해 담당자를 지정하고, Slack 연동으로 변경 사항을 자동 공유해 구두 전달 없이도 원활하게 협업했습니다.

2. 전사 테스트(QA) 프로세스 운영

  • 화면·기능 단위 테스트 케이스를 엑셀로 정리해 1차·2차 오픈 시 공통으로 사용할 QA 기준을 마련했습니다.
  • 사내 직원을 대상으로 전사 테스트를 진행해 발견된 이슈와 피드백을 수집하고, 결과를 Jira 이슈로 등록해 담당자별로 처리했습니다.
  • 동일한 프로세스를 각 오픈 단계마다 반복 적용해 주요 버그를 사전에 제거하고 서비스 안정성을 높였습니다.

3. 기획·디자인·백엔드와의 기능 개발 협업 흐름

  • 개발 전 기획안을 바탕으로 기능 흐름과 요구사항을 파악하고, 개발 과정에서는 Figma 디자인을 참고해 화면 구조와 동작 방식을 정리했습니다.
  • 구현 과정에서 이해가 필요한 부분이나 변경이 필요한 요소는 기획자·디자이너와 직접 커뮤니케이션하며 기능 흐름과 UI를 조율했습니다.
  • API 스펙은 팀장님이 정리한 초기 정의서를 기준으로 URL과 요청/응답 모델을 검토하고 필요한 부분은 팀 내 논의를 통해 보완했습니다.
  • 개발 중 발생한 이슈나 조정이 필요한 사항들은 백엔드 개발자와 협의하며 해결했습니다.

4. AI 도구 활용

  • Cursor를 활용해 코드 자동완성, 반복되는 패턴 생성, 에러 원인 분석 등을 빠르게 처리하며 개발 속도를 높였습니다. 문제 발생 시 오류 메시지나 원인을 분석할 때 활용해 디버깅 시간을 줄였습니다.
  • README나 API 가이드 문서 작성 시, 기존 코드를 기반으로 정리해야 하는 내용은 Cursor를 통해 초안을 생성하고 이후 직접 검토·수정하며 문서 품질을 보완했습니다.
  • ChatGPT는 개발 과정에서 필요한 용어나 개념을 확인하거나, 적합한 라이브러리와 구현 방식을 선택할 때 참고 자료로 활용했습니다.
  • AI 도구는 개발 생산성을 높이기 위한 보조 수단으로 활용하되, 핵심 로직 구현과 구조 설계는 직접 판단하며 진행했습니다.