요청이 들어오면 인근 기사들에게 동시에 뿌리되 **먼저 수락한 한 명에게만 배차가 확정**되고(중복 배차 차단), 기사 위치와 진행 상태가 고객 화면에 실시간으로 갱신되며, 완료 시 거리·할증 기준으로 기사 수수료와 플랫폼 수수료가 자동 분리 정산되는 서비스
‘MVP 기획’·‘AI 빌드 기획 패키지’·‘프로토타입 프롬프트’는 빌드 패키지 하나에 함께 들어갑니다 — 따로 결제하지 않습니다.
어떻게 만드나?
AI 빌드 기획 패키지 · 베타 무료
AI 코딩 에이전트가 바로 투입할 정밀 스펙 + 붙여넣기 프롬프트.
Next.js (App Router) · Firebase Auth · Cloud Firestore · Firebase Hosting
샘플은 여기까지 공개합니다
파일 다운로드와 전문(全文) 복사는 실제 결과물에서만 제공됩니다. 내 아이디어를 입력하면 같은 형식의 결과물을 받아볼 수 있습니다.
AI 코딩 에이전트(Cursor · v0 · Claude Code 등)에 아래 순서대로 붙여넣으면 됩니다. 각 단계를 끝내면 체크하세요.
AI 코딩 에이전트 준비
Cursor · v0 · Claude Code · Bolt 중 편한 도구를 열고 새 프로젝트를 시작하세요. 스택은 Next.js (App Router) · Cloud Firestore (Next.js · Firebase · Firebase Hosting) 기준입니다.
프로젝트 셋업 — 환경변수 · 인증
필요한 환경변수
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) + 인증 기반으로 제한.
전체 골격 만들기 — 마스터 프롬프트 실행
아래 프롬프트를 통째로 복사해 에이전트에 붙여넣으면 프로젝트 뼈대가 만들어집니다.
[역할] - 당신은 베테랑 AI 코딩 에이전트입니다. 비개발자도 이해할 수 있도록 명확하게 설명하며, 본 프롬프트를 Cursor/Claude Code/v0/Bolt 등 AI코딩툴에 그대로 붙여넣으면 아래 웹 MVP를 빌드합니다. [제품 요약] - 동네 퀵서비스 실시간 배차 플랫폼입니다. - 전화/카톡 중심의 기존 지역 퀵서비스의 비효율 문제(수동 배차, 중복 응답, 진행 추적, 정산 혼란 등)를 해결하는 웹 기반 MVP입니다. …
모듈 구현 — 프로젝트 초기 셋업 및 의존성 설치
앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.
다음 조건에 맞게 Next.js(App Router) 프로젝트를 생성하세요. npm/yarn 초기화, TypeScript 활성화, Firebase 관련 패키지(firebase, @firebase/auth, @firebase/firestore 등) 추가, 환경변수(.env.local) 기반 Firebase 설정 템플릿 생성, Firebase Hosting으로 배포 가능한 구조 준비. Test와 Lint는 간단한 기본만 둡니다. app 디렉토리 구조 시작. README 주요 개요 스켈레톤 작성.
모듈 구현 — Firebase Auth 연동 및 인증 플로우 구현
앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.
Firebase Auth를 활용해 email/password 기반 회원가입(드라이버, 관리자, 고객 구분)을 구현하세요. 인증 UI(로그인, 회원가입, 로그아웃) 생성. 권한별로 app 내부 route 접근 제어(예: /admin, /driver, /client 분리). Auth 정보는 context 또는 hook으로 전역 관리. 인증 상태 변화에 따라 사용자를 알맞은 화면으로 라우팅 처리합니다. 보안상 클라이언트에 서비스 Firebase secret을 노출하지 않습니다.
모듈 구현 — Cloud Firestore DB 스키마 설계 및 접근 코드
앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.
DB 스키마를 Firestore에 requests, drivers, dispatches, users, commissions 컬렉션으로 정의합니다. 각 컬렉션의 주요 필드와 타입을 명세한 TypeScript 인터페이스로 선언하세요. read/write는 Firestore client SDK와 Firebase Auth의 authId 기반으로 허용 범위 제어 권장(예: 본인 정보만 수정, 관리자는 전체 열람). 유저 롤별로 Firestore 보안 규칙 샘플을 함께 만드세요. DB 접속 및 CRUD 기본 예시 함수 제공.
모듈 구현 — 퀵서비스 요청 & 배차 핵심 기능 구현
앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.
퀵서비스 요청 등록(고객 화면), 인근 드라이버 리스트 추출 및 배차 알림(드라이버 화면 - 실시간 pending/accept UI), 진행 중/완료 상태로 상태 동기화, 드라이버/고객 위치&상태 실시간 표시, 핵심 업무 플로우를 App Router route별로 구현하세요. 수수료 산출 및 디스패치 완료시 정산 레코드 생성까지 포함. socketX 등 실시간 sync가 Firestore snapshot listener로 구현됨을 가정하고, UI는 간결하게 Listing/Form정도로 충분합니다.
모듈 구현 — 관리자 대시보드, 기본 배포 및 운영 세팅
앞 단계 결과 위에서 이 프롬프트를 실행해 기능을 채웁니다.
/admin 경로에 관리자만 접근 가능한 대시보드를 구현하세요. 전체 요청, 배차, 기사, 고객, 수수료 내역을 테이블 형태로 조회 가능. 각 항목의 상세 기록과 로그를 Firestore에서 불러와 행별 팝업(detail modal)로 볼 수 있습니다. Firebase Hosting 배포 스크립트와 환경변수 예시, README 내 운영 관련 주의사항(시크릿/서비스키 미노출) 마크다운 목차를 추가하세요.
배포하기
# 배포 — 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 관리.
검증 — 핵심 시나리오 테스트
아래 체크리스트로 핵심 기능이 동작하는지 확인하세요.
### 수용 테스트 체크리스트 #### 요청 등록/배차 - [ ] 소상공인 회원이 요청 생성 후, DB에 정확히 기록된다. - [ ] 인근 기사는 새로운 요청 알림 및 조회가 즉시 가능하다. - [ ] 두 기사 동시 수락 시, 한 기사만 최종 배정되고 다른 쪽은 거절 처리된다. - [ ] 아무도 수락하지 않으면 요청이 계속 미배정 상태로 남는다. #### 배송 진행/상태 공유 - [ ] 배차된 한 기사만 실제 배송 진행 상태를 변경할 수 있다. - [ ] 고객은 자신의 요청 배송 상태를 읽을 수 있고, 타인의 것은 볼 수 없다. - [ ] 실시간 위치 공유(모킹 데이터 등) 화면이 정상 동작한다. #### 수수료 및 정산 - [ ] 수수료 내역이 자동 분리되어 저장된다. - [ ] 월별 정산 내역 조회에서 dispatch/fee/조건이 분명히 남아 있다. #### 관리자/보안 - [ ] 일반 사용자가 admin/dashboard 등 관리자 API에 접근 시 차단된다. - [ ] Firestore 출입·작성 제한이 서버 or 보안 규칙으로 100% 보장된다. - [ ] 환경변수/시크릿이 노출되지 않는다.
막혔을 때 — 트러블슈팅
에이전트가 에러로 막히면 아래 대응을 참고하세요.
### 자주 막히는 문제 & 해결
#### 1. Firestore 권한 에러: "Missing or insufficient permissions"
- 증상: DB 쓰기/읽기 시 에러 발생
- 원인: Firestore Security Rules 미설정. 서버 액션 외 클라에서 직접 접근 시도.
- 해결: Firestore Console에서 'users 이메일/권한 확인', DB RULES에 역할별 조건 추가. 모든 민감 쓰기/수정은 반드시 서버안에서만 실행. 클라이언트는 서버 api 경유.
#### 2. 인증 리다이렉트 루프/앱 접근 못함
- 증상: 로그인 후에도 계속 리다이렉트; API 401 반환 반복
- 원인: Firebase Auth의 JWT 토큰 전달이 누락 또는 서버 verify 실패
- 해결: next-auth 등 서드파티 미사용. 요청마다 Authorization: Bearer {jwt} 헤더 추가. Next.js 서버핸들러/액션에서 firebase-admin의 verifyIdToken으로 토큰 검증. 잘못된 토큰 거부.
#### 3. 환경변수/시크릿 노출 및 미설정
- 증상: 배포 또는 빌드시 서비스키 노출, 또는 "Firebase config not found"/500 에러 등
- 원인: 클라이언트 코드에 시크릿 포함, .env.* 미설정
- 해결: .env.local,.env.production 등에만 Firebase admin 키 등 민감정보. 코드에는 process.env로만 접근. gitignore, vercel/Firebase Hosting 환경에 별도 입력.
#### 4. 빌드/타입 에러: 'process is not defined', "window is not defined"
- 증상: SSR 빌드 또는 함수 실행 시 런타임 에러
- 원인: 서버 코드와 클라이언트 코드 구분 부족, 브라우저에서 서버 함수 호출, 혹은 반대로 SSR에서 client-only 함수 실행 시도
- 해결: 서버/클라 분리 명확히. App Router에서 route handler(/api/*)나 server action에만 process.env 등 사용. 클라이언트 컴포넌트에는 window.* 만 허용.
#### 5. CORS 에러: API 호출이 브라우저에서 막힘
- 증상: 브라우저 콘솔에 CORS 블락 메시지 출력, API 정상 호출 불가
- 원인: Next.js API route/server action에서 CORS 헤더 미삽입, Firebase Functions 배포시 CORS 옵션 누락
- 해결: 필요시 @vercel/edge API의 경우 cors 헤더 추가 또는 next.config.js에서 api response header 지정. Firestore 서버리스 함수 사용시도 시 functions.https.onRequest에 cors 미들웨어 적용.막히거나 시간이 없다면? 전문가가 이 빌드킷 그대로 제작해드립니다.
전문가에게 맡기기 →동네 퀵서비스 배차의 비효율성과 분쟁을 웹 서비스로 해소합니다. 관제 담당자는 요청을 등록하고, 기사는 실시간 알림으로 배차를 수락하며, 고객은 진행 상황을 웹에서 확인합니다. 모든 요청, 배차, 위치/상태, 수수료 기록이 자동으로 저장되고 실시간 공유되어 월말 정산과 문의 대응도 간편해집니다.
퀵서비스 요청 등록 및 기사 동시 배차
관제 담당자가 퀵 요청을 등록하면, 인근 가용 기사에게 동시에 실시간 알림이 발송된다.
기사 배차 수락 및 자동 상태 갱신
기사 앱에서 알림을 받고 수락 버튼을 누르면, 해당 요청에 최초 수락자를 배정한다.
배송 진행상태 및 기사 위치 실시간 공유
고객 및 관제 담당자는 배송 상태(예: 픽업 중, 배송 중, 완료)와 기사의 실시간 위치를 웹에서 확인한다.
기사별 자동 수수료 및 정산 기록
모든 배차 건별로 기사 수수료율, 할증 조건 등 산식을 자동으로 기록하고 월말/건별 내역을 확인할 수 있다.
관리자 대시보드 및 요청/기사 현황 관리
관제 담당자는 웹 대시보드에서 모든 요청/배차/기사 현황을 실시간 모니터링한다.
backend/firestore.rules
샘플에서는 일부만 표시rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// Users
match /users/{userId} {
allow read: if request.auth != null && (request.auth.uid == userId || resource.data.role == 'admin');
allow write: if request.auth != null && request.auth.uid == userId;
}나머지 30줄은 실제 결과물에서 확인할 수 있습니다
backend/firestore.indexes.json
샘플에서는 일부만 표시{
"indexes": [
{
"collectionGroup": "requests",
"queryScope": "COLLECTION",
"fields": [
{"fieldPath": "status", "order": "ASCENDING"},
{"fieldPath": "request_time", "order": "DESCENDING"}나머지 14줄은 실제 결과물에서 확인할 수 있습니다
backend/seed.ts
샘플에서는 일부만 표시// Use with Node.js + Firebase Admin SDK manually.
import { initializeApp, cert, ServiceAccount } from "firebase-admin/app";
import { getFirestore, FieldValue } from "firebase-admin/firestore";
// -- REPLACE for actual local admin key if running! --
const serviceAccount = require("./serviceAccountKey.json") as ServiceAccount;
initializeApp({ credential: cert(serviceAccount) });나머지 48줄은 실제 결과물에서 확인할 수 있습니다
frontend/tailwind.config.js
샘플에서는 일부만 표시module.exports = {
content: [
'./app/**/*.{js,ts,jsx,tsx}',
'./components/**/*.{js,ts,jsx,tsx}',
],
theme: {
extend: {
colors: {나머지 9줄은 실제 결과물에서 확인할 수 있습니다
frontend/app/layout.tsx
샘플에서는 일부만 표시import './globals.css'
import type { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="ko">
<body className="bg-gray-50 min-h-screen">
<main className="container mx-auto p-4">나머지 10줄은 실제 결과물에서 확인할 수 있습니다
frontend/components/Button.tsx
샘플에서는 일부만 표시import { ButtonHTMLAttributes } from 'react'
type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
children: React.ReactNode
variant?: 'primary' | 'secondary'
}
export default function Button({ children, variant = 'primary', ...props }: ButtonProps) {나머지 9줄은 실제 결과물에서 확인할 수 있습니다
frontend/app/requests/page.tsx
샘플에서는 일부만 표시// Stub: 고객이 요청을 등록하는 리스트 화면
import Button from '../../components/Button'
export default function RequestsPage() {
// 실제 Firestore fetch 이후로 확장
return (
<section>
<h2 className="text-xl font-bold mb-4">퀵서비스 요청 목록</h2>나머지 10줄은 실제 결과물에서 확인할 수 있습니다
frontend/app/globals.css
샘플에서는 일부만 표시@tailwind base; @tailwind components; @tailwind utilities;
M0. 스토리/모델 구조 설계 및 Firestore 초기화
세부 태스크 3개
M1. Next.js 프로젝트 및 디자인 토큰/레이아웃 구축
세부 태스크 3개
M2. 핵심 첫 화면(퀵 요청 목록) 스텁 구현
세부 태스크 2개
[역할] - 당신은 베테랑 AI 코딩 에이전트입니다. 비개발자도 이해할 수 있도록 명확하게 설명하며, 본 프롬프트를 Cursor/Claude Code/v0/Bolt 등 AI코딩툴에 그대로 붙여넣으면 아래 웹 MVP를 빌드합니다. [제품 요약] - 동네 퀵서비스 실시간 배차 플랫폼입니다. - 전화/카톡 중심의 기존 지역 퀵서비스의 비효율 문제(수동 배차, 중복 응답, 진행 추적, 정산 혼란 등)를 해결하는 웹 기반 MVP입니다. - 주요 사용자: 관제 담당자, 배송 기사, 소상공인 고객(화주)
나머지 35줄은 실제 결과물에서 확인할 수 있습니다
프로젝트 초기 셋업 및 의존성 설치
샘플에서는 일부만 표시다음 조건에 맞게 Next.js(App Router) 프로젝트를 생성하세요. npm/yarn 초기화, TypeScript 활성화, Firebase 관련 패키지(firebase, @firebase/auth, @firebase/firestore 등) 추가, 환경변수(.env.local) 기반 Firebase 설정 템플릿 생성, Firebase Hosting으로 배포 가능한 구조 준비. Test와 Lint는 간단한 기본만 둡니다. app 디렉토리 구조 시작. README 주요 개요 스켈레톤 작성.
Firebase Auth 연동 및 인증 플로우 구현
샘플에서는 일부만 표시Firebase Auth를 활용해 email/password 기반 회원가입(드라이버, 관리자, 고객 구분)을 구현하세요. 인증 UI(로그인, 회원가입, 로그아웃) 생성. 권한별로 app 내부 route 접근 제어(예: /admin, /driver, /client 분리). Auth 정보는 context 또는 hook으로 전역 관리. 인증 상태 변화에 따라 사용자를 알맞은 화면으로 라우팅 처리합니다. 보안상 클라이언트에 서비스 Firebase secret을 노출하지 않습니다.
Cloud Firestore DB 스키마 설계 및 접근 코드
샘플에서는 일부만 표시DB 스키마를 Firestore에 requests, drivers, dispatches, users, commissions 컬렉션으로 정의합니다. 각 컬렉션의 주요 필드와 타입을 명세한 TypeScript 인터페이스로 선언하세요. read/write는 Firestore client SDK와 Firebase Auth의 authId 기반으로 허용 범위 제어 권장(예: 본인 정보만 수정, 관리자는 전체 열람). 유저 롤별로 Firestore 보안 규칙 샘플을 함께 만드세요. DB 접속 및 CRUD 기본 예시 함수 제공.
퀵서비스 요청 & 배차 핵심 기능 구현
샘플에서는 일부만 표시퀵서비스 요청 등록(고객 화면), 인근 드라이버 리스트 추출 및 배차 알림(드라이버 화면 - 실시간 pending/accept UI), 진행 중/완료 상태로 상태 동기화, 드라이버/고객 위치&상태 실시간 표시, 핵심 업무 플로우를 App Router route별로 구현하세요. 수수료 산출 및 디스패치 완료시 정산 레코드 생성까지 포함. socketX 등 실시간 sync가 Firestore snapshot listener로 구현됨을 가정하고, UI는 간결하게 Listing/Form정도로 충분합니다.
관리자 대시보드, 기본 배포 및 운영 세팅
샘플에서는 일부만 표시/admin 경로에 관리자만 접근 가능한 대시보드를 구현하세요. 전체 요청, 배차, 기사, 고객, 수수료 내역을 테이블 형태로 조회 가능. 각 항목의 상세 기록과 로그를 Firestore에서 불러와 행별 팝업(detail modal)로 볼 수 있습니다. Firebase Hosting 배포 스크립트와 환경변수 예시, README 내 운영 관련 주의사항(시크릿/서비스키 미노출) 마크다운 목차를 추가하세요.