88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
# 코딩 컨벤션
|
|
|
|
## 언어
|
|
|
|
- JavaScript (TypeScript 미사용)
|
|
- JSDoc으로 타입 명시
|
|
- Zod로 스키마 검증
|
|
|
|
## 문법
|
|
|
|
- 세미콜론 미사용
|
|
- const/let 사용 (var 미사용)
|
|
- 화살표 함수 우선
|
|
|
|
## 네이밍
|
|
|
|
- Vue 컴포넌트: PascalCase (SiteHeader.vue)
|
|
- 일반 파일/폴더: kebab-case
|
|
- Vue 컴포넌트 파일: PascalCase
|
|
- CSS 클래스: kebab-case
|
|
- 고유 클래스명 필수 (Tailwind 외)
|
|
- Nuxt 컴포넌트 자동 import는 경로 prefix 없이 파일명 기준으로 사용
|
|
|
|
## 스타일
|
|
|
|
- TailwindCSS 기본 사용
|
|
- 다크 인증(`signin`/`signup`/`admin/login`)의 텍스트 입력에는 `auth-form-input` 클래스를 붙여 `main.css`의 글자색·캐럿·placeholder를 적용한다(폼 컨트롤은 부모 `color`를 상속하지 않는 경우가 많음). 모바일 세로 flex 그룹 안의 input에는 `flex-1`을 직접 쓰지 않고, 필요한 경우 `sm:flex-1`처럼 가로 배치 이상에서만 적용한다.
|
|
- 관리자 레이아웃(`admin-layout`)은 공개 사이트 테마와 분리된 라이트 UI로 고정하며, 글쓰기 화면을 제외한 관리자 일반 폼 컨트롤은 `main.css`의 `.admin-layout--light-controls input/textarea/select` 스코프 기준을 따른다.
|
|
- Tailwind 엔트리는 `nuxt.config.js`의 `tailwindcss.cssPath: '~/assets/css/main.css'`로 통일한다(`@nuxtjs/tailwindcss` 기본 `assets/css/tailwind.css` 부재 시 패키지 `tailwind.css`가 중복 주입될 수 있음).
|
|
- 관리자 글 에디터는 Markdown-first textarea 편집을 기준으로 하며 저장 값은 기존 마크다운 문자열을 유지
|
|
- 관리자 미디어 화면에서 모달에 가릴 수 있는 오류·안내는 `useAdminToast`의 `showToast`로 우측 상단(`z-[100]`)에 표시한다.
|
|
- 관리자 메뉴 관리는 상단/하단 탭으로 나누고, 순서는 드래그로 조정한다(상단은 동일 부모의 형제끼리만).
|
|
|
|
```html
|
|
<main class="site-main w-full max-w-full lg:max-w-[720px]">
|
|
```
|
|
|
|
## 문서 (update-log)
|
|
|
|
- `docs/update-log/`는 블로그 방문자용 업데이트 안내 초안이다.
|
|
- v1.1 이후 글은 `안녕하세요.` / `` `sori.studio`입니다. `` 로 시작한 뒤, 버전 요지를 서두에 짧게 적는다. `조금 늦게 정리하는`, `이번 업데이트에서는`, `~한 기록입니다` 같은 표현은 쓰지 않는다.
|
|
- 제목은 `sori.studio vX.Y 업데이트 — {짧은 요약}` 형식을 쓴다. 요약은 한 단어가 아니라, 해당 버전의 핵심이 한눈에 들어오도록 짧은 구(대략 4~10자 내외의 의미 단위)로 적는다.
|
|
- 제목 바로 아래에 해당 minor(`.0`) 릴리스 날짜를 `YYYY년 M월 D일`로 적는다. 날짜는 `docs/update.md`·`docs/history.md`·`package.json` 버전 반영 시점을 기준으로 한다.
|
|
- 서두에 요지를 두므로 하단 `한 줄 요약`은 두지 않는다.
|
|
- 본문 소제목은 `달라진 점`을 기본으로 하고, 방문자가 화면에서 체감하는 변화와 이용상 이점만 적는다. 관리자 전용 절차·내부 구현·배포·검증·수익(광고) 관련 내용은 넣지 않는다.
|
|
- 내부 개선을 적을 때는 처리 과정이 아니라 결과(더 빠름, 더 안정적, 더 안전함 등)로 표현한다.
|
|
|
|
## 주석
|
|
|
|
- JSDoc 형식
|
|
- 한국어 작성
|
|
|
|
```javascript
|
|
/**
|
|
* 게시물 목록 조회
|
|
* @param {Object} options - 조회 옵션
|
|
* @param {number} options.page - 페이지 번호
|
|
* @param {number} options.limit - 페이지당 개수
|
|
* @returns {Promise<Post[]>} 게시물 목록
|
|
*/
|
|
```
|
|
|
|
## 설정
|
|
|
|
- 경로/URL/키값: .env로 관리
|
|
- 하드코딩 금지
|
|
- 로컬 개발 설정과 NAS 운영 설정은 별도 환경 파일로 분리
|
|
- 운영 DB 접속 정보는 개발용 `.env`에 기록하지 않음
|
|
- 운영 환경에서는 `DATABASE_URL`과 `MEMBER_SESSION_SECRET` 누락을 허용하지 않음
|
|
|
|
## 검증
|
|
|
|
- `npm run lint`: JavaScript 파일 문법 점검
|
|
- `npm test`: `npm run test:unit` 별칭
|
|
- `npm run test:unit`: Node 내장 테스트 러너로 `tests/*.test.js` 단위·회귀 테스트 실행
|
|
- `npm run test:api`: Playwright API 통합 테스트 실행
|
|
- `npm run test:e2e`: Playwright Desktop Chrome E2E 테스트 실행
|
|
- `npm run verify`: `lint` → `test:unit` → 프로덕션 `build` 실행
|
|
- `npm run verify:ci`: `lint` → `test:unit` → `test:api` → `test:e2e` → 프로덕션 `build` 실행
|
|
|
|
### 통합 테스트 격리
|
|
|
|
- API/E2E 테스트는 `scripts/run-playwright-tests.js`를 통해 실행하며 `playwright test`를 직접 실행해 개발 DB나 일반 업로드 경로를 사용하지 않는다.
|
|
- 테스트 DB 이름은 반드시 `_test`로 끝나야 하며 `docker-compose.test.yml`의 별도 PostgreSQL 컨테이너·일회성 볼륨만 사용한다.
|
|
- 테스트 업로드는 `PLAYWRIGHT_TEST=1`과 `SORI_TEST_UPLOAD_ROOT`가 지정한 시스템 임시 디렉터리만 사용하고 종료 시 정리한다.
|
|
- DB 상태를 공유하는 통합 시나리오는 Playwright worker 1개와 serial 모드를 유지한다.
|
|
- 테스트 중 비결정적 백그라운드 변경을 막기 위해 Export worker와 추천 사이트 파비콘 cron을 비활성화한다.
|