Revamp/stats

apps/backend/src/domain/entities/user-item.ts

@@ -23,4 +23,6 @@ export type SelectUserItems = {
 export type SelectAllUserItems = {
   status?: UserItemStatus | 'ALL'
   userId: string
+  startDate?: Date
+  endDate?: Date
 }

apps/backend/src/domain/services/user-episodes/get-user-episodes.ts

@@ -1,11 +1,23 @@
 import { selectUserEpisodes } from '@/infra/db/repositories/user-episode'
 
-export type GetUserEpisodesInput = { userId: string; tmdbId?: number }
+export type GetUserEpisodesInput = {
+  userId: string
+  tmdbId?: number
+  startDate?: Date
+  endDate?: Date
+}
 
 export async function getUserEpisodesService({
   userId,
   tmdbId,
+  startDate,
+  endDate,
 }: GetUserEpisodesInput) {
-  const userEpisodes = await selectUserEpisodes({ userId, tmdbId })
+  const userEpisodes = await selectUserEpisodes({
+    userId,
+    tmdbId,
+    startDate,
+    endDate,
+  })
   return { userEpisodes }
 }

apps/backend/src/domain/services/user-stats/cache-utils.ts

@@ -1,8 +1,7 @@
 import type { FastifyRedis } from '@fastify/redis'
 
-// Cache duration for computed statistics (1 hour)
-// Short TTL ensures data freshness while still providing significant performance benefit
 const STATS_CACHE_TTL_SECONDS = 60 * 60
+const STATS_CACHE_SHORT_TTL_SECONDS = 10 * 60
 
 /**
  * Helper to cache computed statistics results
@@ -20,12 +19,17 @@ export async function getCachedStats<T>(
   }
 
   const result = await computeFn()
-  await redis.set(
-    cacheKey,
-    JSON.stringify(result),
-    'EX',
-    STATS_CACHE_TTL_SECONDS
-  )
+
+  const yearMonthPattern = /:\d{4}-\d{2}$/
+  const isPeriodScoped =
+    cacheKey.endsWith(':month') ||
+    cacheKey.endsWith(':last_month') ||
+    yearMonthPattern.test(cacheKey)
+  const ttl = isPeriodScoped
+    ? STATS_CACHE_SHORT_TTL_SECONDS
+    : STATS_CACHE_TTL_SECONDS
+
+  await redis.set(cacheKey, JSON.stringify(result), 'EX', ttl)
 
   return result
 }
@@ -52,10 +56,11 @@ export async function invalidateUserStatsCache(
 export function getUserStatsCacheKey(
   userId: string,
   statType: string,
-  language?: string
+  language?: string,
+  period?: string
 ): string {
-  if (language) {
-    return `user-stats:${userId}:${statType}:${language}`
-  }
-  return `user-stats:${userId}:${statType}`
+  const parts = ['user-stats', userId, statType]
+  if (language) parts.push(language)
+  if (period && period !== 'all') parts.push(period)
+  return parts.join(':')
 }

apps/backend/src/domain/services/user-stats/get-user-best-reviews.ts

@@ -1,5 +1,6 @@
 import type { FastifyRedis } from '@fastify/redis'
 import type { Language } from '@plotwist_app/tmdb'
+import type { StatsPeriod } from '@/infra/http/schemas/common'
 import { selectBestReviews } from '@/infra/db/repositories/reviews-repository'
 import { getTMDBMovieService } from '../tmdb/get-tmdb-movie'
 import { getTMDBTvSeriesService } from '../tmdb/get-tmdb-tv-series'
@@ -10,17 +11,23 @@ type GetUserBestReviewsServiceInput = {
   redis: FastifyRedis
   language: Language
   limit?: number
+  dateRange?: { startDate: Date | undefined; endDate: Date | undefined }
+  period?: StatsPeriod
 }
 
 export async function getUserBestReviewsService({
   userId,
   language,
   redis,
   limit,
+  dateRange,
 }: GetUserBestReviewsServiceInput) {
-  // Note: Not using cache here because createdAt Date serialization
-  // causes issues when retrieved from Redis (Date becomes string)
-  const bestReviews = await selectBestReviews(userId, limit)
+  const bestReviews = await selectBestReviews(
+    userId,
+    limit,
+    dateRange?.startDate,
+    dateRange?.endDate
+  )
 
   const formattedBestReviews = await processInBatches(
     bestReviews,

apps/backend/src/domain/services/user-stats/get-user-items-status.ts

@@ -2,12 +2,18 @@ import { selectUserItemStatus } from '@/infra/db/repositories/user-item-reposito
 
 type GetUserItemsStatusServiceInput = {
   userId: string
+  dateRange?: { startDate: Date | undefined; endDate: Date | undefined }
 }
 
 export async function getUserItemsStatusService({
   userId,
+  dateRange,
 }: GetUserItemsStatusServiceInput) {
-  const userItems = await selectUserItemStatus(userId)
+  const userItems = await selectUserItemStatus(
+    userId,
+    dateRange?.startDate,
+    dateRange?.endDate
+  )
 
   return {
     userItems,

apps/backend/src/domain/services/user-stats/get-user-most-watched-series.ts

@@ -1,5 +1,6 @@
 import type { FastifyRedis } from '@fastify/redis'
 import type { Language } from '@plotwist_app/tmdb'
+import type { StatsPeriod } from '@/infra/http/schemas/common'
 import { selectMostWatched } from '@/infra/db/repositories/user-episode'
 import { getTMDBTvSeriesService } from '../tmdb/get-tmdb-tv-series'
 import { processInBatches } from './batch-utils'
@@ -8,14 +9,21 @@ type GetUserMostWatchedSeriesServiceInput = {
   userId: string
   redis: FastifyRedis
   language: Language
+  dateRange?: { startDate: Date | undefined; endDate: Date | undefined }
+  period?: StatsPeriod
 }
 
 export async function getUserMostWatchedSeriesService({
   userId,
   language,
   redis,
+  dateRange,
 }: GetUserMostWatchedSeriesServiceInput) {
-  const mostWatchedSeries = await selectMostWatched(userId)
+  const mostWatchedSeries = await selectMostWatched(
+    userId,
+    dateRange?.startDate,
+    dateRange?.endDate
+  )
 
   const formattedMostWatchedSeries = await processInBatches(
     mostWatchedSeries,

apps/backend/src/domain/services/user-stats/get-user-stats-timeline.ts

@@ -0,0 +1,119 @@
+import type { FastifyRedis } from '@fastify/redis'
+import type { Language } from '@plotwist_app/tmdb'
+import { periodToDateRange } from '@/http/schemas/common'
+import { getUserBestReviewsService } from './get-user-best-reviews'
+import { getUserTotalHoursService } from './get-user-total-hours'
+import { getUserWatchedGenresService } from './get-user-watched-genres'
+
+type GetUserStatsTimelineInput = {
+  userId: string
+  redis: FastifyRedis
+  language: Language
+  cursor?: string
+  pageSize?: number
+}
+
+export async function getUserStatsTimelineService({
+  userId,
+  redis,
+  language,
+  cursor,
+  pageSize = 3,
+}: GetUserStatsTimelineInput) {
+  const maxScanMonths = 24
+  const sections: Array<{
+    yearMonth: string
+    totalHours: number
+    movieHours: number
+    seriesHours: number
+    topGenre: { name: string; posterPath: string | null } | null
+    topReview: {
+      title: string
+      posterPath: string | null
+      rating: number
+    } | null
+  }> = []
+
+  let currentYM = cursor || getCurrentYearMonth()
+  let scanned = 0
+
+  while (sections.length < pageSize && scanned < maxScanMonths) {
+    const period = currentYM
+    const dateRange = periodToDateRange(period)
+
+    const [hours, genres, reviews] = await Promise.all([
+      getUserTotalHoursService(userId, redis, period, dateRange),
+      getUserWatchedGenresService({
+        userId,
+        redis,
+        language,
+        dateRange,
+        period,
+      }),
+      getUserBestReviewsService({
+        userId,
+        redis,
+        language,
+        limit: 1,
+        dateRange,
+        period,
+      }),
+    ])
+
+    const hasData =
+      hours.totalHours > 0 ||
+      genres.genres.length > 0 ||
+      reviews.bestReviews.length > 0
+
+    if (hasData) {
+      const topGenreData = genres.genres[0]
+      const topReviewData = reviews.bestReviews[0] as
+        | Record<string, unknown>
+        | undefined
+
+      sections.push({
+        yearMonth: currentYM,
+        totalHours: hours.totalHours,
+        movieHours: hours.movieHours,
+        seriesHours: hours.seriesHours,
+        topGenre: topGenreData
+          ? {
+              name: topGenreData.name,
+              posterPath: topGenreData.posterPath,
+            }
+          : null,
+        topReview: topReviewData
+          ? {
+              title: topReviewData.title as string,
+              posterPath: (topReviewData.posterPath ?? null) as string | null,
+              rating: topReviewData.rating as number,
+            }
+          : null,
+      })
+    }
+
+    currentYM = getPreviousYearMonth(currentYM)
+    scanned++
+  }
+
+  const hasMore = sections.length >= pageSize && scanned < maxScanMonths
+
+  return {
+    sections,
+    nextCursor: hasMore ? currentYM : null,
+    hasMore,
+  }
+}
+
+function getCurrentYearMonth(): string {
+  const now = new Date()
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`
+}
+
+function getPreviousYearMonth(ym: string): string {
+  const [year, month] = ym.split('-').map(Number)
+  if (month === 1) {
+    return `${year - 1}-12`
+  }
+  return `${year}-${String(month - 1).padStart(2, '0')}`
+}