feat: 배지 도메인 및 웰컴/시즌 등수/총 공부시간 배지 지급 로직 추가

src/main/java/com/gpt/geumpumtabackend/badge/api/BadgeApi.java

@@ -0,0 +1,183 @@
+package com.gpt.geumpumtabackend.badge.api;
+
+import com.gpt.geumpumtabackend.badge.dto.request.BadgeCreateRequest;
+import com.gpt.geumpumtabackend.badge.dto.request.RepresentativeBadgeRequest;
+import com.gpt.geumpumtabackend.badge.dto.response.BadgeCreateResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.BadgeResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.MyBadgeResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.MyBadgeStatusResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.RepresentativeBadgeResponse;
+import com.gpt.geumpumtabackend.global.aop.AssignUserId;
+import com.gpt.geumpumtabackend.global.config.swagger.SwaggerApiFailedResponse;
+import com.gpt.geumpumtabackend.global.config.swagger.SwaggerApiResponses;
+import com.gpt.geumpumtabackend.global.config.swagger.SwaggerApiSuccessResponse;
+import com.gpt.geumpumtabackend.global.exception.ExceptionType;
+import com.gpt.geumpumtabackend.global.response.ResponseBody;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+@Tag(name = "배지 API", description = """
+    배지 생성/조회/삭제 및 사용자 배지 조회 기능을 제공합니다.
+    """)
+public interface BadgeApi {
+
+    @Operation(
+            summary = "배지 생성",
+            description = """
+                    ADMIN 권한으로 새로운 배지를 생성합니다.
+                    - code: 배지 고유 코드 (중복 불가)
+                    - badgeType: 배지 종류
+                    - thresholdValue: 누적 시간/연속 일수 계열 배지 기준값
+                    - rank: 시즌 랭킹 배지 등수 값(예: 1,2,3)
+                    """
+    )
+    @ApiResponse(content = @Content(schema = @Schema(implementation = BadgeCreateResponse.class)))
+    @SwaggerApiResponses(
+            success = @SwaggerApiSuccessResponse(
+                    response = BadgeCreateResponse.class,
+                    description = "배지 생성 성공"
+            ),
+            errors = {
+                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
+                    @SwaggerApiFailedResponse(ExceptionType.ACCESS_DENIED),
+                    @SwaggerApiFailedResponse(ExceptionType.BADGE_CODE_ALREADY_EXISTS)
+            }
+    )
+    @PostMapping
+    @PreAuthorize("isAuthenticated() and hasRole('ADMIN')")
+    ResponseEntity<ResponseBody<BadgeCreateResponse>> createBadge(
+            @RequestBody @Valid BadgeCreateRequest request
+    );
+
+    @Operation(
+            summary = "전체 배지 조회",
+            description = "ADMIN 권한으로 전체 배지 목록을 조회합니다."
+    )
+    @ApiResponse(content = @Content(schema = @Schema(implementation = BadgeResponse.class)))
+    @SwaggerApiResponses(
+            success = @SwaggerApiSuccessResponse(
+                    response = BadgeResponse.class,
+                    description = "전체 배지 조회 성공"
+            ),
+            errors = {
+                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
+                    @SwaggerApiFailedResponse(ExceptionType.ACCESS_DENIED)
+            }
+    )
+    @GetMapping
+    @PreAuthorize("isAuthenticated() and hasRole('ADMIN')")
+    ResponseEntity<ResponseBody<List<BadgeResponse>>> getAllBadges();
+
+    @Operation(
+            summary = "배지 삭제",
+            description = """
+                    ADMIN 권한으로 배지를 삭제합니다.
+                    이미 사용자에게 지급된 이력이 있으면 삭제할 수 없고 B004(BADGE_IN_USE)를 반환합니다.
+                    """
+    )
+    @ApiResponse(content = @Content(schema = @Schema(implementation = ResponseBody.class)))
+    @SwaggerApiResponses(
+            success = @SwaggerApiSuccessResponse(description = "배지 삭제 성공"),
+            errors = {
+                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
+                    @SwaggerApiFailedResponse(ExceptionType.ACCESS_DENIED),
+                    @SwaggerApiFailedResponse(ExceptionType.BADGE_NOT_FOUND),
+                    @SwaggerApiFailedResponse(ExceptionType.BADGE_IN_USE)
+            }
+    )
+    @DeleteMapping("/{badgeId}")
+    @PreAuthorize("isAuthenticated() and hasRole('ADMIN')")
+    ResponseEntity<ResponseBody<Void>> deleteBadge(
+            @PathVariable Long badgeId
+    );
+
+    @Operation(
+            summary = "내 배지 조회",
+            description = """
+                    항상 전체 배지 목록을 반환합니다.
+                    각 원소는 아래 정보를 포함합니다.
+                    - owned: 사용자의 배지 보유 여부
+                    - awardedAt: 배지 획득 시각 (owned=false이면 null)
+                    """
+    )
+    @ApiResponse(content = @Content(schema = @Schema(implementation = MyBadgeStatusResponse.class)))
+    @SwaggerApiResponses(
+            success = @SwaggerApiSuccessResponse(
+                    response = MyBadgeStatusResponse.class,
+                    description = "내 배지 조회 성공"
+            ),
+            errors = {
+                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
+                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND)
+            }
+    )
+    @GetMapping("/me")
+    @AssignUserId
+    @PreAuthorize("isAuthenticated() and hasRole('USER')")
+    ResponseEntity<ResponseBody<List<MyBadgeStatusResponse>>> getMyBadges(
+            @Parameter(hidden = true) Long userId
+    );
+
+    @Operation(
+            summary = "대표 배지 설정",
+            description = """
+                    보유한 배지 중 하나를 대표 배지로 설정합니다.
+                    요청은 badgeCode 기준으로 처리됩니다.
+                    """
+    )
+    @ApiResponse(content = @Content(schema = @Schema(implementation = RepresentativeBadgeResponse.class)))
+    @SwaggerApiResponses(
+            success = @SwaggerApiSuccessResponse(
+                    response = RepresentativeBadgeResponse.class,
+                    description = "대표 배지 설정 성공"
+            ),
+            errors = {
+                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
+                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND),
+                    @SwaggerApiFailedResponse(ExceptionType.BADGE_NOT_FOUND),
+                    @SwaggerApiFailedResponse(ExceptionType.BADGE_NOT_OWNED)
+            }
+    )
+    @PostMapping("/me/representative-badge")
+    @AssignUserId
+    @PreAuthorize("isAuthenticated() and hasRole('USER')")
+    ResponseEntity<ResponseBody<RepresentativeBadgeResponse>> setRepresentativeBadge(
+            @RequestBody RepresentativeBadgeRequest request,
+            @Parameter(hidden = true) Long userId
+    );
+
+    @Operation(
+            summary = "미확인 배지 조회",
+            description = """
+                    사용자의 미확인 배지 목록을 조회합니다.
+                    조회된 배지는 같은 요청 트랜잭션에서 확인 처리(notifiedAt 설정)됩니다.
+                    """
+    )
+    @ApiResponse(content = @Content(schema = @Schema(implementation = MyBadgeResponse.class)))
+    @SwaggerApiResponses(
+            success = @SwaggerApiSuccessResponse(
+                    response = MyBadgeResponse.class,
+                    description = "미확인 배지 조회 성공"
+            ),
+            errors = {
+                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
+                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND)
+            }
+    )
+    @GetMapping("/unnotified")
+    @AssignUserId
+    @PreAuthorize("isAuthenticated() and hasRole('USER')")
+    ResponseEntity<ResponseBody<List<MyBadgeResponse>>> getUnnotifiedBadges(
+            @Parameter(hidden = true) Long userId
+    );
+}

src/main/java/com/gpt/geumpumtabackend/badge/controller/BadgeController.java

@@ -0,0 +1,90 @@
+package com.gpt.geumpumtabackend.badge.controller;
+
+import com.gpt.geumpumtabackend.badge.api.BadgeApi;
+import com.gpt.geumpumtabackend.badge.dto.request.BadgeCreateRequest;
+import com.gpt.geumpumtabackend.badge.dto.request.RepresentativeBadgeRequest;
+import com.gpt.geumpumtabackend.badge.dto.response.BadgeCreateResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.BadgeResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.MyBadgeResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.MyBadgeStatusResponse;
+import com.gpt.geumpumtabackend.badge.dto.response.RepresentativeBadgeResponse;
+import com.gpt.geumpumtabackend.badge.service.BadgeService;
+import com.gpt.geumpumtabackend.global.aop.AssignUserId;
+import com.gpt.geumpumtabackend.global.response.ResponseBody;
+import com.gpt.geumpumtabackend.global.response.ResponseUtil;
+import lombok.RequiredArgsConstructor;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/v1/badge")
+public class BadgeController implements BadgeApi {
+
+    private final BadgeService badgeService;
+
+    @PostMapping
+    @PreAuthorize("isAuthenticated() and hasRole('ADMIN')")
+    public ResponseEntity<ResponseBody<BadgeCreateResponse>> createBadge(
+            @RequestBody @Valid BadgeCreateRequest request
+    ){
+        return ResponseEntity.ok(ResponseUtil.createSuccessResponse(
+                badgeService.createBadge(request)
+        ));
+    }
+
+    @GetMapping
+    @PreAuthorize("isAuthenticated() and hasRole('ADMIN')")
+    public ResponseEntity<ResponseBody<List<BadgeResponse>>> getAllBadges() {
+        return ResponseEntity.ok(ResponseUtil.createSuccessResponse(
+                badgeService.getAllBadges()
+        ));
+    }
+
+    @DeleteMapping("/{badgeId}")
+    @PreAuthorize("isAuthenticated() and hasRole('ADMIN')")
+    public ResponseEntity<ResponseBody<Void>> deleteBadge(
+            @PathVariable Long badgeId
+    ) {
+        badgeService.deleteBadge(badgeId);
+        return ResponseEntity.ok(ResponseUtil.createSuccessResponse());
+    }
+
+    @GetMapping("/me")
+    @AssignUserId
+    @PreAuthorize("isAuthenticated() and hasRole('USER')")
+    public ResponseEntity<ResponseBody<List<MyBadgeStatusResponse>>> getMyBadges(
+            Long userId
+    ){
+        return ResponseEntity.ok(ResponseUtil.createSuccessResponse(
+                badgeService.getMyBadges(userId)
+        ));
+    }
+
+    @PostMapping("/me/representative-badge")
+    @AssignUserId
+    @PreAuthorize("isAuthenticated() and hasRole('USER')")
+    public ResponseEntity<ResponseBody<RepresentativeBadgeResponse>> setRepresentativeBadge(
+            @RequestBody RepresentativeBadgeRequest request,
+            Long userId
+    ){
+        return ResponseEntity.ok(ResponseUtil.createSuccessResponse(
+                badgeService.setRepresentativeBadge(request, userId)
+        ));
+    }
+
+    @GetMapping("/unnotified")
+    @AssignUserId
+    @PreAuthorize("isAuthenticated() and hasRole('USER')")
+    public ResponseEntity<ResponseBody<List<MyBadgeResponse>>> getUnnotifiedBadges(
+            Long userId
+    ){
+        return ResponseEntity.ok(ResponseUtil.createSuccessResponse(
+                badgeService.getUnnotifiedBadges(userId)
+        ));
+    }
+}

src/main/java/com/gpt/geumpumtabackend/badge/domain/Badge.java

@@ -0,0 +1,54 @@
+package com.gpt.geumpumtabackend.badge.domain;
+
+import com.gpt.geumpumtabackend.global.base.BaseEntity;
+import jakarta.persistence.*;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.AccessLevel;
+import lombok.NoArgsConstructor;
+
+@Entity
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class Badge extends BaseEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(unique = true)
+    private String code;
+
+    private String name;
+
+    private String description;
+
+    private String iconUrl;
+
+    @Enumerated(EnumType.STRING)
+    private BadgeType badgeType;
+
+    private Long thresholdValue;
+
+    @Column(name = "badge_rank")
+    private Long rank;
+
+    @Builder
+    private Badge(
+            String code,
+            String name,
+            String description,
+            String iconUrl,
+            BadgeType badgeType,
+            Long thresholdValue,
+            Long rank
+    ) {
+        this.code = code;
+        this.name = name;
+        this.description = description;
+        this.iconUrl = iconUrl;
+        this.badgeType = badgeType;
+        this.thresholdValue = thresholdValue;
+        this.rank = rank;
+    }
+}

src/main/java/com/gpt/geumpumtabackend/badge/domain/BadgeType.java

@@ -0,0 +1,8 @@
+package com.gpt.geumpumtabackend.badge.domain;
+
+public enum BadgeType {
+    WELCOME,
+    STREAK_DAYS,
+    TOTAL_HOURS,
+    SEASON_PERSONAL_RANK
+}

src/main/java/com/gpt/geumpumtabackend/badge/domain/UserBadge.java

@@ -0,0 +1,41 @@
+package com.gpt.geumpumtabackend.badge.domain;
+
+import jakarta.persistence.*;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+
+@Entity
+@Getter
+@NoArgsConstructor
+@Table(
+        name = "user_badge",
+        uniqueConstraints = @UniqueConstraint(name="uk_user_badge", columnNames = {"user_id", "badge_id"})
+)
+public class UserBadge {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "user_id")
+    private Long userId;
+
+    @Column(name = "badge_id")
+    private Long badgeId;
+
+    private LocalDateTime awardedAt;
+
+    private LocalDateTime notifiedAt;
+
+    public UserBadge(Long userId, Long badgeId, LocalDateTime awardedAt, LocalDateTime notifiedAt) {
+        this.userId = userId;
+        this.badgeId = badgeId;
+        this.awardedAt = awardedAt;
+        this.notifiedAt = notifiedAt;
+    }
+
+    public void markNotified(LocalDateTime notifiedAt) {
+        this.notifiedAt = notifiedAt;
+    }
+}

src/main/java/com/gpt/geumpumtabackend/badge/dto/request/BadgeCreateRequest.java

@@ -0,0 +1,16 @@
+package com.gpt.geumpumtabackend.badge.dto.request;
+
+import com.gpt.geumpumtabackend.badge.domain.BadgeType;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+
+public record BadgeCreateRequest(
+        @NotBlank String code,
+        @NotBlank String name,
+        @NotBlank String description,
+        @NotBlank String iconUrl,
+        @NotNull BadgeType badgeType,
+        Long thresholdValue,
+        Long rank
+) {
+}