tier-maker/docs/convention.md

코딩 컨벤션

공통

• 문서와 사용자 응답은 한국어로 작성한다.
• JavaScript는 세미콜론 없이 현재 코드 스타일을 유지한다.
• 새 주석이 필요할 경우 JSDoc 형식을 사용한다.
• 경로, 주소, 운영 설정은 하드코딩보다 환경변수 기반 구성을 우선한다.
• Git 커밋 메시지는 한국어로 작성한다.
• 버전 릴리스가 포함된 작업은 docs/update.md의 버전 표기와 Git 태그를 함께 맞춘다.
• Git 푸시 전에는 민감 정보(실명, 개인 이메일, 비밀키, 로컬 절대 경로) 포함 여부를 다시 확인한다.

프런트엔드

• API 호출은 frontend/src/lib/api.js 또는 런타임 유틸을 통해 통합한다.
• 정적 파일 URL 조합은 toApiUrl()로 처리한다.
• 화면 상태는 ref, computed, onMounted 중심의 단순한 Composition API 패턴을 유지한다.
• 설정/계정처럼 자주 바꾸지 않는 정보는 상시 입력 폼보다 현재 상태 요약 + 필요 시 모달 편집 흐름을 우선한다.
• 모달이 배경 화면 위에 떠 있고 모달 내부 선택이 주 작업인 경우, 열림 상태 동안 body 스크롤 잠금을 함께 적용해 뒤쪽 화면 위치가 바뀌지 않게 한다.
• 정렬 가능한 카드 목록을 버튼으로도 재정렬할 때는 즉시 재렌더링으로 깜빡이게 두지 않고, TransitionGroup move 전환 등으로 위치 이동을 부드럽게 표현한다.

백엔드

• 라우트 검증은 zod로 처리한다.
• 파일 업로드명은 ASCII 안전 문자열을 사용한다.
• 인증/권한 분기는 미들웨어(requireAuth, requireAdmin)로 분리한다.
• DB 저장 전에는 배포 환경에 종속되는 값(예: 로컬 절대 URL)이 들어가지 않도록 정규화한다.
• 사용자 프로필처럼 “선택 후 저장” 흐름이 필요한 기능은 파일 선택과 실제 저장 요청을 분리한다.
• 관리자 지정 데이터와 사용자 커스텀 데이터는 테이블과 업로드 경로를 분리해서 관리한다.