Feat/295 assigned coupon

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/controller/AssignedCouponController.java

@@ -0,0 +1,101 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.controller;
+
+import java.util.List;
+
+import com.soongsil.CoffeeChat.domain.assignedcoupon.dto.*;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.ErrorResponse;
+import org.springframework.web.bind.annotation.*;
+
+import com.soongsil.CoffeeChat.domain.assignedcoupon.service.AssignedCouponService;
+import com.soongsil.CoffeeChat.global.api.ApiResponse;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/v2/assigned-coupons")
+@Tag(name = "ASSIGNED COUPON", description = "축제 전용 지정 커피 쿠폰 관련 API")
+public class AssignedCouponController {
+
+    private final AssignedCouponService assignedCouponService;
+
+    // 유저 - 보관함 진입 시 발급 자격 확인
+    @GetMapping("/eligibility")
+    @Operation(
+            summary = "지정 쿠폰 발급 자격 확인",
+            description =
+                    "보관함 진입 시 호출합니다. 본인의 name + phoneNum 이 사전 등록된 대상자 명단과 일치하는지 확인합니다."
+                            + " 발급 이력이 있는 경우 발급 정보를 반환합니다.")
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(
+            responseCode = "200",
+            description = "조회 성공 (result.eligible=true && !alreadyIssued 일 때만 발급 버튼 활성화)")
+    public ResponseEntity<ApiResponse<AssignedCouponCheckResponse>> checkEligibility(
+            Authentication authentication) {
+        return ResponseEntity.ok()
+                .body(
+                        ApiResponse.onSuccessOK(
+                                assignedCouponService.checkEligibility(
+                                        authentication.getName())));
+    }
+
+    // 유저 - 매장 PIN 인증으로 지정 쿠폰 발급 (=사용 처리)
+    @PostMapping("/coupons")
+    @Operation(
+            summary = "지정 쿠폰 발급 (매장 PIN 인증)",
+            description = "매장 직원의 핀 번호를 입력받아 최종 검증 후 쿠폰을 발급합니다. 발급과 동시에 사용 처리되어 재사용 불가합니다.")
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(
+            responseCode = "200",
+            description = "발급된 쿠폰 정보 반환")
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(
+            responseCode = "400",
+            description = "EVENT_400_1: 핀 번호 불일치 | ASSIGNED_COUPON_400: 전화번호 미등록",
+            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(
+            responseCode = "404",
+            description = "ASSIGNED_COUPON_404: 발급 대상자 아님",
+            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(
+            responseCode = "409",
+            description = "ASSIGNED_COUPON_409: 이미 발급된 쿠폰",
+            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(
+            responseCode = "503",
+            description = "EVENT_503: 동시성 처리 오류",
+            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
+    public ResponseEntity<ApiResponse<AssignedCouponResponse>> issueCoupon(
+            @RequestParam String storePin, Authentication authentication) {
+        return ResponseEntity.ok()
+                .body(
+                        ApiResponse.onSuccessOK(
+                                assignedCouponService.issueCoupon(
+                                        authentication.getName(), storePin)));
+    }
+
+    // ************ 관리자용 api ************
+
+    @PostMapping("/admin/register")
+    @Operation(
+            summary = "지정 쿠폰 대상자 일괄 등록 (관리자)",
+            description = "대상자(이름 + 전화번호) 목록을 받아 Redis에 등록합니다. 전화번호는 하이픈 유무 무관.")
+    public ResponseEntity<ApiResponse<AssignedCouponRegisterResult>> registerTargets(
+            @RequestBody List<AssignedCouponTargetRequest> targets) {
+        return ResponseEntity.ok()
+                .body(ApiResponse.onSuccessOK(assignedCouponService.registerTargets(targets)));
+    }
+
+    @PostMapping("/admin/register/one")
+    @Operation(summary = "지정 쿠폰 대상자 단건 등록 (관리자)")
+    public ResponseEntity<ApiResponse<AssignedCouponRegisterResult>> registerOneTarget(
+            @RequestBody AssignedCouponTargetRequest target) {
+        return ResponseEntity.ok()
+                .body(
+                        ApiResponse.onSuccessOK(
+                                assignedCouponService.registerTargets(List.of(target))));
+    }
+}

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/dto/AssignedCouponCheckResponse.java

@@ -0,0 +1,30 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.dto;
+
+import java.time.LocalDateTime;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+public class AssignedCouponCheckResponse {
+
+    private boolean eligible;
+    private boolean alreadyIssued;
+    private String name;
+    private String couponNumber;
+    private String status;
+    private LocalDateTime issuedAt;
+    private LocalDateTime usedAt;
+
+    public static AssignedCouponCheckResponse notEligible() {
+        return AssignedCouponCheckResponse.builder()
+                .eligible(false)
+                .alreadyIssued(false)
+                .build();
+    }
+}

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/dto/AssignedCouponRegisterResult.java

@@ -0,0 +1,10 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.dto;
+
+import java.util.List;
+
+public record AssignedCouponRegisterResult(
+        int totalRequested,
+        int newlyRegistered,
+        int duplicated,
+        List<String> failedPhoneNums) {
+}

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/dto/AssignedCouponResponse.java

@@ -0,0 +1,21 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.dto;
+
+import java.time.LocalDateTime;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+public class AssignedCouponResponse {
+
+    private String couponNumber;
+    private String name;
+    private String status;
+    private LocalDateTime issuedAt;
+    private LocalDateTime usedAt;
+}

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/dto/AssignedCouponTargetRequest.java

@@ -0,0 +1,4 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.dto;
+
+public record AssignedCouponTargetRequest(String name, String phoneNum) {
+}

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/message/AssignedCouponIssueEventListener.java

@@ -0,0 +1,45 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.message;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.event.EventListener;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Component;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.soongsil.CoffeeChat.infra.aws.s3.service.AmazonS3Service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class AssignedCouponIssueEventListener {
+
+    private final AmazonS3Service amazonS3Service;
+    private final ObjectMapper objectMapper;
+
+    @Value("${cloud.aws.s3.bucket}")
+    private String bucket;
+
+    @Async
+    @EventListener
+    public void handleAssignedCouponIssuedEvent(AssignedCouponIssuedEvent event) {
+        try {
+            // AssignedCouponIssuedEvent JSON 직렬화
+            String logJson = objectMapper.writeValueAsString(event);
+
+            String fileNamePrefix = "assigned-coupon-" + event.couponNumber();
+
+            // event-logs/assigned-coupon 디렉토리에 저장
+            String fileUrl =
+                    amazonS3Service.uploadJsonFile(
+                            logJson, "event-logs/assigned-coupon", fileNamePrefix);
+
+            log.info("S3 지정 쿠폰 발급 로그 업로드 완료: {} (URL: {})", fileNamePrefix, fileUrl);
+
+        } catch (Exception e) {
+            log.error("S3 지정 쿠폰 발급 로그 업로드 실패. couponNumber: {}", event.couponNumber(), e);
+        }
+    }
+}

src/main/java/com/soongsil/CoffeeChat/domain/assignedcoupon/message/AssignedCouponIssuedEvent.java

@@ -0,0 +1,12 @@
+package com.soongsil.CoffeeChat.domain.assignedcoupon.message;
+
+import java.time.LocalDateTime;
+
+// 지정 쿠폰 비동기 로깅용 dto
+public record AssignedCouponIssuedEvent(
+        String username,
+        String name,
+        String phoneNum,
+        String couponNumber,
+        LocalDateTime issuedAt) {
+}