🏡 가족 공동 별장 예약 관리 서비스

가족이나 외가 친척들이 같이 쓰는 별장을
좀 덜 불편하게 쓰려고 만든 프로젝트입니다.

카톡이나 전화로 “나 이번 주 써도 돼?” 이런 식으로 맞추다 보니까
겹치거나 헷갈리는 경우가 생각보다 많아서,
그걸 조금 정리해보고 싶어서 시작했습니다.

---

📌 프로젝트 한 줄 요약

초대코드 + 관리자 승인 기반으로 운영되는 폐쇄형 별장 예약 서비스

---

🤔 왜 만들었나

실제로 가족끼리 별장 쓰다 보면 이런 문제들이 있었습니다.

• 누가 언제 쓰는지 한눈에 안 보임
• 일정이 겹쳤을 때 기준이 애매함
• 가족 외 인원이 섞일 수 있음
• 관리자 입장에서 통제가 어려움

그래서 단순 예약 기능이 아니라,

• 아무나 접근하지 못하고
• 승인된 사용자만 이용하고
• 예약은 명확하게 관리되는

형태로 만들어보는 것을 목표로 했습니다.

---

⚙️ 주요 기능

👤 회원 / 인증

• 초대코드 기반 회원가입
• 가입 시 PENDING 상태로 저장
• 관리자 승인 후 ACTIVE 상태에서만 로그인 가능
• JWT 기반 인증

---

🎟 초대코드

• 1회용 코드
• 상태 관리
  • ACTIVE
  • USED
  • EXPIRED
  • REVOKED
• 만료된 코드는 사용 시 자동으로 EXPIRED 처리

---

📅 예약 (진행 중)

• 날짜 단위 예약
• 시작일 ~ 종료일 포함
• 하루 단위 예약 가능
• 예약 취소 기능
• 관리자 예약 수정 기능 예정
• 캘린더 기반 조회 예정

---

📏 정책 정리

회원가입

• 초대코드 없으면 가입 불가
• signupNote는 선택 입력
• 가입 후 바로 사용 불가
• 관리자 승인 후 이용 가능

---

로그인

• ACTIVE 상태만 로그인 가능
• PENDING, REJECTED는 로그인 차단
• 아이디 존재 여부는 구체적으로 노출하지 않음 (보안)

---

예약 중복 기준

기존 예약: A ~ B 신규 예약: X ~ Y

A <= Y && B >= X

하루라도 겹치면 중복으로 처리합니다.

---

🛠 기술 스택

Backend

• Java 21
• Spring Boot 4
• Spring Security
• Spring Data JPA
• JWT (jjwt)

Database

• MySQL 8

Frontend

• Thymeleaf

Dev / Infra

• Gradle
• IntelliJ / VSCode
• Git / GitHub

---

📁 프로젝트 구조

com.jinsu.villa ├─ common ├─ auth ├─ user ├─ invite ├─ reservation └─ admin

기능 단위로 나누는 구조로 설계했고,
초기에 잡은 구조를 유지하면서 확장하는 방향으로 개발 중입니다.

---

✅ 현재 구현 범위

회원가입

• loginId 중복 검사
• 초대코드 검증 (존재 / 상태 / 만료)
• 비밀번호 BCrypt 암호화
• 사용자 PENDING 상태 저장
• 초대코드 USED 처리

---

로그인

• loginId 조회
• 비밀번호 검증
• ACTIVE 상태만 로그인 허용
• JWT 토큰 발급

---

JWT 인증

• 토큰 생성 / 검증
• userId / loginId / role 추출
• 인증 필터 적용
• Stateless 구조 적용

---

✔️ 검증 완료

• 정상 회원가입 성공
• 중복 아이디 차단
• 잘못된 초대코드 차단
• 만료 코드 차단
• PENDING 로그인 차단
• ACTIVE 로그인 성공

---

🐛 트러블슈팅

1. 만료된 초대코드 상태 불일치 문제

문제

만료된 초대코드로 회원가입 시도 시
가입은 실패하지만 DB에는 ACTIVE로 남아있던 문제 발생

원인

같은 트랜잭션 안에서

• 상태 변경
• 예외 발생

→ 전체 롤백되면서 상태 변경도 취소됨

해결

• 초대코드 상태 변경 로직을 REQUIRES_NEW 트랜잭션으로 분리

결과

• 회원가입은 실패
• 초대코드는 정상적으로 EXPIRED 반영

---

2. VSCode PowerShell 한글 깨짐

문제

터미널에서 한글 로그가 깨짐

해결

• UTF-8 인코딩 설정
• JVM / Gradle / PowerShell 설정 통일

결과

정상 출력

---

🚧 앞으로 구현할 기능

• /users/me
• 관리자 승인 기능
• 초대코드 관리 API
• 예약 생성 / 조회 / 취소
• 캘린더 조회
• 관리자 예약 수정
• 권한 분리 강화
• 공통 예외 응답 구조 정리
• 배포 환경 구성

---

🔐 설정 관리

민감 정보는 코드에 직접 포함하지 않고
환경변수(.env 등)로 분리해서 관리할 예정입니다.

• DB 접속 정보
• JWT Secret Key
• 기타 배포 설정

---

🧾 마무리

이 프로젝트는 단순 CRUD 연습이 아니라,

• 초대 기반 회원가입
• 관리자 승인
• 인증 처리
• 예약 정책 설계

이런 요소들을 실제 서비스처럼 구현해보는 것을 목표로 진행 중입니다.