🐾 Pet-Pass

이 프로젝트는 Codex, Claude, Antigravity, Jules가 협업함.

반려동물 동반 가능 매장 실시간 탐색 및 디지털 펫 패스 인증 서비스.

• Service: https://pet-pass-web.vercel.app/
• Blog: https://pet-pass-web.vercel.app/blog
• Game (미니게임): https://pet-pass-web.vercel.app/game — 설정은 DEPLOY.md 4장, 구조와 게임 추가 방법은 docs/minigame_structure.md 참고

---

🤖 AI Development Protocol

이 섹션은 Jules, Codex, Antigravity 등 AI 협업 에이전트들이 프로젝트 컨텍스트를 즉시 파악하고 효율적으로 기여하기 위한 기술 지침입니다.

🚨 Critical Rule

• 모든 AI는 작업 완료 후 반드시 docs/dev_history.md에 변경 사항을 기록해야 한다. (최우선 지침)

🛠 Tech Stack

• Frontend: Vanilla JS, Vanilla CSS (Pretendard 폰트), Kakao Maps API
• Backend: Vercel Serverless Functions (Node.js)
• Database: Supabase (PostgreSQL)
• CI/CD: GitHub Actions, Vercel

🔄 Data Flow & Logic

1. Sync Pipeline: GitHub Actions가 정기적으로 공공데이터(Excel/API)를 읽어 Supabase에 UPSERT 합니다.
2. Geocoding & Caching: 신규 매장(좌표 없는 데이터)에 대해서만 Kakao API를 호출하여 좌표를 추출합니다. 기존 데이터의 좌표는 DB에서 캐싱되어 재사용됩니다.
3. Frontend Rendering: 클라이언트에서 Supabase API를 통해 전체 매장 데이터를 가져와 지도에 렌더링하며, 필터링 및 검색은 클라이언트 사이드에서 최적화된 루프로 처리합니다.

📜 Collaboration Principles

• Documentation Only: 로직 수정이 없는 문서 작업(README, docs 등) 커밋 시 반드시 [skip ci]를 포함하여 불필요한 빌드를 방지합니다.
• Commit Convention: 아래의 접두사를 엄격히 준수합니다.
  • feat: 신규 기능 추가
  • fix: 버그 수정
  • docs: 문서 수정
  • chore: 빌드 업무, 패키지 매니저 설정 등
• Performance First: 대용량 데이터(1,700+) 처리 시 불필요한 고차 함수 체이닝보다는 성능 위주의 루프를 선호합니다.

---

📂 Project Structure Summary

Folder	Role
/api	Vercel Serverless Functions (Backend API endpoints)
/public	Frontend static assets (HTML, CSS, JS, Blog)
/scripts	Data sync, build, and utility scripts
/data	Raw data files and local storage for development
/docs	Development history and manual documents
.github/workflows	CI/CD automation (Daily sync, Deployment)

---

🚀 Setup & Execution

1. Environment: .env.example을 복사해 .env를 만들고 키를 채웁니다.
   • 런타임 필수: KAKAO_MAP_API_KEY, SUPABASE_URL, SUPABASE_ANON_KEY, DATA_GO_KR_API_KEY
   • 데이터 동기화 배치(npm run sync-stores) 실행 시 추가 필요: SUPABASE_SECRET_KEY, KAKAO_REST_API_KEY, PET_EXCEL_URL
2. Install: npm install
3. Local Dev: npm start (Express 서버 실행)
4. Build: npm run build (API Key 주입 및 배포 자산 생성)
5. Test (미니게임): npm test · npm run test:sql · npm run test:e2e · npm run test:mutation — 자세한 내용은 docs/minigame_structure.md