feat: 동아리 클릭 게임 API 추가 (POST /api/game/click, GET /api/game/ranking)

Redis INCR을 활용한 원자적 클릭 수 누적, KST 자정 자동 초기화(ShedLock),
클릭 랭킹 조회 시 rank 필드 및 resetAt(다음 자정 ISO8601) 제공

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: seongwon030

backend/src/main/java/moadong/club/controller/ClubClickController.java

@@ -0,0 +1,40 @@
+package moadong.club.controller;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import moadong.club.payload.request.ClubClickRequest;
+import moadong.club.payload.response.ClubClickRankingResponse;
+import moadong.club.payload.response.ClubClickResponse;
+import moadong.club.service.ClubClickService;
+import moadong.global.payload.Response;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/game")
+@RequiredArgsConstructor
+@Tag(name = "Game", description = "동아리 클릭 게임 통계")
+public class ClubClickController {
+
+    private final ClubClickService clubClickService;
+
+    @PostMapping("/click")
+    @Operation(summary = "동아리 클릭 기록", description = "자유 입력 clubName별 클릭 수를 누적합니다. 실제 동아리 DB와 무관합니다.")
+    public ResponseEntity<?> recordClick(@RequestBody ClubClickRequest request) {
+        ClubClickResponse result = clubClickService.recordClick(request.clubName());
+        return Response.ok(result);
+    }
+
+    @GetMapping("/ranking")
+    @Operation(summary = "동아리 클릭 랭킹 조회",
+            description = "클릭 수 기준 내림차순 랭킹을 반환합니다. resetAt은 다음 자정(KST) 시간입니다.")
+    public ResponseEntity<?> getRanking() {
+        ClubClickRankingResponse result = clubClickService.getRanking();
+        return Response.ok(result);
+    }
+}

backend/src/main/java/moadong/club/payload/request/ClubClickRequest.java

@@ -0,0 +1,4 @@
+package moadong.club.payload.request;
+
+public record ClubClickRequest(String clubName, String ctAt) {
+}

backend/src/main/java/moadong/club/payload/response/ClubClickRankingResponse.java

@@ -0,0 +1,9 @@
+package moadong.club.payload.response;
+
+import java.util.List;
+
+public record ClubClickRankingResponse(List<ClubRankItem> clubs, String resetAt) {
+
+    public record ClubRankItem(int rank, String clubName, long clickCount) {
+    }
+}

backend/src/main/java/moadong/club/payload/response/ClubClickResponse.java

@@ -0,0 +1,4 @@
+package moadong.club.payload.response;
+
+public record ClubClickResponse(String clubName, long clickCount) {
+}

backend/src/main/java/moadong/club/service/ClubClickService.java

@@ -0,0 +1,82 @@
+package moadong.club.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import moadong.club.payload.response.ClubClickRankingResponse;
+import moadong.club.payload.response.ClubClickRankingResponse.ClubRankItem;
+import moadong.club.payload.response.ClubClickResponse;
+import net.javacrumbs.shedlock.spring.annotation.SchedulerLock;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Service;
+
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+@ConditionalOnProperty(name = "scheduling.enabled", havingValue = "true", matchIfMissing = true)
+public class ClubClickService {
+
+    private static final String CLICK_KEY_PREFIX = "club:click:";
+    private static final String CLICK_KEY_PATTERN = CLICK_KEY_PREFIX + "*";
+    private static final ZoneId KST = ZoneId.of("Asia/Seoul");
+
+    private final StringRedisTemplate stringRedisTemplate;
+
+    public ClubClickResponse recordClick(String clubName) {
+        String key = CLICK_KEY_PREFIX + clubName;
+        Long clickCount = stringRedisTemplate.opsForValue().increment(key);
+        return new ClubClickResponse(clubName, clickCount != null ? clickCount : 0L);
+    }
+
+    public ClubClickRankingResponse getRanking() {
+        Set<String> keys = stringRedisTemplate.keys(CLICK_KEY_PATTERN);
+        List<ClubRankItem> ranked = new ArrayList<>();
+
+        if (keys != null && !keys.isEmpty()) {
+            List<ClubRankItem> unsorted = new ArrayList<>();
+            for (String key : keys) {
+                String clubName = key.substring(CLICK_KEY_PREFIX.length());
+                String raw = stringRedisTemplate.opsForValue().get(key);
+                long count = raw != null ? Long.parseLong(raw) : 0L;
+                unsorted.add(new ClubRankItem(0, clubName, count));
+            }
+
+            unsorted.sort(Comparator.comparingLong(ClubRankItem::clickCount).reversed());
+
+            AtomicInteger rank = new AtomicInteger(1);
+            for (ClubRankItem item : unsorted) {
+                ranked.add(new ClubRankItem(rank.getAndIncrement(), item.clubName(), item.clickCount()));
+            }
+        }
+
+        return new ClubClickRankingResponse(ranked, nextMidnightKst());
+    }
+
+    @Scheduled(cron = "0 0 0 * * *", zone = "Asia/Seoul")
+    @SchedulerLock(name = "ClubClickReset", lockAtMostFor = "1m", lockAtLeastFor = "1s")
+    public void resetDailyClicks() {
+        Set<String> keys = stringRedisTemplate.keys(CLICK_KEY_PATTERN);
+        if (keys != null && !keys.isEmpty()) {
+            stringRedisTemplate.delete(keys);
+        }
+        log.info("동아리 클릭 수 초기화 완료");
+    }
+
+    private String nextMidnightKst() {
+        ZonedDateTime nextMidnight = ZonedDateTime.now(KST)
+                .toLocalDate()
+                .plusDays(1)
+                .atStartOfDay(KST);
+        return nextMidnight.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME);
+    }
+}