uniare.sori.studio/docs/convention.md

# 프로젝트 컨벤션

## 공통

- 모든 문서와 커뮤니케이션은 한국어로 작성한다.
- 실제 코드와 문서가 다르면 코드를 기준으로 문서를 갱신한다.
- 요청 범위를 넘는 대규모 리팩터링을 하지 않는다.
- 운영 URL, 비밀번호, 토큰, DB 정보는 코드에 하드코딩하지 않는다.
- JavaScript 함수와 클래스에는 필요한 JSDoc을 작성한다.

## 버전

- 현재 버전은 프로젝트 루트 `VERSION`을 기준으로 한다.
- 커밋을 포함하는 완료 작업은 버전을 증가시키고 `VERSION`, `docs/update.md`, 필요 시 `docs/changelog.md`를 함께 갱신한다.
- 커밋 메시지는 한국어로 작성한다.

## 카드 데이터

- 시리즈 파일은 `datas/uaXX.js` 또는 `datas/uapr.js` 형식을 사용한다.
- 카드 객체의 호환 필드 `imgSrc`, `Number`, `count`, `key` 이름은 변경하지 않는다.
- 동일 카드의 패러렐 판본은 같은 `Number`를 사용하고 `parallel`로 구분한다.
- 신규 시리즈는 데이터, 이미지, 한국어·일본어·영어 번역을 한 작업 단위로 검증한다.
- 이미지 파일명 변경 시 관련 `datas/*.js`의 `imgSrc`도 함께 갱신한다.

## 프론트

- 현재 정적 HTML/JavaScript 구조를 유지한다.
- 신규 대형 기능은 페이지 인라인 스크립트보다 `script/` 모듈 분리를 우선 검토한다.
- URL 파라미터, 동적 import, `localStorage` 접근에는 실패 처리를 둔다.
- 기존 인라인 이벤트는 즉시 전면 교체하지 않으며 신규 기능은 `addEventListener`를 우선한다.

## 스타일

- 기존 CSS는 `todo.md`의 화면별 순서에 따라 한 화면씩 Tailwind로 전환한다.
- 새 단순 스타일은 Tailwind 유틸리티를 우선 검토하되 기존 페이지 패턴과 빌드 여부를 함께 확인한다.
- 반복되는 공통 스타일은 공통 CSS 또는 컴포넌트 역할의 클래스로 분리한다.
- `style/output.css`를 직접 편집하지 않고 `npm run build:css`로 생성한다.
- Tailwind 스캔 대상은 `style/input.css`의 `@source`로 지정한다. HTML·JS 전환 후에는 반드시 CSS를 재빌드한다.
- 공통 UI(앱 셸·덱 카드·프로필·인증 헤더)는 `style/components.css`의 `@layer components`에 두고 `input.css`에서 import한다.
- 각 HTML 페이지는 `style/output.css`만 로드한다(`brand.css`는 빌드에 포함).
- 다크모드와 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`: 반복 적용 규칙