# 코딩 컨벤션

## 공통
- 시작 버전은 `v0.0.1`이다.
- 문서와 사용자 응답은 한국어로 작성한다.
- 작업 보고, 릴리스 메모, 주요 문서 업데이트에는 항상 버전명을 함께 표시한다.
- `docs/update.md`는 짧은 항목형으로 작성한다.
- `docs/update.md`는 서술형 문장보다 `~추가.`, `~수정.`, `~정리.`, `~진행.` 형식을 우선 사용한다.
- `docs/update.md`는 날짜가 아니라 버전 기준 섹션으로 구분한다.
- `docs/update.md`는 가장 최신 버전 섹션이 항상 맨 위에 오도록 유지한다.
- `docs/history.md`는 이유를 포함한 서술형 기록을 허용한다.
- `docs/history.md`는 가장 최신 항목이 항상 맨 위에 오도록 유지한다.
- `docs/history.md` 제목에는 날짜와 버전을 함께 적는다.
- JavaScript는 세미콜론 없이 현재 코드 스타일을 유지한다.
- 새 주석이 필요할 경우 JSDoc 형식을 사용한다.
- 경로, 주소, 운영 설정은 하드코딩보다 환경변수 기반 구성을 우선한다.
- 사이트 전역 기본 폰트는 항상 `Pretendard`를 우선 사용한다.
- Git 커밋 메시지는 한국어로 작성한다.
- 로컬 Git 작성자 정보는 항상 `zenn` / `zenn.message@gmail.com` 조합을 사용한다.
- 버전 릴리스가 포함된 작업은 `docs/update.md`의 버전 표기와 Git 태그를 함께 맞춘다.
- Git 푸시 전에는 민감 정보(실명, 개인 이메일, 비밀키, 로컬 절대 경로) 포함 여부를 다시 확인한다.
- 작업이 끝난 뒤에는 문서 업데이트까지 포함한 변경사항을 커밋하고 원격 저장소에 푸시한다.

### Git 업로드 양식
- 작성자 정보 확인: `git config user.name` / `git config user.email`
- 작성자 정보 고정: `git config user.name "zenn"` / `git config user.email "zenn.message@gmail.com"`
- 작업 확인: `git status`
- 변경 스테이징: `git add -A`
- 커밋: `git commit -m "작업 목적을 한 줄로 설명하는 한국어 메시지"`
- 원격 푸시: `git push origin main`
- 푸시 후 확인: `git status`, `git log -1 --oneline`

### Git 커밋 메시지 규칙
- 한국어 한 줄 요약으로 작성한다.
- 가능하면 `영역: 변경 내용` 형식을 사용한다.
- 예시: `docs: Git 업로드 규칙 정리`
- 예시: `app: 기본 Vite 레이아웃 초기 구현`

### 버전 표기 규칙
- 작업이 끝나 커밋할 때마다 버전을 증가시킨다.
- 새 기능 시작, 구조 변경, 배포 준비, 작업 결과 보고 시 현재 버전을 함께 적는다.
- 형식은 항상 `v0.0.1`처럼 `v` 접두사를 포함한다.
- 버전이 변경되면 `docs/update.md`, `docs/spec.md`, `docs/history.md`, `docs/deploy.md`에 함께 반영한다.

---

## 수정 범위 규칙
- 요청된 기능과 직접 관련 없는 코드는 수정하지 않는다.
- 기존에 정상 동작하는 로직은 리팩토링하지 않는다.
- 스타일 변경만으로 해결 가능한 경우 로직 수정 금지.
- 기존 API 구조를 임의로 변경하지 않는다.

---

## 환경 변수 및 설정 규칙
- API 주소, 파일 경로, 외부 서비스 URL은 반드시 환경변수로 관리한다.
- 코드 내에 직접 문자열로 작성하지 않는다.
- 예외적으로 테스트용 임시 값은 주석으로 명시한다.

---

## 로그 및 디버깅 규칙
- console.log는 디버깅 용도로만 사용한다.
- 작업 완료 시 불필요한 로그는 반드시 제거한다.
- 운영 환경에 영향을 줄 수 있는 로그는 추가하지 않는다.

---

## 프런트엔드

### 기본 구조
- API 호출은 `src/lib/pocketBase.js` 및 관련 composable을 통해 통합한다.
- 정적 파일 URL 조합은 `toApiUrl()`로 처리한다.
- 화면 상태는 `ref`, `computed`, `onMounted` 중심의 단순한 Composition API 패턴을 유지한다.

### UI/UX 패턴
- 설정/계정과 같이 자주 변경되지 않는 정보는 `현재 상태 요약 + 필요 시 모달 편집` 구조를 우선한다.
- 모달이 활성화된 동안에는 `body` 스크롤 잠금을 적용한다.
- 배경 화면이 움직이지 않도록 한다.
- 정렬 가능한 리스트는 즉시 재렌더링으로 깜빡이지 않도록 한다.
- `TransitionGroup` 등을 사용해 이동 애니메이션을 적용한다.

### 스타일 (Tailwind + 구조 클래스)
- 기본 스타일링은 Tailwind CSS를 사용한다.
- Tailwind 유틸리티 클래스만으로 구조를 구성하지 않는다.
- 주요 영역에는 반드시 의미 있는 고유 클래스명을 함께 작성한다.
- 고유 클래스명은 개발자 도구에서 구조를 빠르게 파악하기 위한 용도로 사용한다.
- 클래스명은 컴포넌트 또는 역할 기준으로 명확하게 작성한다.
- 임시 이름 사용을 금지한다.

---

## 백엔드

### 기본 규칙
- 라우트 검증은 `zod`로 처리한다.
- 인증/권한 분기는 PocketBase 세션·가드(`requireAuth` 등)로 분리한다.

### 데이터 처리
- DB 저장 전 배포 환경에 종속되는 값(예: 로컬 절대 URL)을 제거하거나 정규화한다.
- 사용자 입력 데이터는 반드시 검증 후 저장한다.

### 파일 업로드
- 업로드 파일명은 ASCII 안전 문자열을 사용한다.
- 관리자 데이터와 사용자 데이터는 업로드 경로를 분리한다.

### 기능 흐름
- 사용자 프로필과 같이 “선택 후 저장” 흐름이 필요한 기능은
  파일 선택과 실제 저장 요청을 분리한다.

---

## 네이밍 규칙
- 변수명, 함수명, 클래스명은 의미가 명확하게 드러나야 한다.
- 축약어 남용을 금지한다.
- 임시 이름(`temp`, `data2`, `testFn`, `aaa`) 사용을 금지한다.
- 컴포넌트 이름은 역할 기반으로 작성한다.

---

## 파일 및 구조 규칙
- 파일 생성은 최소화한다.
- 기존 파일에서 해결 가능한지 먼저 검토한다.
- 사용하지 않는 코드(import, 함수, 스타일)는 반드시 제거한다.
- 파일은 하나의 책임을 가지도록 유지한다.

---

## 주석 규칙
- 주석은 필요한 경우에만 작성한다.
- 함수, 복잡한 로직에는 JSDoc 형식을 사용한다.
- 코드로 설명 가능한 내용은 주석으로 반복하지 않는다.
- 오래되면 잘못될 수 있는 주석은 작성하지 않는다.

---

## 검증 규칙
- 가능한 범위에서 기능 검증을 수행한다.
- 주요 사용자 흐름을 확인한다.
- 에러 발생 가능성이 있는 조건(null, undefined, 실패 응답 등)을 점검한다.
- 검증을 수행하지 못한 경우 그 사유를 명확히 남긴다.