Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
286 lines (213 loc) · 7.32 KB

CONTRIBUTING.md

File metadata and controls

286 lines (213 loc) · 7.32 KB

Contributing to Lie Lab, Dream Club

이 프로젝트에 기여해주셔서 감사합니다! 이 가이드는 로컬 환경에서 Claude Code를 사용하여 프로젝트를 개발하는 방법을 설명합니다.

🎯 개발 철학

  • 간결함: 불필요한 추상화보다 명확한 코드를 선호합니다
  • 타입 안전성: TypeScript를 최대한 활용합니다
  • 사용자 중심: 한영 이중언어를 항상 고려합니다
  • 디자인 일관성: design_guidelines.md를 준수합니다

🛠 로컬 개발 환경 설정

1. 초기 설정

# 저장소 클론
git clone <repository-url>
cd LieLabDreamClub

# 의존성 설치
npm install

# 환경 변수 설정
cp .env.example .env
# .env 파일을 편집하여 필요한 값 입력

2. 환경 변수 설정

.env 파일에서 다음을 설정:

# 로컬 개발용 최소 설정
PORT=5000
NODE_ENV=development
SESSION_SECRET=development-secret-min-32-characters-long

# PostgreSQL 사용시 (선택)
DATABASE_URL=postgresql://user:password@localhost:5432/lielabdreamclub

# Replit Auth 없이 개발하려면 위 두 항목만 있으면 됩니다
# DATABASE_URL이 없으면 자동으로 in-memory storage 사용

3. 데이터베이스 설정 (선택)

PostgreSQL을 사용하려면:

# 로컬 PostgreSQL 실행
# Docker 사용 예시:
docker run --name lielabdb -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres

# 스키마 동기화
npm run db:push

4. 개발 서버 실행

npm run dev

브라우저에서 http://localhost:5000 접속

📂 프로젝트 구조 이해하기

client/src/
├── components/       # 재사용 가능한 컴포넌트
│   ├── ui/          # shadcn/ui 기본 컴포넌트 (수정 지양)
│   ├── navigation.tsx
│   └── story-card.tsx
├── pages/           # 라우트별 페이지 컴포넌트
├── lib/             # Context, 유틸리티, 설정
└── App.tsx          # 루트 컴포넌트 (라우팅)

server/
├── index.ts         # Express 서버 엔트리포인트
├── routes.ts        # API 엔드포인트 정의
├── storage.ts       # 데이터 저장소 추상화
└── replitAuth.ts    # Replit SSO 인증 로직

shared/
└── schema.ts        # Drizzle 스키마 + Zod 검증

🔄 일반적인 개발 워크플로우

1. 새로운 기능 개발

# 새 브랜치 생성
git checkout -b feature/your-feature-name

# 코드 작성 및 테스트
npm run dev

# 타입 체크
npm run check

# 커밋
git add .
git commit -m "feat: Add your feature description"
git push origin feature/your-feature-name

2. 새로운 페이지 추가

  1. client/src/pages/ 에 페이지 컴포넌트 생성
  2. client/src/App.tsx 에 라우트 추가
  3. client/src/components/navigation.tsx 에 네비게이션 링크 추가 (필요시)
  4. 한영 이중언어 텍스트 추가

예시:

// client/src/pages/my-page.tsx
import { useLanguage } from "@/lib/language-context";

export default function MyPage() {
  const { t } = useLanguage();

  return (
    <div>
      <h1>{t("한국어 제목", "English Title")}</h1>
    </div>
  );
}

// client/src/App.tsx
<Route path="/my-page" component={MyPage} />

3. 새로운 API 엔드포인트 추가

  1. shared/schema.ts 에 Zod 스키마 정의
  2. server/routes.ts 에 엔드포인트 추가
  3. 필요시 server/storage.ts 에 데이터 접근 메서드 추가
  4. 프론트엔드에서 TanStack Query로 호출

예시:

// shared/schema.ts
export const mySchema = z.object({
  name: z.string().min(1),
});

// server/routes.ts
app.post("/api/my-endpoint", isAuthenticated, async (req, res) => {
  try {
    const validated = mySchema.parse(req.body);
    // 처리 로직
    res.json({ success: true });
  } catch (error: any) {
    res.status(400).json({ message: error.message });
  }
});

4. UI 컴포넌트 추가

shadcn/ui 컴포넌트 사용:

# components.json 설정이 이미 되어 있으므로
# 새 컴포넌트 추가시 직접 복사하거나
# npx shadcn@latest add [component-name]

🎨 디자인 가이드라인 준수

design_guidelines.md 참조:

  • 타이포그래피: Crimson Pro (serif) + Inter (sans-serif)
  • 컬러: CSS 변수 사용 (bg-background, text-foreground 등)
  • 간격: Tailwind 스페이싱 (4, 6, 8, 12, 16, 24)
  • 다국어: 모든 사용자 대면 텍스트는 t("한국어", "English") 형식 사용

🧪 테스팅

현재 프로젝트에는 테스트가 설정되어 있지 않습니다. 테스팅 추가를 고려한다면:

# Vitest 추가 예시
npm install -D vitest @testing-library/react @testing-library/jest-dom

🔐 인증 관련 개발

로컬 환경에서 Admin 권한 테스트

  1. 개발 서버 실행 (npm run dev)
  2. 브라우저에서 /api/login 접속 (Replit Auth 사용시)
  3. 로그인 후 사용자 ID 확인
  4. Admin 권한 부여:
curl -X POST http://localhost:5000/api/dev/set-admin/YOUR_USER_ID \
  -H "Content-Type: application/json" \
  -d '{"isAdmin": 1}'

📝 커밋 메시지 컨벤션

feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 변경
style: 코드 포매팅, 세미콜론 누락 등
refactor: 코드 리팩토링
perf: 성능 개선
test: 테스트 추가
chore: 빌드 작업, 패키지 매니저 설정 등

예시:

feat: Add story search functionality
fix: Fix rating calculation bug in story-detail page
docs: Update README with deployment instructions

🚨 자주 발생하는 문제

1. 데이터베이스 연결 오류

Error: DATABASE_URL not set

해결: .env 파일에 DATABASE_URL 추가하거나, in-memory storage 사용 (DATABASE_URL 없이 실행)

2. 인증 오류

Error: REPL_ID not set

해결: 로컬 개발시 Replit Auth 없이도 작동합니다. SESSION_SECRET만 설정하면 됩니다.

3. Port 충돌

Error: Port 5000 already in use

해결: .env의 PORT를 변경하거나 기존 프로세스 종료

4. TypeScript 오류

Type error: Cannot find module '@/...'

해결: npm install 재실행 및 IDE 재시작

🤝 풀 리퀘스트 가이드라인

  1. 브랜치 이름: feature/, fix/, docs/ 등의 접두사 사용
  2. 코드 품질: TypeScript 오류 없이 빌드 성공 (npm run check)
  3. 디자인 준수: design_guidelines.md 확인
  4. 이중언어: 모든 텍스트 한영 병기
  5. 설명: PR에 변경 사항 명확히 설명

🔧 유용한 개발 도구

VSCode 확장 프로그램 권장

  • ESLint - 코드 린팅
  • Prettier - 코드 포매팅
  • Tailwind CSS IntelliSense - Tailwind 자동완성
  • TypeScript Error Translator - TS 오류 번역

브라우저 개발자 도구

  • React Developer Tools
  • TanStack Query DevTools (프로젝트에 포함됨)

📚 참고 자료

💬 질문이나 제안

  • GitHub Issues를 통해 버그 리포트 및 기능 제안
  • Pull Request는 언제나 환영합니다!

Happy Coding with Claude! 🤖