코딩 컨벤션

언어

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])에 표시한다.
관리자 메뉴 관리는 상단/하단 탭으로 나누고, 순서는 드래그로 조정한다(상단은 동일 부모의 형제끼리만).

<main class="site-main w-full max-w-full lg:max-w-[720px]">

운영 문서

docs/deploy.md는 상황별로 한 코드 블록을 복사해 실행할 수 있는 운영 명령어만 유지한다. 설치·고급 설정·장애 원인 설명은 docs/deploy-reference.md에 기록한다.
재배포처럼 순서가 중요한 명령은 실패 시 다음 단계로 진행하지 않도록 &&로 연결한다.

문서 (update-log)

docs/update-log/는 블로그 방문자용 업데이트 안내 초안이다.
docs/update.md는 현재 minor와 최신 패치 이력을 중심으로 유지하고, 오래된 상세 이력은 docs/update-archive.md에 보관한다.
v1.1 이후 글은 안녕하세요. / `sori.studio`입니다. 로 시작한 뒤, 버전 요지를 서두에 짧게 적는다. 조금 늦게 정리하는, 이번 업데이트에서는, ~한 기록입니다 같은 표현은 쓰지 않는다.
제목은 sori.studio vX.Y 업데이트 — {짧은 요약} 형식을 쓴다. 요약은 한 단어가 아니라, 해당 버전의 핵심이 한눈에 들어오도록 짧은 구(대략 4~10자 내외의 의미 단위)로 적는다.
제목 바로 아래에 해당 minor(.0) 릴리스 날짜를 YYYY년 M월 D일로 적는다. 날짜는 docs/update.md·docs/history.md·package.json 버전 반영 시점을 기준으로 한다.
서두에 요지를 두므로 하단 한 줄 요약은 두지 않는다.
본문 소제목은 달라진 점을 기본으로 하고, 방문자가 화면에서 체감하는 변화와 이용상 이점만 적는다. 관리자 전용 절차·내부 구현·배포·검증·수익(광고) 관련 내용은 넣지 않는다.
내부 개선을 적을 때는 처리 과정이 아니라 결과(더 빠름, 더 안정적, 더 안전함 등)로 표현한다.

주석

JSDoc 형식
한국어 작성

/**
 * 게시물 목록 조회
 * @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을 비활성화한다.

5.5 KiB Raw Blame History

코딩 컨벤션

언어

문법

네이밍

스타일

운영 문서

문서 (update-log)

주석

설정

검증

통합 테스트 격리

5.5 KiB

Raw Blame History