Skip to content

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

Open
jjangminii wants to merge 12 commits into
developfrom
refactor/web/279-unify-timer-query-invalidation
Open

[REFACTOR] 타이머 상태 관리 동기화 구조 정리#280
jjangminii wants to merge 12 commits into
developfrom
refactor/web/279-unify-timer-query-invalidation

Conversation

@jjangminii

@jjangminii jjangminii commented Aug 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

ISSUE 🔗

close #279



What is this PR? 🔍

타이머 상태 관리에서 발생하던 동기화 부담을 줄이기 위해, 쿼리 무효화 로직을 통일하고 overtime 상태를 zustand로 옮기고, TimerPanel/useFocusSession에 중복돼 있던 진행률 계산을 공통 훅으로 추출했습니다.

배경

  • 기존 구조: 타이머는 React Query만으로 관리되고 있었고, mutation 성공 시 무효화할 쿼리키와 초과시간/진행률 파생 계산이 TimerPanel, useFocusSession, home/today 훅 등 여러 화면에 각각 손으로 흩어져 있었습니다.
  • 발생 문제: 화면이 늘어날 때마다 무효화 목록을 빠짐없이 맞춰야 했고, overtime 상태는 컴포넌트별 로컬 상태라 화면 간 동기화가 안 됐으며, 진행률 계산 로직은 두 곳에 사실상 동일하게 중복돼 있었습니다.
  • 해결 방향: 무효화 조합을 의미 단위(progress/finish) 헬퍼로 통일하고, 여러 화면이 공유해야 하는 overtime 상태만 zustand로 승격하고, 순수 계산 로직은 공통 훅으로 추출했습니다. React Query는 여전히 서버 상태의 유일한 소스로 유지했습니다.
  • 검토한 대안: activeTimer 전체를 zustand로 미러링하는 방안도 검토했습니다. 하지만 이 경우 React Query 캐시와 zustand 스토어라는 진실 소스가 2개가 되어 이 둘을 맞추는 sync bridge 코드가 항상 필요해지고, 버그가 나면 캐시와 스토어가 서로 어긋나는 새로운 동기화 문제가 생깁니다. 게다가 이 방식은 실제로 겪은 문제(여러 화면에 걸친 무효화 목록 관리, 화면 간 파생 상태 중복)를 직접 해결해주지 않아서 채택하지 않았습니다. 대신 서버 상태가 아닌 것(overtime 기준값)만 zustand로 승격하고, 나머지는 React Query 구조 안에서 정리하는 쪽을 택했습니다.
image

쿼리 무효화 로직

  • 변경 요약: 타이머 mutation 성공 시 호출하던 개별 invalidate 나열을 invalidateTimerProgress/invalidateTimerFinish 두 헬퍼로 통일했습니다.
  • 이유: TimerPanel의 mutation마다 무효화할 쿼리키 조합을 다르게 손으로 나열하고 있었고, 기존에 있던 통합 헬퍼(invalidateTimerState)는 TimerPanel에서 쓰이지 않은 채 home/today 화면에서만 쓰이고 있어 이름과 실제 용도가 어긋나 있었습니다.
  • 구현 방식: 일시정지/재개/연장처럼 타이머가 계속 진행 중인 액션은 invalidateTimerProgress(activeTimer+home+timeBoxes+statistics)로, 완료/중지처럼 종료되는 액션은 invalidateTimerFinish(위 4개+today+focusTodo+선택적 todoDetail)로 나눴습니다.
  • 경계 · 제약: home/today 화면에서 쓰던 invalidateTimerState 호출부도 동일한 조합만 하고 있어서, 동작 변화 없이 invalidateTimerProgress로 이름만 맞췄습니다. useFocusSession도 startTimer/changeStatus/extendTimer에서 같은 조합을 직접 나열하고 있던 걸 invalidateTimerProgress 호출로 통일했습니다.
  • 리뷰 중 수정: 처음에는 statistics가 완료된 세션 기준 데이터라 진행 중 액션에서는 무효화할 필요가 없다고 판단해 invalidateTimerProgress에서 뺐었는데, 리뷰 과정에서 이 가정이 틀릴 수 있다는 피드백을 받아 statistics 무효화를 다시 포함했습니다.
  • 후속 정리: home/today 훅에서 useStartTimer/useChangeStatus의 mutation 설정에 달아둔 전역 onSuccess(invalidateTimerProgress() + invalidateFocusTodo())와, pause/resume/start 호출부의 onSuccess(invalidateTodoDetail만 호출)가 각각 따로 존재해 같은 액션에 대해 무효화 호출이 두 군데로 나뉘어 있었습니다. 이를 invalidateTimerProgress가 { includeFocus?, todoId? } 옵션을 받도록 확장해, 호출부 하나에서 invalidateTimerProgress({ includeFocus: true, todoId }) 한 번으로 합쳤습니다. 종료(stop) 액션도 invalidateTimerProgress() 호출과, 이어지는 changeTodoStatus의 중첩 onSuccess(home/today별로 조금씩 다른 무효화 조합을 다시 나열하던 부분)를 invalidateTimerFinish(todoId) 한 번으로 합쳤습니다.
image

Overtime 상태 관리

  • 변경 요약: 초과시간 시작 기준값(overtimeBaseSeconds)을 sessionStorage 기반 컴포넌트 로컬 상태에서 zustand 스토어로 옮겼습니다.
  • 이유: TimerPanel과 useFocusSession이 각자 useTimerOvertime을 호출하면 서로 다른 React 상태 인스턴스를 가지게 되어, 한쪽에서 markOvertimeStart를 호출해도 다른 쪽은 자기 timerId가 바뀌어 useEffect가 재실행되기 전까지 반영되지 않는 화면 간 비동기화가 있었습니다.
  • 구현 방식: stores/timer/useTimerOvertimeStore.ts에 { timerId, baseSeconds } 단일 상태를 두고, sessionStorage 읽기/쓰기는 utils/timer/overtime-storage.ts로 분리했습니다(useAuthStore가 token-manager.ts를 쓰는 기존 패턴과 동일). use-timer-overtime.ts는 이 스토어를 감싸는 얇은 훅으로 남겨 외부 API(useTimerOvertime(timer) => { overtimeBaseSeconds, markOvertimeStart })는 그대로 유지해 호출부 변경을 최소화했습니다.
  • 경계 · 제약: activeTimer 자체(서버 상태)는 여전히 React Query가 유일한 소스이고, zustand는 서버에 없는 순수 클라이언트 상태(overtime 기준값)만 담당합니다.
image

타이머 진행률 계산

  • 변경 요약: TimerPanel과 useFocusSession에 거의 동일하게 중복돼 있던 progress/overtime/분 단위 변환 계산을 useTimerProgress 훅으로 추출했습니다.
  • 이유: 활성 타이머가 없을 때의 fallback 값(0 vs todo.durationSeconds)만 다를 뿐 나머지 계산 로직이 완전히 동일하게 복붙돼 있어서, 한쪽만 고치고 다른 쪽을 놓칠 위험이 있었습니다.
  • 구현 방식: hooks/timer/use-timer-progress.ts가 { timer, overtimeBaseSeconds, fallbackPlannedSeconds? }를 받아 { plannedSeconds, remainingSeconds, progress, isOvertime, overtimeProgress, plannedMinutes, basePlannedMinutes, actualMinutes }를 반환합니다. TimerPanel은 fallbackPlannedSeconds를 생략(0)하고, useFocusSession은 todo?.durationSeconds ?? 0을 넘겨 두 화면의 유일한 차이를 파라미터로 흡수했습니다.



To Reviewers

overtime 스토어를 { timerId, baseSeconds } 단일 값으로 뒀는데, 이건 활성 타이머가 한 번에 하나만 존재한다는 서버 정책(동시 시작 시 409)을 전제로 한 설계입니다. 이 전제가 맞는지 한번 봐주세요.

pause/resume 시 서버 응답을 기다렸다가 무효화하는 방식은 이번 PR에서 그대로 뒀습니다(낙관적 업데이트는 의도적으로 범위에서 제외했고, 후속 작업으로 남겨뒀습니다).

UI 변경은 없고 내부 상태 관리 구조만 정리한 PR이라, 실제 로그인 후 타이머 pause/resume/extend/complete/stop 클릭 테스트는 프로덕션 API 인증이 필요해 제가 직접 하지 못했습니다 — 리뷰 시 한 번 확인 부탁드립니다.



Screenshot 📷



Test Checklist ✔

  • pnpm check-types 통과
  • pnpm lint 통과
  • dev 서버에서 /home, /today, /focus 라우트가 500 없이 컴파일/응답되는지 확인 (curl)
  • 실제 로그인 상태에서 pause/resume/extend/complete/stop 클릭 테스트 — 미실행: 프로덕션 API 인증 필요, 리뷰어 확인 요청

@jjangminii
refactor(web): 타이머 쿼리 무효화 로직 통일 (#279)
4c8a04f 
- 타이머 mutation별로 흩어져 있던 쿼리 무효화 호출을 invalidateTimerProgress(일시정지/재개/연장)와 invalidateTimerFinish(완료/중지) 두 헬퍼로 통일했습니다
- 기존 invalidateTimerState를 invalidateTimerProgress로 이름을 맞춰 다른 화면(home/today)에도 동일하게 적용했습니다
@jjangminii
refactor(web): 타이머 overtime 상태를 zustand 스토어로 전환
c43cbed 
- sessionStorage를 컴포넌트 로컬 상태로 직접 읽던 방식을 zustand 스토어로 옮겼습니다
- TimerPanel과 FocusSession처럼 이 훅을 각자 호출하는 화면들이 초과시간 상태를 서로 동기화해서 볼 수 있게 했습니다
@jjangminii
refactor(web): 타이머 진행률 계산을 공통 훅으로 추출
89f3408 
- TimerPanel과 useFocusSession에 거의 동일하게 중복돼 있던 progress/overtime/분 단위 변환 계산을 useTimerProgress 훅으로 추출했습니다
@vercel

vercel Bot commented Aug 23, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
timo Ready Ready Preview Sep 11, 2026 8:02am UTC

@github-actions
github-actions Bot requested review from ehye1 and kimminna August 23, 2026 08:14
@github-actions github-actions Bot added ⏰ Timo-web Timo 웹 서비스 ♻ Refactor 기능 개선 및 리팩토링 작업 ♠️ 정민 정민양 labels Aug 23, 2026
@github-actions

github-actions Bot commented Aug 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Timo Performance Report

Bundle Size — timo-web
라우트 크기 First Load JS
/[locale]/home 275.04 kB 🔴 480.85 kB
/[locale]/today 259.21 kB 🔴 465.03 kB
/[locale]/focus 221.85 kB 🔴 427.67 kB
/[locale]/settings 228.51 kB 🔴 434.33 kB
/[locale]/statistics 210.21 kB 🔴 416.02 kB
/[locale]/[...rest] 0 B 🟡 205.81 kB
/[locale]/login 281.84 kB 🔴 487.65 kB
/[locale]/oauth/calendar/callback 120.93 kB 🟡 326.75 kB
/[locale]/oauth/callback 120.60 kB 🟡 326.41 kB
/[locale]/onboarding 294.32 kB 🔴 500.13 kB
/[locale] 119.91 kB 🟡 325.73 kB
/[locale]/policy 120.88 kB 🟡 326.70 kB
/robots.txt/route 0 B 🟡 205.81 kB
/sitemap.xml/route 0 B 🟡 205.81 kB

공유 번들: 205.81 kB
🟢 < 200kB  |  🟡 < 350kB  |  🔴 ≥ 350kB (First Load JS · gzip)

Lighthouse — timo-web
URL Perf A11y LCP CLS TBT
/en/home 🔴 43 🟢 96 🔴 16.4s 🟢 0.000 🔴 1953ms
/en/today 🔴 69 🟢 96 🔴 16.1s 🟢 0.000 🟡 280ms
/en/focus 🔴 64 🟢 96 🔴 16.1s 🟢 0.000 🟡 412ms
/en/statistics 🔴 64 🟢 96 🔴 16.1s 🟢 0.000 🟡 427ms

Perf ≥ 70 / A11y ≥ 85 목표
LCP 🟢 < 2.5s 🟡 < 4s 🔴 ≥ 4s  |  CLS 🟢 < 0.1 🟡 < 0.25 🔴 ≥ 0.25  |  TBT 🟢 < 200ms 🟡 < 600ms 🔴 ≥ 600ms

Image Optimization — timo-web
파일 크기 포맷 상태
favicon.png 27.84 kB PNG ⚠️ 🟢
images/google-calendar.png 36.20 kB PNG ⚠️ 🟢
images/google-logo.png 26.79 kB PNG ⚠️ 🟢
og.png 437.44 kB PNG ⚠️ 🟡

총 4개 · 528.28 kB  |  🟢 < 200KB  |  🟡 < 500KB  |  🔴 ≥ 500KB
⚠️ 4개 파일 WebP/AVIF 변환 권장

측정 커밋: c7bb297

@jjangminii

jjangminii commented Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@jjangminii
fix(web): 타이머 진행 중 액션에도 통계 쿼리 무효화 (#279)
d8d468d 
- invalidateTimerProgress(일시정지/재개/연장)에서 빠졌던 invalidateStatistics 호출을 복원했습니다
- use-focus-session.ts가 같은 무효화 로직을 따로 손으로 하고 있어서 invalidateTimerProgress를 쓰도록 함께 정리했습니다
@coderabbitai

coderabbitai Bot commented Aug 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 3ffefae3-6b1e-4b4f-839b-c60c2bacbd47

Comment @coderabbitai help to get the list of available commands.

kimminna
kimminna reviewed Aug 24, 2026
View reviewed changes

@kimminna kimminna left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

타이머 상태는 역시 넘 어렵네요...
다만 구조 측면에서 더 리뷰를 달아보자면, 함수 내부에서 리액트 훅을 직접 호출하는지의 여부에 따라 hooks/ 폴더 내부에 구조화하는 기준을 조금 더 세우면 좋을 것 같아요!

천천히 리팩해봅쉬다~~

Comment thread apps/timo-web/hooks/timer/use-timer-progress.ts Outdated
Comment thread apps/timo-web/hooks/timer/use-timer-query-invalidation.ts
Comment thread apps/timo-web/utils/timer/overtime-storage.ts Outdated
@jjangminii
refactor(web): use-timer-progress를 utils로 이동하고 getTimerProgress로 개명 (#…
ed45072 
…279)

- React 훅을 쓰지 않는 순수 계산 로직이라 hooks/의 use 접두사가 맞지 않다는 리뷰 피드백을 반영했습니다
- utils/timer/get-timer-progress.ts로 옮기고 getTimerProgress로 개명했습니다
- utils 컨벤션에 맞춰 JSDoc(설명/@param/@returns)을 추가했습니다
@jjangminii
refactor(web): getTimerProgress로 개명한 파일과 호출부 반영 (#279)
b2967e2 
- 앞 커밋에서 새 파일 추가와 호출부 수정이 스테이징 누락으로 빠졌던 부분을 마저 커밋했습니다
@jjangminii
refactor(web): overtime storage 파싱을 unknown 후 타입가드로 좁히도록 수정 (#279)
e732db0 
- JSON.parse(raw)를 곧바로 as OvertimeBase로 단언하던 걸 unknown으로 받아 isOvertimeBase 타입가드로 좁히도록 바꿨습니다
- sessionStorage에서 읽은 외부 입력은 검증 전에 타입을 확정하면 안 된다는 리뷰 피드백을 반영했습니다
@jjangminii
refactor(web): use-focus-session도 invalidateTimerFinish 공유 (#279)
84b8185 
- completeTimer/stopTimer의 무효화 목록을 손으로 나열하던 걸 공유 헬퍼 invalidateTimerFinish(todoId)로 교체했습니다
- invalidateTodoDetail(todoId)는 date 파라미터가 없지만 React Query v5의 invalidateQueries는 기본이 prefix 매칭이라 date-scoped 캐시까지 함께 무효화됩니다
- 더는 쓰이지 않는 invalidateActiveTimer/invalidateHomeView 구조분해도 정리했습니다
@jjangminii
docs(web): 타이머 무효화 헬퍼에 JSDoc 추가 (#279)
848ce9e 
- invalidateTimerProgress/invalidateTimerFinish에 여러 줄 JSDoc과 invalidateTimerFinish의 todoId에 @PARAM을 추가했습니다
- 동작 변화는 없고 문서만 보강했습니다
kimminna
kimminna approved these changes Aug 25, 2026
View reviewed changes

@kimminna kimminna left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️ 타이머의 신. 권위자

@kimminna kimminna added the 🫵🏻 Reminded 리마인드 완료 label Aug 26, 2026
@jjangminii
refactor(web): 타이머 진행 무효화에 옵션 추가하고 개별 훅의 중복 로직 통일 (#279)
f21ad3a 
- invalidateTimerProgress에 includeFocus, todoId 옵션을 추가했습니다
- 홈/투데이 훅에서 mutation.onSuccess로 흩어져 있던 무효화 로직을 헬퍼 호출로 통일했습니다
- 타이머 종료 시 invalidateTimerFinish를 사용하도록 변경했습니다
@jjangminii
Merge branch 'develop' of https://github.com/Team-Timo/Timo-client in…
24b94cf 
…to refactor/web/279-unify-timer-query-invalidation
ehye1
ehye1 approved these changes Sep 10, 2026
View reviewed changes

@ehye1 ehye1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

타이머 관련 로직들 깔끔하게 리팩토링해주셨네요!!! 다이어그램과 함께 자세하게 설명해주셔서 전체 흐름 이해하는 데 도움이 많이 됐습니다. 고생 많으셨습니다🥰

Comment thread apps/timo-web/app/[locale]/(main)/(with-time-sidebar)/home/_hooks/use-home-todos-by-date.ts
Comment on lines -162 to -171
changeTodoStatus(
{ todoId, data: { isCompleted: true, date: dateKey } },
{
onSuccess: () => {
invalidateHomeAndFocus();
invalidateTodoDetail(dateKey, todoId);
invalidateStatistics();
},
},
);

@ehye1 ehye1 Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

혹시 기존 onSuccess의 invalidate는 invalidateTimerFinish에서 동일한 쿼리들을 무효화하고 있어서 중복이라고 판단해 삭제하신 걸까요?
삭제하게 되면 현재 구조에서 PATCH 요청보다 invalidateTimerFinish가 먼저 실행되기 때문에 완료 상태가 서버에 반영되기 전에 GET 응답이 돌아올 수 있을 것 같아요. 이후에 PATCH가 정상적으로 완료되더라도 성공 이후에 다시 무효화하는 로직이 없기 때문에, 화면에는 서버와 다르게 미완료로 남아보일 가능성이 있다고 생각했어요. 지금은 서버 응답이 빨라서 눈으로 보기에 문제가 없어 보여서 이 정도 케이스는 고려하지 않아도 되는지 궁금합니다!

@jjangminii @claude
fix(web): 투두 완료 처리 PATCH 이후 재검증 누락 레이스 컨디션 수정 (#279)
850b92e 
- changeTodoStatus의 무효화 로직을 mutation 정의 시점 onSuccess로 옮겨 어떤 호출부에서도 PATCH 완료 후 항상 재검증하도록 했습니다
- 타이머 종료 시 invalidateTimerFinish만 실행되고 투두 완료 PATCH 성공 이후 재검증이 없어 완료 상태가 화면에 반영되지 않을 수 있던 레이스 컨디션을 수정했습니다
- invalidateTodoDetail이 date를 옵션으로 받도록 확장하고 화면별로 중복 구현돼 있던 로컬 무효화 래퍼를 제거해 focus/TimerPanel과 구조를 통일했습니다

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GWUhaUE5dxUTjmjKe4c3LV
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ehye1 ehye1 ehye1 approved these changes
@kimminna kimminna kimminna approved these changes

Assignees

@jjangminii jjangminii

Labels

♠️ 정민 정민양 ♻ Refactor 기능 개선 및 리팩토링 작업 🫵🏻 Reminded 리마인드 완료 ⏰ Timo-web Timo 웹 서비스

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[REFACTOR] 타이머 쿼리 무효화 로직 통일

3 participants

@jjangminii @ehye1 @kimminna