문서 관리

작성일	2024-04-27
버전	1.0
작성자	suzy.kang (강수지)
검토자	kevin
상태	초안

변경 이력

버전	날짜	작성자	검토자	변경내용

---

1. 폴더 구조

1.1 Feature-Sliced Design (FSD) 구조

src/
├── app/ # Next.js App Router
├── pages/ # Next.js Pages Router
├── shared/ # 프로젝트 전역 공통 모듈
│ ├── api/ # 공통 API 클라이언트/함수
│ ├── config/ # 환경설정, 라우트, SEO 등
│ ├── constants/ # 상수 정의
│ ├── lib/ # 범용 유틸리티 함수
│ ├── types/ # 전역 타입/인터페이스
│ └── components/ # 공통 UI 컴포넌트
├── entities/ # 비즈니스 엔티티
│ └── (entity)/ # 예: user, place, moment
│ ├── model/ # 엔티티 상태, store, 비즈니스 로직
│ ├── api/ # 엔티티 전용 API
│ ├── types/ # 엔티티 타입
│ └── components/ # 엔티티 전용 컴포넌트
├── features/ # 기능 단위 폴더
│ ├── user/
│ │ ├── components/ # 인증/유저 관련 컴포넌트
│ │ ├── hooks/ # 인증/유저 관련 커스텀 훅
│ │ ├── model/ # 인증/유저 관련 상태, zustand store 등
│ │ ├── api/ # 인증/유저 관련 API 함수
│ │ ├── types/ # 인증/유저 관련 타입
│ │ └── index.ts
│ ├── place/
│ ├── community/
│ └── onboarding/

• shared/components: Button, Input, Modal, Spinner, Toast 등 어디서나 재사용되는 UI
• entities/(entity)/components: 엔티티(예: user, place) 전용 컴포넌트
• features/(feature)/components: 기능(예: user, place) 전용 컴포넌트

---

2. 반응형 디자인 지원 전략

• 모바일 우선(Mobile First) 접근

  기본 뷰포트는 375px, 모바일 기준으로 UI 설계

  Tailwind CSS의 모바일 우선 클래스 적극 활용

• 웹에서도 모바일 사이즈로 고정

  PC 환경에서도 모바일 뷰(375px)로 고정, 중앙 정렬

• rem/em 단위 사용

  폰트, 여백 등은 rem/em 단위로 통일

• 이미지/아이콘 반응형

  Next.js Image 컴포넌트, SVG 아이콘 사용

---

3. 코드 컨벤션

• 네이밍

  • 컴포넌트/타입/인터페이스: PascalCase
  • 함수/변수/훅: camelCase
  • 상수: UPPER_SNAKE_CASE
  • 파일/폴더: kebab-case

• 컴포넌트

  • 함수형 컴포넌트, React.FC 사용 지양
  • props, state, hooks, handler, render 순서

• 타입

  • interface는 객체 형태의 타입, 확장 가능성이 있는 경우 사용
  • type은 유니온 타입, 교차 타입, 기본 타입의 별칭에 사용
  • 타입/인터페이스는 types.ts로 분리

  // interface 사용 예시 (객체 형태, 확장 가능)
  interface ButtonProps {
    variant?: 'primary' | 'secondary';
    size?: 'sm' | 'md' | 'lg';
    onClick?: () => void;
  }
  
  // type 사용 예시 (유니온 타입, 별칭)
  type ButtonVariant = 'primary' | 'secondary' | 'tertiary';
  type Size = 'sm' | 'md' | 'lg';
  
  

• 주석

  • 함수/컴포넌트 상단 JSDoc 사용
  • 복잡한 로직에만 인라인 주석 추가
  • 사소하거나 자명한 코드에는 주석 사용 지양
  • 주석보다 명확한 변수명과 함수명으로 코드 자체가 설명되도록 작성

  // 좋은 예시
  /**
   * 날짜를 YYYY-MM-DD 형식으로 변환
   * @param date - 변환할 날짜 객체
   * @returns 포맷된 날짜 문자열
   */
  const formatDate = (date: Date): string => {
    // 로컬 시간대로 변환 (국제 표준시와 차이가 있을 수 있음)
    return date.toISOString().split('T')[0];
  };
  
  // 지양할 예시
  // 이름을 반환하는 함수
  const getName = () => name; // 불필요한 주석
  
  

• 코딩 패턴

  • 컴포넌트는 export function 방식으로 작성

    // 예시: shared/components/Button/Button.tsx
    export function Button(props: ButtonProps) {
      // ...
    }
    
    

  • 일반 기능 함수(유틸, 훅 등)는 화살표 함수로 작성

    // 예시: shared/lib/formatDate.ts
    export const formatDate = (date: Date) => {
      // ...
    };
    
    

  • 폴더별 index.ts에서 export하여 import 경로를 단순화

    // 예시: shared/components/Button/index.ts
    export * from './Button';
    // 사용: import { Button } from 'shared/components';
    
    

---

4. Lint & Formatting

• ESLint
  • next/core-web-vitals, prettier, import/order 등 확장
  • import 순서: builtin → external → internal → parent → sibling → index, 알파벳순, 그룹별 한 줄 띄움
• Prettier
  • 세미콜론 사용, 싱글 쿼트, 2칸 들여쓰기, 80자 줄바꿈, trailing comma
• 자동화
  • husky + lint-staged로 커밋 전 lint/format 자동 실행

---

5. Git 전략

• 브랜치
  • main: 배포/운영
  • dev: 통합 개발
  • feat/xxx: 기능 개발
• 커밋 메시지
  • feat:, fix:, chore:, style:, refactor:, test:, docs: 등 prefix 사용
  • 예시: feat: 로그인 API 연동, fix: 프로필 이미지 버그 수정
  • 커밋은 최대한 작은 단위로 쪼개서 작성 (기능, 버그 수정 등 단일 목적)
  • 하나의 커밋에 여러 기능이나 수정사항을 포함하지 않음
• PR 규칙
  • dev → main, feat/xxx → dev로만 머지
  • PR 템플릿 사용

    • PR 제목 형식: [feat] 로그인 기능 구현, [fix] 프로필 이미지 로딩 버그 수정

    • 제목은 [타입] 내용 형식으로 일관되게 작성

    • PR 템플릿 예시:

      ## 📝 PR 개요
      <!-- 이 PR이 해결하는 문제나 추가하는 기능에 대한 간략한 설명 -->
      
      ## 🔍 변경사항
      <!-- 주요 변경사항 목록 (불릿 포인트) -->
      -
      -
      -
      ## 🔗 관련 이슈
      <!-- 관련된 이슈 링크 (e.g. Closes #123) -->
      
      
      ## 📸 스크린샷 (Optional)
      <!-- UI 변경사항이 있거나 필요한 경우 스크린샷 추가 -->
      
      ## 🧪 테스트 (Optional)
      <!-- 테스트 방법 및 결과 -->
      - [ ] 테스트 1
      - [ ] 테스트 2
      
      ## 🚨 주의사항 (Optional)
      <!-- 리뷰어가 알아야 할 주의사항이나 고려사항 -->
      
      
      

---

6. 브라우저 호환성

• 지원 브라우저
  • Chrome, Safari, Firefox, Edge (각 최신 2버전)
  • 모바일: iOS Safari, Android Chrome
• 폴리필 전략
  • Next.js 내장 폴리필 활용 (fetch, Promise, Object.assign 등)

---

7. SEO 전략

• 메타 태그

  • title, description, og/meta 태그 각 페이지별 동적 관리
  • Next.js Head 컴포넌트 활용
  • 장소 데이터의 이름, 주소, 카테고리 등을 meta description에 포함
  • Open Graph 이미지로 장소/기록 대표 이미지 활용

• 구조화된 데이터 마크업

  • 장소 정보는 [Schema.org](http://schema.org/) LocalBusiness 타입으로 마크업

  • 기록/모먼트는 Article 또는 BlogPosting 타입으로 마크업

  • JSON-LD 형식 활용:

    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{
        __html: JSON.stringify({
          "@context": "<https://schema.org>",
          "@type": "LocalBusiness",
          "name": place.name,
          "address": {
            "@type": "PostalAddress",
            "streetAddress": place.address
          },
          "geo": {
            "@type": "GeoCoordinates",
            "latitude": place.latitude,
            "longitude": place.longitude
          },
          "image": place.images[0]
        })
      }}
    />
    
    

• SSR/SSG/ISR

  • 장소 검색 결과 페이지는 SSR로 구현하여 검색 키워드 기반 SEO 최적화
  • 장소 상세 페이지도 SSR로 구현하여 최신 데이터를 검색 엔진에 노출
  • 기록 페이지도 SSR 적용으로 내용 기반 검색 노출 강화
  • Next.js의 getServerSideProps 활용하여 서버 사이드에서 데이터 페칭

• 장소/기록 데이터 SEO 최적화

  • URL 구조에 장소명/카테고리 포함 (예: /place/[category]/[slug])
  • 장소 키워드, 지역명 등 검색 최적화된 콘텐츠 구성
  • 관련 장소와 기록을 내부 링크로 연결하여 검색 엔진 크롤링 개선
  • 이미지에 alt 태그 및 파일명에 키워드 포함

• robots.txt, sitemap.xml

  • 검색엔진 최적화 파일 제공
  • 동적 sitemap 생성으로 모든 장소와 기록 페이지 포함
  • 주요 카테고리별 sitemap 분리

---

8. 테스트 전략

• 단위 테스트: Jest
• E2E 테스트: Cypress
• 테스트 파일 위치: 동일 폴더 내 .test.ts
• 테스트 커버리지:
  • 주요 로직, 핵심 컴포넌트, API 연동 중심으로 테스트 작성
  • 비즈니스 로직이 복잡한 유틸리티 함수 우선 테스트
  • 단순 UI 렌더링이나 사소한 헬퍼 함수는 테스트 작성 지양

---

9. 성능 최적화

• 이미지 최적화: Next.js Image, WebP, lazy loading
• 코드 스플리팅: 동적 import, 필요시 React.lazy
• 번들 크기 관리: shadcn/ui, 필요한 컴포넌트만 import
• 지도/외부 SDK: lazy load, Suspense 활용

---

10. 접근성

• ARIA 속성: 버튼, 입력 등 주요 UI에 ARIA 속성 부여
• 키보드 네비게이션: Tab, Enter, Space 등 키보드 접근성 보장

---

11. 기타

• 상태 관리: zustand, store 분리, persist 사용시 민감정보 주의
• 유효성 검사: zod, 서버-클라이언트 스키마 공유
• API 연동: fetch, TanStack Query, use() 혼합, 에러/로딩 처리 일관성
• 스토리북:
  • UI 컴포넌트 문서화, 디자인 시스템 일관성 유지
  • 스토리 파일은 해당 컴포넌트 폴더 내에 위치
  • 파일명 규칙: 컴포넌트명.stories.tsx

---