MuseReview Web

UMC 10th Project

🎵 MuseReview : 내 연주의 이유를 찾는 가장 쉬운 방법

“Muse + Review” : 뮤즈(영감)를 리뷰하다.

📌 MuseReview는 이런 서비스예요

나의 연주 습관과 화성학적 의도를 정밀 분석하여, 독학 중에도 레슨을 받는 듯한 성장을 경험하게 돕는 AI 음악 멘토링 플랫폼

🔥 스스로 분석하는 힘 기르기

"내가 방금 이 음을 쳤지?"라는 물음에 AI가 화성학적 답변을 들려주는 과정

무심코 연주한 음들의 의미를 깨닫게 되면, 자신의 연주를 객관적으로 바라보는 눈이 생기고 스스로를 가르칠 수 있는 ‘자생력’이 생깁니다.

🔥 성장의 빈틈과 부족함 채우기

혼자 연습하거나 레슨을 받을 때 놓치기 쉬운 ‘내가 모르는 나의 단점’을 정확히 찾아내는 단계

단순히 ‘연습하세요’가 아니라, 무엇이 부족한지 인지시키고 그것을 채울 수 있는 명확한 학습 지도(Roadmap)를 제시하여 연습의 효율을 극대화합니다.

🔥 즉흥 연주의 문턱 낮추기

즉흥 연주를 ‘천재들의 전유물’이 아니라, 누구나 도전하고 즐길 수 있는 ‘놀이’로 만드는 최종 목표

자신의 소리를 이해하고 부족함을 채워가는 작은 성공 경험들이 쌓여, 막연한 두려움을 자신감으로 바꿔줍니다.

🙋🏻‍♀️ MuseReview의 FE Developer를 소개합니다!

김나윤	배서윤	안다현	이민서

💻 기술 스택

역할	종류	선정 이유
Library		컴포넌트 기반 구조로 재사용성과 유지보수성이 높아 개발 효율을 극대화 가능
Programming Language		정적 타입을 제공하여 코드의 안정성과 가독성을 높이고, 개발 중 오류를 사전에 방지할 수 있어 유지보수에 유리
Styling		유틸리티 클래스 기반의 스타일링으로 반복되는 CSS 코드 작성을 줄이고, 빠르고 일관된 UI 구현 가능
Data Fetching		직관적인 API 사용법과 자동 JSON 변환 기능으로 비동기 통신이 간편
State Management		서버 상태는 TanStack Query의 캐싱과 동기화 기능을 통해 효율적으로 관리하고, 전역 상태는 Zustand를 활용해 최소한의 보일러플레이트로 관리 가능
Form		최소한의 리렌더링으로 폼 상태를 관리하고, 유효성 검사를 간편하게 처리 가능
Music / Audio		Web Audio 기반 피아노 사운드·메트로놈 재생과 MusicXML 악보 렌더링 · 커서 싱크를 구현하기 위해 사용
Markdown		AI 분석 리포트와 이론 학습 콘텐츠를 마크다운 그대로 안전하게 렌더링 가능
Icon		일관된 스타일의 아이콘을 트리셰이킹 가능한 컴포넌트 형태로 제공
Routing		SPA에 최적화된 라우팅 기능 제공, 선언적 방식으로 라우트를 쉽게 구성 가능
Formatting		코드 스타일을 통일하고 잠재적인 오류를 사전에 방지하여 협업 시 효율성을 높임
Git Hooks		커밋 전 staged 파일에만 lint · format을 자동 적용해 컨벤션에 어긋난 코드가 올라가는 것을 방지
Code Review		PR마다 AI 기반 자동 코드 리뷰로 일관된 코드 품질 유지
Package Manager		Node 기본 패키지 매니저로 별도 설치 없이 안정적으로 의존성 관리 가능
Deployment		Git 연동 기반의 자동 배포, 프론트엔드 프로젝트에 최적화된 환경 제공으로 빠른 개발 및 배포 사이클 지원
Bundler		빠른 서버 시작과 모듈 번들링 성능으로 개발 생산성을 향상

🧩 Package Manager

• Node 버전

  • v22.20.0

• npm 명령어 예시

npm install            # 전체 설치
npm install 라이브러리   # 라이브러리 설치
npm run dev            # 개발 서버 실행
npm run build          # 타입 체크 + 프로덕션 빌드
npm run preview        # 빌드 결과 로컬 미리보기
npm run lint           # ESLint 검사
npm run stylelint      # 스타일 린트 검사
npm run format         # Prettier 포맷팅
npm run format:check   # 포맷 검사만 수행

🎹 시연 준비

MuseReview는 Web MIDI API로 건반 입력을 받습니다.

항목	내용
브라우저	Chrome 또는 Edge (Safari · Firefox는 Web MIDI 미지원)
권한	최초 접속 시 MIDI 기기 접근 허용 팝업에서 "허용"
기기 선택	설정 → MIDI 기기에서 사용할 기기를 클릭해 선택
레이턴시	연주 시작 전 레이턴시 체크 실행

• 전자 피아노 — USB 케이블로 연결 후 전원을 켜면 자동 인식됩니다. 앱이 자체 사운드를 재생하므로 소리가 겹치면 피아노 볼륨을 줄여 주세요.
• 전자 피아노가 없다면 — 가상 MIDI 건반으로 시연할 수 있습니다 → 가상 건반 시연 가이드

🔗 Git Convention

📌 Git Flow

  develop ← 작업 브랜치

• main branch : 배포 브랜치

• develop branch : 개발 브랜치, feature 브랜치가 merge됨

• feature / chore / refactor branch : 개발 브랜치

  
  

✨ Flow

• 이슈 생성

• 이슈 번호에 맞게 develop 브랜치에서 새로운 브랜치 생성

• 작업 완료 후 커밋 컨벤션에 맞게 커밋

• PR 생성

• 코드 리뷰 후 develop 브랜치로 병합

  • 최소 1명 승인 후 develop 브랜치로 머지
  
  

🌿 Branch Naming Convention

• 구조: 브랜치종류/#이슈번호-기능설명
• 구분자: 하이픈(-) 사용

Prefix	설명
init	초기 프로젝트 세팅
feat	새로운 기능 추가
fix	버그 수정
docs	문서 변경
style	UI 수정
refactor	코드 리팩토링
test	테스트 코드 관련
chore	설정 파일 변경
hotfix	긴급한 버그 수정
deploy	배포 관련 작업

🔥 Commit Message Convention

• 구조: prefix: 상세설명 (#이슈번호)
• 예시
  • init: 프로젝트 초기 세팅 (#1)
  • feat: 로그인 페이지 개발 (#2)

Prefix	설명
init	초기 프로젝트 세팅
feat	새로운 기능 추가
fix	버그 수정
docs	문서 변경
style	UI 수정
refactor	코드 리팩토링
test	테스트 코드 관련
chore	설정 파일 변경
hotfix	긴급한 버그 수정
deploy	배포 관련 작업

📂 프로젝트 구조

📦 MuseReview
┣ 📂 .github                    # 이슈 · PR 템플릿
┣ 📂 .husky                     # 커밋 훅 (lint-staged)
┣ 📂 public                     # 폰트 · 사운드 · 샘플 MusicXML
┣ 📂 src
┃ ┣ 📂 apis                     # axios 인스턴스, 도메인별 API 함수
┃ ┣ 📂 assets                   # 도메인별 정적 에셋
┃ ┣ 📂 components               # 재사용 컴포넌트 (common / history / learn / main / mentor / metronome / piano / practice / score / settings)
┃ ┣ 📂 constants                # 도메인 상수
┃ ┣ 📂 hooks                    # 커스텀 훅 (MIDI · 메트로놈 · 악보 싱크 · 서버 상태)
┃ ┣ 📂 layout                   # 공통 레이아웃
┃ ┣ 📂 pages                    # 도메인별 라우팅 페이지
┃ ┃ ┣ 📂 admin                  # ⚠️ MVP 제외 — 관리자 (대시보드 / 마이페이지 / 수강생 / 강사 / 트랙)
┃ ┃ ┣ 📂 auth                   # 로그인 · 소셜 로그인 콜백
┃ ┃ ┣ 📂 common                 # 공통 페이지 (로딩 / 404)
┃ ┃ ┣ 📂 history                # 기록
┃ ┃ ┣ 📂 landing                # 랜딩 · 인트로
┃ ┃ ┣ 📂 latency                # 레이턴시 측정
┃ ┃ ┣ 📂 learn                  # 학습 (커리큘럼 / 단계학습 / 이론 / 점수)
┃ ┃ ┣ 📂 main                   # 메인 대시보드
┃ ┃ ┣ 📂 onboarding             # 온보딩 (약관 / 역할 / 플랜 / 프로필 설정)
┃ ┃ ┣ 📂 practice               # 연습 (생성 / 상세 / 편집 / 플레이 / 분석)
┃ ┃ ┗ 📂 profile                # 프로필
┃ ┣ 📂 routes                   # 라우팅 정의
┃ ┣ 📂 stores                   # Zustand 전역 상태
┃ ┣ 📂 types                    # TypeScript 타입
┃ ┗ 📂 utils                    # 전역 유틸
┗ 📜 설정 파일                   # .coderabbit.yaml, .prettierrc, .stylelintrc, eslint.config.js, tsconfig.*, vite.config.ts, vercel.json

⚠️ src/pages/admin(및 /admin 라우트)은 MVP 범위에서 제외된 기능입니다.