서울 한 달 살기 방 단위 숙소 예약 웹
설계·구현 참고 자료 — 고객 납품 실적으로 구분된 항목이 아닙니다.
외국인 게스트가 서울의 방 단위 숙소를 찾고, 입주 기간에 맞는 월할·일할 금액을 확인한 뒤 입주 신청과 카드·PayPal 결제까지 이어 가는 흐름을 데모로 구현합니다.
프로젝트 개요
외국인 게스트가 서울의 방 단위 숙소를 찾고, 입주 기간에 맞는 월할·일할 금액을 확인한 뒤 입주 신청과 카드·PayPal 결제까지 이어 가는 흐름을 데모로 구현합니다. 지도 위치 표시와 영어·한국어 화면 전환을 포함하며, 호스트 승인 전 24시간 동안 방이 임시 확보되는 상태를 내 예약에서 확인할 수 있도록 설계합니다.
작업 범위
- 방 단위 숙소 검색과 지도 보기: 오늘 입주 가능한 방이 지도 위 핀과 목록 카드로 함께 보이고, 지역 칩으로 좁힌 뒤 방을 골라 상세로 이동할 수 있습니다. 화면 상단의 언어 전환으로 영어와 한국어 문구를 바꿔 볼 수 있습니다
- 월할·일할 요금 계산: 입주일과 퇴실일을 고르면 월 단위 요금과 남는 일수의 일할 금액, 보증금이 항목별로 나뉘어 계산됩니다. 한 달을 채우는 경우와 중간 일수를 포함하는 경우의 금액 차이를 같은 화면에서 비교할 수 있습니다
- 입주 신청과 카드·PayPal 결제 확정: 입주자 정보와 옵션을 입력해 신청을 접수하고, 카드 또는 PayPal 중 한 가지로 결제를 확인하면 예약이 확정되는 흐름입니다. 결제 확인 전에는 신청 내용과 합계 금액을 한 번 더 보여 줍니다
- 내 예약과 24시간 방 확보 상태: 신청한 예약이 승인 대기, 확정, 취소 중 어느 상태인지와 입주 일정을 목록으로 확인합니다. 승인 대기 건에는 방이 임시 확보되는 24시간의 남은 시간이 표시되고, 취소 시 환불 예정 금액을 안내합니다
주요 업무
- 방 단위 숙소 검색과 지도 보기 화면: 방 단위 입주 가능 일정을 지도 좌표와 함께 조회하고, 선택한 핀과 목록 카드를 서로 연결해 보여 줍니다
- 월할·일할 요금 계산 화면: 월할·일할 규칙을 서버 계산 로직으로 두고, 화면은 계산 결과 항목만 받아 그립니다
- 입주 신청과 카드·PayPal 결제 확정 화면: 신청 접수, 결제 수단 선택, 결제 확인 후 예약 확정까지를 하나의 주문 상태 머신으로 처리합니다
- 내 예약과 24시간 방 확보 상태 화면: 예약 상태별 목록과 확보 만료 시각을 함께 조회하고, 취소 요청 시 환불 규칙에 따른 금액을 계산해 보여 줍니다



프로젝트 핵심 과제
방 단위 일정에서 같은 기간에 두 건의 신청이 겹칠 수
트랜잭션 격리와 확보 시각 검사로 대응합니다
카드 PG의 해외 카드 지원 범위와 PayPal 가맹 승인은 외부 절차에 따라 달라질 수
샌드박스 기준으로 먼저 연동합니다
월 경계를 걸치는 기간의 일할 기준이 해석에 따라 갈릴 수
계산 규칙을 명세서로 먼저 확정합니다
기존 시제품의 검색·날짜 선택 오류는 원인을 재현 가능한 케이스로 정리한 뒤 범위를 정해 보완할 계획입니다
핵심 기능 상세
방 단위 숙소 검색과 지도 보기
오늘 입주 가능한 방이 지도 위 핀과 목록 카드로 함께 보이고, 지역 칩으로 좁힌 뒤 방을 골라 상세로 이동할 수 있습니다. 화면 상단의 언어 전환으로 영어와 한국어 문구를 바꿔 볼 수 있습니다.
- Prisma 쿼리로 방 단위 입주 가능 일정과 위치 좌표를 한 번에 조회
- 지도 API 마커와 목록 카드의 선택 상태를 하나의 상태로 동기화
- i18n 문구 사전과 언어 전환 컨텍스트로 영어·한국어 화면 분리
지도 핀 선택과 목록 카드 선택을 하나의 상태로 묶어 방 단위 검색 결과를 동시에 보여 주는 조회 구조를 설계합니다.


월할·일할 요금 계산
입주일과 퇴실일을 고르면 월 단위 요금과 남는 일수의 일할 금액, 보증금이 항목별로 나뉘어 계산됩니다. 한 달을 채우는 경우와 중간 일수를 포함하는 경우의 금액 차이를 같은 화면에서 비교할 수 있습니다.
- 서버 계산 함수로 월 단위 요금과 잔여 일수 일할 금액을 분리 산출
- 보증금·청소비 옵션을 요금 항목 배열로 합성해 금액 검산 가능한 응답 설계
- 입주 기간 변경 시 디바운스 요청으로 계산 결과를 갱신
월할과 일할 규칙을 서버 한 곳의 계산 로직으로 모아 상세·결제·정산이 같은 금액을 쓰도록 설계합니다.


입주 신청과 카드·PayPal 결제 확정
입주자 정보와 옵션을 입력해 신청을 접수하고, 카드 또는 PayPal 중 한 가지로 결제를 확인하면 예약이 확정되는 흐름입니다. 결제 확인 전에는 신청 내용과 합계 금액을 한 번 더 보여 줍니다.
- 주문 상태(신청·결제 대기·확정·취소)를 상태 머신으로 정의하고 Prisma 트랜잭션으로 전이
- 포트원 카드 결제와 PayPal 결제 승인 응답을 공통 결제 인터페이스로 추상화
- 결제 요청에 멱등 키를 붙여 중복 승인 요청을 막는 구조 설계
카드와 PayPal을 같은 결제 인터페이스 뒤에 두어 결제 수단이 달라도 예약 확정 흐름이 하나로 이어지게 설계합니다.


내 예약과 24시간 방 확보 상태
신청한 예약이 승인 대기, 확정, 취소 중 어느 상태인지와 입주 일정을 목록으로 확인합니다. 승인 대기 건에는 방이 임시 확보되는 24시간의 남은 시간이 표시되고, 취소 시 환불 예정 금액을 안내합니다.
- 예약 상태별 필터 쿼리와 확보 만료 시각 컬럼 인덱스 설계
- 남은 시간 표시를 서버 만료 시각 기준으로 계산하는 훅 구현
- 취소 시점별 환불 규칙을 서버 계산 함수로 분리
서버가 기록한 확보 만료 시각을 기준으로 남은 시간을 그려 화면 시계와 무관하게 같은 상태를 보여 주는 구조를 설계합니다.


프로젝트 진행 단계
요구사항 분석 및 DB 설계 · 2026.10
회원·숙소(집)·방·요금·보증금·입주 일정 테이블과 관계 설계
요금 계산·예약 API 개발 · 2026.10
월할·일할 계산 로직 이관, 입주 신청·예약 상태 전이 API와 카드·PayPal 샌드박스 연동 구현
게스트 화면 개발 · 2026.10
검색·지도·방 상세·입주 신청·내 예약 화면과 다국어 전환 구현
통합 점검 및 배포 · 2026.10
API와 화면 통합 점검, 도메인·SSL 적용과 서버 배포
개발 결과
기술적 주안점
- 지도 핀 선택과 목록 카드 선택을 하나의 상태로 묶어 방 단위 검색 결과를 동시에 보여 주는 조회 구조를 설계합니다
- 월할과 일할 규칙을 서버 한 곳의 계산 로직으로 모아 상세·결제·정산이 같은 금액을 쓰도록 설계합니다
- 카드와 PayPal을 같은 결제 인터페이스 뒤에 두어 결제 수단이 달라도 예약 확정 흐름이 하나로 이어지게 설계합니다