Skip to content

Tools Module

wcorn edited this page Apr 5, 2026 · 2 revisions

Tools 모듈

독립적인 미니 도구를 모아놓은 유틸리티 모듈. 기능 추가가 지속적으로 이루어진다.

1. 개요

목적

학습·게임·업무 보조용 간단한 도구를 한 곳에서 제공한다. 각 도구는 단일 목적이며, 도구 간 데이터 공유가 없다.

특성

  • 독립성: 각 도구는 완전히 독립. 다른 도구에 의존하지 않는다.
  • 간결성: 각 도구는 한 화면에서 완결된다.
  • 확장성: 새 도구 추가 시 라우트·컴포넌트 등록만으로 완료된다.
  • FE only (현재): 설정은 LocalStorage에만 저장한다. BE API 없음.
    • 추후 필요 시 BE 동기화 도입 가능 (기기 간 설정 공유 등)

비기능 요구사항

  • 로그인 사용자만 접근 가능 (PrivateRoute)
  • 반응형 레이아웃 (모바일/데스크탑)
  • 다크모드 지원 (디자인 시스템 따름)

2. 네비게이션

/home (메인 대시보드)
  │
  ├── /tools (Tools 대시보드)
  │    ├── /tools/timer (메이플 재획 타이머)
  │    └── /tools/{future-tool}
  │
  └── /planner (Study Planner)
       └── ...

진입 흐름

  1. 로그인 → /home (메인 대시보드)
  2. /home의 Tools 카드 클릭 → /tools
  3. Tools 대시보드에서 도구 선택 → /tools/{tool-name}

뒤로가기 규칙

  • 도구 상세(/tools/{tool}) → Tools 대시보드(/tools) 로 복귀
  • Tools 대시보드(/tools) → 메인 대시보드(/home) 로 복귀

3. 폴더 구조

FE-Architecture의 feature-based 구조를 따른다.

fe/src/
├── features/tools/
│   ├── components/
│   │   └── ToolCard.tsx           # Tools 대시보드 카드 컴포넌트
│   ├── types/
│   │   └── tool.ts                # Tool 메타 타입
│   ├── registry.ts                # 도구 목록 레지스트리 (확장 포인트)
│   │
│   ├── timer/                     # 도구별 하위 디렉토리
│   │   ├── components/
│   │   ├── hooks/
│   │   └── types/
│   └── {future-tool}/
│
└── pages/
    ├── ToolsPage.tsx              # /tools
    └── tools/
        └── TimerPage.tsx          # /tools/timer

도구 레지스트리 (features/tools/registry.ts)

Tools 대시보드에 표시될 도구 메타 정보를 한 곳에서 관리한다.

interface ToolMeta {
  id: string;              // "timer"
  name: string;            // "메이플 재획 타이머"
  description: string;     // 한 줄 설명
  path: string;            // "/tools/timer"
  icon: LucideIcon;        // 아이콘 컴포넌트
  status: "available" | "coming-soon";
}

export const TOOLS: ToolMeta[] = [
  {
    id: "timer",
    name: "메이플 재획 타이머",
    description: "2단계 주기 알림 타이머. 버프 쿨타임 관리용",
    path: "/tools/timer",
    icon: Timer,
    status: "available",
  },
];

4. Tools 대시보드 (/tools)

레이아웃

  • 상단 헤더: 오리노 로고, 뒤로가기(→ /home), 테마 토글, 로그아웃
  • 페이지 제목: "Tools"
  • 본문: 도구 카드 그리드 (반응형: 모바일 1열 / 태블릿 2열 / 데스크탑 3열)

도구 카드 구성

┌────────────────────────────┐
│ [아이콘]                   │
│                            │
│ 도구명                     │
│ 한 줄 설명                 │
└────────────────────────────┘
  • 클릭 시 해당 도구 경로로 이동
  • coming-soon 상태는 disabled 표시

5. 신규 도구 추가 절차

  1. features/tools/{tool-name}/ 디렉토리 생성
  2. 타입·훅·컴포넌트 작성
  3. pages/tools/{ToolName}Page.tsx 생성
  4. app/router.tsx에 라우트 추가
  5. features/tools/registry.ts TOOLS 배열에 메타 등록
  6. Tools 대시보드에서 자동으로 카드 노출

6. 데이터 저장

LocalStorage 키 네이밍

tools:{tool-id}:{field}:v{version}
  • 예: tools:timer:presets:v1, tools:timer:last-config:v1

버전 관리

  • 스키마 변경 시 버전 suffix 증가
  • 이전 버전 키 제거 정책은 각 도구에서 정의

저장 대상 판단 기준

  • 사용자가 재사용할 가능성이 있는 설정 → 저장
  • 단발성 상태(타이머 실행 상태, 일시적 UI 상태) → 저장하지 않음

7. 공통 훅·유틸

features/tools/ 에 둔다.

이름 용도
useLocalStorage<T> 타입 안전한 LocalStorage 훅 (이미 shared/에 있으면 재사용)
playBeep Web Audio API 기반 비프음 재생 유틸
requestNotificationPermission 브라우저 알림 권한 요청 헬퍼

8. 테스트 전략

Test-Strategy 기준을 따른다.

  • 통합 테스트 (중심): 도구 화면 진입부터 기능 동작까지 RTL + MSW 없이 순수 통합
  • 단위 테스트: 시간 계산·알림 시퀀스 생성 등 순수 로직만 선별적으로
  • E2E: Tools 대시보드 → 도구 진입 플로우 (Playwright)

9. 도구 목록

도구 경로 상태 문서
메이플 재획 타이머 /tools/timer 기획 완료 Tools-Timer

Clone this wiki locally