프로젝트 문서 체계 정비

docs/convention.md

@@ -1,46 +1,66 @@
-# 코딩 컨벤션
+# 프로젝트 컨벤션
 
-## 기본 원칙
-- 모든 문서와 커뮤니케이션은 한국어 기준으로 유지한다.
-- 코드 주석은 필요 시 `JSDoc` 형식을 우선한다.
-- 기존 정적 사이트 구조를 존중하고, 대규모 구조 변경 시에는 먼저 `docs/history.md`에 의사결정을 기록한다.
+## 공통
 
-## 파일 및 폴더 규칙
-- 시리즈 데이터 파일은 `datas/uaXX.js`, `datas/uapr.js`처럼 시리즈 키와 일치하게 관리한다.
-- 이미지 폴더는 `images/<seriesKey>/` 규칙을 유지한다.
-- 새 문서는 `docs/` 하위에서 목적별 단일 파일에 누적 관리한다.
+- 모든 문서와 커뮤니케이션은 한국어로 작성한다.
+- 실제 코드와 문서가 다르면 코드를 기준으로 문서를 갱신한다.
+- 요청 범위를 넘는 대규모 리팩터링을 하지 않는다.
+- 운영 URL, 비밀번호, 토큰, DB 정보는 코드에 하드코딩하지 않는다.
+- JavaScript 함수와 클래스에는 필요한 JSDoc을 작성한다.
 
-## JavaScript 규칙
-- 기존 코드 스타일에 맞춰 기본 들여쓰기는 4칸을 사용한다.
-- 상수는 `const`, 재할당 변수는 `let`을 사용한다.
-- DOM 참조가 반복될 경우 `getEl()`처럼 묶어서 관리하는 패턴을 우선 고려한다.
-- URL 파라미터, `localStorage`, 동적 import는 예외 처리와 함께 사용한다.
-- 카드 데이터 객체의 필드명은 기존 호환성을 위해 현재 형태(`imgSrc`, `Number`, `count`, `key`)를 유지한다.
+## 버전
 
-## HTML 규칙
-- 정적 페이지는 의미 단위별로 `header`, `main`, `aside` 등을 우선 사용한다.
-- 페이지별 스크립트가 길어질 경우 신규 기능은 별도 JS 파일 분리 여부를 먼저 검토한다.
-- 인라인 이벤트(`onclick`)는 기존 파일에 이미 존재하므로 즉시 제거 대상은 아니지만, 신규 대형 기능은 `addEventListener` 방식 우선 검토한다.
-
-## CSS 규칙
-- 공통 UI는 가능한 한 Tailwind 유틸리티 클래스를 우선 사용한다.
-- **헤더 로고**는 `style/brand.css`의 `.app-brand-logo` + `--brand-logo-height`(32px)만 사용한다. 페이지마다 `h-8` 등 Tailwind로 크기를 주지 않는다.
-- `style/output.css`는 **빌드 산출물**이다. HTML 등에 새 Tailwind 클래스를 추가한 뒤 `npm run build:css`로 재생성한다.
-- `style/output.css`에 포함되지 않은 유틸리티 클래스는 적용되지 않으므로, 빌드 전까지는 페이지 특화 스타일을 인라인 `<style>` 또는 전용 CSS 파일(`style/auth-pages.css` 등)에 명시한다.
-- 페이지 특화 보정 스타일만 인라인 `<style>` 또는 전용 CSS 파일에 둔다.
-- 캡처 안정성처럼 이유가 분명한 예외 스타일은 주석으로 목적을 남긴다.
-
-## 데이터 관리 규칙
-- 카드 데이터 추가 시 최소 필드는 `imgSrc`, `Number`, `count`, `key`, `color`, `parallel`, `rarity`, `trigger`를 맞춘다.
-- 동일 카드의 패러렐 판본은 동일 `Number`를 유지하고 `parallel` 값으로 구분한다.
-- 파일명 변경 시 `datas/*.js`와 `images/<seriesKey>/`가 함께 일치하는지 확인한다.
-
-## Git 규칙
+- 현재 버전은 프로젝트 루트 `VERSION`을 기준으로 한다.
+- 커밋을 포함하는 완료 작업은 버전을 증가시키고 `VERSION`, `docs/update.md`, 필요 시 `docs/changelog.md`를 함께 갱신한다.
 - 커밋 메시지는 한국어로 작성한다.
-- 버전 상승 작업은 `docs/update.md` 반영 후 태그명과 맞춘다.
-- 민감 정보, 로컬 경로, 개인 식별 정보가 커밋되지 않도록 확인한다.
 
-## 이미지 자산 규칙
-- `images/**`는 `Git LFS`로 관리한다.
-- 이미지 파일을 새로 추가하거나 교체할 때는 일반 Git 객체로 들어가지 않도록 `.gitattributes` 설정을 유지한다.
-- 대량 이미지 추가 전에는 원격 저장소의 LFS 정책과 비용 한도를 확인한다.
+## 카드 데이터
+
+- 시리즈 파일은 `datas/uaXX.js` 또는 `datas/uapr.js` 형식을 사용한다.
+- 카드 객체의 호환 필드 `imgSrc`, `Number`, `count`, `key` 이름은 변경하지 않는다.
+- 동일 카드의 패러렐 판본은 같은 `Number`를 사용하고 `parallel`로 구분한다.
+- 신규 시리즈는 데이터, 이미지, 한국어·일본어·영어 번역을 한 작업 단위로 검증한다.
+- 이미지 파일명 변경 시 관련 `datas/*.js`의 `imgSrc`도 함께 갱신한다.
+
+## 프론트
+
+- 현재 정적 HTML/JavaScript 구조를 유지한다.
+- 신규 대형 기능은 페이지 인라인 스크립트보다 `script/` 모듈 분리를 우선 검토한다.
+- URL 파라미터, 동적 import, `localStorage` 접근에는 실패 처리를 둔다.
+- 기존 인라인 이벤트는 즉시 전면 교체하지 않으며 신규 기능은 `addEventListener`를 우선한다.
+
+## 스타일
+
+- 현재 CSS를 Tailwind로 일괄 전환하지 않는다.
+- 새 단순 스타일은 Tailwind 유틸리티를 우선 검토하되 기존 페이지 패턴과 빌드 여부를 함께 확인한다.
+- 반복되는 공통 스타일은 공통 CSS 또는 컴포넌트 역할의 클래스로 분리한다.
+- `style/output.css`를 직접 편집하지 않고 `npm run build:css`로 생성한다.
+- 헤더 로고는 `style/brand.css`의 `.app-brand-logo`만 사용한다.
+- 다크모드와 Pretendard 계열 기본 글꼴을 고려한다.
+
+## API·DB
+
+- API 베이스 경로는 `/api/v1`을 유지한다.
+- 운영 설정은 `.env`로 관리하며 `.env.example`에는 예시값만 둔다.
+- 로컬 DB와 운영 DB를 같은 파일 또는 볼륨으로 공유하지 않는다.
+- DB에는 최소 카드 정보만 저장하고 카드 메타는 `datas/`에서 합성한다.
+- 권한 검사는 화면뿐 아니라 API에서도 수행한다.
+
+## 이미지·Git
+
+- `images/**`는 Git LFS로 관리한다.
+- `api/data/`의 DB, 아바타, 덱 미리보기는 커밋하지 않는다.
+- 대량 이미지 추가 전 변경 수와 LFS 추적 여부를 확인한다.
+- 민감 정보와 개인 로컬 경로가 diff에 포함되지 않았는지 확인한다.
+
+## 문서
+
+- `spec.md`: 현재 구현 상태
+- `update.md`: 개발자 작업 로그
+- `history.md`: 유지할 의사결정과 이유
+- `todo.md`: 미완료 작업만
+- `deploy.md`: 실행·배포·롤백
+- `widget.md`: 외부 서비스 연동
+- `map.md`: 파일과 기능 연결
+- `changelog.md`: 사용자 공개 변경사항
+- `convention.md`: 반복 적용 규칙