3.2 KiB
3.2 KiB
프로젝트 컨벤션
공통
- 모든 문서와 커뮤니케이션은 한국어로 작성한다.
- 실제 코드와 문서가 다르면 코드를 기준으로 문서를 갱신한다.
- 요청 범위를 넘는 대규모 리팩터링을 하지 않는다.
- 운영 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로 생성한다.- 헤더 로고는
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: 반복 적용 규칙