반려동물 입양 매칭 서비스

AI 코딩 에이전트(Cursor · v0 · Claude Code 등)에 아래 순서대로 붙여넣으면 됩니다. 각 단계를 끝내면 체크하세요.

1. 1

   AI 코딩 에이전트 준비

   Cursor · v0 · Claude Code · Bolt 중 편한 도구를 열고 새 프로젝트를 시작하세요. 스택은 Next.js (App Router) · Cloud Firestore (Next.js · Firebase · Firebase Hosting) 기준입니다.

2. 2

   프로젝트 셋업 — 환경변수 · 인증

   필요한 환경변수

   NEXT_PUBLIC_FIREBASE_API_KEY
   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN
   NEXT_PUBLIC_FIREBASE_PROJECT_ID
   NEXT_PUBLIC_FIREBASE_APP_ID
   FIREBASE_SERVICE_ACCOUNT_KEY

   인증 설정 가이드 보기

   # 인증 설정 — Firebase Auth (Google 로그인)
   
   1. Firebase 콘솔에서 프로젝트 생성 → 웹 앱 등록 후 firebaseConfig 확보
   2. Authentication > Sign-in method > Google 사용 설정
   3. 환경변수에 firebaseConfig 값(NEXT_PUBLIC_FIREBASE_*) 등록. Admin 작업용 service account 키는 서버 전용.
   4. 패키지: `firebase`(클라이언트), `firebase-admin`(서버)
   5. 클라이언트는 firebase/auth 로 Google 로그인. 서버 검증은 firebase-admin 으로 ID 토큰 verify.
   6. Firestore 접근은 보안 규칙(firestore.rules) + 인증 기반으로 제한.

3. 3

   전체 골격 만들기 — 마스터 프롬프트 실행

   아래 프롬프트를 통째로 복사해 에이전트에 붙여넣으면 프로젝트 뼈대가 만들어집니다.

   프롬프트 샘플에서는 일부만 표시

   # 반려동물 입양 매칭 플랫폼 — MVP 마스터 프롬프트
   
   ## 역할
   당신은 풀스택 시니어 엔지니어입니다. 아래 명세를 읽고 반려동물 입양 매칭 플랫폼 MVP를 처음부터 끝까지 완성하세요. 비개발자도 그대로 실행할 수 있도록 모든 파일·명령·설정을 빠짐없이 작성합니다.
   
   ---
   …

4. 4

   모듈 구현 — 1단계: 프로젝트 셋업

   앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.

   프롬프트 샘플에서는 일부만 표시

   Next.js 14 App Router 프로젝트를 아래 조건으로 세팅해줘.
   
   ## 기술 스택
   - Next.js 14 (App Router)
   …

5. 5

   모듈 구현 — 2단계: Firebase Auth 인증

   앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.

   프롬프트 샘플에서는 일부만 표시

   Firebase Auth 기반 인증 기능을 구현해줘.
   
   ## 요구사항
   - 이메일/비밀번호 로그인·회원가입만 구현 (Firebase Auth 외 인증 방식 추가 금지)
   …

6. 6

   모듈 구현 — 3단계: Firestore DB 스키마 & 보안 규칙

   앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.

   프롬프트 샘플에서는 일부만 표시

   Cloud Firestore 스키마와 보안 규칙을 설계하고 구현해줘.
   
   ## 컬렉션 스키마
   ```
   …

7. 7

   모듈 구현 — 4단계: 핵심 기능 구현

   앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.

   프롬프트 샘플에서는 일부만 표시

   반려동물 입양 매칭 플랫폼의 핵심 기능 화면과 API를 구현해줘.
   
   ## 화면 목록
   
   …

8. 8

   모듈 구현 — 5단계: 관리자 페이지 & Firebase Hosting 배포

   앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.

   프롬프트 샘플에서는 일부만 표시

   관리자 승인 페이지를 구현하고 Firebase Hosting 배포 설정을 완성해줘.
   
   ## 관리자 페이지 (`/admin`)
   - AuthGuard + role='admin' 검증 (서버에서 검증, 클라이언트 우회 불가)
   …

9. 9

   배포하기

   배포 가이드 보기

   # 배포 — Firebase Hosting
   
   1. `npm i -g firebase-tools` 후 `firebase login`, `firebase init`(Hosting + Firestore)
   2. Next.js → Firebase Hosting 은 `firebase experiments:enable webframeworks` 또는 정적 export/SSR 설정 사용
   3. `firebase.json` 에 hosting/firestore 설정. `firebase deploy --only hosting,firestore:rules,firestore:indexes`
   4. 환경변수는 빌드 시 주입(NEXT_PUBLIC_*) + 서버 함수용 secret 관리.

10. 10

    검증 — 핵심 시나리오 테스트

    아래 체크리스트로 핵심 기능이 동작하는지 확인하세요.

    테스트 계획 보기

    # 수용 테스트 / QA 체크리스트
    
    ## TC-01. 회원가입 · 로그인 (Firebase Auth)
    - [ ] 이메일+비밀번호로 신규 가입 시 `users/{uid}` 문서가 `role: 'adopter'`로 생성된다
    - [ ] 보호소 계정은 관리자가 Firestore에서 role을 `shelter`로 수동 변경 후 권한이 적용된다
    - [ ] 로그인 후 클라이언트에서 ID Token을 획득할 수 있다
    - [ ] 로그아웃 후 보호된 Server Action 호출 시 401 응답을 받는다
    
    ## TC-02. 동물 등록
    - [ ] `shelter` role 계정으로 필수 항목(name·species·imageUrl 등) 입력 시 동물이 정상 등록된다
    - [ ] 등록된 동물은 Firestore `animals` 컬렉션에 `status: 'available'`로 저장된다
    - [ ] `adopter` 계정으로 동물 등록 시도 시 403 에러가 반환된다
    - [ ] 미인증 사용자가 동물 등록 시도 시 401 에러가 반환된다
    - [ ] 필수 항목 누락 시 클라이언트 및 서버 양측에서 유효성 오류가 표시된다
    
    ## TC-03. 동물 목록 · 상세 조회
    - [ ] 비로그인 상태에서 `/animals` 페이지가 정상 렌더링된다
    - [ ] `species` 필터 적용 시 해당 종만 표시된다
    - [ ] `status=available` 필터 적용 시 입양 가능한 동물만 표시된다
    - [ ] 페이지 하단 도달 시 다음 20건이 커서 기반으로 추가 로드된다
    - [ ] 존재하지 않는 동물 ID로 상세 접근 시 404 페이지가 표시된다
    
    ## TC-04. 입양 신청
    - [ ] `adopter` 로그인 후 `available` 동물에 신청 시 `applications` 문서가 `status: 'pending'`으로 생성된다
    - [ ] 동일 동물에 중복 신청 시 409 에러가 반환되고 UI에 안내 메시지가 표시된다
    - [ ] `status: 'adopted'` 동물에 신청 시도 시 서버에서 거부된다
    - [ ] 미인증 사용자가 신청 시도 시 로그인 페이지로 리다이렉트된다
    - [ ] `shelter` 계정으로 신청 시도 시 403 에러가 반환된다
    
    ## TC-05. 신청자 목록 · 관리자 승인
    - [ ] 보호소 계정으로 본인 등록 동물의 신청자 목록이 조회된다
    - [ ] 타 보호소 동물의 신청자 목록 조회 시 403 에러가 반환된다
    - [ ] 신청 승인 시 해당 `application.status → 'approved'`, `animal.status → 'adopted'` 로 트랜잭션 처리된다
    - [ ] 한 신청 승인 후 같은 동물의 나머지 신청들이 모두 `rejected`로 변경된다
    - [ ] 신청 거절 시 `application.status → 'rejected'`로 변경되고 동물 status는 유지된다
    
    ## TC-06. 문의 폼
    - [ ] 비로그인 상태에서 문의 폼 제출이 정상 처리된다
    - [ ] 필수 항목(name·email·message) 누락 시 오류 메시지가 표시된다
    - [ ] 제출 성공 시 Firestore `inquiries` 컬렉션에 문서가 생성된다
    - [ ] 클라이언트에서 Firestore SDK로 `inquiries`에 직접 쓰기 시 Security Rules에 의해 차단된다
    
    ## TC-07. 보안 · 환경변수
    - [ ] 브라우저 Network 탭에서 Firebase 서비스 계정 키(JSON)가 노출되지 않는다
    - [ ] `.env.local`의 `FIREBASE_ADMIN_*` 변수가 빌드 번들에 포함되지 않는다 (`NEXT_PUBLIC_` 접두사 없음 확인)
    - [ ] Firestore Security Rules에서 `animals`·`applications`·`inquiries` 컬렉션에 대한 클라이언트 직접 쓰기가 거부된다
    - [ ] `users/{uid}.role` 필드를 클라이언트에서 직접 변경 시 Security Rules에 의해 거부된다
    
    ## TC-08. UI · UX
    - [ ] 랜딩 페이지에서 "입양하기" CTA 클릭 시 동물 목록 페이지로 이동한다
    - [ ] 동물 상세 페이지에서 이미지 로드 실패 시 placeholder 이미지가 표시된다
    - [ ] 신청/문의 폼 제출 중 로딩 인디케이터가 표시된다
    - [ ] 모바일(375px) 기준으로 목록·상세·신청 페이지 레이아웃이 깨지지 않는다
    

11. 11

    막혔을 때 — 트러블슈팅

    에이전트가 에러로 막히면 아래 대응을 참고하세요.

    트러블슈팅 보기

    ## 빌드/타입 에러가 나요
    - **증상**: 빌드 시 타입 에러. **원인**: 서버/클라이언트 컴포넌트 경계 혼동. **해결**: 데이터 조회는 서버에서, 상호작용은 `"use client"` 로 분리하라고 지시.
    
    ## 로그인이 안 되거나 팝업이 닫혀요
    - **증상**: 구글 로그인 실패. **원인**: Firebase Authentication 에서 Google 공급자 미활성 또는 승인된 도메인 누락. **해결**: Authentication > Sign-in method 에서 Google 켜고, Settings > Authorized domains 에 localhost 와 배포 도메인 추가.
    
    ## 환경변수 관련 에러
    - **증상**: Firebase config 관련 에러. **원인**: `.env.local` 미설정. **해결**: `.env.example` 를 복사해 값을 채우고 서버 재시작. `NEXT_PUBLIC_` 접두사 확인.
    
    ## 데이터가 안 보이거나 저장이 안 돼요
    - **증상**: 읽기/쓰기 권한 거부. **원인**: Firestore 보안 규칙이 기본 차단. **해결**: 규칙에 컬렉션별 read/write 조건을 추가(공개 읽기/본인 쓰기 등). 서버(관리자 SDK) 쓰기는 서비스 계정 키 사용.
    
    ## 서버 전용 키가 노출돼요
    - **증상**: 서비스 계정 키가 브라우저에 노출. **원인**: 클라이언트에서 admin SDK 사용. **해결**: 관리자 SDK/서비스 키는 서버 라우트에서만 사용하고 절대 `NEXT_PUBLIC_` 로 두지 않는다.