Challenge App Backend

챌린지 앱 백엔드 서버입니다. 사용자들이 다양한 챌린지에 참여하고, 인증 사진을 업로드하며, 성공 시 보상을 받을 수 있는 시스템을 제공합니다.

📋 목차

• 기술 스택
• 주요 기능
• 프로젝트 구조
• 시작하기
• API 문서
• 환경 설정
• 데이터베이스
• 보안

🛠 기술 스택

• Java: 17
• Framework: Spring Boot 3.1.4
• Build Tool: Maven
• Database: MySQL 8.0
• ORM: Spring Data JPA / Hibernate
• Security: Spring Security, JWT
• API Documentation: Springdoc OpenAPI (Swagger)
• Cloud Storage: AWS S3
• Payment: Toss Payments API
• Push Notification: Firebase Cloud Messaging (FCM)
• Authentication: Firebase Admin SDK

✨ 주요 기능

1. 사용자 관리

• 회원가입 및 로그인 (전화번호 기반)
• JWT 기반 인증
• Firebase 인증 지원
• 프로필 관리
• 알림 설정

2. 챌린지 관리

• 공개 챌린지 (PUBLIC): 누구나 참여 가능한 챌린지
• 개인 챌린지 (PERSONAL): 토큰을 소모하여 생성하는 개인 챌린지
• 이벤트 챌린지 (EVENT): 특별 이벤트용 챌린지
• 챌린지 생성, 수정, 삭제
• 챌린지 검색 및 추천
• 챌린지 상세 정보 조회

3. 챌린지 참여

• 챌린지 참여 신청
• 참가비 결제 (Toss Payments)
• 참여 상태 관리 (진행중/성공/실패/탈퇴)
• 참여자 목록 조회

4. 인증 시스템

• 인증 사진 업로드 (AWS S3)
• 인증 시간대 설정 (시작 시간 ~ 종료 시간)
• 인증 주기 설정 (N일마다)
• 갤러리 업로드 지원
• 인증 사진 평가 (통과/실패)
• 자동 승인 스케줄러

5. 진행 상황 관리

• 챌린지 진행률 조회
• 인증 횟수 통계
• 참여자별 진행 상황

6. 결제 시스템

• Toss Payments 연동
• 결제 준비 및 승인
• 환불 처리
• 결제 내역 조회

7. 알림 시스템

• FCM 푸시 알림
• 챌린지 시작/종료 알림
• 사용자 알림 설정 관리

8. 스케줄러

• 인증 자동 승인 처리
• 챌린지 정리 작업
• 알림 발송

📁 프로젝트 구조

src/main/java/com/example/challenge/
├── ChallengeApplication.java          # 메인 애플리케이션 클래스
├── config/                            # 설정 클래스
│   ├── FirebaseConfig.java
│   ├── PasswordEncoderConfig.java
│   └── SwaggerConfig.java
├── controller/                        # REST API 컨트롤러
│   ├── AuthController.java
│   ├── ChallengeController.java
│   ├── ChallengeParticipationController.java
│   ├── ChallengeProgressController.java
│   ├── CertificationController.java
│   ├── CertificationApprovalController.java
│   ├── CertificationEvaluationController.java
│   ├── CertificationQueryController.java
│   ├── PaymentController.java
│   ├── UserController.java
│   └── FirebaseAuthController.java
├── domain/model/                      # 엔티티 모델
│   ├── Challenge.java
│   ├── User.java
│   ├── ChallengeParticipation.java
│   ├── ChallengeCertification.java
│   ├── CertificationEvaluation.java
│   ├── CertificationHistory.java
│   ├── Payment.java
│   └── CommunityPost.java
├── dto/                               # 데이터 전송 객체
├── exception/                         # 예외 처리
│   ├── CustomException.java
│   ├── ErrorResponse.java
│   └── GlobalExceptionHandler.java
├── external/                          # 외부 API 클라이언트
│   └── TossPaymentClient.java
├── repository/                        # 데이터 접근 계층
├── security/                          # 보안 관련
│   ├── JwtFilter.java
│   ├── JwtUtil.java
│   ├── SecurityConfig.java
│   ├── SecurityUtil.java
│   └── UserPrincipal.java
├── service/                           # 비즈니스 로직
│   ├── ChallengeService.java
│   ├── ChallengeParticipationService.java
│   ├── ChallengeProgressService.java
│   ├── ChallengeCertificationService.java
│   ├── CertificationEvaluationService.java
│   ├── CertificationQueryService.java
│   ├── CertificationHistoryService.java
│   ├── PaymentService.java
│   ├── UserService.java
│   ├── S3UploadService.java
│   ├── FCMService.java
│   ├── CertificationAutoApprovalScheduler.java
│   ├── ChallengeCleanupScheduler.java
│   └── ChallengeNotificationScheduler.java
└── util/                              # 유틸리티
    └── RewardCalculator.java

🚀 시작하기

필수 요구사항

• JDK 17 이상
• Maven 3.6 이상
• MySQL 8.0 이상
• AWS 계정 (S3 사용 시)
• Firebase 프로젝트 (FCM 사용 시)
• Toss Payments 계정 (결제 기능 사용 시)

설치 및 실행

1. 저장소 클론

git clone https://github.com/your-username/challenge-backend.git
cd challenge-backend

2. 환경 변수 설정

   • src/main/resources/application.yaml 파일을 참고하여 application-local.yaml 파일 생성
   • 데이터베이스 연결 정보, JWT 시크릿, AWS 자격 증명 등 설정

3. 데이터베이스 생성

CREATE DATABASE challenge CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. 애플리케이션 빌드

mvn clean install

5. 애플리케이션 실행

mvn spring-boot:run

또는

java -jar target/challenge-1.0.0.jar

애플리케이션이 성공적으로 시작되면 http://localhost:8080에서 접근할 수 있습니다.

📚 API 문서

애플리케이션 실행 후 Swagger UI를 통해 API 문서를 확인할 수 있습니다:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

주요 API 엔드포인트

인증

• POST /api/v1/auth/register - 회원가입
• POST /api/v1/auth/login - 로그인
• GET /api/v1/auth/me - 현재 사용자 정보

챌린지

• GET /api/v1/challenges - 챌린지 목록 조회
• GET /api/v1/challenges/{id} - 챌린지 상세 조회
• POST /api/v1/challenges - 공개 챌린지 생성
• POST /api/v1/challenges/personal - 개인 챌린지 생성
• POST /api/v1/challenges/event - 이벤트 챌린지 생성
• GET /api/v1/challenges/search - 챌린지 검색
• GET /api/v1/challenges/recommend/banner - 추천 챌린지

챌린지 참여

• POST /api/v1/participations - 챌린지 참여
• GET /api/v1/participations - 참여 챌린지 목록
• DELETE /api/v1/participations/{id} - 챌린지 탈퇴

인증

• POST /api/v1/certifications - 인증 사진 업로드
• GET /api/v1/certifications - 인증 내역 조회
• POST /api/v1/certifications/{id}/evaluate - 인증 평가

결제

• POST /api/v1/payments/ready - 결제 준비
• POST /api/v1/payments/confirm - 결제 승인
• POST /api/v1/payments/refund - 환불 요청

⚙️ 환경 설정

application.yaml 설정 예시

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/challenge?useSSL=false&allowPublicKeyRetrieval=true
    username: your_username
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false

jwt:
  secret: your_jwt_secret_key_here

cloud:
  aws:
    credentials:
      access-key: your_aws_access_key
      secret-key: your_aws_secret_key
    region:
      static: ap-northeast-2
    s3:
      bucket: your_s3_bucket_name

toss:
  secret-key: your_toss_payments_secret_key

Firebase 설정

1. Firebase 콘솔에서 서비스 계정 키 다운로드
2. src/main/resources/firebase/firebase-service-account.json 파일에 저장

🗄 데이터베이스

주요 엔티티

• User: 사용자 정보
• Challenge: 챌린지 정보
• ChallengeParticipation: 챌린지 참여 정보
• ChallengeCertification: 인증 사진 정보
• CertificationEvaluation: 인증 평가 정보
• Payment: 결제 정보

데이터베이스 마이그레이션

현재 프로젝트는 JPA의 ddl-auto: update를 사용하여 자동으로 스키마를 생성합니다. 프로덕션 환경에서는 Flyway 또는 Liquibase를 사용하는 것을 권장합니다.

🔒 보안

• JWT 인증: Bearer 토큰 기반 인증
• 비밀번호 암호화: BCrypt 사용
• CORS 설정: 필요에 따라 설정
• 민감 정보 보호: 환경 변수 또는 설정 파일 분리

보안 주의사항

⚠️ 중요: 프로덕션 환경에 배포하기 전에 다음을 확인하세요:

1. application.yaml 파일에 하드코딩된 민감한 정보 제거

   • 현재 application.yaml 파일에 데이터베이스 비밀번호, AWS 키, JWT 시크릿 등이 포함되어 있습니다
   • GitHub에 업로드하기 전에 반드시 민감한 정보를 제거하거나 application.yaml.example을 참고하여 템플릿으로 변경하세요
   • 실제 설정은 application-local.yaml 또는 환경 변수로 관리하세요

2. 환경 변수 또는 외부 설정 서버 사용

   • Spring Boot의 @Value 어노테이션과 환경 변수 사용 권장
   • 또는 AWS Secrets Manager, HashiCorp Vault 등 사용

3. JWT 시크릿 키를 강력한 랜덤 문자열로 변경

   • 최소 64자 이상의 랜덤 문자열 사용 권장

4. 데이터베이스 접근 권한 최소화

   • 필요한 권한만 부여

5. HTTPS 사용

   • 프로덕션 환경에서는 반드시 HTTPS 사용

6. Firebase 서비스 계정 키 파일 보안 관리

   • firebase-service-account.json 파일은 절대 Git에 커밋하지 마세요
   • 이미 .gitignore에 추가되어 있습니다

설정 파일 사용 방법

1. application.yaml.example 파일을 복사하여 application.yaml 생성
2. 실제 값으로 채워넣기
3. 또는 application-local.yaml 파일을 생성하여 로컬 개발 환경 설정
4. 프로덕션 환경에서는 환경 변수 사용 권장

📝 라이선스

이 프로젝트는 개인 프로젝트입니다.

👤 작성자

• 작성자: [박재욱]

🙏 감사의 말

이 프로젝트는 Spring Boot와 다양한 오픈소스 라이브러리를 사용하여 개발되었습니다.