Skip to content

Tools Timer

wcorn edited this page Apr 5, 2026 · 4 revisions

메이플 재획 타이머

메이플스토리 재획/버프 재사용을 돕는 2단계 주기 알림 타이머. Tools 모듈 내 첫 도구.

1. 유스케이스

배경

메이플스토리 사냥 중 재물획득의 비약·재획서 등 시간제 버프를 주기적으로 재사용해야 한다. 두 종류의 쿨타임이 연속으로 순환하는 경우가 많다.

시나리오

  1. 사용자가 타이머 화면에 진입한다.
  2. Timer 1, Splits, Timer 2를 입력한다 (예: 105, 2, 15).
  3. 시작 버튼을 누르면 알림 시퀀스가 순환한다.
  4. 매 알림마다 소리·시각 피드백으로 재사용 타이밍을 알려준다.
  5. 필요 시 일시정지·리셋·정지로 제어한다.
  6. 자주 쓰는 설정은 프리셋으로 저장해 재사용한다.

핵심 가치

  • 화면을 계속 보지 않아도 소리로 알림을 받는다.
  • 여러 중간 알림으로 버프 끝나기 전 미리 준비할 수 있다.

2. 타이머 모델

2.1 입력 파라미터

필드 타입 범위 기본값 설명
time1 number (seconds) > 0 105 첫 번째 시간
splits integer ≥ 1 2 time1 등분 개수
time2 number (seconds) ≥ 0 15 두 번째 시간
  • 입력 단위는 초. 소수점 1자리까지 허용.
  • time2 = 0이면 Timer 2 구간 생략.

2.2 알림 시퀀스 생성 규칙

intervals = [time1/splits] × splits  +  [time2]   (time2 > 0)
intervals = [time1/splits] × splits                (time2 = 0)
  • 사이클당 알림 개수: splits + 1 (time2=0이면 splits)
  • 주기: time1 + time2

2.3 예시

time1 splits time2 알림 간격 시퀀스 주기
105 2 15 52.5, 52.5, 15 120s
105 3 15 35, 35, 35, 15 120s
60 1 0 60 60s
120 4 30 30, 30, 30, 30, 30 150s
105 2 0 52.5, 52.5 105s

2.4 알림 누적 시각

t[0] = 0 (시작 시점)
t[k] = t[k-1] + intervals[(k-1) mod len(intervals)]

사용자 예시 (105, 2, 15)의 알림 누적 시각:

52.5s, 105s, 120s, 172.5s, 225s, 240s, 292.5s, 345s, 360s, ...

3. 상태 머신

     ┌─── start ───┐
     ▼             │
   idle ─────→ running ──── pause ───→ paused
     ▲             │                     │
     │             │ reset              resume
     │             │   ▲                 │
     │             ▼   │                 │
     └── stop ── running ◄──────────────┘
상태 설명 가능 액션
idle 초기 상태. 설정 편집 가능 start
running 알림 루프 동작 중 pause, reset, stop
paused 일시정지. 경과 시간 보존 resume, reset, stop
액션 동작
start 현재 설정으로 타이머 시작. idle → running
pause 현재 경과 시간 유지, 알림 루프 중단. running → paused
resume 중단된 지점부터 이어서 진행. paused → running
reset 경과 시간·알림 카운트 초기화. 상태는 유지
stop 모든 상태 초기화. * → idle

4. 화면 설계

4.1 레이아웃

┌──────────────────────────────────────────┐
│  ← 뒤로  |  메이플 재획 타이머  |  테마 ⏻ │  헤더
├──────────────────────────────────────────┤
│  ┌─ 설정 패널 ──────────────────────┐    │
│  │  Timer 1: [  105  ] 초           │    │
│  │  등분:   [   2   ] 회            │    │
│  │  Timer 2: [  15   ] 초           │    │
│  │  미리보기: 52.5s → 52.5s → 15s   │    │
│  │  (주기 120s, 사이클당 3회 알림)   │    │
│  └──────────────────────────────────┘    │
│                                          │
│  ┌─ 실행 뷰 ────────────────────────┐    │
│  │                                  │    │
│  │      00 : 52 . 5                 │    │
│  │   다음 알림까지                   │    │
│  │                                  │    │
│  │  [━━━━━━━━━────────]  60%        │    │
│  │                                  │    │
│  │  3회차 진행 중 · 단계 1/3         │    │
│  └──────────────────────────────────┘    │
│                                          │
│  [▶ 시작]  [⟲ 리셋]  [■ 정지]            │
│                                          │
│  알림 설정                               │
│  ☑ 소리                                  │
│    알림음 [기본 알림     ▼] [▶ 미리듣기]  │
│    볼륨  [━━━━━━──] 70%                  │
│  ☐ 브라우저 알림                         │
│                                          │
│  프리셋                                  │
│  [+ 현재 설정 저장]                      │
│  • 기본 재획 (105/2/15)        [불러오기]│
│  • 빠른 재획 (60/1/0)           [불러오기]│
└──────────────────────────────────────────┘

4.2 설정 패널

  • idle 상태에서만 편집 가능 (running/paused는 비활성화)
  • 숫자 입력 필드 3개 (Timer 1, Splits, Timer 2)
  • 실시간 미리보기: 알림 간격 시퀀스 + 주기 + 사이클당 알림 수
  • 입력값 유효성:
    • Timer 1 > 0
    • Splits ≥ 1 (정수)
    • Timer 2 ≥ 0
    • 최소 알림 간격 1초 이상 (미달 시 경고)

4.3 실행 뷰

  • 카운트다운 (큰 글씨): 다음 알림까지 남은 시간 mm:ss.s
  • 진행률 바: 현재 단계의 경과 비율
  • 사이클 카운트: N회차 진행 중
  • 단계 표시: 단계 k/(splits+1) (또는 "Timer 1 (k/splits)" / "Timer 2")
  • 알림 순간: 카운트다운이 0에 도달하면 피드백 출력 후 다음 단계 시작

4.4 제어 버튼

버튼 상태별 표시
▶ 시작 / ⏸ 일시정지 idle: "시작" / running: "일시정지" / paused: "재개"
⟲ 리셋 항상 활성 (idle에서는 비활성)
■ 정지 idle에서는 비활성

4.5 알림 수단

수단 기본값 동작
소리 ON 공통 사운드 시스템(Shared-Audio)의 mp3 파일 재생. 드롭다운으로 선택, 볼륨 조절, 미리듣기
브라우저 알림 OFF Notifications API. 최초 활성화 시 권한 요청
시각 피드백 ON (항상) 알림 순간 카운트다운 영역 플래시 애니메이션
  • 브라우저 알림 거부 시: 체크박스 자동 해제, 소리만 유지 (에러 메시지 없이 degrade)

소리 선택 UI

설정 패널에 "알림 소리" 드롭다운을 둔다. shared/audio/sounds.ts의 SOUNDS 레지스트리를 목록으로 사용.

알림 소리  [기본 알림       ▼]  [▶ 미리듣기]
볼륨       [━━━━━━──] 70%
  • 선택값(soundId)은 tools:timer:last-config:v1에 저장
  • 저장된 soundId가 레지스트리에 없으면 DEFAULT_ALERT_SOUND_ID로 폴백

4.6 프리셋

항목 내용
저장 "현재 설정 저장" → 이름 입력 모달 → LocalStorage 저장
불러오기 목록에서 클릭 → idle 상태일 때만 입력값 채움
삭제 프리셋 항목 hover 시 ✕ 버튼 노출
제한 최대 10개. 초과 시 가장 오래된 것 자동 삭제

5. 데이터 저장 (LocalStorage)

5.1 키 정의

키 설명
tools:timer:presets:v1 사용자 저장 프리셋 목록
tools:timer:last-config:v1 마지막으로 사용한 설정·알림 옵션

5.2 스키마

// tools:timer:presets:v1
type TimerPresets = TimerPreset[];

interface TimerPreset {
  id: string;           // uuid
  name: string;         // 사용자 입력 이름
  time1: number;        // seconds
  splits: number;       // integer
  time2: number;        // seconds
  createdAt: string;    // ISO8601
}

// tools:timer:last-config:v1
interface LastConfig {
  time1: number;
  splits: number;
  time2: number;
  soundEnabled: boolean;
  soundId: string;              // shared/audio SOUNDS 레지스트리의 id
  soundVolume: number;          // 0.0 ~ 1.0
  notificationEnabled: boolean;
}

5.3 복원 정책

  • 화면 진입 시 last-config를 읽어 설정 패널에 주입
  • 실행 상태(running/paused)는 복원하지 않음 (의도적. 페이지 이탈 시 정지)

6. 기술 구현 노트

6.1 시간 정확도

  • setInterval은 드리프트 발생 → 사용 금지
  • 시작 시각(performance.now())을 기준으로 목표 시각 비교 방식 사용
  • requestAnimationFrame 루프에서 매 프레임 now - startAt 계산
  • 알림은 목표 시각을 지난 첫 프레임에 발생시키고, 다음 목표 시각으로 갱신

6.2 백그라운드 탭

  • requestAnimationFrame은 백그라운드 탭에서 정지 → 복귀 시 경과 시간 계산 보정
  • 대안: 보정 로직으로 누락된 알림을 복귀 시 한꺼번에 fire (구현 단순성 우선)
  • Web Worker 기반 정확 타이머는 v2 검토 항목

6.3 오디오

  • 공통 사운드 시스템(Shared-Audio) 사용 — shared/audio/useSound 훅
  • mp3 파일 재생 (HTMLAudioElement 기반)
  • 첫 사용자 인터랙션(시작 버튼 클릭) 이후 재생 가능 (브라우저 자동재생 정책)
  • 연속 재생 시 currentTime = 0으로 리셋 후 play
  • 미리듣기 버튼은 사용자 클릭 이벤트이므로 언제든 재생 가능

6.4 알림 시퀀스 생성 함수

function buildIntervals(time1: number, splits: number, time2: number): number[] {
  const unit = time1 / splits;
  const first = Array.from({ length: splits }, () => unit);
  return time2 > 0 ? [...first, time2] : first;
}

7. 에지 케이스

케이스 처리
splits = 1 중간 알림 없이 time1 종료 시 1회 알림
time2 = 0 Timer 2 구간 생략, time1만 반복
너무 짧은 간격 (<1s) 설정 저장 시 경고 표시. 그래도 진행은 허용
브라우저 알림 권한 거부 체크박스 해제, 소리 피드백만
탭 백그라운드 복귀 경과 시간 재계산, 누락 알림 1회로 합쳐 fire
페이지 이탈·새로고침 실행 상태 파기. 설정만 복원
LocalStorage 가득참 가장 오래된 프리셋부터 삭제

8. 접근성

  • 키보드: Space = 시작/일시정지, R = 리셋 (옵션)
  • 스크린 리더: 알림마다 aria-live="assertive" 영역에 "3회차 단계 2 알림" 같은 메시지
  • 카운트다운 숫자는 충분히 큰 폰트·고대비
  • 버튼은 아이콘 + 텍스트 병기

9. 디자인 시스템 적용

디자인 시스템의 공통 토큰·컴포넌트를 따른다.

  • 색상·타이포그래피: 토큰으로만 지정 (하드코딩 금지)
  • 브랜드 컬러: --brand (OKLCH 297.5° 보라)
  • 컴포넌트: shadcn/ui (Button, Input, Card, Switch, Slider)
  • 다크모드 지원 필수

10. PWA 상호작용 (향후 검토)

메이플 재획 시나리오는 화면을 보지 않고 소리 알림에 의존하는 대표 유스케이스다. 따라서 백그라운드 동작 보장이 중요하다.

현재 동작 (PWA 미적용)

상황 동작
같은 탭 활성화 중 requestAnimationFrame 정확 동작
다른 탭으로 전환 requestAnimationFrame 일시정지. 복귀 시 경과 시간 보정
브라우저 최소화 위와 동일
폰 화면 꺼짐 동작 보장 안 됨 (Web Audio/HTMLAudio 정지)

PWA 도입 시 검토 항목

wcorn/orino#177 FE: PWA 구성이 구현되면 다음을 재검토:

  • 서비스 워커 기반 정확 타이머: 탭 비활성/화면 꺼짐 상태에서도 시간 측정 유지
  • Web Push API: 알림 시점에 OS 수준 푸시 알림 발송 (폰 화면 꺼져도 수신)
  • Wake Lock API: 타이머 실행 중 화면 꺼짐 방지 옵션 (사용자 토글)
  • Periodic Background Sync: 실험적 API, 긴 타이머용 (브라우저 지원 제한)

기획 결정 필요 시점

PWA 기본 구성(#177) 완료 후, 타이머 실제 사용 중 백그라운드 동작 한계를 체감하면 별도 Issue로 확장 기획.

11. 향후 확장 (v2+)

현재 범위에서 제외하지만 기록:

  • 알림 소리 종류 선택 (여러 톤) — 방식 B 도입 시 해결
  • 음성 카운트 ("3초 전!" 등)
  • 실행 이력 로그 (몇 사이클 돌았는지 누적)
  • BE 동기화 (기기 간 프리셋 공유)
  • 3개 이상의 Timer 단계 지원
  • Wake Lock으로 화면 꺼짐 방지 (PWA 연계)

Clone this wiki locally