[REFACTOR] 타이머 상태 관리 동기화 구조 정리

apps/timo-web/app/[locale]/(main)/(with-time-sidebar)/home/_hooks/use-home-todos-by-date.ts

@@ -55,7 +55,7 @@ export const useHomeTodosByDate = (
   const {
     invalidateHomeView,
     invalidateStatistics,
-    invalidateTimerState,
+    invalidateTimerProgress,
     invalidateTimeBoxes,
     invalidateFocusTodo,
   } = useTimerQueryInvalidation();
@@ -64,7 +64,7 @@ export const useHomeTodosByDate = (
     useStartTimer<ApiError>({
       mutation: {
         onSuccess: () => {
-          invalidateTimerState();
+          invalidateTimerProgress();
           invalidateFocusTodo();
         },
       },
@@ -73,7 +73,7 @@ export const useHomeTodosByDate = (
     useChangeStatus({
       mutation: {
         onSuccess: () => {
-          invalidateTimerState();
+          invalidateTimerProgress();
           invalidateFocusTodo();
         },
       },
@@ -153,7 +153,7 @@ export const useHomeTodosByDate = (
       {
         onSuccess: (response) => {
           onStopFeedback(response.data?.aiFeedback ?? undefined);
-          invalidateTimerState();
+          invalidateTimerProgress();
 
           updateTodo(dateKey, todoId, (todo) => ({
             ...todo,

apps/timo-web/app/[locale]/(main)/(with-time-sidebar)/today/_hooks/useTodayTodoList.ts

@@ -48,7 +48,7 @@ export const useTodayTodoList = (
   const { mutate: changeSubtaskStatus } = useChangeSubtaskStatus();
   const { mutate: stopTimer } = useStopTimer();
   const {
-    invalidateTimerState,
+    invalidateTimerProgress,
     invalidateTimeBoxes,
     invalidateTodayView,
     invalidateFocusTodo,
@@ -58,7 +58,7 @@ export const useTodayTodoList = (
   const { mutate: startTimer, isPending: isStartTimerPending } = useStartTimer({
     mutation: {
       onSuccess: () => {
-        invalidateTimerState();
+        invalidateTimerProgress();
         invalidateFocusTodo();
       },
     },
@@ -68,7 +68,7 @@ export const useTodayTodoList = (
     useChangeStatus({
       mutation: {
         onSuccess: () => {
-          invalidateTimerState();
+          invalidateTimerProgress();
           invalidateFocusTodo();
         },
       },
@@ -141,7 +141,7 @@ export const useTodayTodoList = (
       {
         onSuccess: (response) => {
           onStopFeedback(response.data?.aiFeedback ?? undefined);
-          invalidateTimerState();
+          invalidateTimerProgress();
 
           updateTodo(todoId, (todo) => ({ ...todo, completed: true }));
           changeTodoStatus(

apps/timo-web/app/[locale]/(main)/focus/_hooks/use-focus-session.ts

@@ -22,8 +22,8 @@ import { convertDateToBadgeText } from "@/app/[locale]/(main)/focus/_utils/date"
 import { useActiveTimer } from "@/hooks/timer/use-active-timer";
 import { useTimerActions } from "@/hooks/timer/use-timer-actions";
 import { useTimerOvertime } from "@/hooks/timer/use-timer-overtime";
+import { useTimerProgress } from "@/hooks/timer/use-timer-progress";
 import { useTimerQueryInvalidation } from "@/hooks/timer/use-timer-query-invalidation";
-import { convertDurationToMinutes } from "@/utils/duration/convert-duration-to-minutes";
 
 export interface UseFocusSessionOptions {
   onMutationError: () => void;
@@ -48,6 +48,7 @@ export const useFocusSession = ({
     invalidateTodayView,
     invalidateFocusTodo,
     invalidateStatistics,
+    invalidateTimerProgress,
   } = useTimerQueryInvalidation();
   const invalidateTodoDetail = () => {
     const todo = focusView.todo;
@@ -60,29 +61,23 @@ export const useFocusSession = ({
   const { mutate: startTimer } = useStartTimer({
     mutation: {
       onSuccess: () => {
-        invalidateActiveTimer();
-        invalidateHomeView();
-        invalidateTimeBoxes();
+        invalidateTimerProgress();
       },
       onError: onMutationError,
     },
   });
   const { mutate: changeStatus } = useChangeStatus({
     mutation: {
       onSuccess: () => {
-        invalidateActiveTimer();
-        invalidateHomeView();
-        invalidateTimeBoxes();
+        invalidateTimerProgress();
       },
       onError: onMutationError,
     },
   });
   const { mutate: extendTimer } = useExtendTimer({
     mutation: {
       onSuccess: () => {
-        invalidateActiveTimer();
-        invalidateHomeView();
-        invalidateTimeBoxes();
+        invalidateTimerProgress();
       },
       onError: onMutationError,
     },
@@ -219,35 +214,20 @@ export const useFocusSession = ({
   const today = new Date(focusView.date);
   const dateText = convertDateToBadgeText(today);
 
-  const plannedSeconds = timer
-    ? timer.plannedSeconds + timer.extendedSeconds
-    : (todo?.durationSeconds ?? 0);
-  const remainingSeconds = timer ? timer.remainingSeconds : plannedSeconds;
-  const progress =
-    plannedSeconds > 0
-      ? ((plannedSeconds - remainingSeconds) / plannedSeconds) * 100
-      : 0;
-  const isOvertime = overtimeBaseSeconds !== null;
-  const overtimeTotal = timer
-    ? timer.plannedSeconds + timer.extendedSeconds - (overtimeBaseSeconds ?? 0)
-    : 0;
-  const overtimeProgress =
-    timer && overtimeBaseSeconds !== null && overtimeTotal > 0
-      ? Math.min(
-          100,
-          Math.max(
-            0,
-            ((timer.elapsedSeconds - overtimeBaseSeconds) / overtimeTotal) *
-              100,
-          ),
-        )
-      : 0;
-  const plannedMinutes = convertDurationToMinutes(plannedSeconds);
-  // 완료 모달의 "계획"은 연장 시간을 제외한 순수 계획 시간만 보여줘야 한다
-  const basePlannedMinutes = convertDurationToMinutes(
-    timer ? timer.plannedSeconds : (todo?.durationSeconds ?? 0),
-  );
-  const actualMinutes = convertDurationToMinutes(timer?.elapsedSeconds ?? 0);
+  const {
+    plannedSeconds,
+    remainingSeconds,
+    progress,
+    isOvertime,
+    overtimeProgress,
+    plannedMinutes,
+    basePlannedMinutes,
+    actualMinutes,
+  } = useTimerProgress({
+    timer,
+    overtimeBaseSeconds,
+    fallbackPlannedSeconds: todo?.durationSeconds ?? 0,
+  });
 
   return {
     focusSessionState: {

apps/timo-web/components/layout/sidebar/time/TimerPanel.tsx

@@ -17,9 +17,9 @@ import {
 import { useActiveTimer } from "@/hooks/timer/use-active-timer";
 import { useTimerActions } from "@/hooks/timer/use-timer-actions";
 import { useTimerOvertime } from "@/hooks/timer/use-timer-overtime";
+import { useTimerProgress } from "@/hooks/timer/use-timer-progress";
 import { useTimerQueryInvalidation } from "@/hooks/timer/use-timer-query-invalidation";
 import { formatDateKey } from "@/utils/date/date";
-import { convertDurationToMinutes } from "@/utils/duration/convert-duration-to-minutes";
 import { convertDurationToTimeText } from "@/utils/duration/convert-duration-to-time-text";
 import { formatDurationLabel } from "@/utils/duration/format-duration-label";
 
@@ -30,54 +30,41 @@ export const TimerPanel = () => {
 
   const { data: activeTimer } = useActiveTimer();
   const {
-    invalidateActiveTimer,
     invalidateHomeView,
     invalidateTimeBoxes,
     invalidateTodayView,
     invalidateFocusTodo,
-    invalidateTodoDetail,
+    invalidateTimerProgress,
+    invalidateTimerFinish,
   } = useTimerQueryInvalidation();
 
   const { mutate: changeStatus } = useChangeStatus({
     mutation: {
       onSuccess: () => {
-        invalidateActiveTimer();
-        invalidateHomeView();
-        invalidateTimeBoxes();
+        invalidateTimerProgress();
       },
     },
   });
   const { mutate: extendTimer } = useExtendTimer({
     mutation: {
       onSuccess: () => {
-        invalidateActiveTimer();
-        invalidateTimeBoxes();
+        invalidateTimerProgress();
       },
     },
   });
   const { mutate: completeTimer } = useCompleteTimer({
     mutation: {
       onSuccess: (response) => {
         setFeedbackText(response.data?.aiFeedback ?? undefined);
-        invalidateActiveTimer();
-        invalidateHomeView();
-        invalidateTimeBoxes();
-        invalidateTodayView();
-        invalidateFocusTodo();
-        if (response.data?.todoId) invalidateTodoDetail(response.data.todoId);
+        invalidateTimerFinish(response.data?.todoId);
       },
     },
   });
   const { mutate: stopTimer } = useStopTimer({
     mutation: {
       onSuccess: (response) => {
         setFeedbackText(response.data?.aiFeedback ?? undefined);
-        invalidateActiveTimer();
-        invalidateHomeView();
-        invalidateTimeBoxes();
-        invalidateTodayView();
-        invalidateFocusTodo();
-        if (response.data?.todoId) invalidateTodoDetail(response.data.todoId);
+        invalidateTimerFinish(response.data?.todoId);
       },
     },
   });
@@ -130,40 +117,15 @@ export const TimerPanel = () => {
     changeTodoStatus,
   });
 
-  const plannedSeconds = activeTimer
-    ? activeTimer.plannedSeconds + activeTimer.extendedSeconds
-    : 0;
-  const remainingSeconds = activeTimer ? activeTimer.remainingSeconds : 0;
-  const progress =
-    plannedSeconds > 0
-      ? ((plannedSeconds - remainingSeconds) / plannedSeconds) * 100
-      : 0;
-  const isOvertime = overtimeBaseSeconds !== null;
-  const overtimeTotal = activeTimer
-    ? activeTimer.plannedSeconds +
-      activeTimer.extendedSeconds -
-      (overtimeBaseSeconds ?? 0)
-    : 0;
-  const overtimeProgress =
-    activeTimer && overtimeBaseSeconds !== null && overtimeTotal > 0
-      ? Math.min(
-          100,
-          Math.max(
-            0,
-            ((activeTimer.elapsedSeconds - overtimeBaseSeconds) /
-              overtimeTotal) *
-              100,
-          ),
-        )
-      : 0;
-  const plannedMinutes = convertDurationToMinutes(plannedSeconds);
-  // 완료 모달의 "계획"은 연장 시간을 제외한 순수 계획 시간만 보여줘야 한다
-  const basePlannedMinutes = convertDurationToMinutes(
-    activeTimer?.plannedSeconds ?? 0,
-  );
-  const actualMinutes = convertDurationToMinutes(
-    activeTimer?.elapsedSeconds ?? 0,
-  );
+  const {
+    remainingSeconds,
+    progress,
+    isOvertime,
+    overtimeProgress,
+    plannedMinutes,
+    basePlannedMinutes,
+    actualMinutes,
+  } = useTimerProgress({ timer: activeTimer, overtimeBaseSeconds });
 
   return (
     <div className="flex flex-col items-center gap-11.25">

apps/timo-web/hooks/timer/use-timer-overtime.ts

@@ -1,38 +1,17 @@
 "use client";
 
-import { useEffect, useState } from "react";
-
 import type { ActiveTimer } from "@/schemas/timer/timer-schema";
 
-const STORAGE_KEY_PREFIX = "timo:overtime-base:";
-
-const readStoredBase = (timerId: number): number | null => {
-  if (typeof window === "undefined") return null;
-
-  const raw = window.sessionStorage.getItem(`${STORAGE_KEY_PREFIX}${timerId}`);
-  if (raw === null) return null;
-
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) ? parsed : null;
-};
+import { useTimerOvertimeStore } from "@/stores/timer/useTimerOvertimeStore";
 
 export const useTimerOvertime = (timer: ActiveTimer | undefined) => {
   const timerId = timer?.timerId;
-  const [overtimeBaseSeconds, setOvertimeBaseSeconds] = useState<number | null>(
-    null,
+  const overtimeBaseSeconds = useTimerOvertimeStore((state) =>
+    state.timerId === timerId ? state.baseSeconds : null,
+  );
+  const markOvertimeStart = useTimerOvertimeStore(
+    (state) => state.markOvertimeStart,
   );
-
-  useEffect(() => {
-    setOvertimeBaseSeconds(timerId ? readStoredBase(timerId) : null);
-  }, [timerId]);
-
-  const markOvertimeStart = (timerId: number, baseSeconds: number) => {
-    setOvertimeBaseSeconds(baseSeconds);
-    window.sessionStorage.setItem(
-      `${STORAGE_KEY_PREFIX}${timerId}`,
-      String(baseSeconds),
-    );
-  };
 
   return { overtimeBaseSeconds, markOvertimeStart };
 };

apps/timo-web/hooks/timer/use-timer-progress.ts

@@ -0,0 +1,59 @@
+import type { ActiveTimer } from "@/schemas/timer/timer-schema";
+
+import { convertDurationToMinutes } from "@/utils/duration/convert-duration-to-minutes";
+
+export interface UseTimerProgressOptions {
+  timer: ActiveTimer | undefined;
+  overtimeBaseSeconds: number | null;
+  /** 활성 타이머가 없을 때 사용할 계획 시간(초). 기본값 0 */
+  fallbackPlannedSeconds?: number;
+}
+
+export const useTimerProgress = ({
+  timer,
+  overtimeBaseSeconds,
+  fallbackPlannedSeconds = 0,
+}: UseTimerProgressOptions) => {
+  const plannedSeconds = timer
+    ? timer.plannedSeconds + timer.extendedSeconds
+    : fallbackPlannedSeconds;
+  const remainingSeconds = timer ? timer.remainingSeconds : plannedSeconds;
+  const progress =
+    plannedSeconds > 0
+      ? ((plannedSeconds - remainingSeconds) / plannedSeconds) * 100
+      : 0;
+
+  const isOvertime = overtimeBaseSeconds !== null;
+  const overtimeTotal = timer
+    ? timer.plannedSeconds + timer.extendedSeconds - (overtimeBaseSeconds ?? 0)
+    : 0;
+  const overtimeProgress =
+    timer && overtimeBaseSeconds !== null && overtimeTotal > 0
+      ? Math.min(
+          100,
+          Math.max(
+            0,
+            ((timer.elapsedSeconds - overtimeBaseSeconds) / overtimeTotal) *
+              100,
+          ),
+        )
+      : 0;
+
+  const plannedMinutes = convertDurationToMinutes(plannedSeconds);
+  // 완료 모달의 "계획"은 연장 시간을 제외한 순수 계획 시간만 보여줘야 한다
+  const basePlannedMinutes = convertDurationToMinutes(
+    timer ? timer.plannedSeconds : fallbackPlannedSeconds,
+  );
+  const actualMinutes = convertDurationToMinutes(timer?.elapsedSeconds ?? 0);
+
+  return {
+    plannedSeconds,
+    remainingSeconds,
+    progress,
+    isOvertime,
+    overtimeProgress,
+    plannedMinutes,
+    basePlannedMinutes,
+    actualMinutes,
+  };
+};