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: 반복 적용 규칙