📋 Planu Backend

할 일 관리와 커스터마이징을 함께, Planu 앱의 백엔드 API 서버

🌟 주요 기능

📝 Todo 관리

• Todo: 날짜별 할 일 생성, 수정, 삭제, 조회
• Someday: 언젠가 할 일 관리
• Category: 카테고리별 할 일 분류

🎨 커스터마이징 상점

• Sticker Shop: 다양한 스티커 판매 및 구매
• Color Shop: 앱 테마 컬러 판매 및 구매
• 판매량 기반 인기 아이템 조회

🎟️ 쿠폰 시스템

• 쿠폰 발급 및 사용
• 사용 내역 관리

🔐 인증 & 보안

• JWT 기반 인증
• Spring Security 적용
• Firebase Authentication 연동

🛠️ 기술 스택

Backend

• Framework: Spring Boot 3.x
• Language: Java 17
• Build Tool: Gradle

Database & Cache

• Database: MySQL (JPA/Hibernate)
• Cache: Redis

Authentication & Security

• JWT: Token 기반 인증
• Spring Security: 보안 설정
• Firebase: 소셜 로그인 연동

Documentation

• Swagger/OpenAPI: API 문서 자동화

🏗️ 아키텍처 및 설계

계층형 아키텍처 (Layered Architecture)

┌─────────────────────────────────────┐
│         Controller Layer            │  ← REST API 엔드포인트
├─────────────────────────────────────┤
│          Service Layer              │  ← 비즈니스 로직
├─────────────────────────────────────┤
│        Repository Layer             │  ← 데이터 접근
├─────────────────────────────────────┤
│         Database (MySQL)            │  ← 영속성 계층
└─────────────────────────────────────┘

주요 디자인 패턴

• DTO Pattern: 계층 간 데이터 전송
• Repository Pattern: 데이터 접근 추상화
• Dependency Injection: Spring IoC 컨테이너 활용
• Builder Pattern: 엔티티 및 DTO 생성
• Exception Handling: 전역 예외 처리 (@ControllerAdvice)

🔐 보안 구현

JWT 인증 플로우

1. 사용자 로그인 요청
2. 서버에서 자격증명 검증
3. JWT Access Token + Refresh Token 발급
4. 클라이언트는 요청 시 Authorization Header에 토큰 포함
5. JwtRequestFilter에서 토큰 검증 및 인증 처리

보안 기능

• JWT Token: Access Token (단기) + Refresh Token (장기) 전략
• Spring Security: 엔드포인트별 접근 제어
• Password Encryption: BCrypt 해싱 알고리즘
• CORS 설정: 크로스 도메인 요청 제어
• Custom Exception Handling: 보안 예외 상황 처리

🚀 주요 기술 구현

1. JWT 인증 시스템

- JwtUtil: JWT 토큰 생성, 파싱, 검증
- JwtRequestFilter: 요청마다 토큰 검증 (OncePerRequestFilter)
- SecurityConfig: Spring Security 설정

2. Firebase 연동

- Firebase Admin SDK 초기화
- Firebase Authentication 토큰 검증
- 소셜 로그인 (Google, Apple 등) 지원

3. Redis 캐싱

- Redis Template 설정
- 세션 관리 및 임시 데이터 저장
- Refresh Token 저장소

4. 예외 처리 전략

- CustomException: 비즈니스 예외 정의
- ErrorCode: 에러 코드 및 메시지 enum
- CustomExceptionHandler: @RestControllerAdvice로 전역 예외 처리
- ErrorResponseEntity: 일관된 에러 응답 형식

5. API 문서화

- Swagger/OpenAPI 3.0 사용
- @Operation, @ApiResponse 어노테이션으로 상세 문서화
- JWT 인증 포함한 Try-it-out 기능

💾 데이터베이스 설계

주요 엔티티

• User: 사용자 정보 (OAuth 정보 포함)
• Category: 할 일 카테고리
• Todo: 날짜별 할 일
• TodoSomeday: 언젠가 할 일
• Sticker: 사용자 스티커
• ShopSticker/ShopColor: 상점 아이템
• PurchaseSticker/PurchaseColor: 구매 내역
• Coupon: 쿠폰 정보
• CouponUsage: 쿠폰 사용 내역

관계 설정

• User ↔ Category: 1:N
• Category ↔ Todo: 1:N
• User ↔ Todo: 1:N
• User ↔ PurchaseSticker/Color: 1:N
• User ↔ CouponUsage: 1:N

⚡ 성능 최적화

데이터베이스 최적화

• JPA N+1 문제 해결: Fetch Join 사용
• 인덱스 설정: 자주 조회되는 컬럼에 인덱스 적용
• Lazy Loading: 연관관계 지연 로딩 전략

캐싱 전략

• Redis 캐시: 자주 조회되는 데이터 캐싱
• 로컬 캐시: Spring Cache 활용

API 최적화

• DTO 변환: 필요한 데이터만 응답
• 페이지네이션: 대량 데이터 조회 시 페이징 처리

📁 프로젝트 구조

src/main/java/planu/app/
├── api/              # API 스펙 인터페이스
├── config/           # 설정 클래스 (Security, Swagger, Firebase, Redis 등)
├── controller/       # REST API 컨트롤러
├── dto/              # 요청/응답 DTO
│   ├── request/      # 요청 객체
│   └── response/     # 응답 객체
├── entity/           # JPA 엔티티
├── exception/        # 예외 처리
├── interceptor/      # 인터셉터
├── repository/       # JPA 레포지토리
├── security/         # 보안 설정
├── service/          # 비즈니스 로직
└── util/             # 유틸리티 (JWT 등)

🚀 시작하기

사전 요구사항

• Java 17 이상
• MySQL 8.0 이상
• Redis
• Gradle

설치 및 실행

1. 저장소 클론

git clone https://github.com/jungyuminn/planu-backend.git
cd planu-backend

2. 환경 설정

# application-local.yml 파일 생성 (gitignore에 포함됨)
cp src/main/resources/application.yml src/main/resources/application-local.yml

application-local.yml에 다음 정보를 설정:

• Database 연결 정보
• Redis 연결 정보
• JWT Secret Key
• Firebase 설정

3. 빌드 및 실행

# Gradle 빌드
./gradlew build

# 애플리케이션 실행
./gradlew bootRun

4. API 문서 확인

http://localhost:8080/swagger-ui.html

📚 API 엔드포인트

인증

• POST /api/auth/register - 회원가입
• POST /api/auth/login - 로그인
• POST /api/auth/refresh - 토큰 갱신

Todo

• GET /api/todos - Todo 목록 조회
• POST /api/todos - Todo 생성
• PUT /api/todos/{id} - Todo 수정
• DELETE /api/todos/{id} - Todo 삭제

Someday

• GET /api/todos/someday - Someday 목록 조회
• POST /api/todos/someday - Someday 생성
• PUT /api/todos/someday/{id} - Someday 수정
• DELETE /api/todos/someday/{id} - Someday 삭제

Category

• GET /api/categories - 카테고리 목록 조회
• POST /api/categories - 카테고리 생성
• PUT /api/categories/{id} - 카테고리 수정
• DELETE /api/categories/{id} - 카테고리 삭제

Shop

• GET /api/shop/stickers - 스티커 상점 목록
• GET /api/shop/colors - 컬러 상점 목록
• POST /api/purchase/stickers - 스티커 구매
• POST /api/purchase/colors - 컬러 구매

Coupon

• GET /api/coupons - 쿠폰 목록 조회
• POST /api/coupons/use - 쿠폰 사용

상세한 API 명세는 Swagger 문서를 참고해주세요.

🔧 개발 환경 설정

IDE 설정

• IntelliJ IDEA 권장
• Lombok 플러그인 설치 필요

코드 스타일

• Java Code Convention 준수
• 4 spaces 들여쓰기

🤝 기여하기

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

커밋 컨벤션

• feat: 새로운 기능 추가
• fix: 버그 수정
• docs: 문서 수정
• style: 코드 포맷팅, 세미콜론 누락 등
• refactor: 코드 리팩토링
• test: 테스트 코드
• chore: 빌드 업무 수정, 패키지 매니저 수정

📝 라이선스

This project is licensed under the MIT License - see the LICENSE file for details

👤 개발자

JungYumin

• GitHub: @jungyuminn

📮 문의

프로젝트에 대한 질문이나 제안사항이 있으시면 Issue를 등록해주세요.

---

⭐️ 이 프로젝트가 도움이 되었다면 Star를 눌러주세요!