[FIX] 시간 총량제 타이머 한 팀 시간 소진 시 버그 수정

[i-meant-to-be]

🚩 연관 이슈

closed #384

📝 작업 내용

들어가기에 앞서

제가 PR을 쉽게 써보려고는 했는데 로직이 좀 복잡해서 생각대로 되지 않네요... 그래서 Gemini의 도움을 받아 최대한 받아들이기 쉽게 적어 봤습니다. 그럼에도 불구하고 이해가 어려운 부분이 있으시면 Discord로 편하게 질문 남겨주세요! 빠르게 답변 드리도록 하겠습니다.

요약

상대 팀의 시간이 모두 소진되었을 때, 시간 총량제 타이머의 원형 진행률 표시가 비정상적으로 계산되던 문제를 해결합니다.

세부 내용

1. 문제 상황

시간 총량제 타이머에는 한 팀의 시간(팀당 발언 시간)이 모두 소진되면, 상대 팀은 더 이상 1회당 발언 시간에 제한받지 않고 남은 시간을 한 번에 모두 사용할 수 있는 특별한 규칙이 있습니다.

하지만 이 규칙이 적용되는 상황에서, 타이머의 진행률을 계산하는 기준 시간(분모)이 올바르게 갱신되지 않아 원형 프로그레스 바가 비정상적으로 표시되는 문제가 있었습니다.

예시 시나리오

• 찬성 팀: 시간 모두 소진
• 반대 팀: 팀당 발언 시간 3분 40초 남음 / 1회당 발언 시간은 2분으로 설정됨
• 기대 동작: 반대 팀은 이제부터 2분이 아닌, 남은 3분 40초를 한 번에 사용할 수 있습니다. 따라서 진행률의 기준 시간(100%)은 3분 40초가 되어야 합니다.
• 실제 문제: 기준 시간이 갱신되지 않아 진행률 계산에 오류가 발생했습니다.

2. 원인 분석

문제의 원인은 두 가지였습니다.

• 상대 팀 상태 미확인: 진행률을 계산하는 로직에서, 상대 팀의 시간이 모두 소진되었는지 확인하는 과정이 누락되어 있었습니다.
• 잘못된 변수 사용: 진행률의 기준 시간(분모)이 useState와 같은 상태(State)로 관리되지 않고, 렌더링마다 실시간으로 재계산되는 일반 const 변수로 선언되어 있었습니다. 이 때문에 타이머가 시작되는 시점의 값을 고정하지 못하고, 시간이 흐름에 따라 기준값이 계속 변하는 문제가 발생했습니다.

3. 해결 방안

이 문제를 해결하기 위해, 진행률의 기준 시간인 denominator(분모)를 useTimeBasedTimer 훅 내부에서 useState로 관리하도록 구조를 변경했습니다.

이제 denominator 값은 다음과 같은 주요 시점에 맞게 명시적으로 갱신됩니다:

• 타이머가 시작될 때
• 발언 팀이 전환될 때
• 타이머가 리셋될 때

결과적으로, 상대 팀의 시간이 소진되는 등의 특수 상황에서도 타이머가 시작되는 순간의 정확한 시간을 기준으로 삼아 진행률을 올바르게 계산하고 표시합니다.

🏞️ 스크린샷 (선택)

2025-10-04.231525.mp4

🗣️ 리뷰 요구사항 (선택)

제가 테스트를 하긴 하였으나 꼭 로컬에서 다양한 시나리오로 테스트 진행해보신 후 문제 있는지 확인해주세요. 제가 빼먹은 게 있을 수 있으니... 항상 감사합니다 😭

Summary by CodeRabbit

• 신기능

  • 타이머 시작 시 상대 완료 상태(isOpponentDone)를 전달해 상대 상태 기반 동작·스타일 반영
  • 진행률의 분모(denominator) 도입으로 퍼센트 기반 표시가 일관되게 계산됨
  • 좌/우 타이머 간 상태 연동 및 단일 타이머 토글로 핫키 동작 간소화

• 버그 수정

  • 상대 타이머 종료 시 진행률 표시 이상 수정
  • 재시작·일시정지·리셋 시 분모 갱신 누락 문제 해결

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

타이머 흐름에 상대팀 완료 플래그(isOpponentDone)와 진행률 분모(denominator)를 도입했다. startTimer 시그니처를 (isOpponentDone: boolean)으로 변경하고 컴포넌트·뷰·훅·핫키 전반에서 해당 값을 전달·갱신하도록 연동했으며 훅은 denominator 상태를 관리한다.

Changes

Cohort / File(s)	Change Summary
타이머 컴포넌트 API 업데이트 src/page/TimerPage/components/TimeBasedTimer.tsx	TimeBasedTimerProps에 isOpponentDone 추가, TimeBasedTimerInstance에 denominator 추가. startTimer 시그니처가 startTimer(isOpponentDone: boolean)으로 변경되고 컴포넌트가 onStart로 해당 플래그를 전달. 진행률 계산에서 denominator 사용.
타이머 뷰 연동 src/page/TimerPage/components/TimerView.tsx	PROS/CONS 타이머 인스턴스에 denominator 포함 및 상대 타이머의 isDone 기반으로 isOpponentDone 전달. startTimer 인자 변경 반영.
타이머 훅 로직 확장 src/page/TimerPage/hooks/useTimeBasedTimer.ts	denominator 상태와 updateDenominator 추가. startTimer(isOpponentDone: boolean)로 시그니처 변경. start/pause/reset/clear/next-phase 등에서 updateDenominator(isOpponentDone) 호출하도록 수정. 훅 반환값에 denominator 노출.
핫키 처리 변경 src/page/TimerPage/hooks/useTimerHotkey.ts	개별 토글 함수를 통합하여 선택된 PROS/CONS에 따라 해당 타이머의 startTimer를 호출하되 인자로 상대 타이머의 isDone 전달. Space 키 처리 경로에서 통합 로직 사용.
스토리(테스트) 수정 src/page/TimerPage/stories/TimeBasedTimer.stories.tsx	목(mock) 타이머 인스턴스에 denominator: 1 추가(스토리/테스트용 필드 확장).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as 사용자
  participant View as TimerView
  participant Comp as TimeBasedTimer
  participant Hook as useTimeBasedTimer

  User->>View: 시작/토글 액션
  View->>Comp: props (isOpponentDone, denominator, ...)
  Comp->>Hook: startTimer(isOpponentDone)
  activate Hook
  Hook->>Hook: updateDenominator(isOpponentDone)
  Hook->>Hook: interval 시작 → progress 계산 (denominator 사용)
  Hook-->>Comp: 진행률/상태 업데이트
  deactivate Hook

  Note over Hook,Comp: 상대팀 완료 여부에 따라 denominator 기반 계산 경로 전환

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• [REFACTOR] TimerPage 비즈니스 로직 분리 #304: TimeBasedTimer API 확장(denominator/isOpponentDone/startTimer 시그니처 변경)과 직접적 연관.
• [FIX] 상대팀이 모두 시간 소진, 2회 이상 발언할 시간이 남아있을 때, 1회 발언 이후, 전체시간을 전부 소비할 수 없는 문제 수정 #334: 훅에서 opponent-aware 동작을 도입한 변경과 유사한 코드 레이어 겹침.
• [FIX] 타이머 오류 해결 #350: 진행률 계산 로직 변경과 연관되어 있음.

Suggested reviewers

• jaeml06
• useon

Poem

깡총깡총 토끼가 시곗바늘 곁에서 속삭여 🐇
상대가 끝나면 분모를 살짝 고쳐보고
초는 부드럽게, 바늘은 공평하게 돌고
버그는 숲속에 숨고 우리는 다시 셈하며
깡총, 변화는 또 한 걸음 춤춘다

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	PR 제목이 한 팀의 시간 소진 시 발생하는 버그 수정이라는 핵심 변경사항을 명확하고 간결하게 전달하고 있어 변경 내용을 잘 요약하고 있습니다.
Linked Issues Check	✅ Passed	코드 변경사항이 useTimeBasedTimer 훅과 컴포넌트에서 denominator 상태 관리와 isOpponentDone 플래그를 도입해 한 팀 시간 소진 시 진행률 계산 로직을 올바르게 갱신하도록 구현하여 이슈 #384의 요구 사항을 충족합니다.
Out of Scope Changes Check	✅ Passed	모든 변경 사항이 상대 팀 시간 소진 시 진행률 기준 시간 처리 버그 수정과 직접적으로 관련되어 있으며, 범위를 벗어난 코드 변경은 포함되어 있지 않습니다.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2fa1965 and 97ac92e.

📒 Files selected for processing (1)

• src/page/TimerPage/hooks/useTimeBasedTimer.ts (9 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3f7cffb and f2e58e7.

📒 Files selected for processing (3)

• src/page/TimerPage/components/TimeBasedTimer.tsx (5 hunks)
• src/page/TimerPage/components/TimerView.tsx (2 hunks)
• src/page/TimerPage/hooks/useTimeBasedTimer.ts (9 hunks)

🔇 Additional comments (1)

src/page/TimerPage/hooks/useTimeBasedTimer.ts (1)

43-66: ...

[jaeml06]

넵 확인했습니다. dev환경에서 정상적으로 진행바가 차오르는 것을 확인했습니다.
리뷰 내용은 한건이 있으나 사소한 내용이라고 생각되니 approve 드리겠습니다

[useon]

dev 환경에서 정상 작동 확인했습니다 !!!! PR에 잘 설명해 주셔서 이해하기 편했습니다 감사해요 !! 🤩