🚀 [기능개선][백엔드][Timer] today-stats 응답에 누적 통계 필드 3개 추가

[EM-H20]

📝 현재 문제점

• 클라이언트의 누적 통계 (totalStudyMinutesProvider, totalSessionCountProvider, monthlyStudyMinutesProvider) 가 GET /api/timer-sessions 의 첫 페이지(20개) 만 합산하고 있어 인증 사용자에게 부정확한 값이 노출됨.
• 영향 범위:
  • 프로필 화면 의 "공부 시간" 통계 카드가 최근 20세션 기준으로만 표시됨 (실제 누적과 다름).
  • 뱃지 해금 시스템 의 조건 평가가 부정확해 "총 100시간 공부", "총 50회 세션 완료" 류 뱃지가 영원히 해금되지 않을 수 있음.
• 클라에서 모든 페이지를 순회해 합산하는 방식은 세션이 많아질수록 N번 API 호출이 발생해 비효율적.

🛠️ 해결 방안 / 제안 기능

• 기존 GET /api/timer-sessions/today-stats 응답에 누적 통계 필드 3개 추가.
• 신규 endpoint 대신 today-stats 확장을 선택한 이유:
  • 클라의 호출 시점·캐시 정책이 today-stats 와 동일 (홈/프로필 진입 시).
  • API 표면적 최소화.
  • 기존 TodayStatsResponse 스키마와 자연스러운 확장 관계.

⚙️ 작업 내용

• TodayStatsResponse DTO 에 필드 3개 추가
  • lifetimeMinutes: 회원의 전체 누적 공부 시간 (분) — SUM(duration_minutes) WHERE member_id = ?
  • lifetimeSessionCount: 회원의 전체 세션 수 — COUNT(*) WHERE member_id = ?
  • monthlyMinutes: 이번 달 누적 공부 시간 (분, KST 기준) — SUM(duration_minutes) WHERE member_id = ? AND started_at >= 이번 달 1일 00:00 KST
• 이번 달 경계는 streak 와 동일하게 Asia/Seoul 기준 적용
• docs/api-docs.json 의 TodayStatsResponse 스키마 갱신 (description, example 포함)
• 응답 예시 갱신:

  {
    "totalMinutes": 180,
    "sessionCount": 3,
    "streak": 7,
    "lifetimeMinutes": 12450,
    "lifetimeSessionCount": 287,
    "monthlyMinutes": 1820
  }

• 회원의 세션 0건 케이스 — 세 필드 모두 0 반환 (null 금지)
• 기존 필드명·구조는 유지하여 호환성 보장 (클라 측 무중단 배포 가능)

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: 이름
• 디자인: 이름

[EM-H20]

Guide by SUH-LAB

브랜치

20260526_#40_today_stats_응답에_누적_통계_필드_3개_추가

커밋 메시지

today-stats 응답에 누적 통계 필드 3개 추가 : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-BE/issues/40