feat(ranking): Phase 5 개인/학교/우리학교 랭킹 API

backend/src/main/java/com/studycafe/ranking/ranking/NameMasker.java

@@ -0,0 +1,42 @@
+package com.studycafe.ranking.ranking;
+
+import com.studycafe.ranking.domain.School;
+import com.studycafe.ranking.domain.User;
+
+/** 랭킹 표시용 이름 마스킹(§3.3). */
+public final class NameMasker {
+
+    private NameMasker() {
+    }
+
+    /** 첫/끝 글자만 노출, 사이는 O. 2글자=첫+O, 1글자 이하=원문 그대로. */
+    public static String maskName(String name) {
+        if (name == null) {
+            return "";
+        }
+        int n = name.length();
+        if (n <= 1) {
+            return name;
+        }
+        if (n == 2) {
+            return name.charAt(0) + "O";
+        }
+        return name.charAt(0) + "O".repeat(n - 2) + name.charAt(n - 1);
+    }
+
+    /** `마스킹이름(학교축약명)` + 같은 학교 동명이인 접미 숫자(name_seq>1). 무소속은 `(무소속)`. */
+    public static String rankingLabel(User user) {
+        String masked = maskName(user.getDisplayName());
+        School school = user.getSchool();
+        String schoolPart;
+        if (school == null) {
+            schoolPart = "무소속";
+        } else {
+            String shortName = school.getShortName();
+            // short_name 이 null 또는 공백이면 name 으로 폴백(빈 괄호 `()` 방지).
+            schoolPart = (shortName != null && !shortName.isBlank()) ? shortName : school.getName();
+        }
+        String suffix = user.getNameSeq() > 1 ? String.valueOf(user.getNameSeq()) : "";
+        return masked + "(" + schoolPart + ")" + suffix;
+    }
+}

backend/src/main/java/com/studycafe/ranking/ranking/RankingController.java

@@ -0,0 +1,39 @@
+package com.studycafe.ranking.ranking;
+
+import com.studycafe.ranking.ranking.dto.IndividualRankingResponse;
+import com.studycafe.ranking.ranking.dto.SchoolMineResponse;
+import com.studycafe.ranking.ranking.dto.SchoolRankingResponse;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/** 랭킹(§5.2/§5.3). 전부 인증 필요. period 기본값 this_week, 잘못된 값이면 400. */
+@RestController
+@RequestMapping("/api/rankings")
+public class RankingController {
+
+    private final RankingService rankingService;
+
+    public RankingController(RankingService rankingService) {
+        this.rankingService = rankingService;
+    }
+
+    @GetMapping("/individual")
+    public IndividualRankingResponse individual(@AuthenticationPrincipal Long userId,
+                                                @RequestParam(defaultValue = "this_week") RankingPeriod period) {
+        return rankingService.individual(userId, period);
+    }
+
+    @GetMapping("/school")
+    public SchoolRankingResponse school(@RequestParam(defaultValue = "this_week") RankingPeriod period) {
+        return rankingService.school(period);
+    }
+
+    @GetMapping("/school/mine")
+    public SchoolMineResponse schoolMine(@AuthenticationPrincipal Long userId,
+                                         @RequestParam(defaultValue = "this_week") RankingPeriod period) {
+        return rankingService.schoolMine(userId, period);
+    }
+}

backend/src/main/java/com/studycafe/ranking/ranking/RankingPeriod.java

@@ -0,0 +1,46 @@
+package com.studycafe.ranking.ranking;
+
+import java.time.DayOfWeek;
+import java.time.LocalDate;
+import java.time.YearMonth;
+import java.time.temporal.TemporalAdjusters;
+
+/**
+ * 랭킹 기간(§5.2). 스터디 날짜(04:00 기준, §3.2) 범위로 환산한다.
+ * 주간(this_week/last_week)만 주 84h 캡 적용 대상(§3.6e).
+ */
+public enum RankingPeriod {
+    THIS_WEEK,
+    LAST_WEEK,
+    THIS_MONTH,
+    LAST_MONTH,
+    THIS_YEAR;
+
+    public boolean isWeekly() {
+        return this == THIS_WEEK || this == LAST_WEEK;
+    }
+
+    public LocalDate start(LocalDate today) {
+        return switch (this) {
+            case THIS_WEEK -> monday(today);
+            case LAST_WEEK -> monday(today).minusWeeks(1);
+            case THIS_MONTH -> today.withDayOfMonth(1);
+            case LAST_MONTH -> YearMonth.from(today).minusMonths(1).atDay(1);
+            case THIS_YEAR -> today.withDayOfYear(1);
+        };
+    }
+
+    public LocalDate end(LocalDate today) {
+        return switch (this) {
+            case THIS_WEEK -> monday(today).plusDays(6);
+            case LAST_WEEK -> monday(today).minusWeeks(1).plusDays(6);
+            case THIS_MONTH -> YearMonth.from(today).atEndOfMonth();
+            case LAST_MONTH -> YearMonth.from(today).minusMonths(1).atEndOfMonth();
+            case THIS_YEAR -> today.withDayOfYear(1).plusYears(1).minusDays(1);
+        };
+    }
+
+    private static LocalDate monday(LocalDate date) {
+        return date.with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY));
+    }
+}

backend/src/main/java/com/studycafe/ranking/ranking/RankingService.java

@@ -0,0 +1,206 @@
+package com.studycafe.ranking.ranking;
+
+import com.studycafe.ranking.common.exception.UserNotFoundException;
+import com.studycafe.ranking.domain.User;
+import com.studycafe.ranking.ranking.dto.IndividualRankingResponse;
+import com.studycafe.ranking.ranking.dto.RankEntry;
+import com.studycafe.ranking.ranking.dto.SchoolEntry;
+import com.studycafe.ranking.ranking.dto.SchoolMineResponse;
+import com.studycafe.ranking.ranking.dto.SchoolRankingResponse;
+import com.studycafe.ranking.repository.CheckInSessionRepository;
+import com.studycafe.ranking.repository.DailyStudyRecordRepository;
+import com.studycafe.ranking.repository.UserRepository;
+import com.studycafe.ranking.studytime.StudyClock;
+import com.studycafe.ranking.studytime.StudyTimeAggregator;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.sql.Timestamp;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.OffsetDateTime;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * 랭킹(§5.2/§5.3). 여기서 **랭킹 캡(하루 16h/주 84h, §3.6e)** 을 적용한다(마이페이지=실제시간과 대비).
+ * 파일럿 규모(수십 명)라 per-user 집계를 가져와 Java에서 캡·정렬·마스킹·내순위를 계산한다.
+ */
+@Service
+@Transactional(readOnly = true)
+public class RankingService {
+
+    private static final int MIN_SCHOOL_MEMBERS = 5; // §3.4
+    private static final int LIST_MAX = 10;          // 4~10위
+    private static final int PODIUM = 3;
+
+    private final DailyStudyRecordRepository recordRepository;
+    private final CheckInSessionRepository sessionRepository;
+    private final UserRepository userRepository;
+
+    public RankingService(DailyStudyRecordRepository recordRepository,
+                          CheckInSessionRepository sessionRepository,
+                          UserRepository userRepository) {
+        this.recordRepository = recordRepository;
+        this.sessionRepository = sessionRepository;
+        this.userRepository = userRepository;
+    }
+
+    public IndividualRankingResponse individual(Long meUserId, RankingPeriod period) {
+        LocalDate today = StudyClock.studyDateOf(Instant.now());
+        return buildIndividual(period, rankedIndividuals(period, today, null), meUserId);
+    }
+
+    public SchoolMineResponse schoolMine(Long meUserId, RankingPeriod period) {
+        User me = userRepository.findByIdWithSchool(meUserId)
+                .orElseThrow(() -> new UserNotFoundException(meUserId));
+        if (me.getSchool() == null) {
+            return SchoolMineResponse.unavailable(); // 무소속 → 안내(§5.3)
+        }
+        LocalDate today = StudyClock.studyDateOf(Instant.now());
+        List<RankRow> ranked = rankedIndividuals(period, today, me.getSchool().getId());
+        return SchoolMineResponse.of(me.getSchool().getName(), buildIndividual(period, ranked, meUserId));
+    }
+
+    public SchoolRankingResponse school(RankingPeriod period) {
+        LocalDate today = StudyClock.studyDateOf(Instant.now());
+        Map<Long, Long> capped = cappedTotalsByUser(period, today);
+        Map<Long, User> users = usersById(capped.keySet());
+
+        Map<Long, List<Long>> bySchool = new HashMap<>();
+        Map<Long, String> schoolNames = new HashMap<>();
+        capped.forEach((userId, total) -> {
+            User u = users.get(userId);
+            if (u == null || u.getSchool() == null) {
+                return; // 무소속 제외(§3.7)
+            }
+            Long schoolId = u.getSchool().getId();
+            bySchool.computeIfAbsent(schoolId, k -> new ArrayList<>()).add(total);
+            schoolNames.putIfAbsent(schoolId, u.getSchool().getName());
+        });
+
+        List<SchoolAgg> aggs = new ArrayList<>();
+        bySchool.forEach((schoolId, totals) -> {
+            int count = totals.size(); // 활동 인원 = 그 기간 기록 있는 학생 수
+            if (count < MIN_SCHOOL_MEMBERS) {
+                return; // 최소 인원 미달 제외(§3.4)
+            }
+            long sum = totals.stream().mapToLong(Long::longValue).sum();
+            aggs.add(new SchoolAgg(schoolNames.get(schoolId), count, sum / count));
+        });
+        // 동점: 평균 desc → 활동 인원 desc → 학교명 asc (§3.5)
+        aggs.sort(Comparator.comparingLong(SchoolAgg::avgSeconds).reversed()
+                .thenComparing(Comparator.comparingInt(SchoolAgg::memberCount).reversed())
+                .thenComparing(SchoolAgg::schoolName));
+
+        List<SchoolEntry> all = new ArrayList<>();
+        for (int i = 0; i < aggs.size(); i++) {
+            SchoolAgg a = aggs.get(i);
+            all.add(new SchoolEntry(i + 1, a.schoolName(), a.memberCount(), a.avgSeconds()));
+        }
+        return new SchoolRankingResponse(periodKey(period),
+                all.stream().limit(PODIUM).toList(),
+                all.stream().skip(PODIUM).limit(LIST_MAX - PODIUM).toList());
+    }
+
+    // ---------- helpers ----------
+
+    private List<RankRow> rankedIndividuals(RankingPeriod period, LocalDate today, Long schoolFilter) {
+        Map<Long, Long> capped = cappedTotalsByUser(period, today);
+        if (capped.isEmpty()) {
+            return List.of();
+        }
+        Map<Long, User> users = usersById(capped.keySet());
+        if (schoolFilter != null) {
+            capped.keySet().removeIf(uid -> {
+                User u = users.get(uid);
+                return u == null || u.getSchool() == null || !u.getSchool().getId().equals(schoolFilter);
+            });
+            if (capped.isEmpty()) {
+                return List.of();
+            }
+        }
+        Map<Long, Instant> lastCheckout = lastCheckoutByUser(period, today);
+        List<RankRow> rows = new ArrayList<>();
+        capped.forEach((uid, total) ->
+                rows.add(new RankRow(uid, total, lastCheckout.get(uid), NameMasker.rankingLabel(users.get(uid)))));
+        // 동점: 합계 desc → 기간 내 마지막 체크아웃 이른 순(§3.5)
+        rows.sort(Comparator.comparingLong(RankRow::total).reversed()
+                .thenComparing(r -> r.lastCheckout() == null ? Instant.MAX : r.lastCheckout()));
+        return rows;
+    }
+
+    private IndividualRankingResponse buildIndividual(RankingPeriod period, List<RankRow> rows, Long meUserId) {
+        List<RankEntry> all = new ArrayList<>();
+        for (int i = 0; i < rows.size(); i++) {
+            RankRow r = rows.get(i);
+            all.add(new RankEntry(i + 1, r.label(), r.total(), r.userId().equals(meUserId)));
+        }
+        RankEntry myRank = all.stream().filter(RankEntry::isMe).findFirst().orElse(null);
+        return new IndividualRankingResponse(periodKey(period),
+                all.stream().limit(PODIUM).toList(),
+                all.stream().skip(PODIUM).limit(LIST_MAX - PODIUM).toList(),
+                myRank);
+    }
+
+    /** period 범위의 user별 캡 적용 합계(초). 하루 16h 캡 + (주간이면) 주 84h 캡 — StudyTimeAggregator 재사용. */
+    private Map<Long, Long> cappedTotalsByUser(RankingPeriod period, LocalDate today) {
+        Map<Long, List<Long>> dailyByUser = new HashMap<>();
+        for (Object[] row : recordRepository.findUserSecondsInPeriod(period.start(today), period.end(today))) {
+            dailyByUser.computeIfAbsent((Long) row[0], k -> new ArrayList<>()).add((Long) row[1]);
+        }
+        boolean weekly = period.isWeekly();
+        Map<Long, Long> capped = new HashMap<>();
+        dailyByUser.forEach((userId, daily) ->
+                capped.put(userId, StudyTimeAggregator.rankingTotalSeconds(daily, weekly)));
+        return capped;
+    }
+
+    private Map<Long, Instant> lastCheckoutByUser(RankingPeriod period, LocalDate today) {
+        Instant start = StudyClock.startOf(period.start(today));
+        Instant end = StudyClock.endOf(period.end(today));
+        Map<Long, Instant> map = new HashMap<>();
+        for (Object[] row : sessionRepository.lastCheckoutByUser(start, end)) {
+            map.put((Long) row[0], toInstant(row[1]));
+        }
+        return map;
+    }
+
+    private Map<Long, User> usersById(Collection<Long> ids) {
+        if (ids.isEmpty()) {
+            return Map.of();
+        }
+        return userRepository.findAllByIdInWithSchool(ids).stream()
+                .collect(Collectors.toMap(User::getId, u -> u));
+    }
+
+    private static String periodKey(RankingPeriod period) {
+        return period.name().toLowerCase(Locale.ROOT);
+    }
+
+    /** 집계 max(checkOutAt) 의 반환 타입(Instant/Timestamp/OffsetDateTime)을 Instant 로 정규화. */
+    private static Instant toInstant(Object value) {
+        if (value instanceof Instant i) {
+            return i;
+        }
+        if (value instanceof Timestamp t) {
+            return t.toInstant();
+        }
+        if (value instanceof OffsetDateTime odt) {
+            return odt.toInstant();
+        }
+        return null;
+    }
+
+    private record RankRow(Long userId, long total, Instant lastCheckout, String label) {
+    }
+
+    private record SchoolAgg(String schoolName, int memberCount, long avgSeconds) {
+    }
+}

backend/src/main/java/com/studycafe/ranking/ranking/StringToRankingPeriodConverter.java

@@ -0,0 +1,19 @@
+package com.studycafe.ranking.ranking;
+
+import org.springframework.core.convert.converter.Converter;
+import org.springframework.stereotype.Component;
+
+import java.util.Locale;
+
+/**
+ * "this_week" 같은 쿼리 파라미터 → RankingPeriod. 잘못된 값이면 valueOf 가 IllegalArgumentException →
+ * Spring 이 MethodArgumentTypeMismatchException 으로 감싸 400(ApiError) 응답.
+ */
+@Component
+class StringToRankingPeriodConverter implements Converter<String, RankingPeriod> {
+
+    @Override
+    public RankingPeriod convert(String source) {
+        return RankingPeriod.valueOf(source.trim().toUpperCase(Locale.ROOT));
+    }
+}

backend/src/main/java/com/studycafe/ranking/ranking/dto/IndividualRankingResponse.java

@@ -0,0 +1,12 @@
+package com.studycafe.ranking.ranking.dto;
+
+import java.util.List;
+
+/** 개인별 랭킹(§5.2). podium=1~3위, list=4~10위, myRank=내 순위(top10 밖이어도, 기록 없으면 null). */
+public record IndividualRankingResponse(
+        String period,
+        List<RankEntry> podium,
+        List<RankEntry> list,
+        RankEntry myRank
+) {
+}

backend/src/main/java/com/studycafe/ranking/ranking/dto/RankEntry.java

@@ -0,0 +1,5 @@
+package com.studycafe.ranking.ranking.dto;
+
+/** 개인 랭킹 한 줄. seconds = 랭킹 캡 적용된 초. isMe = 현재 사용자 여부(강조용). */
+public record RankEntry(int rank, String displayName, long seconds, boolean isMe) {
+}

backend/src/main/java/com/studycafe/ranking/ranking/dto/SchoolEntry.java

@@ -0,0 +1,5 @@
+package com.studycafe.ranking.ranking.dto;
+
+/** 학교 랭킹 한 줄. avgSeconds = 활동 인원 평균(랭킹 캡 적용), memberCount = 그 기간 활동 인원. */
+public record SchoolEntry(int rank, String schoolName, int memberCount, long avgSeconds) {
+}

backend/src/main/java/com/studycafe/ranking/ranking/dto/SchoolMineResponse.java

@@ -0,0 +1,13 @@
+package com.studycafe.ranking.ranking.dto;
+
+/** 우리 학교 페이지(§5.3). 무소속이면 available=false(안내 문구용), 그 외엔 학교 내부 개인 랭킹. */
+public record SchoolMineResponse(boolean available, String schoolName, IndividualRankingResponse ranking) {
+
+    public static SchoolMineResponse unavailable() {
+        return new SchoolMineResponse(false, null, null);
+    }
+
+    public static SchoolMineResponse of(String schoolName, IndividualRankingResponse ranking) {
+        return new SchoolMineResponse(true, schoolName, ranking);
+    }
+}