🚀 [기능개선][Timer][프로필] today-stats 누적 통계 필드 3개 클라이언트 연동

[EM-H20]

📝 현재 문제점

• 인증 사용자의 누적 통계가 첫 페이지(20세션) 만 합산되어 부정확한 값이 노출됨.
• 영향:
  • 프로필 화면 통계 카드 의 "공부 시간" 이 최근 20세션 기준으로만 계산됨 (profile_screen.dart:83).
  • 뱃지 해금 시스템 의 조건 평가 (badge_provider.dart:53-55) — "총 100시간 공부", "총 50회 세션 완료" 류 뱃지가 영원히 해금되지 않음.
• 게스트 모드는 로컬 전체 세션이 메모리에 있어 정확함 → 분기 처리 필요.
• 백엔드 측 대응 이슈: today-stats-cumulative-fields.md

🛠️ 해결 방안 / 제안 기능

• 백엔드가 GET /api/timer-sessions/today-stats 응답에 추가하는 3개 필드를 클라이언트가 받아 누적 통계 provider 에 노출.
• 기존 todayStatsProvider 패턴 (인증=서버 / 게스트=로컬) 그대로 적용.
• 게스트 모드 로직은 손대지 않음 — 로컬 전체 세션 합산이 이미 정확.

⚙️ 작업 내용

• 선행 조건: 백엔드 작업 완료 + docs/api-docs.json 의 TodayStatsResponse 스키마 갱신
• TodayStatsResponseModel DTO 에 필드 3개 추가
  • lifetimeMinutes, lifetimeSessionCount, monthlyMinutes
• TodayStats 도메인 엔티티에도 동일 필드 추가 (toEntity() 매핑 갱신)
• study_stats_provider.dart 의 3개 provider 를 인증/게스트 분기로 리팩터링
  • totalStudyMinutesProvider → 인증: lifetimeMinutes, 게스트: 기존 로컬 합산
  • totalSessionCountProvider → 인증: lifetimeSessionCount, 게스트: 기존
  • monthlyStudyMinutesProvider → 인증: monthlyMinutes, 게스트: 기존
• build_runner build --delete-conflicting-outputs 재실행
• 단위 테스트
  • today_stats_response_model_test.dart — 새 필드 직렬화/엔티티 변환
  • study_stats_provider_test.dart — 인증/게스트 분기별 값 확인
• 회귀 가드: 기존 today_stats_provider_test.dart 통과 유지

🙋‍♂️ 담당자

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

[EM-H20]

Guide by SUH-LAB

브랜치

20260526_#83_today_stats_누적_통계_필드_3개_클라이언트_연동

커밋 메시지

today-stats 누적 통계 필드 3개 클라이언트 연동 : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-FE/issues/83

[EM-H20]

#83 today-stats 누적 통계 필드 3개 클라이언트 연동

📌 작업 개요

서버 GET /api/timer-sessions/today-stats 응답에 추가된 누적 통계 3필드(lifetimeMinutes, lifetimeSessionCount, monthlyMinutes)를 클라이언트가 수신·노출하도록 연동. 프로필 화면과 뱃지 해금 조건에서 발생하던 누적값 계산 오류를 단일 진실 소스(todayStatsNotifierProvider) 패턴으로 해결.

PR #84 머지 완료 — main 브랜치 반영.

---

🔍 문제 분석

기존 study_stats_provider.dart 의 3개 provider(totalStudyMinutes, totalSessionCount, monthlyStudyMinutes) 가 전부 로컬 timerSessionListNotifierProvider 의 결과를 fold 해서 계산했음. 인증 모드에서 이 provider 는 서버 페이지네이션(size=20) 의 첫 페이지만 보유하므로 다음 문제 발생:

• 프로필 화면(profile_screen.dart:83) 의 "공부 시간" 카드가 최근 20세션만 합산되어 표시.
• 뱃지 해금(badge_provider.dart:53,55) 의 "총 100시간 공부" / "총 50회 세션" 조건이 영구 미해금 상태.

게스트 모드는 전체 세션이 인메모리에 있어 fold 합산이 정확하므로 분기 처리가 필요했음.

---

✅ 구현 내용

DTO 6필드 확장 — TodayStatsResponseModel

• 파일: lib/features/timer/data/models/today_stats_response_model.dart
• 변경 내용: lifetimeMinutes, lifetimeSessionCount, monthlyMinutes 3필드 추가. toEntity() 매핑 갱신.
• 이유: 서버 스펙(docs/api-docs.json TodayStatsResponse) 이 6필드로 갱신됨 — DTO 동기화 필요.

Entity 6필드 확장 — TodayStats

• 파일: lib/features/timer/domain/entities/today_stats.dart
• 변경 내용: 동일 3필드 추가(required int). TodayStats.empty() 의 0 초기값 6필드로 확장.
• 이유: Repository 계층이 6필드 모두 전달할 수 있도록 도메인 모델 확장.

게스트 분기 6필드 fold — today_stats_provider

• 파일: lib/features/timer/presentation/providers/today_stats_provider.dart
• 변경 내용: 게스트 모드에서 로컬 세션을 fold 해서 6필드 모두 채움. lifetimeMinutes(전체 세션 합), lifetimeSessionCount(전체 세션 개수), monthlyMinutes(이번 달 1일 이후 합) 계산 로직 추가.
• 이유: Entity 가 6필드 required 로 변경되면서 컴파일 에러 해소 + 단일 진실 소스 보장.

study_stats_provider 단순화 — todayStats 위임

• 파일: lib/features/timer/presentation/providers/study_stats_provider.dart
• 변경 내용: 3개 provider 를 ref.watch(todayStatsNotifierProvider).valueOrNull?.X ?? 0 한 줄로 단순화. isAuthenticatedProvider watch 제거 — 분기 책임 전부 todayStatsNotifierProvider 에 위임.
• 이유: 호출처 시그니처(int 반환) 는 유지하면서 데이터 출처를 단일화. 인증/게스트 분기 코드 중복 제거.

타이머 통계 패널 — 이번 주 → 이번 달

• 파일: lib/features/timer/presentation/screens/timer_screen.dart
• 변경 내용: 타이머 화면 통계 패널에서 weeklyStudyMinutesProvider → monthlyStudyMinutesProvider 로 교체. 라벨 "이번 주" → "이번 달".
• 이유: 서버가 제공하는 monthlyMinutes 를 활용해 정확한 누적값 표시 + 프로필 화면과 일관된 통계 기간.

CodeRabbit 리뷰 반영 (fix bd1e1c5)

• 게스트 streak 다일 복원 — today_stats_provider.dart 의 streak 계산이 "오늘 있으면 1, 없으면 0" 으로 회귀했던 부분 복원. _calculateStreak() 헬퍼로 날짜 fold 통해 다일 연속 계산.
• OpenAPI 에러 응답 스키마 교정 — docs/api-docs.json 의 4곳에서 401/500 에러 응답이 성공 DTO 를 참조하던 부분을 ErrorResponse 로 교정.
  • GET /api/timer-sessions 401
  • POST /api/timer-sessions 500
  • GET /api/timer-sessions/today-stats 401
  • GET /api/fuel/transactions 401/500
• 테스트 assertion 보강 — timer_session_remote_datasource_test, timer_session_repository_impl_test 에 lifetimeSessionCount, monthlyMinutes 단언 추가.

---

🔧 주요 변경사항 상세

today_stats_provider.dart 게스트 분기

게스트 모드는 로컬 세션 전체가 메모리에 있다는 특성을 활용해 6필드 모두 정확히 계산:

final lifetimeMinutes = sessions.fold<int>(0, (sum, s) => sum + s.durationMinutes);
final monthlyMinutes = sessions
    .where((s) => !s.startedAt.isBefore(monthStart))
    .fold<int>(0, (sum, s) => sum + s.durationMinutes);

streak 계산은 별도 헬퍼(_calculateStreak) 로 분리. 오늘 또는 어제 공부 기록 있어야 streak 유지, 날짜 정규화 후 연속 일수 카운팅.

특이사항:

• 인증 분기는 repository.getTodayStats() 한 줄 위임 — 서버 응답 신뢰.
• 무효화 트리거는 기존 4곳(timer_provider.dart:174 세션 저장, auth_provider.dart 로그인/로그아웃/탈퇴) 그대로 사용. 신규 트리거 불필요.

study_stats_provider.dart 단순화

@riverpod
int totalStudyMinutes(Ref ref) {
  return ref.watch(todayStatsNotifierProvider).valueOrNull?.lifetimeMinutes ?? 0;
}

• 동기 int 시그니처 유지 → profile_screen.dart, badge_provider.dart 호출처 무수정.
• 로딩/에러 시 valueOrNull → null → ?? 0 fallback (기존 빈 상태도 0 표시였으므로 신규 깜빡임 아님).

호출처 영향

호출처	시그니처	동작 변화
profile_screen.dart:83	변경 없음	인증 사용자: 최근 20세션 → 전체 누적값 정확 표시
badge_provider.dart:53,55	변경 없음	"총 100시간", "총 50회 세션" 뱃지 정상 해금 가능
timer_screen.dart:116	provider 교체	"이번 주" → "이번 달" 누적 표시

---

🧪 테스트 및 검증

신규 테스트

• study_stats_provider_test.dart (신규) — todayStatsNotifierProvider override 로 위임 동작 검증. lifetimeMinutes, lifetimeSessionCount, monthlyMinutes 주입 → 3 provider 가 일치값 반환.
• today_stats_provider_test.dart — 게스트 다일 streak 회귀 가드(3일 연속 → streak=3) 케이스 추가.

회귀 가드 — fixture 6필드 갱신

DTO/Entity 가 6필드 required 로 변경되며 기존 픽스처 컴파일 에러 해소:

• today_stats_test.dart
• today_stats_provider_test.dart
• timer_session_repository_impl_test.dart
• timer_session_remote_datasource_test.dart
• today_stats_response_model_test.dart

검증 결과

• flutter pub run build_runner build --delete-conflicting-outputs 성공
• flutter analyze 경고 0
• flutter test test/features/timer/ 전체 통과
• CodeRabbit 리뷰 라운드 1회 → fix 반영 후 PR 20260526 #83 today stats 누적 통계 필드 3개 클라이언트 연동 #84 머지 완료

---

📌 참고사항

• 명시적 비범위: todayStudyMinutes, weeklyStudyMinutes, currentStreak provider 는 이슈 범위 밖이므로 손대지 않음. 단, currentStreak 은 자연스럽게 todayStats.streak 위임 패턴으로 통합됨.
• 백엔드 작업: 이미 완료. docs/api-docs.json 의 TodayStatsResponse 6필드 동기화 완료 상태에서 진행.
• 단일 진실 소스 효과: 향후 누적 통계가 필요한 새 호출처는 todayStatsNotifierProvider 만 watch 하면 됨. study_stats_provider 는 호환성 위한 얇은 어댑터 역할.
• 다음 후보 작업: 게스트 모드 streak 계산 로직이 인증 모드(서버) 와 동일한 규칙인지 통합 검증 필요 시 별도 이슈로 분리 가능.

---

📦 관련 커밋 (10개)

Hash	메시지
559bd68	docs : today-stats 누적 통계 필드 3개 클라이언트 연동 design spec
b33a791	docs : today-stats spec 보완 — 게스트 분기 6필드 fold + study_stats_provider 단순화
38cbf5a	docs : today-stats spec 테스트 계획 간소화 — 회귀 가드 fixture 갱신 위주
a58182d	docs : today-stats 누적 통계 필드 클라이언트 연동 implementation plan
7882ae3	feat : TodayStats 누적 통계 3필드 추가 + 게스트 분기 6필드 fold
ec74ce9	test : TodayStats monthlyMinutes / sessionCount assertion 보강
25bf987	refactor : study_stats_provider 누적 통계 3개 todayStats 위임 단순화
0062919	refactor : 타이머 통계 패널 todayStats API 위임 + 이번 주 → 이번 달
45ddad2	fix : CI format
bd1e1c5	fix : CodeRabbit 리뷰 반영 — 게스트 streak 다일 복원 + OpenAPI 에러 응답 스키마 + assertion 보강
9bc0df9	Merge pull request #84