CHAM-51 가족 초대 비즈니스 로직 구현

[pillow12360]

유형

• 기능 추가
• 버그 수정
• 리팩토링
• 문서 수정
• 기타

설명

🏠 가족 스페이스 백엔드 API 구현 완료

📝 구현 개요

• 기능: 가족 스페이스 생성/관리 REST API
• 기술: Spring Boot 3.4.6, MyBatis, MariaDB, Swagger
• 브랜치: feature/family-space-backend

---

🚀 핵심 구현 사항

1. REST API 엔드포인트 (7개)

Method	Endpoint	기능
POST	/api/family-space	가족 생성
POST	/api/family-space/join	가족 참여
GET	/api/family-space/{fid}	대시보드 조회
GET	/api/family-space/invite/{code}/validate	초대코드 검증
POST	/api/family-space/{fid}/invite-code	새 초대코드 생성
DELETE	/api/family-space/{fid}/leave	가족 탈퇴
GET	/api/family-space/my-family	내 가족 조회

2. 핵심 비즈니스 로직

• 초대코드: 영문대문자+숫자 6자리 (A1B2C3)
• 인원제한: 최대 5명
• 가족명 제한: 최대 10자
• 자동탈퇴: 새 가족 참여 시 기존 가족 자동 탈퇴
• 할인계산: 기본 14,000원/인 + 청소년(19세 미만) 10,000원 추가
• 데이터 정리: 마지막 구성원 탈퇴 시 가족 자동 삭제

3. 데이터베이스 설계

• 기존 ERD 활용 (Family_space ↔ Users 관계)
• 16개 SQL 쿼리로 모든 기능 구현
• 트랜잭션 처리로 데이터 일관성 보장

---

📁 파일 구조

family/
├── controller/FamilyController.java    # REST API (7개 엔드포인트)
├── service/FamilyService.java          # 비즈니스 로직 (트랜잭션 관리)
├── dao/FamilyDao.java                  # MyBatis 인터페이스 (16개 메서드)
└── dto/                                # 9개 DTO 클래스
    ├── FamilySpace.java               # 가족 스페이스 정보
    ├── FamilyMember.java              # 구성원 정보 (요금제 포함)
    ├── CreateFamilyRequest/Response.java # 생성/참여 요청/응답
    ├── FamilyDashboardResponse.java   # 대시보드 전체 정보
    └── ...
resources/mapper/Family.xml             # MyBatis SQL 매퍼 (16개 쿼리)

config/SwaggerConfig.java               # API 문서화 설정

---

🔧 기술적 특징

보안 및 검증

• 사용자 존재 검증: 모든 API에서 유효한 사용자인지 확인
• 권한 체크: 가족 구성원만 해당 가족 정보 접근 가능
• 입력값 검증: 가족명, 초대코드 형식 검증

트랜잭션 관리

• @Transactional로 가족 생성/참여의 원자성 보장
• 실패 시 모든 변경사항 롤백

예외 처리

• FamilyServiceException: 비즈니스 로직 예외
• FamilyAccessDeniedException: 권한 관련 예외
• 상황별 명확한 에러 메시지 제공

MyBatis 활용

• LEFT JOIN으로 요금제 정보 선택적 포함
• useGeneratedKeys로 가족 ID 자동 생성
• 동적 쿼리 및 파라미터 검증

---

✅ 해결된 주요 이슈

버그 수정

• ❌ 존재하지 않는 사용자 문제: 없는 uid로 가족 생성/참여 가능
• ✅ 해결: 모든 API에서 사용자 존재 여부 검증 추가
• ❌ 응답 메시지 불일치: 가족 참여 시 "생성되었습니다" 메시지 표시
• ✅ 해결: 상황별 적절한 메시지 반환 (success(family, message) 오버로드)

데이터 정리

• 가족 관련 모든 데이터 안전 삭제 SQL 제공
• 외래키 제약조건 고려한 순차 삭제
• 테스트용 데이터 초기화 스크립트

---

✅ 가족 스페이스 CRUD 작업

✅ 초대 시스템 (코드 생성/검증/참여)

✅ 할인 계산 로직

✅ 권한 관리 및 보안

✅ API 문서화

✅ 에러 처리 및 검증

---

🎯 결과

✅ 가족 스페이스 핵심 기능 완성

• 안정적인 API 7개 구현
• 완전한 에러 처리 및 검증
• 프론트엔드 연동 준비 완료

📋 코드 리뷰 요청: 비즈니스 로직, 보안, 성능 검토

---

📊 통계

• 구현 파일: 13개
• API 엔드포인트: 7개
• SQL 쿼리: 16개
• DTO 클래스: 9개
• 테스트 커버리지: 모든 핵심 시나리오 검증 완료

테스트

1. 로컬 Swagger 테스트 완료 각자 로컬 확인 필요
2. http://localhost:8090/swagger-ui/index.html

[Jetty-Lee]

수고하셨습니다.

[LuaKimm]

굿